ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/cvsroot/kgsueme/doc/protocol.xml
Revision: 1.35
Committed: Fri Jul 25 19:39:16 2003 UTC (23 years, 3 months ago) by pcg
Content type: text/xml
Branch: MAIN
Changes since 1.34: +13 -1 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.35 <h1>$Revision: 1.34 $</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 pcg 1.33 almost trivial.</p>
33 pcg 1.10
34     <p><b>Please note that the author of KGS has told me that he will
35 pcg 1.32 change the protocol in response to my efforts. No problems with
36     changing the protocol for good, but he does this just to make it
37     more difficult to reverse-engineer it, since his changes are neither
38     required, nor useful (they just make the protocol less robust, without
39     adding added value). He doesn't even care that this locks out some
40     users who cannot upgrade (cgoban2 isn't available for their platform
41     anymore). It hurts to see such a waste of time and efforts that could have been used
42     to fix bugs or improve the client...</b></p>
43 pcg 1.1
44 pcg 1.4 <p>If you feel you need to update the visual appearance of this
45 pcg 1.11 document, feel free to look <tt>doc/doc2html.xsl</tt> and improve
46 pcg 1.4 it.</p>
47    
48 pcg 1.8 <p>The current version of this document can always be found at
49     <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
50     the HTML version of it can be found
51     <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>.
52 pcg 1.32 (update: sourceforge is weeks behind on their anonymous cvs servers so the above might be out-of-date. sorry.)</p>
53 pcg 1.23
54 pcg 1.1 <h2>Structure and conventions of this document and the protocol</h2>
55    
56 pcg 1.32 <p>"ORIGIN: CLIENT" means messages send from the client to the server,
57     while "ORIGIN: SERVER" means messages send by the server to the
58     client.</p>
59 pcg 1.1
60 pcg 1.4 <p>Everything on the wire is in little-endian format (what a shame).</p>
61 pcg 1.1
62 pcg 1.4 <p>Primitive types are mostly integers (signed
63     "<code>I</code>&lt;bits&gt;", unsigned "<code>U</code>&lt;bits&gt;"),
64     ascii strings ("<code>username</code>"), or zero-terminated
65     UCS2-Strings ("<code>STRING</code>"). Yes, I know java is supposed to
66     do UTF-16, but no implementation seems to care...</p>
67 pcg 1.1
68 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>
69 pcg 1.1
70     <h2>Stream and message structure.</h2>
71    
72 pcg 1.4 <p>After connecting to the server, a handshake byte is sent. It's
73     the major version number of the protocol the client expects to
74     receive. Version 3 and 4 are mostly the same, except that Version 4
75     clients expect server messages to be compressed, version 3 clients
76     not.</p>
77    
78     <p>The server sends back his protocol number, which is always 3 in
79     the current protocol. Most of the protocol variation is determined by
80     the server using the client version that is used in the initial login
81     message, not the initial handshake byte.</p>
82 pcg 1.1
83     <p>After the initial handshake, the client sends uncompressed
84     messages, while the server sends back a zlib-compressed
85     stream (<a href="http://rfc1950.x42.com/">rfc1950</a> and <a
86     href="http://rfc1950.x42.com/">rfc1951</a>).</p>
87    
88     <p>All messages have the same header:</p>
89    
90 pcg 1.28 <struct name="message_header">
91 pcg 1.3 <member name="_unknown" type="U16"/>
92     <member name="length" type="U16"/>
93 pcg 1.23
94 pcg 1.18 <p>The length is the length of the full message including the header.</p>
95 pcg 1.23
96 pcg 1.24 <p>Beginning with version 2.5.x, a number is xored into the low
97     byte of the length in <em>sent</em> packages only, as given by the
98     following recurrence: <code>rand[0] = 0; rand[i+1] = msg[i].length
99     + (rand[i] * 0x04c2af9b + 0xfffffffb); xorbyte = rand &gt;&gt;
100     24</code>, all in 32 bit unsigned iso-c arithmetic.</p>
101 pcg 1.23
102 pcg 1.3 <member name="type" type="U16"/>
103 pcg 1.18 <p>If the type is &gt;= 0x4000 this is a message for a specific channel. The channel
104     number is always the next U16.</p>
105 pcg 1.24
106     <p>Beginning with version 2.5.x, a number is <em>added</em> on <em>received</em>
107     messages only. The algorithm is as follows:
108    
109     <pre>
110     msglen &lt; 44: type = typefield
111     msglen &gt; 44: type = (typefield + rand[i]) % 0x10000
112     rand[0] = 0
113     rand[i+1] = username[type % length username] + rand[i] * (type - 0x6cdd)
114     where username is the user name of the logged-in user. coooool.
115     </pre>
116     </p>
117    
118 pcg 1.3 </struct>
119    
120     <h2>Primitive types used in the protocol.</h2>
121    
122 pcg 1.9 <p>Apart from the basic types, I need to define some extra types to
123     deal with fixed-point values (based on integer types) or fixed-length
124     strings (either 7-bit-ascii or more limited (<code>A</code>), or UCS-2
125     based (<code>S</code>)).</p>
126 pcg 1.3
127 pcg 1.23 <type name="username" type="A" length="10"/>
128 pcg 1.9
129     <p>The basic user or login name, used throughout the protocol
130     as a handle to the user.</p>
131    
132 pcg 1.3 <type name="roomname" type="S" length="25"/><!-- argh, how horribly broken -->
133 pcg 1.9
134     <p>Many strings in the protocol are fixed-width for no good reason
135 pcg 1.18 (maybe this is one reason for using compression in newer versions, as
136 pcg 1.9 the packets itself are wasting lots of space.</p>
137    
138 pcg 1.16 <type name="realname" type="S" length="50"/>
139     <type name="email" type="S" length="70"/>
140     <type name="userinfo" type="S" length="1000"/>
141     <type name="url" type="A" length="100"/>
142    
143     <p>Used in user_record.</p>
144    
145 pcg 1.3 <type name="locale" type="A" length="5"/>
146 pcg 1.9
147     <p>A kind of locale specifier. It seems the general format seems to be
148     lowercase language, underscore, uppercase location, e.g. en_US. More
149     fancy specifications don't fit.</p>
150    
151 pcg 1.3 <type name="flag" type="U8" multiplier="1"/>
152 pcg 1.9
153     <p>Just a simple boolean value. 0 means false, and 1 generally true,
154     but I suggest ccepting != 0 as true.</p>
155    
156 pcg 1.6 <type name="komi16" type="I16" multiplier="2"/>
157     <type name="komi32" type="I32" multiplier="2"/>
158 pcg 1.20 <type name="komi324" type="I32" multiplier="4"/>
159 pcg 1.9
160     <p>Komi values are multiplied by 2 to make them integer in the
161 pcg 1.20 protocol. Well, *most* of the time at least...</p>
162 pcg 1.9
163 pcg 1.3 <type name="result" type="I32" multiplier="2"/>
164 pcg 1.9
165 pcg 1.15 <p>The game result is also multiplied by two to give it higher
166     resolution. There are also special values for wins by time etc., either
167     in result or in the score* types, or both :)</p>
168 pcg 1.9
169 pcg 1.13 <type name="score16" type="I16" multiplier="4"/>
170     <type name="score32" type="I32" multiplier="4"/>
171 pcg 1.27 <type name="score1000" type="I32" multiplier="1000"/>
172 pcg 1.9
173     <p>A score value (used for displaying the score at the end of a game)
174 pcg 1.15 are multiplied by four for a change (the 0.25 resolution is not
175     used). In game structures it is encoded by dividing by two, though, so
176 pcg 1.27 watch out! And in some others, it's encoded by multiplying by 1000...
177     yuck!</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.32 <h2>Structs used in messages from the client</h2>
229 pcg 1.1
230 pcg 1.32 <h2>Client-generated messages</h2>
231 pcg 1.18
232 pcg 1.31 <message type="0000" name="login" src="client">
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.31 <message type="0007" name="req_userinfo" src="client">
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.31 <message type="0007" name="update_userinfo" src="client">
259 pcg 1.18 <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.31 <message type="0014" name="req_stats" src="client">
273 pcg 1.18 <p>Request server statistics. Replied with <ref reply="stats"/></p>
274 pcg 1.19 </message>
275    
276 pcg 1.31 <message type="0016" name="idle_reset" src="client">
277 pcg 1.29 <p>Send in response to <ref reply="idle_warn"/> to keep the server from disconnecting.</p>
278     </message>
279    
280 pcg 1.31 <message type="001d" name="ping" src="client">
281 pcg 1.19 <p>Wild guess, I send it in <ref ref="idle_warn"/>.</p>
282 pcg 1.1 </message>
283    
284 pcg 1.31 <message type="001e" name="req_usergraph" src="client">
285 pcg 1.18 <p>Request user graph data, replied with <ref reply="usergraph"/>.</p>
286 pcg 1.17 <member name="name" type="username"/>
287     </message>
288    
289 pcg 1.31 <message type="001f" name="fetch_memos" src="client">
290 pcg 1.18 <p>Unclear. Fetch all outstanding memos? Replied with <ref reply="memo"/></p>
291 pcg 1.17 </message>
292    
293 pcg 1.31 <message type="0021" name="req_pic" src="client">
294 pcg 1.18 <p>Request a user picture from the server. Results in a <ref reply="userpic"/>
295     or a timeout.</p>
296 pcg 1.3 <member name="name" type="username"/>
297 pcg 1.1 </message>
298    
299 pcg 1.31 <message type="0021" name="upload_pic" src="client">
300 pcg 1.1 Same code as pic_req, but with an additional data section that
301 pcg 1.4 must contain a JPEG image that is &lt;=7KB. It must have 141×200 pixels.
302 pcg 1.3 <member name="name" type="username"/>
303 pcg 1.1 <member name="data" type="DATA"/>
304 pcg 1.29 </message>
305    
306 pcg 1.31 <message type="0023" name="send_memo" src="client">
307 pcg 1.29 <member name="name" type="username"/>
308     <member name="msg" type="STRING"/>
309 pcg 1.1 </message>
310    
311 pcg 1.31 <message type="0100" name="gnotice" src="client">
312 pcg 1.18 <p>Send a global message. Maybe. Never tried, for obvious reasons :/. Results
313     in a <ref reply="gnotice"/> sent to all users.</p>
314 pcg 1.1 <member name="notice" type="STRING"/>
315     </message>
316    
317 pcg 1.33 <message type="0200" name="notify_add" src="client">
318    
319     <p>Probably setting a notifier on a username, to get informed about
320     changes using <ref reply="notify_upd"/> messages. ???</p>
321    
322     <member name="name" type="username"/>
323     </message>
324    
325     <message type="0201" name="notify_del" src="client">
326    
327     <p>Probably remove the notifier again.</p>
328    
329     <member name="name" type="username"/>
330     </message>
331    
332 pcg 1.31 <message type="0318" name="list_rooms" src="client">
333 pcg 1.18 <p>List the rooms in a specific group/category. Results in a <ref reply="upd_rooms"/> message.</p>
334 pcg 1.3 <member name="group" type="U8"/>
335 pcg 1.1 </message>
336    
337 pcg 1.31 <message type="031a" name="new_room" src="client">
338 pcg 1.1 Create a new room. Not verified.
339 pcg 1.3 <member name="name" type="username"/>
340     <member name="i1" type="U32" default="0"/>
341     <member name="b1" type="U8" default="0"/>
342     <member name="b2" type="U8" default="255"/>
343     <member name="b3" type="U8" default="255"/>
344     <member name="group" type="U8" default="1"/>
345 pcg 1.1 <member name="name" type="STRING"/>
346     <member name="description" type="STRING"/>
347 pcg 1.3 <member name="flags" type="U8"/>
348 pcg 1.1 0x10 .. private room etc.. see code
349     </message>
350    
351 pcg 1.31 <message type="0413" name="req_game_record" src="client">
352 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>
353 pcg 1.16 <member name="name" type="username"/>
354     <member name="timestamp" type="timestamp"/>
355     If zero, start at the newest games, else only send games
356     before the given timestap.
357     </message>
358    
359 pcg 1.31 <message type="4300" name="join_room" src="client">
360 pcg 1.18 <p>Joins the given room. <ref reply="join_room"/> messages for yourself
361 pcg 1.9 and all users in that room, as well as the initial gamelist, are
362 pcg 1.18 send if the room exists. If not, timeout...</p>
363 pcg 1.3 <member name="channel" type="U16"/>
364 pcg 1.1 <member name="user" type="user"/>
365     </message>
366    
367 pcg 1.31 <message type="4301" name="msg_room" src="client">
368 pcg 1.9 Send a message to the room.
369 pcg 1.3 <member name="channel" type="U16"/>
370     <member name="name" type="username"/>
371 pcg 1.9 Must be the login-name of the user.
372 pcg 1.1 <member name="message" type="STRING"/>
373     </message>
374    
375 pcg 1.31 <message type="4302" name="part_room" src="client">
376 pcg 1.9 Remove yourself (or maybe others as admin) from a room.
377 pcg 1.3 <member name="channel" type="U16"/>
378     <member name="name" type="username"/>
379 pcg 1.1 </message>
380    
381 pcg 1.31 <message type="4305" name="new_game" src="client">
382 pcg 1.17 Unclear. Start a new game.
383 pcg 1.3 <member name="channel" type="U16"/>
384     <member name="id" type="U16"/>
385     <member name="gametype" type="U32"/>
386 pcg 1.1 <member name="rules" type="rules"/>
387     <member name="notes" type="STRING"/>
388     </message>
389    
390 pcg 1.31 <message type="430b" name="req_games" src="client">
391 pcg 1.9 Request to update room game list (send this once per minute to get
392     updated). Results in upd_games messages.
393 pcg 1.3 <member name="channel" type="U16"/>
394 pcg 1.1 </message>
395    
396 pcg 1.31 <message type="4319" name="req_desc" src="client">
397 pcg 1.1 Request room description.
398 pcg 1.3 <member name="channel" type="U16"/>
399 pcg 1.1 </message>
400    
401 pcg 1.31 <message type="4400" name="send_challenge" src="client">
402 pcg 1.9 Unclear.
403 pcg 1.3 <member name="channel" type="U16"/>
404     <member name="black" type="username"/>
405     <member name="white" type="username"/>
406 pcg 1.1 More following... TREE or challenge.
407     </message>
408    
409 pcg 1.31 <message type="4403" name="join_game" src="client">
410 pcg 1.9 Join a game. See join_room.
411 pcg 1.5 <member name="channel" type="U16"/>
412 pcg 1.1 <member name="user" type="user"/>
413     </message>
414    
415 pcg 1.31 <message type="4404" name="part_game" src="client">
416 pcg 1.9 Leave (or kick as admin?) a certain user from a game.
417 pcg 1.3 <member name="channel" type="U16"/>
418     <member name="name" type="username"/>
419 pcg 1.1 </message>
420    
421 pcg 1.35 <message type="4405" name="set_tree" src="client">
422     Possibly upload an initial game to an empty room. Not tested.
423    
424     <member name="channel" type="U16"/>
425     <member name="tree" type="TREE"/>
426     </message>
427    
428 pcg 1.31 <message type="4406" name="upd_tree" src="client">
429 pcg 1.28 Upload a partial game tree to the server. This is used to send moves
430     and even in-game comments to the server. For the comments, the
431     server prepends the username and rank.
432    
433 pcg 1.3 <member name="channel" type="U16"/>
434 pcg 1.1 <member name="tree" type="TREE"/>
435     </message>
436    
437 pcg 1.31 <message type="4408" name="get_tree" src="client">
438 pcg 1.9 Request the game tree starting at a given node. This is used
439     when the server only sends a partial tree (with end code "more").
440 pcg 1.3 <member name="channel" type="U16"/>
441     <member name="node" type="U32"/>
442 pcg 1.1 </message>
443    
444 pcg 1.31 <message type="440c" name="claim_win" src="client">
445 pcg 1.9 Unclear.
446 pcg 1.3 <member name="channel" type="U16"/>
447     <member name="_byte" type="U8 "/>
448 pcg 1.1 Player colour maybe? Unclear.
449     </message>
450    
451 pcg 1.31 <message type="440d" name="add_time" src="client">
452 pcg 1.9 Not checked.
453    
454 pcg 1.3 <member name="channel" type="U16"/>
455     <member name="time" type="U32"/>
456     <member name="player" type="U8"/>
457 pcg 1.1 </message>
458    
459 pcg 1.31 <message type="440f" name="grant_undo" src="client">
460 pcg 1.9 Can be send after a req_undo message was received to grant the undo.
461 pcg 1.3 <member name="channel" type="U16"/>
462 pcg 1.1 </message>
463    
464 pcg 1.31 <message type="4410" name="resign_game" src="client">
465 pcg 1.9 Resign the game.
466 pcg 1.3 <member name="channel" type="U16"/>
467     <member name="player" type="U8"/>
468 pcg 1.1 </message>
469    
470 pcg 1.31 <message type="441a" name="set_teacher" src="client">
471 pcg 1.9 Change the teacher to somebody else (or possibly yourself == take it).
472 pcg 1.3 <member name="channel" type="U16"/>
473     <member name="name" type="username"/>
474 pcg 1.1 </message>
475    
476 pcg 1.31 <message type="4422" name="add_user" src="client">
477 pcg 1.9 Unclear. Maybe allow users to talk? No idea, really.
478    
479 pcg 1.3 <member name="channel" type="U16"/>
480     <member name="othername" type="username"/>
481     <member name="name" type="username"/>; # gives user access to the game (to what? ;)
482 pcg 1.1 </message>
483    
484 pcg 1.31 <message type="4423" name="set_privacy" src="client">
485 pcg 1.9 Probably sets the "quiet" flag. Not checked.
486 pcg 1.3 <member name="channel" type="U16"/>
487     <member name="private" type="U8"/>
488 pcg 1.1 </message>
489    
490 pcg 1.31 <message type="4429" name="reject_challenge" src="client">
491 pcg 1.9 Reject a challenge from a given user. Not checked.
492    
493 pcg 1.3 <member name="channel" type="U16"/>
494     <member name="name" type="username"/>
495 pcg 1.1 </message>
496    
497 pcg 1.31 <message type="4433" name="req_result" src="client">
498 pcg 1.9 I forgot.
499    
500 pcg 1.3 <member name="channel" type="U16"/>
501 pcg 1.35 </message>
502    
503     <message type="4436" name="msg_game" src="client">
504     <member name="channel" type="U16"/>
505     <member name="message" type="STRING"/>
506 pcg 1.1 </message>
507    
508 pcg 1.32 <h2>Structs mainly used in messages send by the server</h2>
509 pcg 1.1
510 pcg 1.3 <struct name="challenge_defaults">
511 pcg 1.9 Send soon after log-in to set the defaults for game challenges.
512 pcg 1.3 <member name="gametype" type="U32"/>
513     <member name="size" type="U32"/>
514     <member name="timesys" type="U32"/>
515     <member name="time" type="U32"/>
516     <member name="byo_time" type="U32"/>
517     <member name="byo_periods" type="U32"/>
518     <member name="can_time" type="U32"/>
519     <member name="can_stones" type="U32"/>
520     </struct>
521    
522     <struct name="challenge" class="KGS::Challenge">
523 pcg 1.9 A challenge.
524    
525 pcg 1.1 <member name="user1" type="user"/>
526     <member name="user2" type="user"/>
527 pcg 1.3 <member name="gametype" type="U32"/>
528 pcg 1.1 <member name="rules" type="rules"/>
529     Maybe the rules" are in TREE format. I forgot.
530 pcg 1.3 </struct>
531 pcg 1.1
532 pcg 1.3 <struct name="game" class="KGS::Game">
533 pcg 1.9 Basic information about a game. Used in rooms for the gamelist and
534     in games to detect when a game is saved, changed type (e.g. R => D)
535     etc.
536    
537 pcg 1.3 <member name="channel" type="U16"/>
538 pcg 1.26 <member name="type" type="U8"/>
539 pcg 1.1 <member name="user1" type="user"/>
540     White
541     <member name="user2" type="user"/>
542     Black
543     <member name="user3" type="user"/>
544     Owner
545 pcg 1.26 <member name="size" type="U8"/>
546     <member name="handicap" type="I8"/>
547 pcg 1.1 &lt; 0 not fully setup
548 pcg 1.26 <member name="komi" type="komi16"/>
549 pcg 1.15 <member name="moves" type="I16"/>
550 pcg 1.14 This field reflects either the movenum or the score, sorry, not even guards help, as
551 pcg 1.15 the flags to determine that are _after_ the field. Arg. Divide by two to get the actual
552 pcg 1.27 score (NOT score16!) (arg²).
553 pcg 1.3 <member name="flags" type="U16"/>
554     <member name="observers" type="U32"/>
555     <member name="saved" type="flag"/>
556     <member name="notes" type="STRING" guard-member="handicap" guard-cond="&lt; 0"/>
557     </struct>
558    
559     <struct name="room_obs">
560 pcg 1.9 Obsolete.
561    
562 pcg 1.3 <member name="name" type="roomname"/>
563     <member name="channel" type="U16"/>
564     <member name="flags" type="U32"/>
565 pcg 1.4 <member name="users" type="U32"/>
566 pcg 1.3 </struct>
567    
568     <struct name="room" class="KGS::Room">
569     <member name="channel" type="U16"/>
570     <member name="flags" type="U8"/>
571     <member name="group" type="U8"/>
572     <member name="users" type="U16"/>
573     <member name="games" type="U16"/>
574 pcg 1.4 <member name="name" type="STRING"/>
575 pcg 1.3 </struct>
576 pcg 1.1
577 pcg 1.12 <struct name="scorevalues" class="KGS::Score">
578 pcg 1.13 <member name="score" type="score32"/>
579 pcg 1.3 <member name="territory" type="U32"/>
580     <member name="captures" type="U32"/>
581     <member name="i3" type="U32"/>
582     <member name="f2" type="U32"/>
583 pcg 1.20 <member name="komi" type="komi324"/>
584 pcg 1.4 <member name="i4" type="U32"/>
585 pcg 1.3 Apparently the i3, f2, i4 are zero.
586     </struct>
587 pcg 1.1
588 pcg 1.16 <struct name="game_record" class="KGS::GameRecord">
589 pcg 1.18 <p>A single game record entry, as seen in <ref ref="userinfo"/>.</p>
590 pcg 1.16
591     <member name="timestamp" type="timestamp"/>
592     Time this game was played.
593 pcg 1.34 <member name="type" type="U8"/>
594 pcg 1.16 High four bits are handicap, low four bits are gametype (encoded strangely? unclear).
595     <member name="user1" type="user"/>
596     White, flags contain low 8 bits of revision (bits 16-23).
597     <member name="user2" type="user"/>
598     Black, flags contain high 8 bits of revision (bits 16-23).
599     <member name="user3" type="user"/>
600 pcg 1.34
601     <p><p>Owner (or empty)</p>
602    
603     <p>The bits 16-24 of user1.flags and user2.flags give the high and
604     low bits of a revision number in case there are multiple similar
605     games.</p></p>
606    
607 pcg 1.16 <member name="komi" type="komi16"/>
608     <member name="score" type="score16"/>
609     <member name="status" type="U8"/>
610 pcg 1.34
611     <p>0x80 game in progress</p>
612    
613 pcg 1.16 </struct>
614    
615 pcg 1.32 <h2>Server-generated messages</h2>
616 pcg 1.1
617 pcg 1.31 <message type="0001" name="login" src="server">
618 pcg 1.3 <member name="result" type="CONSTANT" default='"login ok"'/>
619 pcg 1.1 <member name="success" type="CONSTANT" default="1"/>
620     </message>
621    
622 pcg 1.31 <message type="0002" name="login" src="server">
623 pcg 1.3 <member name="result" type="CONSTANT" default='"guest login ok"'/>
624 pcg 1.1 <member name="success" type="CONSTANT" default="1"/>
625     </message>
626    
627 pcg 1.31 <message type="0003" name="login" src="server">
628 pcg 1.3 <member name="result" type="CONSTANT" default='"login error 3"'/>
629 pcg 1.1 ** maybe more following? **
630     </message>
631    
632 pcg 1.31 <message type="0004" name="login" src="server">
633 pcg 1.3 <member name="result" type="CONSTANT" default='"wrong password"'/>
634 pcg 1.1 ** maybe more following? **
635     </message>
636    
637 pcg 1.31 <message type="0005" name="login" src="server">
638 pcg 1.3 <member name="result" type="CONSTANT" default='"user unknown"'/>
639 pcg 1.1 ** maybe more following? **
640     </message>
641    
642 pcg 1.31 <message type="0006" name="login" src="server">
643 pcg 1.3 <member name="result" type="CONSTANT" default='"user exists"'/>
644 pcg 1.1 ** maybe more following? **
645     </message>
646    
647 pcg 1.31 <message type="0008" name="userinfo" src="server">
648 pcg 1.17 User info.
649 pcg 1.33 <member name="_unused0" type="flag"/>
650 pcg 1.16 <member name="user" type="user"/>
651 pcg 1.33 <member name="_unused1" type="U64"/>
652 pcg 1.16 <member name="realname" type="realname"/>
653     <member name="email" type="email"/>
654     <member name="info" type="userinfo"/>
655     <member name="homepage" type="url"/>
656     <member name="regdate" type="timestamp"/>
657     When the user registered (0 == never registered).
658     <member name="lastlogin" type="timestamp"/>
659     When the user logged in for the last time.
660     <!-- maybe more? -->
661     </message>
662    
663 pcg 1.31 <message type="0013" name="msg_chat" src="server">
664 pcg 1.34 <member name="name" type="username"/>
665     <member name="name2" type="username"/>
666 pcg 1.1 <member name="message" type="STRING"/>
667     </message>
668    
669 pcg 1.31 <message type="0015" name="stats" src="server">
670 pcg 1.3 <member name="ver_major" type="U16"/>
671     <member name="ver_minor" type="U16"/>
672     <member name="ver_micro" type="U16"/>
673 pcg 1.16 <member name="boot_time" type="timestamp"/>
674 pcg 1.3 <member name="users_cur" type="U32"/>
675     <member name="users_max" type="U32"/>
676     <member name="users_lim" type="U32"/>
677     <member name="accts_cur" type="U32"/>
678     <member name="accts_max" type="U32"/>
679     <member name="unknown1" type="U32"/>
680     <member name="work_max" type="U32"/>
681     <member name="rooms_cur" type="U32"/>
682     <member name="rooms_max" type="U32"/>
683     <member name="rooms_lim" type="U32"/>
684     <member name="games_cur" type="U32"/>
685     <member name="games_max" type="U32"/>
686     <member name="games_lim" type="U32"/>
687     <member name="results_cur" type="U32"/>
688     <member name="results_max" type="U32"/>
689     <member name="unknown2" type="U32"/>
690     <member name="params_cur" type="U32"/>
691     <member name="params_max" type="U32"/>
692     <member name="bytes_in" type="U64"/>
693     <member name="packets_in" type="U64"/>
694     <member name="bytes_out" type="U64"/>
695 pcg 1.4 <member name="packets_out" type="U64"/>
696 pcg 1.1 </message>
697    
698 pcg 1.31 <message type="0016" name="idle_warn" src="server">
699 pcg 1.1 idle warning, autologout soon (10 minutes...)
700     </message>
701    
702 pcg 1.34 <message type="0018" name="login" src="server">
703     <member name="result" type="CONSTANT" default='"login error 18"'/>
704     ** maybe more following? **
705     </message>
706    
707     <message type="0022" name="login" src="server">
708     I was blocked sooo many times for developing this client that it was
709     easy to figure out. The KGS admins sure need no extra nazi training
710     :(
711     <member name="reason" type="STRING"/>
712     <member name="result" type="CONSTANT" default='"user or ip blocked"'/>
713     </message>
714    
715 pcg 1.31 <message type="001b" name="timewarning_default" src="server">
716 pcg 1.1 WILD guess
717 pcg 1.3 <member name="channel" type="U16"/>
718     <member name="time" type="U16"/>
719 pcg 1.1 </message>
720    
721 pcg 1.31 <message type="001c" name="idle_err" src="server">
722 pcg 1.1 autologout
723     </message>
724    
725 pcg 1.31 <message type="001d" name="ping" src="server">
726 pcg 1.16 Sent by the server regularly, but not answering them
727     isn't valid. Strange form of keepalive?
728 pcg 1.1 </message>
729    
730 pcg 1.31 <message type="001e" name="usergraph" src="server">
731 pcg 1.17 User graph data.
732 pcg 1.33 <member name="name" type="username"/>
733 pcg 1.17 <member name="data" type="I16" array="yes"/>
734     If empty, no graph is available. The unit seems to
735     be centi-kyu, with 1 dan == 0, 2 dan == 100, 1 kyu == -100.
736     There is probably one entry per day, the newest one last.
737     </message>
738    
739 pcg 1.31 <message type="001f" name="memo" src="server">
740 pcg 1.17 Unclear. "Leave Message"?
741     6 strings following.
742     <member name="s1" type="STRING"/>
743     <member name="s2" type="STRING"/>
744     <member name="s3" type="STRING"/>
745     <member name="s4" type="STRING"/>
746     <member name="s5" type="STRING"/>
747     <member name="s6" type="STRING"/>
748     </message>
749    
750 pcg 1.31 <message type="0021" name="userpic" src="server">
751 pcg 1.3 <member name="name" type="username"/>
752 pcg 1.1 Reply to pic_req, contains an image in jpeg format.
753     <member name="data" type="DATA"/>
754     </message>
755    
756 pcg 1.31 <message type="0100" name="gnotice" src="server">
757 pcg 1.1 global notice, sent to everybody
758     <member name="notice" type="STRING"/>
759     </message>
760    
761 pcg 1.33 <message type="0202" name="notify_event" src="server">
762 pcg 1.17 # maybe soe notify? Totally unclear.
763 pcg 1.16 # loc 0" type="chat(?) loc 1 => gameinfo?, loc 2 => game result (more data)
764 pcg 1.33 <member name="event" type="U32"/>
765 pcg 1.16 <member name="user" type="user"/>
766 pcg 1.34 <member name="gamerecord" type="game_record" guard-member="event" guard-cond="== 2"/>
767 pcg 1.33 <p>Game result record?</p>
768    
769 pcg 1.16 </message>
770 pcg 1.1
771 pcg 1.31 <message type="0310" name="priv_room" src="server">
772 pcg 1.1 "permission denied" when joining a room
773     <member name="name" type="STRING"/>
774     </message>
775    
776 pcg 1.31 <message type="0318" name="upd_rooms" src="server">
777 pcg 1.1 <member name="rooms" type="room" array="yes"/>
778     </message>
779    
780 pcg 1.31 <message type="0411" name="chal_defaults" src="server">
781 pcg 1.16 <member name="channel" type="U16"/>
782     <member name="defaults" type="challenge_defaults"/>
783     </message>
784    
785 pcg 1.31 <message type="0412" name="rej_game" src="server">
786 pcg 1.17 Unable to create challenge. The channel might be optional.
787     <member name="channel" type="U16"/>
788     </message>
789    
790 pcg 1.31 <message type="0414" name="game_record" src="server">
791 pcg 1.16 The users game record.
792     <member name="name" type="username"/>
793     <member name="more" type="flag"/>
794     Wether more games are available (must be requested manually)
795     <member name="games" type="game_record" array="yes"/>
796     </message>
797    
798 pcg 1.31 <message type="041c" name="upd_game2" src="server">
799 pcg 1.17 Unclear.
800 pcg 1.3 <member name="channel_junk" type="U16"/>
801 pcg 1.1 <member name="game" type="game"/>
802     </message>
803    
804     <h3>Room messages</h3>
805    
806     <p>Not all room messages are for rooms only, and rooms need to parse
807     not only these messages. Orthogonality, what for?</p>
808    
809 pcg 1.31 <message type="4300" name="join_room" src="server">
810 pcg 1.3 <member name="channel" type="U16"/>
811 pcg 1.1 <member name="users" type="user" array="yes"/>
812     </message>
813    
814 pcg 1.31 <message type="4301" name="msg_room" src="server">
815 pcg 1.3 <member name="channel" type="U16"/>
816     <member name="name" type="username"/>
817 pcg 1.1 <member name="message" type="STRING"/>
818     </message>
819    
820 pcg 1.31 <message type="4302" name="part_room" src="server">
821 pcg 1.3 <member name="channel" type="U16"/>
822 pcg 1.1 <member name="user" type="user"/>
823     </message>
824    
825 pcg 1.31 <message type="4303" name="del_room" src="server">
826 pcg 1.3 <member name="channel" type="U16"/>
827 pcg 1.1 </message>
828    
829 pcg 1.31 <message type="4304" name="upd_games" src="server">
830 pcg 1.3 <member name="channel" type="U16"/>
831 pcg 1.1 <member name="games" type="game" array="yes"/>
832     </message>
833    
834 pcg 1.31 <message type="4319" name="desc_room" src="server">
835 pcg 1.3 <member name="channel" type="U16"/>
836     <member name="owner" type="username"/>
837 pcg 1.1 <member name="description" type="STRING"/>
838     </message>
839 pcg 1.28
840 pcg 1.1 <h3>Game messages</h3>
841    
842 pcg 1.31 <message type="4400" name="upd_challenge" src="server">
843 pcg 1.1 Unclear.
844 pcg 1.3 <member name="channel" type="U16"/>
845 pcg 1.1 <member name="challenge" type="challenge"/>
846     </message>
847    
848 pcg 1.31 <message type="4401" name="upd_game" src="server">
849 pcg 1.3 <member name="channel" type="U16"/>
850 pcg 1.1 <member name="game" type="game"/>
851     </message>
852    
853 pcg 1.31 <message type="4402" name="del_game" src="server">
854 pcg 1.3 <member name="channel" type="U16"/>
855 pcg 1.1 </message>
856    
857 pcg 1.31 <message type="4403" name="upd_observers" src="server">
858 pcg 1.3 <member name="channel" type="U16"/>
859 pcg 1.1 <member name="users" type="user" array="yes"/>
860     </message>
861    
862 pcg 1.31 <message type="4404" name="del_observer" src="server">
863 pcg 1.3 <member name="channel" type="U16"/>
864     <member name="name" type="username"/>
865 pcg 1.1 </message>
866    
867 pcg 1.31 <message type="4405" name="set_tree" src="server">
868 pcg 1.3 <member name="channel" type="U16"/>
869 pcg 1.1 <member name="tree" type="TREE"/>
870     </message>
871    
872 pcg 1.31 <message type="4406" name="upd_tree" src="server">
873 pcg 1.3 <member name="channel" type="U16"/>
874 pcg 1.1 <member name="tree" type="TREE"/>
875     </message>
876    
877 pcg 1.31 <message type="4409" name="superko" src="server">
878 pcg 1.1 Superko-warning.
879 pcg 1.3 <member name="channel" type="U16"/>
880 pcg 1.1 </message>
881    
882 pcg 1.31 <message type="440b" name="final_result" src="server">
883 pcg 1.3 <member name="channel" type="U16"/>
884 pcg 1.12 <member name="blackscore" type="scorevalues"/>
885     <member name="whitescore" type="scorevalues"/>
886 pcg 1.1 </message>
887    
888 pcg 1.31 <message type="440e" name="req_undo" src="server">
889 pcg 1.3 <member name="channel" type="U16"/>
890 pcg 1.1
891     </message>
892    
893 pcg 1.31 <message type="4410" name="resign_game" src="server">
894 pcg 1.3 <member name="channel" type="U16"/>
895     <member name="player" type="U8"/>
896 pcg 1.1 </message>
897    
898 pcg 1.31 <message type="441a" name="set_teacher" src="server">
899 pcg 1.3 <member name="channel" type="U16"/>
900     <member name="name" type="username"/>
901 pcg 1.1 </message>
902    
903 pcg 1.31 <message type="441d" name="owner_left" src="server">
904 pcg 1.1 Unclear.
905 pcg 1.3 <member name="channel" type="U16"/>
906 pcg 1.1 </message>
907    
908 pcg 1.31 <message type="441e" name="teacher_left" src="server">
909 pcg 1.1 Unclear.
910 pcg 1.3 <member name="channel" type="U16"/>
911 pcg 1.1 </message>
912    
913 pcg 1.31 <message type="4422" name="unknown4422" src="server">
914 pcg 1.1 change teacher? something to do with editing?
915 pcg 1.3 <member name="channel" type="U16"/>
916     <member name="name1" type="username"/>
917     <member name="name2" type="username"/>
918 pcg 1.27 </message>
919    
920 pcg 1.31 <message type="4428" name="add_tree" src="server">
921 pcg 1.27 <p>See <ref ref="set_tree"/>. In addition, flags the tree as being
922     uploaded completely.</p>
923     <member name="channel" type="U16"/>
924     <member name="tree" type="TREE"/>
925 pcg 1.1 </message>
926    
927 pcg 1.31 <message type="4433" name="req_result" src="server">
928 pcg 1.1 Unclear.
929 pcg 1.3 <member name="channel" type="U16"/>
930 pcg 1.1 # # recv_result(?)
931     </message>
932    
933 pcg 1.31 <message type="4434" name="unknown4434" src="server">
934 pcg 1.3 <member name="channel" type="U16"/>
935     <member name="b1" type="U8"/>
936 pcg 1.1 ?? !demonstration game??
937     </message>
938    
939     </body>
940     </html>
941