ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/cvsroot/kgsueme/doc/protocol.xml
Revision: 1.23
Committed: Fri Jul 18 21:40:41 2003 UTC (23 years, 3 months ago) by pcg
Content type: text/xml
Branch: MAIN
Changes since 1.22: +30 -4 lines
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 pcg 1.23 <h1>$Revision: 1.22 $</h1>
26 pcg 1.10
27 pcg 1.1 <h1>KGS Protocol Description</h1>
28    
29     <p>This XML document describes the KGS protocol. It is also used
30     to automatically generate the perl parser for all the messages and
31     structures in the protocol. Adapting it to other languages should be
32     trivial.</p>
33 pcg 1.10
34     <p><b>Please note that the author of KGS has told me that he will
35     change the protocol in response to my efforts. This does not
36     necessarily mean that he will change the protocol just to make it
37     difficult to reverse-engineer the protocol, but if this happens,
38     I might not have the resources the track them, if they are too
39     extensive. Anyway, he made it clear that no help whatsoever is to be
40     expected.</b></p>
41 pcg 1.1
42 pcg 1.4 <p>If you feel you need to update the visual appearance of this
43 pcg 1.11 document, feel free to look <tt>doc/doc2html.xsl</tt> and improve
44 pcg 1.4 it.</p>
45    
46 pcg 1.8 <p>The current version of this document can always be found at
47     <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/kgsueme/kgsueme/doc/protocol.xml?rev=HEAD&amp;content-type=text/xml">here</a>, while
48     the HTML version of it can be found
49     <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/kgsueme/kgsueme/doc/protocol.html?rev=HEAD&amp;content-type=text/html">here</a>.
50     </p>
51    
52 pcg 1.23 <h2>Changes for protocol version 2.5.0</h2>
53    
54     <p>Sorry - I have little time to dissect the protocol, but as far
55     as I can see, there was no deeper need for the protocol change, as
56     the protocol itself didn't change in a significant way. The only
57     significant change was the addition of a linear congruence generator
58     that is xor'ed into the packet length. This makes the protocol less
59     robust and doesn't help much, so the only big effect of that is to make
60     it more difficult to analyze the protocol. It seems that wms prefers
61     to lock out users than to have a few people write their own client. I
62     didn't really expect that from him, but instead expected real changes
63     for the good, as he is claiming all the time.</p>
64    
65     <p>Well, that's what he wrote to me, after all, so he just did what he
66     said...</p>
67    
68     <p>Anything I know about changes in 2.5.x are reflected in this
69     document already.</p>
70    
71 pcg 1.1 <h2>Structure and conventions of this document and the protocol</h2>
72    
73     <p>"Send" means messages send from the client to the server, while
74     "received" means messages send by the server to the client.</p>
75    
76 pcg 1.4 <p>Everything on the wire is in little-endian format (what a shame).</p>
77 pcg 1.1
78 pcg 1.4 <p>Primitive types are mostly integers (signed
79     "<code>I</code>&lt;bits&gt;", unsigned "<code>U</code>&lt;bits&gt;"),
80     ascii strings ("<code>username</code>"), or zero-terminated
81     UCS2-Strings ("<code>STRING</code>"). Yes, I know java is supposed to
82     do UTF-16, but no implementation seems to care...</p>
83 pcg 1.1
84 pcg 1.17 <p>For the rest, go figure or bug me, <a href="mailto:pcg@goof.com">Marc Lehmann &lt;pcg@goof.com&gt;</a></p>
85 pcg 1.1
86     <h2>Stream and message structure.</h2>
87    
88 pcg 1.4 <p>After connecting to the server, a handshake byte is sent. It's
89     the major version number of the protocol the client expects to
90     receive. Version 3 and 4 are mostly the same, except that Version 4
91     clients expect server messages to be compressed, version 3 clients
92     not.</p>
93    
94     <p>The server sends back his protocol number, which is always 3 in
95     the current protocol. Most of the protocol variation is determined by
96     the server using the client version that is used in the initial login
97     message, not the initial handshake byte.</p>
98 pcg 1.1
99     <p>After the initial handshake, the client sends uncompressed
100     messages, while the server sends back a zlib-compressed
101     stream (<a href="http://rfc1950.x42.com/">rfc1950</a> and <a
102     href="http://rfc1950.x42.com/">rfc1951</a>).</p>
103    
104     <p>All messages have the same header:</p>
105    
106 pcg 1.3 <struct name="message_header" send="yes" recv="yes">
107     <member name="_unknown" type="U16"/>
108     <member name="length" type="U16"/>
109 pcg 1.23
110 pcg 1.18 <p>The length is the length of the full message including the header.</p>
111 pcg 1.23
112     <p>Beginning with version 2.5.x, a number is xored into the low byte
113     of the length, as given by the following recurrence: <code>rand[0]
114     = 0; rand[i+1] = msg[i].length + (rand[i] * 0x04c2af9b + 0xfffffffb); xorbyte =
115     rand &gt;&gt; 24</code>, all in 32 bit unsigned iso-c arithmetic.</p>
116    
117 pcg 1.3 <member name="type" type="U16"/>
118 pcg 1.18 <p>If the type is &gt;= 0x4000 this is a message for a specific channel. The channel
119     number is always the next U16.</p>
120 pcg 1.3 </struct>
121    
122     <h2>Primitive types used in the protocol.</h2>
123    
124 pcg 1.9 <p>Apart from the basic types, I need to define some extra types to
125     deal with fixed-point values (based on integer types) or fixed-length
126     strings (either 7-bit-ascii or more limited (<code>A</code>), or UCS-2
127     based (<code>S</code>)).</p>
128 pcg 1.3
129 pcg 1.23 <type name="username" type="A" length="10"/>
130 pcg 1.9
131     <p>The basic user or login name, used throughout the protocol
132     as a handle to the user.</p>
133    
134 pcg 1.3 <type name="roomname" type="S" length="25"/><!-- argh, how horribly broken -->
135 pcg 1.9
136     <p>Many strings in the protocol are fixed-width for no good reason
137 pcg 1.18 (maybe this is one reason for using compression in newer versions, as
138 pcg 1.9 the packets itself are wasting lots of space.</p>
139    
140 pcg 1.16 <type name="realname" type="S" length="50"/>
141     <type name="email" type="S" length="70"/>
142     <type name="userinfo" type="S" length="1000"/>
143     <type name="url" type="A" length="100"/>
144    
145     <p>Used in user_record.</p>
146    
147 pcg 1.3 <type name="locale" type="A" length="5"/>
148 pcg 1.9
149     <p>A kind of locale specifier. It seems the general format seems to be
150     lowercase language, underscore, uppercase location, e.g. en_US. More
151     fancy specifications don't fit.</p>
152    
153 pcg 1.3 <type name="flag" type="U8" multiplier="1"/>
154 pcg 1.9
155     <p>Just a simple boolean value. 0 means false, and 1 generally true,
156     but I suggest ccepting != 0 as true.</p>
157    
158 pcg 1.6 <type name="komi16" type="I16" multiplier="2"/>
159     <type name="komi32" type="I32" multiplier="2"/>
160 pcg 1.20 <type name="komi324" type="I32" multiplier="4"/>
161 pcg 1.9
162     <p>Komi values are multiplied by 2 to make them integer in the
163 pcg 1.20 protocol. Well, *most* of the time at least...</p>
164 pcg 1.9
165 pcg 1.3 <type name="result" type="I32" multiplier="2"/>
166 pcg 1.9
167 pcg 1.15 <p>The game result is also multiplied by two to give it higher
168     resolution. There are also special values for wins by time etc., either
169     in result or in the score* types, or both :)</p>
170 pcg 1.9
171 pcg 1.13 <type name="score16" type="I16" multiplier="4"/>
172     <type name="score32" type="I32" multiplier="4"/>
173 pcg 1.9
174     <p>A score value (used for displaying the score at the end of a game)
175 pcg 1.15 are multiplied by four for a change (the 0.25 resolution is not
176     used). In game structures it is encoded by dividing by two, though, so
177     watch out!</p>
178 pcg 1.9
179 pcg 1.7 <type name="time" type="U32" multiplier="1000"/>
180 pcg 1.1
181 pcg 1.9 <p>Time values are multiplied by 1000, giving them millisecond
182     accuracy.</p>
183    
184 pcg 1.16 <type name="timestamp" type="U64" multiplier="1000"/>
185    
186     <p>64 bit timeval, milliseconds since posix epoch, e.g. <code>my
187     ($year, $month, $day) = (gmtime $date * 0.001)[5,4,3];</code></p>
188    
189 pcg 1.17 <type name="password" type="U64"/>
190    
191     <p>Password is a number calculated as follows (VERY insecure, basically
192     plaintext!): <code>password = 0; for char in characters do password ←
193     password * 1055 + ascii_code (char)</code></p>
194    
195 pcg 1.2 <h2>Constants, enumeration and set types used in the protocol.</h2>
196 pcg 1.1
197     <p>Baaah... not yet.</p>
198    
199 pcg 1.3 <h2>Structs used in send &amp; receive messages</h2>
200 pcg 1.1
201 pcg 1.3 <struct name="user" class="KGS::User">
202 pcg 1.9
203 pcg 1.18 <p>Everywhere a user + flags is required, even used in some places
204 pcg 1.9 where only a username is required. I see no general rule on when a
205 pcg 1.18 complete user and when a partial user is required.</p>
206 pcg 1.9
207 pcg 1.3 <member name="name" type="username"/>
208     <member name="flags" type="U32" default="1"/>
209     </struct>
210 pcg 1.1
211 pcg 1.6 <struct name="rules" class="KGS::Rules">
212 pcg 1.9
213 pcg 1.18 <p>This structure is used for challanges as well as in the special
214     TREE "subprotocol". It tightly encodes the game parameters.</p>
215 pcg 1.9
216 pcg 1.6 <member name="ruleset" type="U8"/>
217     <member name="size" type="U8"/>
218     <member name="handicap" type="U8"/>
219     <member name="komi" type="komi16"/>
220     <member name="timesys" type="U8"/>
221     <member name="time" type="U32"/>
222     <member name="interval" type="U32"/>
223     byo-yomi time / canadian time
224     <member name="count" type="U16"/>
225     periods / moves
226     </struct>
227    
228 pcg 1.3 <h2>Structs used in send messages</h2>
229 pcg 1.1
230 pcg 1.18 <h2>Send messages</h2>
231    
232 pcg 1.1 <message type="0000" name="login" send="yes">
233 pcg 1.9
234 pcg 1.18 <p>Sent to login, usually the first message sent. The password needs to be set when the
235 pcg 1.9 guest flag is true.
236 pcg 1.18 Possible replies: <ref reply="login"/>. Followed by: <ref reply="timewarning_default"/> <ref reply="chal_defaults"/>
237     </p>
238 pcg 1.9
239 pcg 1.3 <member name="ver_major" type="U32" default="2"/>
240 pcg 1.23 <member name="ver_minor" type="U32" default="5"/>
241     <member name="ver_micro" type="U32" default="1"/>
242 pcg 1.3 <member name="name" type="username"/>
243 pcg 1.17 <member name="password" type="password" default="0"/>
244 pcg 1.3 <member name="guest" type="flag" default="1"/>
245     <member name="_unknown3" type="U16" default="0"/>
246     <member name="locale" type="locale" default='"en_US"'/>
247     <member name="clientver" type="DATA" default='"1.4.1_01:Swing app:Sun Microsystems Inc."'/>
248 pcg 1.4 The "default" is the java vm version, not exactly he client version. However,
249 pcg 1.18 you should always send a text like "Jonathan's C client bersion 0.6" or somesuch,
250 pcg 1.4 so the server can, if necessary, block broken clients or client versions.
251 pcg 1.1 </message>
252    
253 pcg 1.17 <message type="0007" name="req_userinfo" send="yes">
254 pcg 1.18 <p>Request info about a certain user. Possible reply: <ref reply="userinfo"/></p>
255 pcg 1.17 <member name="name" type="username"/>
256     </message>
257    
258 pcg 1.18 <message type="0007" name="update_userinfo" send="yes">
259     <p>Update user info. Message structure is very similar
260     to <ref ref="userinfo"/>.</p>
261 pcg 1.17 <member name="setpass" type="flag"/>
262     Should the password be updated?
263     <member name="password" type="password" default="0"/>
264     <member name="realname" type="realname"/>
265     <member name="email" type="email"/>
266     <member name="info" type="userinfo"/>
267     <member name="homepage" type="url"/>
268     <member name="_unused" type="U64" default="0"/>
269     <member name="_unused" type="U64" default="0"/>
270     </message>
271    
272 pcg 1.18 <message type="0014" name="req_stats" send="yes">
273     <p>Request server statistics. Replied with <ref reply="stats"/></p>
274 pcg 1.19 </message>
275    
276 pcg 1.21 <message type="001d" name="ping" send="yes">
277 pcg 1.19 <p>Wild guess, I send it in <ref ref="idle_warn"/>.</p>
278 pcg 1.1 </message>
279    
280 pcg 1.17 <message type="001e" name="req_usergraph" send="yes">
281 pcg 1.18 <p>Request user graph data, replied with <ref reply="usergraph"/>.</p>
282 pcg 1.17 <member name="name" type="username"/>
283     </message>
284    
285     <message type="001f" name="fetch_memos" send="yes">
286 pcg 1.18 <p>Unclear. Fetch all outstanding memos? Replied with <ref reply="memo"/></p>
287 pcg 1.17 </message>
288    
289     <message type="0021" name="req_pic" send="yes">
290 pcg 1.18 <p>Request a user picture from the server. Results in a <ref reply="userpic"/>
291     or a timeout.</p>
292 pcg 1.3 <member name="name" type="username"/>
293 pcg 1.1 </message>
294    
295 pcg 1.17 <message type="0021" name="upload_pic" send="yes">
296 pcg 1.1 Same code as pic_req, but with an additional data section that
297 pcg 1.4 must contain a JPEG image that is &lt;=7KB. It must have 141×200 pixels.
298 pcg 1.3 <member name="name" type="username"/>
299 pcg 1.1 <member name="data" type="DATA"/>
300     </message>
301    
302 pcg 1.2 <message type="0100" name="gnotice" send="yes">
303 pcg 1.18 <p>Send a global message. Maybe. Never tried, for obvious reasons :/. Results
304     in a <ref reply="gnotice"/> sent to all users.</p>
305 pcg 1.1 <member name="notice" type="STRING"/>
306     </message>
307    
308 pcg 1.2 <message type="0318" name="list_rooms" send="yes">
309 pcg 1.18 <p>List the rooms in a specific group/category. Results in a <ref reply="upd_rooms"/> message.</p>
310 pcg 1.3 <member name="group" type="U8"/>
311 pcg 1.1 </message>
312    
313 pcg 1.2 <message type="031a" name="new_room" send="yes">
314 pcg 1.1 Create a new room. Not verified.
315 pcg 1.3 <member name="name" type="username"/>
316     <member name="i1" type="U32" default="0"/>
317     <member name="b1" type="U8" default="0"/>
318     <member name="b2" type="U8" default="255"/>
319     <member name="b3" type="U8" default="255"/>
320     <member name="group" type="U8" default="1"/>
321 pcg 1.1 <member name="name" type="STRING"/>
322     <member name="description" type="STRING"/>
323 pcg 1.3 <member name="flags" type="U8"/>
324 pcg 1.1 0x10 .. private room etc.. see code
325     </message>
326    
327 pcg 1.17 <message type="0413" name="req_game_record" send="yes">
328 pcg 1.18 <p>Requests part of the users game record to be sent. Results in a <ref reply="game_record"/> or maybe a timeout.</p>
329 pcg 1.16 <member name="name" type="username"/>
330     <member name="timestamp" type="timestamp"/>
331     If zero, start at the newest games, else only send games
332     before the given timestap.
333     </message>
334    
335 pcg 1.1 <message type="4300" name="join_room" send="yes">
336 pcg 1.18 <p>Joins the given room. <ref reply="join_room"/> messages for yourself
337 pcg 1.9 and all users in that room, as well as the initial gamelist, are
338 pcg 1.18 send if the room exists. If not, timeout...</p>
339 pcg 1.3 <member name="channel" type="U16"/>
340 pcg 1.1 <member name="user" type="user"/>
341     </message>
342    
343     <message type="4301" name="msg_room" send="yes">
344 pcg 1.9 Send a message to the room.
345 pcg 1.3 <member name="channel" type="U16"/>
346     <member name="name" type="username"/>
347 pcg 1.9 Must be the login-name of the user.
348 pcg 1.1 <member name="message" type="STRING"/>
349     </message>
350    
351     <message type="4302" name="part_room" send="yes">
352 pcg 1.9 Remove yourself (or maybe others as admin) from a room.
353 pcg 1.3 <member name="channel" type="U16"/>
354     <member name="name" type="username"/>
355 pcg 1.1 </message>
356    
357     <message type="4305" name="new_game" send="yes">
358 pcg 1.17 Unclear. Start a new game.
359 pcg 1.3 <member name="channel" type="U16"/>
360     <member name="id" type="U16"/>
361     <member name="gametype" type="U32"/>
362 pcg 1.1 <member name="rules" type="rules"/>
363     <member name="notes" type="STRING"/>
364     </message>
365    
366     <message type="430b" name="req_games" send="yes">
367 pcg 1.9 Request to update room game list (send this once per minute to get
368     updated). Results in upd_games messages.
369 pcg 1.3 <member name="channel" type="U16"/>
370 pcg 1.1 </message>
371    
372     <message type="4319" name="req_desc" send="yes">
373     Request room description.
374 pcg 1.3 <member name="channel" type="U16"/>
375 pcg 1.1 </message>
376    
377     <message type="4400" name="send_chal" send="yes">
378 pcg 1.9 Unclear.
379 pcg 1.3 <member name="channel" type="U16"/>
380     <member name="black" type="username"/>
381     <member name="white" type="username"/>
382 pcg 1.1 More following... TREE or challenge.
383     </message>
384    
385     <message type="4403" name="join_game" send="yes">
386 pcg 1.9 Join a game. See join_room.
387 pcg 1.5 <member name="channel" type="U16"/>
388 pcg 1.1 <member name="user" type="user"/>
389     </message>
390    
391     <message type="4404" name="part_game" send="yes">
392 pcg 1.9 Leave (or kick as admin?) a certain user from a game.
393 pcg 1.3 <member name="channel" type="U16"/>
394     <member name="name" type="username"/>
395 pcg 1.1 </message>
396    
397     <message type="4405" name="set_tree" send="yes">
398 pcg 1.9 Upload a partial game tree to the server. This is used
399     to send moves and even in-game comments to the server. For the comments,
400     the server prepends the username and rank.
401 pcg 1.3 <member name="channel" type="U16"/>
402 pcg 1.1 <member name="tree" type="TREE"/>
403     </message>
404    
405     <message type="4408" name="get_tree" send="yes">
406 pcg 1.9 Request the game tree starting at a given node. This is used
407     when the server only sends a partial tree (with end code "more").
408 pcg 1.3 <member name="channel" type="U16"/>
409     <member name="node" type="U32"/>
410 pcg 1.1 </message>
411    
412     <message type="440c" name="claim_win" send="yes">
413 pcg 1.9 Unclear.
414 pcg 1.3 <member name="channel" type="U16"/>
415     <member name="_byte" type="U8 "/>
416 pcg 1.1 Player colour maybe? Unclear.
417     </message>
418    
419     <message type="440d" name="add_time" send="yes">
420 pcg 1.9 Not checked.
421    
422 pcg 1.3 <member name="channel" type="U16"/>
423     <member name="time" type="U32"/>
424     <member name="player" type="U8"/>
425 pcg 1.1 </message>
426    
427     <message type="440f" name="grant_undo" send="yes">
428 pcg 1.9 Can be send after a req_undo message was received to grant the undo.
429 pcg 1.3 <member name="channel" type="U16"/>
430 pcg 1.1 </message>
431    
432     <message type="4410" name="resign_game" send="yes">
433 pcg 1.9 Resign the game.
434 pcg 1.3 <member name="channel" type="U16"/>
435     <member name="player" type="U8"/>
436 pcg 1.1 </message>
437    
438     <message type="441a" name="set_teacher" send="yes">
439 pcg 1.9 Change the teacher to somebody else (or possibly yourself == take it).
440 pcg 1.3 <member name="channel" type="U16"/>
441     <member name="name" type="username"/>
442 pcg 1.1 </message>
443    
444     <message type="4422" name="add_user" send="yes">
445 pcg 1.9 Unclear. Maybe allow users to talk? No idea, really.
446    
447 pcg 1.3 <member name="channel" type="U16"/>
448     <member name="othername" type="username"/>
449     <member name="name" type="username"/>; # gives user access to the game (to what? ;)
450 pcg 1.1 </message>
451    
452     <message type="4423" name="set_privacy" send="yes">
453 pcg 1.9 Probably sets the "quiet" flag. Not checked.
454 pcg 1.3 <member name="channel" type="U16"/>
455     <member name="private" type="U8"/>
456 pcg 1.1 </message>
457    
458     <message type="4429" name="reject_chal" send="yes">
459 pcg 1.9 Reject a challenge from a given user. Not checked.
460    
461 pcg 1.3 <member name="channel" type="U16"/>
462     <member name="name" type="username"/>
463 pcg 1.1 </message>
464    
465     <message type="4433" name="req_result" send="yes">
466 pcg 1.9 I forgot.
467    
468 pcg 1.3 <member name="channel" type="U16"/>
469 pcg 1.1 </message>
470    
471 pcg 1.3 <h2>Structs mainly used in receive messages</h2>
472 pcg 1.1
473 pcg 1.3 <struct name="challenge_defaults">
474 pcg 1.9 Send soon after log-in to set the defaults for game challenges.
475 pcg 1.3 <member name="gametype" type="U32"/>
476     <member name="size" type="U32"/>
477     <member name="timesys" type="U32"/>
478     <member name="time" type="U32"/>
479     <member name="byo_time" type="U32"/>
480     <member name="byo_periods" type="U32"/>
481     <member name="can_time" type="U32"/>
482     <member name="can_stones" type="U32"/>
483     </struct>
484    
485     <struct name="challenge" class="KGS::Challenge">
486 pcg 1.9 A challenge.
487    
488 pcg 1.1 <member name="user1" type="user"/>
489     <member name="user2" type="user"/>
490 pcg 1.3 <member name="gametype" type="U32"/>
491 pcg 1.1 <member name="rules" type="rules"/>
492     Maybe the rules" are in TREE format. I forgot.
493 pcg 1.3 </struct>
494 pcg 1.1
495 pcg 1.3 <struct name="game" class="KGS::Game">
496 pcg 1.9 Basic information about a game. Used in rooms for the gamelist and
497     in games to detect when a game is saved, changed type (e.g. R => D)
498     etc.
499    
500 pcg 1.3 <member name="channel" type="U16"/>
501     <member name="type" type="U32"/>
502 pcg 1.1 <member name="user1" type="user"/>
503     White
504     <member name="user2" type="user"/>
505     Black
506     <member name="user3" type="user"/>
507     Owner
508 pcg 1.3 <member name="size" type="U32"/>
509 pcg 1.1 <member name="handicap" type="I32"/>
510     &lt; 0 not fully setup
511 pcg 1.6 <member name="komi" type="komi32"/>
512 pcg 1.15 <member name="moves" type="I16"/>
513 pcg 1.14 This field reflects either the movenum or the score, sorry, not even guards help, as
514 pcg 1.15 the flags to determine that are _after_ the field. Arg. Divide by two to get the actual
515     score (NOT score16!).
516 pcg 1.3 <member name="flags" type="U16"/>
517     <member name="observers" type="U32"/>
518     <member name="saved" type="flag"/>
519     <member name="notes" type="STRING" guard-member="handicap" guard-cond="&lt; 0"/>
520     </struct>
521    
522     <struct name="room_obs">
523 pcg 1.9 Obsolete.
524    
525 pcg 1.3 <member name="name" type="roomname"/>
526     <member name="channel" type="U16"/>
527     <member name="flags" type="U32"/>
528 pcg 1.4 <member name="users" type="U32"/>
529 pcg 1.3 </struct>
530    
531     <struct name="room" class="KGS::Room">
532     <member name="channel" type="U16"/>
533     <member name="flags" type="U8"/>
534     <member name="group" type="U8"/>
535     <member name="users" type="U16"/>
536     <member name="games" type="U16"/>
537 pcg 1.4 <member name="name" type="STRING"/>
538 pcg 1.3 </struct>
539 pcg 1.1
540 pcg 1.12 <struct name="scorevalues" class="KGS::Score">
541 pcg 1.13 <member name="score" type="score32"/>
542 pcg 1.3 <member name="territory" type="U32"/>
543     <member name="captures" type="U32"/>
544     <member name="i3" type="U32"/>
545     <member name="f2" type="U32"/>
546 pcg 1.20 <member name="komi" type="komi324"/>
547 pcg 1.4 <member name="i4" type="U32"/>
548 pcg 1.3 Apparently the i3, f2, i4 are zero.
549     </struct>
550 pcg 1.1
551 pcg 1.16 <struct name="game_record" class="KGS::GameRecord">
552 pcg 1.18 <p>A single game record entry, as seen in <ref ref="userinfo"/>.</p>
553 pcg 1.16
554     <member name="timestamp" type="timestamp"/>
555     Time this game was played.
556     <member name="flags" type="U8"/>
557     High four bits are handicap, low four bits are gametype (encoded strangely? unclear).
558     <member name="user1" type="user"/>
559     White, flags contain low 8 bits of revision (bits 16-23).
560     <member name="user2" type="user"/>
561     Black, flags contain high 8 bits of revision (bits 16-23).
562     <member name="user3" type="user"/>
563     Owner (or empty)
564     <member name="komi" type="komi16"/>
565     <member name="score" type="score16"/>
566     <member name="status" type="U8"/>
567     0x80 inprogress
568     </struct>
569    
570 pcg 1.1 <h2>Receive messages</h2>
571    
572     <message type="0001" name="login" recv="yes">
573 pcg 1.3 <member name="result" type="CONSTANT" default='"login ok"'/>
574 pcg 1.1 <member name="success" type="CONSTANT" default="1"/>
575     </message>
576    
577     <message type="0002" name="login" recv="yes">
578 pcg 1.3 <member name="result" type="CONSTANT" default='"guest login ok"'/>
579 pcg 1.1 <member name="success" type="CONSTANT" default="1"/>
580     </message>
581    
582     <message type="0003" name="login" recv="yes">
583 pcg 1.3 <member name="result" type="CONSTANT" default='"login error 3"'/>
584 pcg 1.1 ** maybe more following? **
585     </message>
586    
587     <message type="0004" name="login" recv="yes">
588 pcg 1.3 <member name="result" type="CONSTANT" default='"wrong password"'/>
589 pcg 1.1 ** maybe more following? **
590     </message>
591    
592     <message type="0005" name="login" recv="yes">
593 pcg 1.3 <member name="result" type="CONSTANT" default='"user unknown"'/>
594 pcg 1.1 ** maybe more following? **
595     </message>
596    
597     <message type="0006" name="login" recv="yes">
598 pcg 1.3 <member name="result" type="CONSTANT" default='"user exists"'/>
599 pcg 1.1 ** maybe more following? **
600     </message>
601    
602 pcg 1.17 <message type="0008" name="userinfo" recv="yes">
603     User info.
604 pcg 1.16 <member name="user" type="user"/>
605 pcg 1.17 <member name="_unused" type="U64"/>
606 pcg 1.16 <member name="realname" type="realname"/>
607     <member name="email" type="email"/>
608     <member name="info" type="userinfo"/>
609     <member name="homepage" type="url"/>
610     <member name="regdate" type="timestamp"/>
611     When the user registered (0 == never registered).
612     <member name="lastlogin" type="timestamp"/>
613     When the user logged in for the last time.
614     <!-- maybe more? -->
615     </message>
616    
617 pcg 1.1 <message type="0018" name="login" recv="yes">
618 pcg 1.3 <member name="result" type="CONSTANT" default='"login error 18"'/>
619 pcg 1.1 ** maybe more following? **
620     </message>
621    
622     <message type="0022" name="login" recv="yes">
623 pcg 1.22 I was blocked sooo many times for developing this client that it was
624     easy to figure out. The KGS admins sure need no extra nazi training
625     :(
626     <member name="reason" type="STRING"/>
627 pcg 1.3 <member name="result" type="CONSTANT" default='"user or ip blocked"'/>
628 pcg 1.1 </message>
629    
630     <message type="0013" name="msg_chat" recv="yes">
631 pcg 1.3 <member name="user1" type="username"/>
632     <member name="user2" type="username"/>
633 pcg 1.1 <member name="message" type="STRING"/>
634     </message>
635    
636     <message type="0015" name="stats" recv="yes">
637 pcg 1.3 <member name="ver_major" type="U16"/>
638     <member name="ver_minor" type="U16"/>
639     <member name="ver_micro" type="U16"/>
640 pcg 1.16 <member name="boot_time" type="timestamp"/>
641 pcg 1.3 <member name="users_cur" type="U32"/>
642     <member name="users_max" type="U32"/>
643     <member name="users_lim" type="U32"/>
644     <member name="accts_cur" type="U32"/>
645     <member name="accts_max" type="U32"/>
646     <member name="unknown1" type="U32"/>
647     <member name="work_max" type="U32"/>
648     <member name="rooms_cur" type="U32"/>
649     <member name="rooms_max" type="U32"/>
650     <member name="rooms_lim" type="U32"/>
651     <member name="games_cur" type="U32"/>
652     <member name="games_max" type="U32"/>
653     <member name="games_lim" type="U32"/>
654     <member name="results_cur" type="U32"/>
655     <member name="results_max" type="U32"/>
656     <member name="unknown2" type="U32"/>
657     <member name="params_cur" type="U32"/>
658     <member name="params_max" type="U32"/>
659     <member name="bytes_in" type="U64"/>
660     <member name="packets_in" type="U64"/>
661     <member name="bytes_out" type="U64"/>
662 pcg 1.4 <member name="packets_out" type="U64"/>
663 pcg 1.1 </message>
664    
665     <message type="0016" name="idle_warn" recv="yes">
666     idle warning, autologout soon (10 minutes...)
667     </message>
668    
669     <message type="001b" name="timewarning_default" recv="yes">
670     WILD guess
671 pcg 1.3 <member name="channel" type="U16"/>
672     <member name="time" type="U16"/>
673 pcg 1.1 </message>
674    
675     <message type="001c" name="idle_err" recv="yes">
676     autologout
677     </message>
678    
679     <message type="001d" name="ping" recv="yes">
680 pcg 1.16 Sent by the server regularly, but not answering them
681     isn't valid. Strange form of keepalive?
682 pcg 1.1 </message>
683    
684 pcg 1.17 <message type="001e" name="usergraph" recv="yes">
685     User graph data.
686     <member name="data" type="I16" array="yes"/>
687     If empty, no graph is available. The unit seems to
688     be centi-kyu, with 1 dan == 0, 2 dan == 100, 1 kyu == -100.
689     There is probably one entry per day, the newest one last.
690     </message>
691    
692     <message type="001f" name="memo" recv="yes">
693     Unclear. "Leave Message"?
694     6 strings following.
695     <member name="s1" type="STRING"/>
696     <member name="s2" type="STRING"/>
697     <member name="s3" type="STRING"/>
698     <member name="s4" type="STRING"/>
699     <member name="s5" type="STRING"/>
700     <member name="s6" type="STRING"/>
701     </message>
702    
703 pcg 1.1 <message type="0021" name="userpic" recv="yes">
704 pcg 1.3 <member name="name" type="username"/>
705 pcg 1.1 Reply to pic_req, contains an image in jpeg format.
706     <member name="data" type="DATA"/>
707     </message>
708    
709     <message type="0100" name="gnotice" recv="yes">
710     global notice, sent to everybody
711     <member name="notice" type="STRING"/>
712     </message>
713    
714 pcg 1.16 <message type="0202" name="upd_user" recv="yes">
715 pcg 1.17 # maybe soe notify? Totally unclear.
716 pcg 1.16 # loc 0" type="chat(?) loc 1 => gameinfo?, loc 2 => game result (more data)
717     <member name="location" type="U32"/>
718     <member name="user" type="user"/>
719     <member name="lotsofinfo" type="DATA" guard-member="location" guard-cond="== 2"/>
720     </message>
721 pcg 1.1
722     <message type="0310" name="priv_room" recv="yes">
723     "permission denied" when joining a room
724     <member name="name" type="STRING"/>
725     </message>
726    
727     <message type="0318" name="upd_rooms" recv="yes">
728     <member name="rooms" type="room" array="yes"/>
729     </message>
730    
731 pcg 1.16 <message type="0411" name="chal_defaults" recv="yes">
732     <member name="channel" type="U16"/>
733     <member name="defaults" type="challenge_defaults"/>
734     </message>
735    
736 pcg 1.17 <message type="0412" name="rej_game" send="yes">
737     Unable to create challenge. The channel might be optional.
738     <member name="channel" type="U16"/>
739     </message>
740    
741 pcg 1.16 <message type="0414" name="game_record" recv="yes">
742     The users game record.
743     <member name="name" type="username"/>
744     <member name="more" type="flag"/>
745     Wether more games are available (must be requested manually)
746     <member name="games" type="game_record" array="yes"/>
747     </message>
748    
749 pcg 1.1 <message type="041c" name="upd_game2" recv="yes">
750 pcg 1.17 Unclear.
751 pcg 1.3 <member name="channel_junk" type="U16"/>
752 pcg 1.1 <member name="game" type="game"/>
753     </message>
754    
755     <h3>Room messages</h3>
756    
757     <p>Not all room messages are for rooms only, and rooms need to parse
758     not only these messages. Orthogonality, what for?</p>
759    
760     <message type="4300" name="join_room" recv="yes">
761 pcg 1.3 <member name="channel" type="U16"/>
762 pcg 1.1 <member name="users" type="user" array="yes"/>
763     </message>
764    
765     <message type="4301" name="msg_room" recv="yes">
766 pcg 1.3 <member name="channel" type="U16"/>
767     <member name="name" type="username"/>
768 pcg 1.1 <member name="message" type="STRING"/>
769     </message>
770    
771     <message type="4302" name="part_room" recv="yes">
772 pcg 1.3 <member name="channel" type="U16"/>
773 pcg 1.1 <member name="user" type="user"/>
774     </message>
775    
776     <message type="4303" name="del_room" recv="yes">
777 pcg 1.3 <member name="channel" type="U16"/>
778 pcg 1.1 </message>
779    
780     <message type="4304" name="upd_games" recv="yes">
781 pcg 1.3 <member name="channel" type="U16"/>
782 pcg 1.1 <member name="games" type="game" array="yes"/>
783     </message>
784    
785     <message type="4319" name="desc_room" recv="yes">
786 pcg 1.3 <member name="channel" type="U16"/>
787     <member name="owner" type="username"/>
788 pcg 1.1 <member name="description" type="STRING"/>
789     </message>
790    
791     <h3>Game messages</h3>
792    
793     <message type="4400" name="upd_chal" recv="yes">
794     Unclear.
795 pcg 1.3 <member name="channel" type="U16"/>
796 pcg 1.1 <member name="challenge" type="challenge"/>
797     </message>
798    
799     <message type="4401" name="upd_game" recv="yes">
800 pcg 1.3 <member name="channel" type="U16"/>
801 pcg 1.1 <member name="game" type="game"/>
802     </message>
803    
804     <message type="4402" name="del_game" recv="yes">
805 pcg 1.3 <member name="channel" type="U16"/>
806 pcg 1.1 </message>
807    
808     <message type="4403" name="upd_observers" recv="yes">
809 pcg 1.3 <member name="channel" type="U16"/>
810 pcg 1.1 <member name="users" type="user" array="yes"/>
811     </message>
812    
813     <message type="4404" name="del_observer" recv="yes">
814 pcg 1.3 <member name="channel" type="U16"/>
815     <member name="name" type="username"/>
816 pcg 1.1 </message>
817    
818     <message type="4405" name="set_tree" recv="yes">
819 pcg 1.3 <member name="channel" type="U16"/>
820 pcg 1.1 <member name="tree" type="TREE"/>
821     </message>
822    
823     <message type="4406" name="upd_tree" recv="yes">
824 pcg 1.3 <member name="channel" type="U16"/>
825 pcg 1.1 <member name="tree" type="TREE"/>
826     </message>
827    
828     <message type="4407" name="set_node" recv="yes">
829 pcg 1.3 <member name="channel" type="U16"/>
830     <member name="node" type="U32"/>
831 pcg 1.1 </message>
832    
833     <message type="4409" name="superko" recv="yes">
834     Superko-warning.
835 pcg 1.3 <member name="channel" type="U16"/>
836 pcg 1.1 </message>
837    
838     <message type="440b" name="final_result" recv="yes">
839 pcg 1.3 <member name="channel" type="U16"/>
840 pcg 1.12 <member name="blackscore" type="scorevalues"/>
841     <member name="whitescore" type="scorevalues"/>
842 pcg 1.1 </message>
843    
844     <message type="440e" name="req_undo" recv="yes">
845 pcg 1.3 <member name="channel" type="U16"/>
846 pcg 1.1
847     </message>
848    
849     <message type="4410" name="resign_game" recv="yes">
850 pcg 1.3 <member name="channel" type="U16"/>
851     <member name="player" type="U8"/>
852 pcg 1.1 </message>
853    
854     <message type="441a" name="set_teacher" recv="yes">
855 pcg 1.3 <member name="channel" type="U16"/>
856     <member name="name" type="username"/>
857 pcg 1.1 </message>
858    
859     <message type="441d" name="owner_left" recv="yes">
860     Unclear.
861 pcg 1.3 <member name="channel" type="U16"/>
862 pcg 1.1 </message>
863    
864     <message type="441e" name="teacher_left" recv="yes">
865     Unclear.
866 pcg 1.3 <member name="channel" type="U16"/>
867 pcg 1.1 </message>
868    
869     <message type="4422" name="unknown4422" recv="yes">
870     change teacher? something to do with editing?
871 pcg 1.3 <member name="channel" type="U16"/>
872     <member name="name1" type="username"/>
873     <member name="name2" type="username"/>
874 pcg 1.1 </message>
875    
876     <message type="4433" name="req_result" recv="yes">
877     Unclear.
878 pcg 1.3 <member name="channel" type="U16"/>
879 pcg 1.1 # # recv_result(?)
880     </message>
881    
882     <message type="4434" name="unknown4434" recv="yes">
883 pcg 1.3 <member name="channel" type="U16"/>
884     <member name="b1" type="U8"/>
885 pcg 1.1 ?? !demonstration game??
886     </message>
887    
888     </body>
889     </html>
890