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