Description of the new interface protocol (version 2.00)
========================================================
The protocol is mainly specified by its implementation in files
common/commonTypes.ml (generic types)
commmon/gui_proto.ml (GUI protocol)
The specification should be moved in an human readable form to this file in
the future.
Basic ideas:
============
The GUI must connect to the core via a TCP socket. Binary messages are
sent on this socket, with the following format:
| size of content (4 bytes) | content |
size of content: 4 bytes integer (in network order, ie
1025 = 1 + 256 * 4 = | 1 | 4 | 0 | 0 | ), indicating the length
of the content of the message
content: the content of the message. the content starts by a 2 bytes integer,
which is the opcode of the message, followed with the arguments.
If the opcode is not known by the GUI, the GUI can simply discard the whole
message, and continue with other messages (this way, partial implementations
of the protocol should work for simple functions).
| opcode (2 bytes) | arguments |
When connected, both sides start by sending a 0-opcode message, with
a 4-bytes argument indicating the version of the protocol used
(CoreProtocol and GuiProtocol messages in the gui_proto.ml file).
Then, they should use the smallest protocol version, so that all messages
should be understandandable by both sides (the core should always remain
backward compatible in the future with old versions of this GUI protocol).
Current version of the protocol is 0.
The remaining of this file will describe encoding and meaning of messages.
Some remarks:
- In the core, all data structures have unique identifiers (an integer)
in their types (one result and one server can have the same number, but
not two different results). Thus, these identifiers are often used
between the GUI and the core.
- The basic core engine uses the following types:
network: a peer to peer network (donkey, open napster, gnutella, ...)
search: a search (network independant)
server: a server on a given network
file: a file being downloaded on a given network
client: a source for a file being downloaded, or a friend
result: the result of a search, or a browse operation on a friend
user: another peer connected on a server, or a source for a result of
a search (it will become a client if we download its files or
if it becomes a friend)
room: a chat room, with many users connected to dialog.
Basic encoding:
===============
For basic types, the following encoding is used in the messages:
int8: one byte
int16: two bytes in network order
int/int32: 4 bytes in network order
1025 = 1 + 256 * 4 = | 1 | 4 | 0 | 0 |
string: an int16 for the length, followed by the characters of the string
without 0 at the end.
bool: an int8, with 0 for FALSE and 1 for TRUE.
float: a string (see above), ASCII representation of the float.
list or arrays of values: an int16 for the number of elements, followed by
the elements, without separators.
records, pairs, tuples: the fields are encoded without separators.
md4: the 16 bytes corresponding to the hash.
Messages from Core to GUI for protocol 0
========================================
CoreProtocol (opcode 0) + int32 (protocol version)
Indicates the most up-to-date version of the protocol understood by the
core.
Options_info (opcode 1) + a list of string pairs
Indicates the names of some options and their associated value (converted
to a string).
DefineSearches (opcode 3) + query description list
Indicates to the GUI predefined or user-defined queries formats.
See buf_query in gui_proto.ml to see how queries are encoded exactly.
Result_info (opcode 4) + result description
Describes a result. The result is not associated with a search.
Another message is used to associate the result (number) with a search.
result format: see buf_result in gui_proto.ml.
etc...
Messages from GUI to Core for protocol 0
========================================
