ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/kgsueme/doc/protocol.xml
(Generate patch)

Comparing kgsueme/doc/protocol.xml (file contents):
Revision 1.3 by pcg, Thu Jun 5 10:09:10 2003 UTC vs.
Revision 1.4 by pcg, Thu Jun 5 10:28:35 2003 UTC

… …
27 <p>This XML document describes the KGS protocol. It is also used 27 <p>This XML document describes the KGS protocol. It is also used
28 to automatically generate the perl parser for all the messages and 28 to automatically generate the perl parser for all the messages and
29 structures in the protocol. Adapting it to other languages should be 29 structures in the protocol. Adapting it to other languages should be
30 trivial.</p> 30 trivial.</p>
31 31
32 <p>If you feel you need to update the visual appearance of this
33 document, feel free to look at <tt>doc/doc2html.xsl</tt> and improve
34 it.</p>
35
32<h2>Structure and conventions of this document and the protocol</h2> 36<h2>Structure and conventions of this document and the protocol</h2>
33 37
34 <p>"Send" means messages send from the client to the server, while 38 <p>"Send" means messages send from the client to the server, while
35 "received" means messages send by the server to the client.</p> 39 "received" means messages send by the server to the client.</p>
36 40
37 <p>Everything on the wire are in little-endian format (what a shame).</p> 41 <p>Everything on the wire is in little-endian format (what a shame).</p>
38 42
39 <p>Primitive types are mostly integers (signed "I&lt;bits&gt;", 43 <p>Primitive types are mostly integers (signed
40 unsigned "I&lt;bits&gt;"), ascii strings ("username"), or 44 "<code>I</code>&lt;bits&gt;", unsigned "<code>U</code>&lt;bits&gt;"),
45 ascii strings ("<code>username</code>"), or zero-terminated
41 zero-terminated UCS2-Strings ("STRING"). Yes, I know java is supposed 46 UCS2-Strings ("<code>STRING</code>"). Yes, I know java is supposed to
42 to do UTF-16, but no implementation seems to care...</p> 47 do UTF-16, but no implementation seems to care...</p>
43 48
44 <p>For the rest, go figure or bug me, Marc Lehmann &lt;pcg@goof.com&gt;</p> 49 <p>For the rest, go figure or bug me, Marc Lehmann &lt;pcg@goof.com&gt;</p>
45 50
46<h2>Stream and message structure.</h2> 51<h2>Stream and message structure.</h2>
47 52
48 <p>After connecting to the server, a handshake byte is exchanged. It's the 53 <p>After connecting to the server, a handshake byte is sent. It's
49 major version number of the protocol the client uses. Version 3 and 4 are 54 the major version number of the protocol the client expects to
50 mostly the same, except that Version 4 clients expect server messages to 55 receive. Version 3 and 4 are mostly the same, except that Version 4
51 be compressed, version 3 clients not.</p> 56 clients expect server messages to be compressed, version 3 clients
57 not.</p>
52 58
53 <p>After that, the server sends back his version number, which is 59 <p>The server sends back his protocol number, which is always 3 in
54 always 3 in the current protocol. Most of the protocol variation is 60 the current protocol. Most of the protocol variation is determined by
55 determined by the server using the client version that is used in the 61 the server using the client version that is used in the initial login
56 initial login message.</p> 62 message, not the initial handshake byte.</p>
57 63
58 <p>After the initial handshake, the client sends uncompressed 64 <p>After the initial handshake, the client sends uncompressed
59 messages, while the server sends back a zlib-compressed 65 messages, while the server sends back a zlib-compressed
60 stream (<a href="http://rfc1950.x42.com/">rfc1950</a> and <a 66 stream (<a href="http://rfc1950.x42.com/">rfc1950</a> and <a
61 href="http://rfc1950.x42.com/">rfc1951</a>).</p> 67 href="http://rfc1950.x42.com/">rfc1951</a>).</p>
… …
102 <member name="ver_minor" type="U32" default="4"/> 108 <member name="ver_minor" type="U32" default="4"/>
103 <member name="ver_micro" type="U32" default="67"/> 109 <member name="ver_micro" type="U32" default="67"/>
104 <member name="name" type="username"/> 110 <member name="name" type="username"/>
105 <member name="password " type="U64" default="0"/> 111 <member name="password " type="U64" default="0"/>
106 Password is a number calculated as follows (VERY insecure, basically plaintext!): 112 Password is a number calculated as follows (VERY insecure, basically plaintext!):
107 password = 0; for (characters) { password = password * 1055 + ascii (char) } 113 password = 0; for char in characters do password ← password * 1055 + ascii_code (char);
108 <member name="guest" type="flag" default="1"/> 114 <member name="guest" type="flag" default="1"/>
109 <member name="_unknown3" type="U16" default="0"/> 115 <member name="_unknown3" type="U16" default="0"/>
110 <member name="locale" type="locale" default='"en_US"'/> 116 <member name="locale" type="locale" default='"en_US"'/>
111 <member name="clientver" type="DATA" default='"1.4.1_01:Swing app:Sun Microsystems Inc."'/> 117 <member name="clientver" type="DATA" default='"1.4.1_01:Swing app:Sun Microsystems Inc."'/>
118 The "default" is the java vm version, not exactly he client version. However,
119 you should always send a tetx like "Jonathan's C client bersion 0.6" or somesuch,
120 so the server can, if necessary, block broken clients or client versions.
112 </message> 121 </message>
113 122
114 <message type="0014" name="server_stats" send="yes"> 123 <message type="0014" name="server_stats" send="yes">
115 Request server statistics. 124 Request server statistics.
116 </message> 125 </message>
… …
120 <member name="name" type="username"/> 129 <member name="name" type="username"/>
121 </message> 130 </message>
122 131
123 <message type="0021" name="pic_upload" send="yes"> 132 <message type="0021" name="pic_upload" send="yes">
124 Same code as pic_req, but with an additional data section that 133 Same code as pic_req, but with an additional data section that
125 should contain a JPEG image that is &lt;=7KB. It must have 141×200 Pixels. 134 must contain a JPEG image that is &lt;=7KB. It must have 141×200 pixels.
126 <member name="name" type="username"/> 135 <member name="name" type="username"/>
127 <member name="data" type="DATA"/> 136 <member name="data" type="DATA"/>
128 </message> 137 </message>
129 138
130 <message type="0100" name="gnotice" send="yes"> 139 <message type="0100" name="gnotice" send="yes">
… …
315 324
316 <struct name="room_obs"> 325 <struct name="room_obs">
317 <member name="name" type="roomname"/> 326 <member name="name" type="roomname"/>
318 <member name="channel" type="U16"/> 327 <member name="channel" type="U16"/>
319 <member name="flags" type="U32"/> 328 <member name="flags" type="U32"/>
320 <member name="users" type="U32"/>) 329 <member name="users" type="U32"/>
321 </struct> 330 </struct>
322 331
323 <struct name="room" class="KGS::Room"> 332 <struct name="room" class="KGS::Room">
324 <member name="channel" type="U16"/> 333 <member name="channel" type="U16"/>
325 <member name="flags" type="U8"/> 334 <member name="flags" type="U8"/>
326 <member name="group" type="U8"/> 335 <member name="group" type="U8"/>
327 <member name="users" type="U16"/> 336 <member name="users" type="U16"/>
328 <member name="games" type="U16"/> 337 <member name="games" type="U16"/>
329 <member name="name" type="STRING"/>) 338 <member name="name" type="STRING"/>
330 </struct> 339 </struct>
331 340
332 <struct name="score" class="KGS::Score"> 341 <struct name="score" class="KGS::Score">
333 <member name="score" type="score"/> 342 <member name="score" type="score"/>
334 <member name="territory" type="U32"/> 343 <member name="territory" type="U32"/>
335 <member name="captures" type="U32"/> 344 <member name="captures" type="U32"/>
336 <member name="i3" type="U32"/> 345 <member name="i3" type="U32"/>
337 <member name="f2" type="U32"/> 346 <member name="f2" type="U32"/>
338 <member name="komi" type="komi"/> 347 <member name="komi" type="komi"/>
339 <member name="i4" type="U32"/>) 348 <member name="i4" type="U32"/>
340 Apparently the i3, f2, i4 are zero. 349 Apparently the i3, f2, i4 are zero.
341 </struct> 350 </struct>
342 351
343<h2>Receive messages</h2> 352<h2>Receive messages</h2>
344 353
… …
413 <member name="params_cur" type="U32"/> 422 <member name="params_cur" type="U32"/>
414 <member name="params_max" type="U32"/> 423 <member name="params_max" type="U32"/>
415 <member name="bytes_in" type="U64"/> 424 <member name="bytes_in" type="U64"/>
416 <member name="packets_in" type="U64"/> 425 <member name="packets_in" type="U64"/>
417 <member name="bytes_out" type="U64"/> 426 <member name="bytes_out" type="U64"/>
418 <member name="packets_out" type="U64"/>) 427 <member name="packets_out" type="U64"/>
419 </message> 428 </message>
420 429
421 <message type="0016" name="idle_warn" recv="yes"> 430 <message type="0016" name="idle_warn" recv="yes">
422 idle warning, autologout soon (10 minutes...) 431 idle warning, autologout soon (10 minutes...)
423 </message> 432 </message>

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines