ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/kgsueme/doc/protocol.xml
Revision: 1.2
Committed: Wed Jun 4 19:12:51 2003 UTC (21 years ago) by pcg
Content type: text/xml
Branch: MAIN
Changes since 1.1: +18 -16 lines
Log Message:
*** empty log message ***

File Contents

# Content
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, enumeration 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 Password is a number calculated as follows:
94 password = 0; for (characters) { password = password * 1055 + ascii (char) }
95 <member name="guest" type="FLAG" default="1"/>
96 <member name="_unknown3" type="I16" default="0"/>
97 <member name="locale" type="A5" default="en_US"/>
98 <member name="clientver" type="DATA"/>
99 </message>
100
101 <message type="0014" name="server_stats" send="yes">
102 Request server statistics.
103 </message>
104
105 <message type="0021" name="pic_req" send="yes">
106 Request a user picture from the server.
107 <member name="name" type="USERNAME"/>
108 </message>
109
110 <message type="0021" name="pic_upload" send="yes">
111 Same code as pic_req, but with an additional data section that
112 should contain a JPEG image that is &lt;=7KB. It must have 141×200 Pixels.
113 <member name="name" type="USERNAME"/>
114 <member name="data" type="DATA"/>
115 </message>
116
117 <message type="0100" name="gnotice" send="yes">
118 Send a global message. Maybe. Never tried, for obvious reasons :/
119 <member name="notice" type="STRING"/>
120 </message>
121
122 <message type="0318" name="list_rooms" send="yes">
123 List the rooms in a specific group/category.
124 <member name="group" type="I8"/>
125 </message>
126
127 <message type="031a" name="new_room" send="yes">
128 Create a new room. Not verified.
129 <member name="name" type="USERNAME"/>
130 <member name="i1" type="I32" default="0"/>
131 <member name="b1" type="I8" default="0"/>
132 <member name="b2" type="I8" default="255"/>
133 <member name="b3" type="I8" default="255"/>
134 <member name="group" type="I8" default="1"/>
135 <member name="name" type="STRING"/>
136 <member name="description" type="STRING"/>
137 <member name="flags" type="I8"/>
138 0x10 .. private room etc.. see code
139 </message>
140
141 <message type="4300" name="join_room" send="yes">
142 <member name="channel" type="I16"/>
143 <member name="user" type="user"/>
144 </message>
145
146 <message type="4301" name="msg_room" send="yes">
147 <member name="channel" type="I16"/>
148 <member name="name" type="USERNAME"/>
149 <member name="message" type="STRING"/>
150 </message>
151
152 <message type="4302" name="part_room" send="yes">
153 <member name="channel" type="I16"/>
154 <member name="name" type="USERNAME"/>
155 </message>
156
157 <message type="4305" name="new_game" send="yes">
158 <member name="channel" type="I16"/>
159 <member name="id" type="I16"/>
160 <member name="gametype" type="I32"/>
161 <member name="rules" type="rules"/>
162 <member name="notes" type="STRING"/>
163 </message>
164
165 <message type="430b" name="req_games" send="yes">
166 request to update room game list (send once per minute)
167 <member name="channel" type="I16"/>
168 </message>
169
170 <message type="4319" name="req_desc" send="yes">
171 Request room description.
172 <member name="channel" type="I16"/>
173 </message>
174
175 <message type="4400" name="send_chal" send="yes">
176 No idea.
177 <member name="channel" type="I16"/>
178 <member name="black" type="USERNAME"/>
179 <member name="white" type="USERNAME"/>
180 More following... TREE or challenge.
181 </message>
182
183 <message type="4403" name="join_game" send="yes">
184 <member name="user" type="user"/>
185 <member name="channel" type="I16"/>
186 </message>
187
188 <message type="4404" name="part_game" send="yes">
189 <member name="channel" type="I16"/>
190 <member name="name" type="USERNAME"/>
191 </message>
192
193 <message type="4405" name="set_tree" send="yes">
194 <member name="channel" type="I16"/>
195 <member name="tree" type="TREE"/>
196 </message>
197
198 <message type="4408" name="get_tree" send="yes">
199 <member name="channel" type="I16"/>
200 <member name="node" type="I32"/>
201 </message>
202
203 <message type="440c" name="claim_win" send="yes">
204 <member name="channel" type="I16"/>
205 <member name="_byte" type="I8 "/>
206 Player colour maybe? Unclear.
207 </message>
208
209 <message type="440d" name="add_time" send="yes">
210 <member name="channel" type="I16"/>
211 <member name="time" type="I32"/>
212 <member name="player" type="I8"/>
213 </message>
214
215 <message type="440f" name="grant_undo" send="yes">
216 <member name="channel" type="I16"/>
217 </message>
218
219 <message type="4410" name="resign_game" send="yes">
220 <member name="channel" type="I16"/>
221 <member name="player" type="I8"/>
222 </message>
223
224 <message type="441a" name="set_teacher" send="yes">
225 <member name="channel" type="I16"/>
226 <member name="name" type="USERNAME"/>
227 </message>
228
229 <message type="4422" name="add_user" send="yes">
230 <member name="channel" type="I16"/>
231 <member name="othername" type="USERNAME"/>
232 <member name="name" type="USERNAME"/>; # gives user access to the game (to what? ;)
233 </message>
234
235 <message type="4423" name="set_privacy" send="yes">
236 <member name="channel" type="I16"/>
237 <member name="private" type="I8"/>
238 </message>
239
240 <message type="4429" name="reject_chal" send="yes">
241 <member name="channel" type="I16"/>
242 <member name="name" type="USERNAME"/>
243 </message>
244
245 <message type="4433" name="req_result" send="yes">
246 <member name="channel" type="I16"/>
247 <member name="channel" type="I16"/>
248 </message>
249
250 <h2>Macros mainly used in receive messages</h2>
251
252 <macro name="challenge_defaults">
253 <member name="gametype" type="I32"/>
254 <member name="size" type="I32"/>
255 <member name="timesys" type="I32"/>
256 <member name="time" type="I32"/>
257 <member name="byo_time" type="I32"/>
258 <member name="byo_periods" type="I32"/>
259 <member name="can_time" type="I32"/>
260 <member name="can_stones" type="I32"/>)
261 </macro>
262
263 <macro id="rules" class="KGS::Rules">
264 <member name="ruleset" type="I8"/>
265 <member name="size" type="I8"/>
266 <member name="handicap" type="I8"/>
267 <member name="komi" type="KOMI"/>
268 <member name="timesys" type="I8"/>
269 <member name="time" type="I32"/>
270 <member name="interval" type="I32"/>
271 byo-yomi time / canadian time
272 <member name="count" type="I16"/>
273 periods / moves
274 </macro>
275
276 <macro name="challenge" class="KGS::Challenge">
277 <member name="user1" type="user"/>
278 <member name="user2" type="user"/>
279 <member name="gametype" type="I32"/>
280 <member name="rules" type="rules"/>
281 Maybe the rules" are in TREE format. I forgot.
282 </macro>
283
284 <macro name="game" class="KGS::Game">
285 <member name="channel" type="I16"/>
286 <member name="type " type="I32"/>
287 <member name="user1" type="user"/>
288 White
289 <member name="user2" type="user"/>
290 Black
291 <member name="user3" type="user"/>
292 Owner
293 <member name="size" type="I32"/>
294 <member name="handicap" type="I32"/>
295 &lt; 0 not fully setup
296 <member name="komi" type="I322"/>
297 <member name="moves" type="I16"/>
298 <member name="flags" type="I16"/>
299 <member name="observers" type="I32"/>
300 <member name="saved" type="FLAG"/>
301 <member name="notes" type="STRING" guard="handicap &lt; 0"/>
302 </macro>
303
304 <macro name="room_obs">
305 <member name="name" type="A50"/>
306 <member name="channel" type="I16"/>
307 <member name="flags" type="I32"/>
308 <member name="users" type="I32"/>)
309 </macro>
310
311 <macro name="room" class="KGS::Room">
312 <member name="channel" type="I16"/>
313 <member name="flags" type="I8"/>
314 <member name="group" type="I8"/>
315 <member name="users" type="I16"/>
316 <member name="games" type="I16"/>
317 <member name="name" type="STRING"/>)
318 </macro>
319
320 <macro name="score" class="KGS::Score">
321 <member name="score" type="I324"/>
322 <member name="territory" type="I32"/>
323 <member name="captures" type="I32"/>
324 <member name="i3" type="I32"/>
325 <member name="f2" type="I324"/>
326 <member name="komi" type="I324"/>
327 <member name="i4" type="I32"/>)
328 Apperently the i3, f2, i4 are zero.
329 </macro>
330
331 <h2>Receive messages</h2>
332
333 <message type="0001" name="login" recv="yes">
334 <member name="result" type="CONSTANT" default="login ok"/>
335 <member name="success" type="CONSTANT" default="1"/>
336 </message>
337
338 <message type="0002" name="login" recv="yes">
339 <member name="result" type="CONSTANT" default="guest login ok"/>
340 <member name="success" type="CONSTANT" default="1"/>
341 </message>
342
343 <message type="0003" name="login" recv="yes">
344 <member name="result" type="CONSTANT" default="login error 3"/>
345 ** maybe more following? **
346 </message>
347
348 <message type="0004" name="login" recv="yes">
349 <member name="result" type="CONSTANT" default="wrong password"/>
350 ** maybe more following? **
351 </message>
352
353 <message type="0005" name="login" recv="yes">
354 <member name="result" type="CONSTANT" default="user unknown"/>
355 ** maybe more following? **
356 </message>
357
358 <message type="0006" name="login" recv="yes">
359 <member name="result" type="CONSTANT" default="user exists"/>
360 ** maybe more following? **
361 </message>
362
363 <message type="0018" name="login" recv="yes">
364 <member name="result" type="CONSTANT" default="login error 18"/>
365 ** maybe more following? **
366 </message>
367
368 <message type="0022" name="login" recv="yes">
369 <!-- "thanks" to jylem for blocking me ;)-->
370 <member name="result" type="CONSTANT" default="user or ip blocked"/>
371 <member name="reason" type="STRING"/>
372 </message>
373
374 <message type="0013" name="msg_chat" recv="yes">
375 <member name="user1" type="USERNAME"/>
376 <member name="user2" type="USERNAME"/>
377 <member name="message" type="STRING"/>
378 </message>
379
380 <message type="0015" name="stats" recv="yes">
381 <member name="ver_major" type="I16"/>
382 <member name="ver_minor" type="I16"/>
383 <member name="ver_micro" type="I16"/>
384 <member name="boot_time" type="I64"/>
385 <member name="users_cur" type="I32"/>
386 <member name="users_max" type="I32"/>
387 <member name="users_lim" type="I32"/>
388 <member name="accts_cur" type="I32"/>
389 <member name="accts_max" type="I32"/>
390 <member name="unknown1" type="I32"/>
391 <member name="work_max" type="I32"/>
392 <member name="rooms_cur" type="I32"/>
393 <member name="rooms_max" type="I32"/>
394 <member name="rooms_lim" type="I32"/>
395 <member name="games_cur" type="I32"/>
396 <member name="games_max" type="I32"/>
397 <member name="games_lim" type="I32"/>
398 <member name="results_cur" type="I32"/>
399 <member name="results_max" type="I32"/>
400 <member name="unknown2" type="I32"/>
401 <member name="params_cur" type="I32"/>
402 <member name="params_max" type="I32"/>
403 <member name="bytes_in" type="I64"/>
404 <member name="packets_in" type="I64"/>
405 <member name="bytes_out" type="I64"/>
406 <member name="packets_out" type="I64"/>)
407 </message>
408
409 <message type="0016" name="idle_warn" recv="yes">
410 idle warning, autologout soon (10 minutes...)
411 </message>
412
413 <message type="001b" name="timewarning_default" recv="yes">
414 WILD guess
415 <member name="channel" type="I16"/>
416 <member name="time" type="I16"/>
417 </message>
418
419 <message type="001c" name="idle_err" recv="yes">
420 autologout
421 </message>
422
423 <message type="001d" name="ping" recv="yes">
424 </message>
425
426 <message type="0021" name="userpic" recv="yes">
427 <member name="name" type="USERNAME"/>
428 Reply to pic_req, contains an image in jpeg format.
429 <member name="data" type="DATA"/>
430 </message>
431
432 <message type="0100" name="gnotice" recv="yes">
433 global notice, sent to everybody
434 <member name="notice" type="STRING"/>
435 </message>
436
437
438 <message type="0310" name="priv_room" recv="yes">
439 "permission denied" when joining a room
440 <member name="name" type="STRING"/>
441 </message>
442
443 <message type="0318" name="upd_rooms" recv="yes">
444 <member name="rooms" type="room" array="yes"/>
445 </message>
446
447 <message type="041c" name="upd_game2" recv="yes">
448 <member name="channel_junk" type="I16"/>
449 <member name="game" type="game"/>
450 </message>
451
452 <message type="0202" name="upd_user" recv="yes">
453 # loc 0" type="chat(?) loc 1 => gameinfo?, loc 2 => game result (more data)
454 <member name="location" type="I32"/>
455 <member name="user" type="user"/>
456 <member name="lotsofinfo" type="DATA" guard="location == 2"/>
457 </message>
458
459 <h3>Room messages</h3>
460
461 <p>Not all room messages are for rooms only, and rooms need to parse
462 not only these messages. Orthogonality, what for?</p>
463
464 <message type="4300" name="join_room" recv="yes">
465 <member name="channel" type="I16"/>
466 <member name="users" type="user" array="yes"/>
467 </message>
468
469 <message type="4301" name="msg_room" recv="yes">
470 <member name="channel" type="I16"/>
471 <member name="name" type="USERNAME"/>
472 <member name="message" type="STRING"/>
473 </message>
474
475 <message type="4302" name="part_room" recv="yes">
476 <member name="channel" type="I16"/>
477 <member name="user" type="user"/>
478 </message>
479
480 <message type="4303" name="del_room" recv="yes">
481 <member name="channel" type="I16"/>
482
483 </message>
484
485 <message type="4304" name="upd_games" recv="yes">
486 <member name="channel" type="I16"/>
487 <member name="games" type="game" array="yes"/>
488 </message>
489
490 <message type="4319" name="desc_room" recv="yes">
491 <member name="channel" type="I16"/>
492 <member name="owner" type="USERNAME"/>
493 <member name="description" type="STRING"/>
494 </message>
495
496
497 <message type="0411" name="chal_defaults" recv="yes">
498 <member name="channel" type="I16"/>
499 <member name="defaults" type="challenge_defaults"/>
500 </message>
501
502 <h3>Game messages</h3>
503
504 <message type="4400" name="upd_chal" recv="yes">
505 Unclear.
506 <member name="channel" type="I16"/>
507 <member name="challenge" type="challenge"/>
508 </message>
509
510 <message type="4401" name="upd_game" recv="yes">
511 <member name="channel" type="I16"/>
512 <member name="game" type="game"/>
513 </message>
514
515 <message type="4402" name="del_game" recv="yes">
516 <member name="channel" type="I16"/>
517 </message>
518
519 <message type="4403" name="upd_observers" recv="yes">
520 <member name="channel" type="I16"/>
521 <member name="users" type="user" array="yes"/>
522 </message>
523
524 <message type="4404" name="del_observer" recv="yes">
525 <member name="channel" type="I16"/>
526 <member name="name" type="USERNAME"/>
527 </message>
528
529 <message type="4405" name="set_tree" recv="yes">
530 <member name="channel" type="I16"/>
531 <member name="tree" type="TREE"/>
532 </message>
533
534 <message type="4406" name="upd_tree" recv="yes">
535 <member name="channel" type="I16"/>
536 <member name="tree" type="TREE"/>
537 </message>
538
539 <message type="4407" name="set_node" recv="yes">
540 <member name="channel" type="I16"/>
541 <member name="node" type="I32"/>
542 </message>
543
544 <message type="4409" name="superko" recv="yes">
545 Superko-warning.
546 <member name="channel" type="I16"/>
547 </message>
548
549 <message type="440b" name="final_result" recv="yes">
550 <member name="channel" type="I16"/>
551 <member name="blackscore" type="score"/>
552 <member name="whitescore" type="score"/>
553 </message>
554
555 <message type="440e" name="req_undo" recv="yes">
556 <member name="channel" type="I16"/>
557
558 </message>
559
560 <message type="4410" name="resign_game" recv="yes">
561 <member name="channel" type="I16"/>
562 <member name="player" type="I8"/>
563 </message>
564
565 <message type="441a" name="set_teacher" recv="yes">
566 <member name="channel" type="I16"/>
567 <member name="name" type="USERNAME"/>
568 </message>
569
570 <message type="441d" name="owner_left" recv="yes">
571 Unclear.
572 <member name="channel" type="I16"/>
573 </message>
574
575 <message type="441e" name="teacher_left" recv="yes">
576 Unclear.
577 <member name="channel" type="I16"/>
578 </message>
579
580 <message type="4422" name="unknown4422" recv="yes">
581 change teacher? something to do with editing?
582 <member name="channel" type="I16"/>
583 <member name="name1" type="USERNAME"/>
584 <member name="name2" type="USERNAME"/>
585 </message>
586
587 <message type="4433" name="req_result" recv="yes">
588 Unclear.
589 <member name="channel" type="I16"/>
590 # # recv_result(?)
591 </message>
592
593 <message type="4434" name="unknown4434" recv="yes">
594 <member name="channel" type="I16"/>
595 <member name="b1" type="I8"/>
596 ?? !demonstration game??
597 </message>
598
599 </body>
600 </html>
601