2 Description of the new interface protocol (version 2.00)
3 ========================================================
5 The protocol is mainly specified by its implementation in files
7 common/commonTypes.ml (generic types)
8 commmon/gui_proto.ml (GUI protocol)
10 The specification should be moved in an human readable form to this file in
16 The GUI must connect to the core via a TCP socket. Binary messages are
17 sent on this socket, with the following format:
19 | size of content (4 bytes) | content |
21 size of content: 4 bytes integer (in network order, ie
22 1025 = 1 + 256 * 4 = | 1 | 4 | 0 | 0 | ), indicating the length
23 of the content of the message
25 content: the content of the message. the content starts by a 2 bytes integer,
26 which is the opcode of the message, followed with the arguments.
27 If the opcode is not known by the GUI, the GUI can simply discard the whole
28 message, and continue with other messages (this way, partial implementations
29 of the protocol should work for simple functions).
31 | opcode (2 bytes) | arguments |
33 When connected, both sides start by sending a 0-opcode message, with
34 a 4-bytes argument indicating the version of the protocol used
35 (CoreProtocol and GuiProtocol messages in the gui_proto.ml file).
37 Then, they should use the smallest protocol version, so that all messages
38 should be understandandable by both sides (the core should always remain
39 backward compatible in the future with old versions of this GUI protocol).
41 Current version of the protocol is 0.
43 The remaining of this file will describe encoding and meaning of messages.
46 - In the core, all data structures have unique identifiers (an integer)
47 in their types (one result and one server can have the same number, but
48 not two different results). Thus, these identifiers are often used
49 between the GUI and the core.
51 - The basic core engine uses the following types:
53 network: a peer to peer network (donkey, open napster, gnutella, ...)
54 search: a search (network independant)
56 server: a server on a given network
57 file: a file being downloaded on a given network
58 client: a source for a file being downloaded, or a friend
59 result: the result of a search, or a browse operation on a friend
60 user: another peer connected on a server, or a source for a result of
61 a search (it will become a client if we download its files or
62 if it becomes a friend)
63 room: a chat room, with many users connected to dialog.
68 For basic types, the following encoding is used in the messages:
71 int16: two bytes in network order
72 int/int32: 4 bytes in network order
73 1025 = 1 + 256 * 4 = | 1 | 4 | 0 | 0 |
75 string: an int16 for the length, followed by the characters of the string
78 bool: an int8, with 0 for FALSE and 1 for TRUE.
80 float: a string (see above), ASCII representation of the float.
82 list or arrays of values: an int16 for the number of elements, followed by
83 the elements, without separators.
85 records, pairs, tuples: the fields are encoded without separators.
87 md4: the 16 bytes corresponding to the hash.
89 Messages from Core to GUI for protocol 0
90 ========================================
91 CoreProtocol (opcode 0) + int32 (protocol version)
93 Indicates the most up-to-date version of the protocol understood by the
96 Options_info (opcode 1) + a list of string pairs
98 Indicates the names of some options and their associated value (converted
101 DefineSearches (opcode 3) + query description list
103 Indicates to the GUI predefined or user-defined queries formats.
104 See buf_query in gui_proto.ml to see how queries are encoded exactly.
106 Result_info (opcode 4) + result description
108 Describes a result. The result is not associated with a search.
109 Another message is used to associate the result (number) with a search.
111 result format: see buf_result in gui_proto.ml.
115 Messages from GUI to Core for protocol 0
116 ========================================