docs/interface_protocol.txt

   1
   2   Description of the new interface protocol (version 2.00)
   3   ========================================================
   4
   5 The protocol is mainly specified by its implementation in files
   6
   7 common/commonTypes.ml (generic types)
   8 commmon/gui_proto.ml (GUI protocol)
   9
  10 The specification should be moved in an human readable form to this file in
  11 the future.
  12
  13 Basic ideas:
  14 ============
  15
  16   The GUI must connect to the core via a TCP socket. Binary messages are
  17 sent on this socket, with the following format:
  18
  19 | size of content (4 bytes) | content |
  20
  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
  24
  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).
  30
  31   | opcode (2 bytes) | arguments |
  32
  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).
  36
  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).
  40
  41 Current version of the protocol is 0.
  42
  43 The remaining of this file will describe encoding and meaning of messages.
  44 Some remarks:
  45
  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.
  50
  51  - The basic core engine uses the following types:
  52
  53       network: a peer to peer network (donkey, open napster, gnutella, ...)
  54       search: a search (network independant)
  55
  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.
  64
  65 Basic encoding:
  66 ===============
  67
  68   For basic types, the following encoding is used in the messages:
  69
  70 int8: one byte
  71 int16: two bytes in network order
  72 int/int32: 4 bytes in network order
  73                       1025 = 1 + 256 * 4  =     |   1 |   4 |  0 |  0 |
  74
  75 string: an int16 for the length, followed by the characters of the string
  76   without 0 at the end.
  77
  78 bool: an int8, with 0 for FALSE and 1 for TRUE.
  79
  80 float: a string (see above), ASCII representation of the float.
  81
  82 list or arrays of values: an int16 for the number of elements, followed by
  83    the elements, without separators.
  84
  85 records, pairs, tuples: the fields are encoded without separators.
  86
  87 md4: the 16 bytes corresponding to the hash.
  88
  89 Messages from Core to GUI for protocol 0
  90 ========================================
  91 CoreProtocol (opcode 0) + int32 (protocol version)
  92
  93     Indicates the most up-to-date version of the protocol understood by the
  94     core.
  95
  96 Options_info (opcode 1) + a list of string pairs
  97
  98     Indicates the names of some options and their associated value (converted
  99     to a string).
 100
 101 DefineSearches (opcode 3) + query description list
 102
 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.
 105
 106 Result_info (opcode 4) + result description
 107
 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.
 110
 111     result format: see buf_result in gui_proto.ml.
 112
 113 etc...
 114
 115 Messages from GUI to Core for protocol 0
 116 ========================================
 117
 118
 119
 120
 121
 122