ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/cvsroot/kgsueme/doc/protocol.xml
Revision: 1.1
Committed: Wed Jun 4 15:51:48 2003 UTC (23 years, 4 months ago) by pcg
Content type: text/xml
Branch: MAIN
Log Message:
*** empty log message ***

File Contents

# User Rev Content
1 pcg 1.1 <?xml version="1.0" encoding="utf-8"?>
2     <html>
3     <head>
4     <title>KGS Protocol Description</title>
5     <!--
6     Copyright (C) 2003 Marc Lehmannn &lt;pcg@goof.com&gt;
7    
8     You can redistribute and/or modify this document under the terms of
9     the GNU General Public License as published by the Free Software
10     Foundation; either version 2 of the License, or (at your option) any
11     later version.
12    
13     This document is distributed in the hope that it will be useful,
14     but WITHOUT ANY WARRANTY; without even the implied warranty of
15     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16     General Public License for more details.
17    
18     You should have received a copy of the GNU General Public License
19     along with this program; if not, write to the Free Software
20     Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
21     -->
22     </head>
23     <body>
24    
25     <h1>KGS Protocol Description</h1>
26    
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
29     structures in the protocol. Adapting it to other languages should be
30     trivial.</p>
31    
32     <h2>Structure and conventions of this document and the protocol</h2>
33    
34     <p>"Send" means messages send from the client to the server, while
35     "received" means messages send by the server to the client.</p>
36    
37     <p>Everything on the wire are in little-endian format (what a shame).</p>
38    
39     <p>Primitive types (in upper case) are mostly integers ("Ibits"), ascii
40     strings ("USERNAME", "Alength"), or UCS2-Strings ("STRING"). Yes, I
41     know java is supposed to do UTF-16, but no implementation seems to
42     care...</p>
43    
44     <p>For the rest, go figure or bug me, Marc Lehmann &lt;pcg@goof.com&gt;</p>
45    
46     <h2>Stream and message structure.</h2>
47    
48     <p>After connecting to the server, a handshake byte is exchanged. It's the
49     major version number of the protocol the client uses. Version 3 and 4 are
50     mostly the same, except that Version 4 clients expect server messages to
51     be compressed, version 3 clients not.</p>
52    
53     <p>After that, the server sends back his version number, which is
54     always 3 in the current protocol. Most of the protocol variation is
55     determined by the server using the client version that is used in the
56     initial login message.</p>
57    
58     <p>After the initial handshake, the client sends uncompressed
59     messages, while the server sends back a zlib-compressed
60     stream (<a href="http://rfc1950.x42.com/">rfc1950</a> and <a
61     href="http://rfc1950.x42.com/">rfc1951</a>).</p>
62    
63     <p>All messages have the same header:</p>
64    
65     <macro name="message_header" send="yes" recv="yes">
66     <member name="_unknown" type="I16"/>
67     <member name="length" type="I16"/>
68     The length is the length of the full message including the header.
69     <member name="type" type="I16"/>
70     If the type is &gt;= 0x4000 this is a message for a specific channel. The channel
71     number is always the next I16.
72     </macro>
73    
74     <h2>Constants, enumartaion and set types used in the protocol.</h2>
75    
76     <p>Baaah... not yet.</p>
77    
78     <h2>Macros used in send &amp; receive messages</h2>
79    
80     <macro name="user">
81     <member name="name" type="USERNAME"/>
82     <member name="flags" type="I32" default="1"/>
83     </macro>
84    
85     <h2>Macros used in send messages</h2>
86    
87     <message type="0000" name="login" send="yes">
88     <member name="ver_major" type="I32" default="2"/>
89     <member name="ver_minor" type="I32" default="4"/>
90     <member name="ver_micro" type="I32" default="67"/>
91     <member name="login " type="USERNAME"/>
92     <member name="password " type="i64" default="0"/>
93     <member name="guest " type="FLAG" default="1"/>
94     <member name="_unknown3" type="I16" default="0"/>
95     <member name="locale " type="A5" default="en_US"/>
96     <member name="clientver" type="DATA"/>
97     </message>
98    
99     <message type="0014" name="server_stats">
100     Request server statistics.
101     </message>
102    
103     <message type="0021" name="pic_req">
104     Request a user picture from the server.
105     <member name="name" type="USERNAME"/>
106     </message>
107    
108     <message type="0021" name="pic_upload">
109     Same code as pic_req, but with an additional data section that
110     should contain a JPEG image that is &lt;=7KB. It must have 141×200 Pixels.
111     <member name="name" type="USERNAME"/>
112     <member name="data" type="DATA"/>
113     </message>
114    
115     <message type="0100" name="gnotice">
116     Send a global message. Maybe. Never tried, for obvious reasons :/
117     <member name="notice" type="STRING"/>
118     </message>
119    
120     <message type="0318" name="list_rooms">
121     List the rooms in a specific group/category.
122     <member name="group" type="I8"/>
123     </message>
124    
125     <message type="031a" name="new_room">
126     Create a new room. Not verified.
127     <member name="name" type="USERNAME"/>
128     <member name="i1" type="I32" default="0"/>
129     <member name="b1" type="I8" default="0"/>
130     <member name="b2" type="I8" default="255"/>
131     <member name="b3" type="I8" default="255"/>
132     <member name="group" type="I8" default="1"/>
133     <member name="name" type="STRING"/>
134     <member name="description" type="STRING"/>
135     <member name="flags" type="I8"/>
136     0x10 .. private room etc.. see code
137     </message>
138    
139     <message type="4300" name="join_room" send="yes">
140     <member name="channel" type="I16"/>
141     <member name="user" type="user"/>
142     </message>
143    
144     <message type="4301" name="msg_room" send="yes">
145     <member name="channel" type="I16"/>
146     <member name="name" type="USERNAME"/>
147     <member name="message" type="STRING"/>
148     </message>
149    
150     <message type="4302" name="part_room" send="yes">
151     <member name="channel" type="I16"/>
152     <member name="name" type="USERNAME"/>
153     </message>
154    
155     <message type="4305" name="new_game" send="yes">
156     <member name="channel" type="I16"/>
157     <member name="id" type="I16"/>
158     <member name="gametype" type="I32"/>
159     <member name="rules" type="rules"/>
160     <member name="notes" type="STRING"/>
161     </message>
162    
163     <message type="430b" name="req_games" send="yes">
164     request to update room game list (send once per minute)
165     <member name="channel" type="I16"/>
166     </message>
167    
168     <message type="4319" name="req_desc" send="yes">
169     Request room description.
170     <member name="channel" type="I16"/>
171     </message>
172    
173     <message type="4400" name="send_chal" send="yes">
174     No idea.
175     <member name="channel" type="I16"/>
176     <member name="black" type="USERNAME"/>
177     <member name="white" type="USERNAME"/>
178     More following... TREE or challenge.
179     </message>
180    
181     <message type="4403" name="join_game" send="yes">
182     <member name="user" type="user"/>
183     <member name="channel" type="I16"/>
184     </message>
185    
186     <message type="4404" name="part_game" send="yes">
187     <member name="channel" type="I16"/>
188     <member name="name" type="USERNAME"/>
189     </message>
190    
191     <message type="4405" name="set_tree" send="yes">
192     <member name="channel" type="I16"/>
193     <member name="tree" type="TREE"/>
194     </message>
195    
196     <message type="4408" name="get_tree" send="yes">
197     <member name="channel" type="I16"/>
198     <member name="node" type="I32"/>
199     </message>
200    
201     <message type="440c" name="claim_win" send="yes">
202     <member name="channel" type="I16"/>
203     <member name="_byte" type="I8 "/>
204     Player colour maybe? Unclear.
205     </message>
206    
207     <message type="440d" name="add_time" send="yes">
208     <member name="channel" type="I16"/>
209     <member name="time" type="I32"/>
210     <member name="player" type="I8"/>
211     </message>
212    
213     <message type="440f" name="grant_undo" send="yes">
214     <member name="channel" type="I16"/>
215     </message>
216    
217     <message type="4410" name="resign_game" send="yes">
218     <member name="channel" type="I16"/>
219     <member name="player" type="I8"/>
220     </message>
221    
222     <message type="441a" name="set_teacher" send="yes">
223     <member name="channel" type="I16"/>
224     <member name="name" type="USERNAME"/>
225     </message>
226    
227     <message type="4422" name="add_user" send="yes">
228     <member name="channel" type="I16"/>
229     <member name="othername" type="USERNAME"/>
230     <member name="name" type="USERNAME"/>; # gives user access to the game (to what? ;)
231     </message>
232    
233     <message type="4423" name="set_privacy" send="yes">
234     <member name="channel" type="I16"/>
235     <member name="private" type="I8"/>
236     </message>
237    
238     <message type="4429" name="reject_chal" send="yes">
239     <member name="channel" type="I16"/>
240     <member name="name" type="USERNAME"/>
241     </message>
242    
243     <message type="4433" name="req_result" send="yes">
244     <member name="channel" type="I16"/>
245     <member name="channel" type="I16"/>
246     </message>
247    
248     <h2>Macros mainly used in receive messages</h2>
249    
250     <macro name="challenge_defaults">
251     <member name="gametype" type="I32"/>
252     <member name="size" type="I32"/>
253     <member name="timesys" type="I32"/>
254     <member name="time" type="I32"/>
255     <member name="byo_time" type="I32"/>
256     <member name="byo_periods" type="I32"/>
257     <member name="can_time" type="I32"/>
258     <member name="can_stones" type="I32"/>)
259     </macro>
260    
261     <macro id="rules" class="KGS::Rules">
262     <member name="ruleset" type="I8"/>
263     <member name="size" type="I8"/>
264     <member name="handicap" type="I8"/>
265     <member name="komi" type="KOMI"/>
266     <member name="timesys" type="I8"/>
267     <member name="time" type="I32"/>
268     <member name="interval" type="I32"/>
269     byo-yomi time / canadian time
270     <member name="count" type="I16"/>
271     periods / moves
272     </macro>
273    
274     <macro name="challenge" class="KGS::Challenge">
275     <member name="user1" type="user"/>
276     <member name="user2" type="user"/>
277     <member name="gametype" type="I32"/>
278     <member name="rules" type="rules"/>
279     Maybe the rules" are in TREE format. I forgot.
280     </macro>
281    
282     <macro name="game" class="KGS::Game">
283     <member name="channel" type="I16"/>
284     <member name="type " type="I32"/>
285     <member name="user1" type="user"/>
286     White
287     <member name="user2" type="user"/>
288     Black
289     <member name="user3" type="user"/>
290     Owner
291     <member name="size" type="I32"/>
292     <member name="handicap" type="I32"/>
293     &lt; 0 not fully setup
294     <member name="komi" type="I322"/>
295     <member name="moves" type="I16"/>
296     <member name="flags" type="I16"/>
297     <member name="observers" type="I32"/>
298     <member name="saved" type="FLAG"/>
299     <member name="notes" type="STRING" guard="handicap &lt; 0"/>
300     </macro>
301    
302     <macro name="room_obs">
303     <member name="name" type="A50"/>
304     <member name="channel" type="I16"/>
305     <member name="flags" type="I32"/>
306     <member name="users" type="I32"/>)
307     </macro>
308    
309     <macro name="room" class="KGS::Room">
310     <member name="channel" type="I16"/>
311     <member name="flags" type="I8"/>
312     <member name="group" type="I8"/>
313     <member name="users" type="I16"/>
314     <member name="games" type="I16"/>
315     <member name="name" type="STRING"/>)
316     </macro>
317    
318     <macro name="score" class="KGS::Score">
319     <member name="score" type="I324"/>
320     <member name="territory" type="I32"/>
321     <member name="captures" type="I32"/>
322     <member name="i3" type="I32"/>
323     <member name="f2" type="I324"/>
324     <member name="komi" type="I324"/>
325     <member name="i4" type="I32"/>)
326     Apperently the i3, f2, i4 are zero.
327     </macro>
328    
329     <h2>Receive messages</h2>
330    
331     <message type="0001" name="login" recv="yes">
332     <member name="result" type="CONSTANT" default="login ok"/>
333     <member name="success" type="CONSTANT" default="1"/>
334     </message>
335    
336     <message type="0002" name="login" recv="yes">
337     <member name="result" type="CONSTANT" default="guest login ok"/>
338     <member name="success" type="CONSTANT" default="1"/>
339     </message>
340    
341     <message type="0003" name="login" recv="yes">
342     <member name="result" type="CONSTANT" default="login error 3"/>
343     ** maybe more following? **
344     </message>
345    
346     <message type="0004" name="login" recv="yes">
347     <member name="result" type="CONSTANT" default="wrong password"/>
348     ** maybe more following? **
349     </message>
350    
351     <message type="0005" name="login" recv="yes">
352     <member name="result" type="CONSTANT" default="user unknown"/>
353     ** maybe more following? **
354     </message>
355    
356     <message type="0006" name="login" recv="yes">
357     <member name="result" type="CONSTANT" default="user exists"/>
358     ** maybe more following? **
359     </message>
360    
361     <message type="0018" name="login" recv="yes">
362     <member name="result" type="CONSTANT" default="login error 18"/>
363     ** maybe more following? **
364     </message>
365    
366     <message type="0022" name="login" recv="yes">
367     <!-- "thanks" to jylem for blocking me ;)-->
368     <member name="result" type="CONSTANT" default="user or ip blocked"/>
369     <member name="reason" type="STRING"/>
370     </message>
371    
372     <message type="0013" name="msg_chat" recv="yes">
373     <member name="user1" type="USERNAME"/>
374     <member name="user2" type="USERNAME"/>
375     <member name="message" type="STRING"/>
376     </message>
377    
378     <message type="0015" name="stats" recv="yes">
379     <member name="ver_major" type="I16"/>
380     <member name="ver_minor" type="I16"/>
381     <member name="ver_micro" type="I16"/>
382     <member name="boot_time" type="i64"/>
383     <member name="users_cur" type="I32"/>
384     <member name="users_max" type="I32"/>
385     <member name="users_lim" type="I32"/>
386     <member name="accts_cur" type="I32"/>
387     <member name="accts_max" type="I32"/>
388     <member name="unknown1" type="I32"/>
389     <member name="work_max" type="I32"/>
390     <member name="rooms_cur" type="I32"/>
391     <member name="rooms_max" type="I32"/>
392     <member name="rooms_lim" type="I32"/>
393     <member name="games_cur" type="I32"/>
394     <member name="games_max" type="I32"/>
395     <member name="games_lim" type="I32"/>
396     <member name="results_cur" type="I32"/>
397     <member name="results_max" type="I32"/>
398     <member name="unknown2" type="I32"/>
399     <member name="params_cur" type="I32"/>
400     <member name="params_max" type="I32"/>
401     <member name="bytes_in" type="i64"/>
402     <member name="packets_in" type="i64"/>
403     <member name="bytes_out" type="i64"/>
404     <member name="packets_out" type="i64"/>)
405     </message>
406    
407     <message type="0016" name="idle_warn" recv="yes">
408     idle warning, autologout soon (10 minutes...)
409     </message>
410    
411     <message type="001b" name="timewarning_default" recv="yes">
412     WILD guess
413     <member name="channel" type="I16"/>
414     <member name="time" type="I16"/>
415     </message>
416    
417     <message type="001c" name="idle_err" recv="yes">
418     autologout
419     </message>
420    
421     <message type="001d" name="ping" recv="yes">
422     </message>
423    
424     <message type="0021" name="userpic" recv="yes">
425     <member name="name" type="USERNAME"/>
426     Reply to pic_req, contains an image in jpeg format.
427     <member name="data" type="DATA"/>
428     </message>
429    
430     <message type="0100" name="gnotice" recv="yes">
431     global notice, sent to everybody
432     <member name="notice" type="STRING"/>
433     </message>
434    
435    
436     <message type="0310" name="priv_room" recv="yes">
437     "permission denied" when joining a room
438     <member name="name" type="STRING"/>
439     </message>
440    
441     <message type="0318" name="upd_rooms" recv="yes">
442     <member name="rooms" type="room" array="yes"/>
443     </message>
444    
445     <message type="041c" name="upd_game2" recv="yes">
446     <member name="channel_junk" type="I16"/>
447     <member name="game" type="game"/>
448     </message>
449    
450     <message type="0202" name="upd_user" recv="yes">
451     # loc 0" type="chat(?) loc 1 => gameinfo?, loc 2 => game result (more data)
452     <member name="location" type="I32"/>
453     <member name="user" type="user"/>
454     <member name="lotsofinfo" type="DATA" guard="location == 2"/>
455     </message>
456    
457     <h3>Room messages</h3>
458    
459     <p>Not all room messages are for rooms only, and rooms need to parse
460     not only these messages. Orthogonality, what for?</p>
461    
462     <message type="4300" name="join_room" recv="yes">
463     <member name="channel" type="I16"/>
464     <member name="users" type="user" array="yes"/>
465     </message>
466    
467     <message type="4301" name="msg_room" recv="yes">
468     <member name="channel" type="I16"/>
469     <member name="name" type="USERNAME"/>
470     <member name="message" type="STRING"/>
471     </message>
472    
473     <message type="4302" name="part_room" recv="yes">
474     <member name="channel" type="I16"/>
475     <member name="user" type="user"/>
476     </message>
477    
478     <message type="4303" name="del_room" recv="yes">
479     <member name="channel" type="I16"/>
480    
481     </message>
482    
483     <message type="4304" name="upd_games" recv="yes">
484     <member name="channel" type="I16"/>
485     <member name="games" type="game" array="yes"/>
486     </message>
487    
488     <message type="4319" name="desc_room" recv="yes">
489     <member name="channel" type="I16"/>
490     <member name="owner" type="USERNAME"/>
491     <member name="description" type="STRING"/>
492     </message>
493    
494    
495     <message type="0411" name="chal_defaults" recv="yes">
496     <member name="channel" type="I16"/>
497     <member name="defaults" type="challenge_defaults"/>
498     </message>
499    
500     <h3>Game messages</h3>
501    
502     <message type="4400" name="upd_chal" recv="yes">
503     Unclear.
504     <member name="channel" type="I16"/>
505     <member name="challenge" type="challenge"/>
506     </message>
507    
508     <message type="4401" name="upd_game" recv="yes">
509     <member name="channel" type="I16"/>
510     <member name="game" type="game"/>
511     </message>
512    
513     <message type="4402" name="del_game" recv="yes">
514     <member name="channel" type="I16"/>
515     </message>
516    
517     <message type="4403" name="upd_observers" recv="yes">
518     <member name="channel" type="I16"/>
519     <member name="users" type="user" array="yes"/>
520     </message>
521    
522     <message type="4404" name="del_observer" recv="yes">
523     <member name="channel" type="I16"/>
524     <member name="name" type="USERNAME"/>
525     </message>
526    
527     <message type="4405" name="set_tree" recv="yes">
528     <member name="channel" type="I16"/>
529     <member name="tree" type="TREE"/>
530     </message>
531    
532     <message type="4406" name="upd_tree" recv="yes">
533     <member name="channel" type="I16"/>
534     <member name="tree" type="TREE"/>
535     </message>
536    
537     <message type="4407" name="set_node" recv="yes">
538     <member name="channel" type="I16"/>
539     <member name="node" type="I32"/>
540     </message>
541    
542     <message type="4409" name="superko" recv="yes">
543     Superko-warning.
544     <member name="channel" type="I16"/>
545     </message>
546    
547     <message type="440b" name="final_result" recv="yes">
548     <member name="channel" type="I16"/>
549     <member name="blackscore" type="score"/>
550     <member name="whitescore" type="score"/>
551     </message>
552    
553     <message type="440e" name="req_undo" recv="yes">
554     <member name="channel" type="I16"/>
555    
556     </message>
557    
558     <message type="4410" name="resign_game" recv="yes">
559     <member name="channel" type="I16"/>
560     <member name="player" type="I8"/>
561     </message>
562    
563     <message type="441a" name="set_teacher" recv="yes">
564     <member name="channel" type="I16"/>
565     <member name="name" type="USERNAME"/>
566     </message>
567    
568     <message type="441d" name="owner_left" recv="yes">
569     Unclear.
570     <member name="channel" type="I16"/>
571     </message>
572    
573     <message type="441e" name="teacher_left" recv="yes">
574     Unclear.
575     <member name="channel" type="I16"/>
576     </message>
577    
578     <message type="4422" name="unknown4422" recv="yes">
579     change teacher? something to do with editing?
580     <member name="channel" type="I16"/>
581     <member name="name1" type="USERNAME"/>
582     <member name="name2" type="USERNAME"/>
583     </message>
584    
585     <message type="4433" name="req_result" recv="yes">
586     Unclear.
587     <member name="channel" type="I16"/>
588     # # recv_result(?)
589     </message>
590    
591     <message type="4434" name="unknown4434" recv="yes">
592     <member name="channel" type="I16"/>
593     <member name="b1" type="I8"/>
594     ?? !demonstration game??
595     </message>
596    
597     </body>
598     </html>
599