ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/cvsroot/kgsueme/doc/protocol.xml
Revision: 1.19
Committed: Sat Jun 14 22:46:08 2003 UTC (23 years, 4 months ago) by pcg
Content type: text/xml
Branch: MAIN
Changes since 1.18: +5 -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.19 <h1>$Revision: 1.18 $</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.19 </message>
248    
249     <message type="001d" name="ping" recv="yes">
250     <p>Wild guess, I send it in <ref ref="idle_warn"/>.</p>
251 pcg 1.1 </message>
252    
253 pcg 1.17 <message type="001e" name="req_usergraph" send="yes">
254 pcg 1.18 <p>Request user graph data, replied with <ref reply="usergraph"/>.</p>
255 pcg 1.17 <member name="name" type="username"/>
256     </message>
257    
258     <message type="001f" name="fetch_memos" send="yes">
259 pcg 1.18 <p>Unclear. Fetch all outstanding memos? Replied with <ref reply="memo"/></p>
260 pcg 1.17 </message>
261    
262     <message type="0021" name="req_pic" send="yes">
263 pcg 1.18 <p>Request a user picture from the server. Results in a <ref reply="userpic"/>
264     or a timeout.</p>
265 pcg 1.3 <member name="name" type="username"/>
266 pcg 1.1 </message>
267    
268 pcg 1.17 <message type="0021" name="upload_pic" send="yes">
269 pcg 1.1 Same code as pic_req, but with an additional data section that
270 pcg 1.4 must contain a JPEG image that is &lt;=7KB. It must have 141×200 pixels.
271 pcg 1.3 <member name="name" type="username"/>
272 pcg 1.1 <member name="data" type="DATA"/>
273     </message>
274    
275 pcg 1.2 <message type="0100" name="gnotice" send="yes">
276 pcg 1.18 <p>Send a global message. Maybe. Never tried, for obvious reasons :/. Results
277     in a <ref reply="gnotice"/> sent to all users.</p>
278 pcg 1.1 <member name="notice" type="STRING"/>
279     </message>
280    
281 pcg 1.2 <message type="0318" name="list_rooms" send="yes">
282 pcg 1.18 <p>List the rooms in a specific group/category. Results in a <ref reply="upd_rooms"/> message.</p>
283 pcg 1.3 <member name="group" type="U8"/>
284 pcg 1.1 </message>
285    
286 pcg 1.2 <message type="031a" name="new_room" send="yes">
287 pcg 1.1 Create a new room. Not verified.
288 pcg 1.3 <member name="name" type="username"/>
289     <member name="i1" type="U32" default="0"/>
290     <member name="b1" type="U8" default="0"/>
291     <member name="b2" type="U8" default="255"/>
292     <member name="b3" type="U8" default="255"/>
293     <member name="group" type="U8" default="1"/>
294 pcg 1.1 <member name="name" type="STRING"/>
295     <member name="description" type="STRING"/>
296 pcg 1.3 <member name="flags" type="U8"/>
297 pcg 1.1 0x10 .. private room etc.. see code
298     </message>
299    
300 pcg 1.17 <message type="0413" name="req_game_record" send="yes">
301 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>
302 pcg 1.16 <member name="name" type="username"/>
303     <member name="timestamp" type="timestamp"/>
304     If zero, start at the newest games, else only send games
305     before the given timestap.
306     </message>
307    
308 pcg 1.1 <message type="4300" name="join_room" send="yes">
309 pcg 1.18 <p>Joins the given room. <ref reply="join_room"/> messages for yourself
310 pcg 1.9 and all users in that room, as well as the initial gamelist, are
311 pcg 1.18 send if the room exists. If not, timeout...</p>
312 pcg 1.3 <member name="channel" type="U16"/>
313 pcg 1.1 <member name="user" type="user"/>
314     </message>
315    
316     <message type="4301" name="msg_room" send="yes">
317 pcg 1.9 Send a message to the room.
318 pcg 1.3 <member name="channel" type="U16"/>
319     <member name="name" type="username"/>
320 pcg 1.9 Must be the login-name of the user.
321 pcg 1.1 <member name="message" type="STRING"/>
322     </message>
323    
324     <message type="4302" name="part_room" send="yes">
325 pcg 1.9 Remove yourself (or maybe others as admin) from a room.
326 pcg 1.3 <member name="channel" type="U16"/>
327     <member name="name" type="username"/>
328 pcg 1.1 </message>
329    
330     <message type="4305" name="new_game" send="yes">
331 pcg 1.17 Unclear. Start a new game.
332 pcg 1.3 <member name="channel" type="U16"/>
333     <member name="id" type="U16"/>
334     <member name="gametype" type="U32"/>
335 pcg 1.1 <member name="rules" type="rules"/>
336     <member name="notes" type="STRING"/>
337     </message>
338    
339     <message type="430b" name="req_games" send="yes">
340 pcg 1.9 Request to update room game list (send this once per minute to get
341     updated). Results in upd_games messages.
342 pcg 1.3 <member name="channel" type="U16"/>
343 pcg 1.1 </message>
344    
345     <message type="4319" name="req_desc" send="yes">
346     Request room description.
347 pcg 1.3 <member name="channel" type="U16"/>
348 pcg 1.1 </message>
349    
350     <message type="4400" name="send_chal" send="yes">
351 pcg 1.9 Unclear.
352 pcg 1.3 <member name="channel" type="U16"/>
353     <member name="black" type="username"/>
354     <member name="white" type="username"/>
355 pcg 1.1 More following... TREE or challenge.
356     </message>
357    
358     <message type="4403" name="join_game" send="yes">
359 pcg 1.9 Join a game. See join_room.
360 pcg 1.5 <member name="channel" type="U16"/>
361 pcg 1.1 <member name="user" type="user"/>
362     </message>
363    
364     <message type="4404" name="part_game" send="yes">
365 pcg 1.9 Leave (or kick as admin?) a certain user from a game.
366 pcg 1.3 <member name="channel" type="U16"/>
367     <member name="name" type="username"/>
368 pcg 1.1 </message>
369    
370     <message type="4405" name="set_tree" send="yes">
371 pcg 1.9 Upload a partial game tree to the server. This is used
372     to send moves and even in-game comments to the server. For the comments,
373     the server prepends the username and rank.
374 pcg 1.3 <member name="channel" type="U16"/>
375 pcg 1.1 <member name="tree" type="TREE"/>
376     </message>
377    
378     <message type="4408" name="get_tree" send="yes">
379 pcg 1.9 Request the game tree starting at a given node. This is used
380     when the server only sends a partial tree (with end code "more").
381 pcg 1.3 <member name="channel" type="U16"/>
382     <member name="node" type="U32"/>
383 pcg 1.1 </message>
384    
385     <message type="440c" name="claim_win" send="yes">
386 pcg 1.9 Unclear.
387 pcg 1.3 <member name="channel" type="U16"/>
388     <member name="_byte" type="U8 "/>
389 pcg 1.1 Player colour maybe? Unclear.
390     </message>
391    
392     <message type="440d" name="add_time" send="yes">
393 pcg 1.9 Not checked.
394    
395 pcg 1.3 <member name="channel" type="U16"/>
396     <member name="time" type="U32"/>
397     <member name="player" type="U8"/>
398 pcg 1.1 </message>
399    
400     <message type="440f" name="grant_undo" send="yes">
401 pcg 1.9 Can be send after a req_undo message was received to grant the undo.
402 pcg 1.3 <member name="channel" type="U16"/>
403 pcg 1.1 </message>
404    
405     <message type="4410" name="resign_game" send="yes">
406 pcg 1.9 Resign the game.
407 pcg 1.3 <member name="channel" type="U16"/>
408     <member name="player" type="U8"/>
409 pcg 1.1 </message>
410    
411     <message type="441a" name="set_teacher" send="yes">
412 pcg 1.9 Change the teacher to somebody else (or possibly yourself == take it).
413 pcg 1.3 <member name="channel" type="U16"/>
414     <member name="name" type="username"/>
415 pcg 1.1 </message>
416    
417     <message type="4422" name="add_user" send="yes">
418 pcg 1.9 Unclear. Maybe allow users to talk? No idea, really.
419    
420 pcg 1.3 <member name="channel" type="U16"/>
421     <member name="othername" type="username"/>
422     <member name="name" type="username"/>; # gives user access to the game (to what? ;)
423 pcg 1.1 </message>
424    
425     <message type="4423" name="set_privacy" send="yes">
426 pcg 1.9 Probably sets the "quiet" flag. Not checked.
427 pcg 1.3 <member name="channel" type="U16"/>
428     <member name="private" type="U8"/>
429 pcg 1.1 </message>
430    
431     <message type="4429" name="reject_chal" send="yes">
432 pcg 1.9 Reject a challenge from a given user. Not checked.
433    
434 pcg 1.3 <member name="channel" type="U16"/>
435     <member name="name" type="username"/>
436 pcg 1.1 </message>
437    
438     <message type="4433" name="req_result" send="yes">
439 pcg 1.9 I forgot.
440    
441 pcg 1.3 <member name="channel" type="U16"/>
442 pcg 1.1 </message>
443    
444 pcg 1.3 <h2>Structs mainly used in receive messages</h2>
445 pcg 1.1
446 pcg 1.3 <struct name="challenge_defaults">
447 pcg 1.9 Send soon after log-in to set the defaults for game challenges.
448 pcg 1.3 <member name="gametype" type="U32"/>
449     <member name="size" type="U32"/>
450     <member name="timesys" type="U32"/>
451     <member name="time" type="U32"/>
452     <member name="byo_time" type="U32"/>
453     <member name="byo_periods" type="U32"/>
454     <member name="can_time" type="U32"/>
455     <member name="can_stones" type="U32"/>
456     </struct>
457    
458     <struct name="challenge" class="KGS::Challenge">
459 pcg 1.9 A challenge.
460    
461 pcg 1.1 <member name="user1" type="user"/>
462     <member name="user2" type="user"/>
463 pcg 1.3 <member name="gametype" type="U32"/>
464 pcg 1.1 <member name="rules" type="rules"/>
465     Maybe the rules" are in TREE format. I forgot.
466 pcg 1.3 </struct>
467 pcg 1.1
468 pcg 1.3 <struct name="game" class="KGS::Game">
469 pcg 1.9 Basic information about a game. Used in rooms for the gamelist and
470     in games to detect when a game is saved, changed type (e.g. R => D)
471     etc.
472    
473 pcg 1.3 <member name="channel" type="U16"/>
474     <member name="type" type="U32"/>
475 pcg 1.1 <member name="user1" type="user"/>
476     White
477     <member name="user2" type="user"/>
478     Black
479     <member name="user3" type="user"/>
480     Owner
481 pcg 1.3 <member name="size" type="U32"/>
482 pcg 1.1 <member name="handicap" type="I32"/>
483     &lt; 0 not fully setup
484 pcg 1.6 <member name="komi" type="komi32"/>
485 pcg 1.15 <member name="moves" type="I16"/>
486 pcg 1.14 This field reflects either the movenum or the score, sorry, not even guards help, as
487 pcg 1.15 the flags to determine that are _after_ the field. Arg. Divide by two to get the actual
488     score (NOT score16!).
489 pcg 1.3 <member name="flags" type="U16"/>
490     <member name="observers" type="U32"/>
491     <member name="saved" type="flag"/>
492     <member name="notes" type="STRING" guard-member="handicap" guard-cond="&lt; 0"/>
493     </struct>
494    
495     <struct name="room_obs">
496 pcg 1.9 Obsolete.
497    
498 pcg 1.3 <member name="name" type="roomname"/>
499     <member name="channel" type="U16"/>
500     <member name="flags" type="U32"/>
501 pcg 1.4 <member name="users" type="U32"/>
502 pcg 1.3 </struct>
503    
504     <struct name="room" class="KGS::Room">
505     <member name="channel" type="U16"/>
506     <member name="flags" type="U8"/>
507     <member name="group" type="U8"/>
508     <member name="users" type="U16"/>
509     <member name="games" type="U16"/>
510 pcg 1.4 <member name="name" type="STRING"/>
511 pcg 1.3 </struct>
512 pcg 1.1
513 pcg 1.12 <struct name="scorevalues" class="KGS::Score">
514 pcg 1.13 <member name="score" type="score32"/>
515 pcg 1.3 <member name="territory" type="U32"/>
516     <member name="captures" type="U32"/>
517     <member name="i3" type="U32"/>
518     <member name="f2" type="U32"/>
519 pcg 1.6 <member name="komi" type="komi32"/>
520 pcg 1.4 <member name="i4" type="U32"/>
521 pcg 1.3 Apparently the i3, f2, i4 are zero.
522     </struct>
523 pcg 1.1
524 pcg 1.16 <struct name="game_record" class="KGS::GameRecord">
525 pcg 1.18 <p>A single game record entry, as seen in <ref ref="userinfo"/>.</p>
526 pcg 1.16
527     <member name="timestamp" type="timestamp"/>
528     Time this game was played.
529     <member name="flags" type="U8"/>
530     High four bits are handicap, low four bits are gametype (encoded strangely? unclear).
531     <member name="user1" type="user"/>
532     White, flags contain low 8 bits of revision (bits 16-23).
533     <member name="user2" type="user"/>
534     Black, flags contain high 8 bits of revision (bits 16-23).
535     <member name="user3" type="user"/>
536     Owner (or empty)
537     <member name="komi" type="komi16"/>
538     <member name="score" type="score16"/>
539     <member name="status" type="U8"/>
540     0x80 inprogress
541     </struct>
542    
543 pcg 1.1 <h2>Receive messages</h2>
544    
545     <message type="0001" name="login" recv="yes">
546 pcg 1.3 <member name="result" type="CONSTANT" default='"login ok"'/>
547 pcg 1.1 <member name="success" type="CONSTANT" default="1"/>
548     </message>
549    
550     <message type="0002" name="login" recv="yes">
551 pcg 1.3 <member name="result" type="CONSTANT" default='"guest login ok"'/>
552 pcg 1.1 <member name="success" type="CONSTANT" default="1"/>
553     </message>
554    
555     <message type="0003" name="login" recv="yes">
556 pcg 1.3 <member name="result" type="CONSTANT" default='"login error 3"'/>
557 pcg 1.1 ** maybe more following? **
558     </message>
559    
560     <message type="0004" name="login" recv="yes">
561 pcg 1.3 <member name="result" type="CONSTANT" default='"wrong password"'/>
562 pcg 1.1 ** maybe more following? **
563     </message>
564    
565     <message type="0005" name="login" recv="yes">
566 pcg 1.3 <member name="result" type="CONSTANT" default='"user unknown"'/>
567 pcg 1.1 ** maybe more following? **
568     </message>
569    
570     <message type="0006" name="login" recv="yes">
571 pcg 1.3 <member name="result" type="CONSTANT" default='"user exists"'/>
572 pcg 1.1 ** maybe more following? **
573     </message>
574    
575 pcg 1.17 <message type="0008" name="userinfo" recv="yes">
576     User info.
577 pcg 1.16 <member name="user" type="user"/>
578 pcg 1.17 <member name="_unused" type="U64"/>
579 pcg 1.16 <member name="realname" type="realname"/>
580     <member name="email" type="email"/>
581     <member name="info" type="userinfo"/>
582     <member name="homepage" type="url"/>
583     <member name="regdate" type="timestamp"/>
584     When the user registered (0 == never registered).
585     <member name="lastlogin" type="timestamp"/>
586     When the user logged in for the last time.
587     <!-- maybe more? -->
588     </message>
589    
590 pcg 1.1 <message type="0018" name="login" recv="yes">
591 pcg 1.3 <member name="result" type="CONSTANT" default='"login error 18"'/>
592 pcg 1.1 ** maybe more following? **
593     </message>
594    
595     <message type="0022" name="login" recv="yes">
596 pcg 1.7 <!-- "thanks" to jyem for blocking me ;)-->
597 pcg 1.3 <member name="result" type="CONSTANT" default='"user or ip blocked"'/>
598 pcg 1.1 <member name="reason" type="STRING"/>
599     </message>
600    
601     <message type="0013" name="msg_chat" recv="yes">
602 pcg 1.3 <member name="user1" type="username"/>
603     <member name="user2" type="username"/>
604 pcg 1.1 <member name="message" type="STRING"/>
605     </message>
606    
607     <message type="0015" name="stats" recv="yes">
608 pcg 1.3 <member name="ver_major" type="U16"/>
609     <member name="ver_minor" type="U16"/>
610     <member name="ver_micro" type="U16"/>
611 pcg 1.16 <member name="boot_time" type="timestamp"/>
612 pcg 1.3 <member name="users_cur" type="U32"/>
613     <member name="users_max" type="U32"/>
614     <member name="users_lim" type="U32"/>
615     <member name="accts_cur" type="U32"/>
616     <member name="accts_max" type="U32"/>
617     <member name="unknown1" type="U32"/>
618     <member name="work_max" type="U32"/>
619     <member name="rooms_cur" type="U32"/>
620     <member name="rooms_max" type="U32"/>
621     <member name="rooms_lim" type="U32"/>
622     <member name="games_cur" type="U32"/>
623     <member name="games_max" type="U32"/>
624     <member name="games_lim" type="U32"/>
625     <member name="results_cur" type="U32"/>
626     <member name="results_max" type="U32"/>
627     <member name="unknown2" type="U32"/>
628     <member name="params_cur" type="U32"/>
629     <member name="params_max" type="U32"/>
630     <member name="bytes_in" type="U64"/>
631     <member name="packets_in" type="U64"/>
632     <member name="bytes_out" type="U64"/>
633 pcg 1.4 <member name="packets_out" type="U64"/>
634 pcg 1.1 </message>
635    
636     <message type="0016" name="idle_warn" recv="yes">
637     idle warning, autologout soon (10 minutes...)
638     </message>
639    
640     <message type="001b" name="timewarning_default" recv="yes">
641     WILD guess
642 pcg 1.3 <member name="channel" type="U16"/>
643     <member name="time" type="U16"/>
644 pcg 1.1 </message>
645    
646     <message type="001c" name="idle_err" recv="yes">
647     autologout
648     </message>
649    
650     <message type="001d" name="ping" recv="yes">
651 pcg 1.16 Sent by the server regularly, but not answering them
652     isn't valid. Strange form of keepalive?
653 pcg 1.1 </message>
654    
655 pcg 1.17 <message type="001e" name="usergraph" recv="yes">
656     User graph data.
657     <member name="data" type="I16" array="yes"/>
658     If empty, no graph is available. The unit seems to
659     be centi-kyu, with 1 dan == 0, 2 dan == 100, 1 kyu == -100.
660     There is probably one entry per day, the newest one last.
661     </message>
662    
663     <message type="001f" name="memo" recv="yes">
664     Unclear. "Leave Message"?
665     6 strings following.
666     <member name="s1" type="STRING"/>
667     <member name="s2" type="STRING"/>
668     <member name="s3" type="STRING"/>
669     <member name="s4" type="STRING"/>
670     <member name="s5" type="STRING"/>
671     <member name="s6" type="STRING"/>
672     </message>
673    
674 pcg 1.1 <message type="0021" name="userpic" recv="yes">
675 pcg 1.3 <member name="name" type="username"/>
676 pcg 1.1 Reply to pic_req, contains an image in jpeg format.
677     <member name="data" type="DATA"/>
678     </message>
679    
680     <message type="0100" name="gnotice" recv="yes">
681     global notice, sent to everybody
682     <member name="notice" type="STRING"/>
683     </message>
684    
685 pcg 1.16 <message type="0202" name="upd_user" recv="yes">
686 pcg 1.17 # maybe soe notify? Totally unclear.
687 pcg 1.16 # loc 0" type="chat(?) loc 1 => gameinfo?, loc 2 => game result (more data)
688     <member name="location" type="U32"/>
689     <member name="user" type="user"/>
690     <member name="lotsofinfo" type="DATA" guard-member="location" guard-cond="== 2"/>
691     </message>
692 pcg 1.1
693     <message type="0310" name="priv_room" recv="yes">
694     "permission denied" when joining a room
695     <member name="name" type="STRING"/>
696     </message>
697    
698     <message type="0318" name="upd_rooms" recv="yes">
699     <member name="rooms" type="room" array="yes"/>
700     </message>
701    
702 pcg 1.16 <message type="0411" name="chal_defaults" recv="yes">
703     <member name="channel" type="U16"/>
704     <member name="defaults" type="challenge_defaults"/>
705     </message>
706    
707 pcg 1.17 <message type="0412" name="rej_game" send="yes">
708     Unable to create challenge. The channel might be optional.
709     <member name="channel" type="U16"/>
710     </message>
711    
712 pcg 1.16 <message type="0414" name="game_record" recv="yes">
713     The users game record.
714     <member name="name" type="username"/>
715     <member name="more" type="flag"/>
716     Wether more games are available (must be requested manually)
717     <member name="games" type="game_record" array="yes"/>
718     </message>
719    
720 pcg 1.1 <message type="041c" name="upd_game2" recv="yes">
721 pcg 1.17 Unclear.
722 pcg 1.3 <member name="channel_junk" type="U16"/>
723 pcg 1.1 <member name="game" type="game"/>
724     </message>
725    
726     <h3>Room messages</h3>
727    
728     <p>Not all room messages are for rooms only, and rooms need to parse
729     not only these messages. Orthogonality, what for?</p>
730    
731     <message type="4300" name="join_room" recv="yes">
732 pcg 1.3 <member name="channel" type="U16"/>
733 pcg 1.1 <member name="users" type="user" array="yes"/>
734     </message>
735    
736     <message type="4301" name="msg_room" recv="yes">
737 pcg 1.3 <member name="channel" type="U16"/>
738     <member name="name" type="username"/>
739 pcg 1.1 <member name="message" type="STRING"/>
740     </message>
741    
742     <message type="4302" name="part_room" recv="yes">
743 pcg 1.3 <member name="channel" type="U16"/>
744 pcg 1.1 <member name="user" type="user"/>
745     </message>
746    
747     <message type="4303" name="del_room" recv="yes">
748 pcg 1.3 <member name="channel" type="U16"/>
749 pcg 1.1 </message>
750    
751     <message type="4304" name="upd_games" recv="yes">
752 pcg 1.3 <member name="channel" type="U16"/>
753 pcg 1.1 <member name="games" type="game" array="yes"/>
754     </message>
755    
756     <message type="4319" name="desc_room" recv="yes">
757 pcg 1.3 <member name="channel" type="U16"/>
758     <member name="owner" type="username"/>
759 pcg 1.1 <member name="description" type="STRING"/>
760     </message>
761    
762     <h3>Game messages</h3>
763    
764     <message type="4400" name="upd_chal" recv="yes">
765     Unclear.
766 pcg 1.3 <member name="channel" type="U16"/>
767 pcg 1.1 <member name="challenge" type="challenge"/>
768     </message>
769    
770     <message type="4401" name="upd_game" recv="yes">
771 pcg 1.3 <member name="channel" type="U16"/>
772 pcg 1.1 <member name="game" type="game"/>
773     </message>
774    
775     <message type="4402" name="del_game" recv="yes">
776 pcg 1.3 <member name="channel" type="U16"/>
777 pcg 1.1 </message>
778    
779     <message type="4403" name="upd_observers" recv="yes">
780 pcg 1.3 <member name="channel" type="U16"/>
781 pcg 1.1 <member name="users" type="user" array="yes"/>
782     </message>
783    
784     <message type="4404" name="del_observer" recv="yes">
785 pcg 1.3 <member name="channel" type="U16"/>
786     <member name="name" type="username"/>
787 pcg 1.1 </message>
788    
789     <message type="4405" name="set_tree" recv="yes">
790 pcg 1.3 <member name="channel" type="U16"/>
791 pcg 1.1 <member name="tree" type="TREE"/>
792     </message>
793    
794     <message type="4406" name="upd_tree" recv="yes">
795 pcg 1.3 <member name="channel" type="U16"/>
796 pcg 1.1 <member name="tree" type="TREE"/>
797     </message>
798    
799     <message type="4407" name="set_node" recv="yes">
800 pcg 1.3 <member name="channel" type="U16"/>
801     <member name="node" type="U32"/>
802 pcg 1.1 </message>
803    
804     <message type="4409" name="superko" recv="yes">
805     Superko-warning.
806 pcg 1.3 <member name="channel" type="U16"/>
807 pcg 1.1 </message>
808    
809     <message type="440b" name="final_result" recv="yes">
810 pcg 1.3 <member name="channel" type="U16"/>
811 pcg 1.12 <member name="blackscore" type="scorevalues"/>
812     <member name="whitescore" type="scorevalues"/>
813 pcg 1.1 </message>
814    
815     <message type="440e" name="req_undo" recv="yes">
816 pcg 1.3 <member name="channel" type="U16"/>
817 pcg 1.1
818     </message>
819    
820     <message type="4410" name="resign_game" recv="yes">
821 pcg 1.3 <member name="channel" type="U16"/>
822     <member name="player" type="U8"/>
823 pcg 1.1 </message>
824    
825     <message type="441a" name="set_teacher" recv="yes">
826 pcg 1.3 <member name="channel" type="U16"/>
827     <member name="name" type="username"/>
828 pcg 1.1 </message>
829    
830     <message type="441d" name="owner_left" recv="yes">
831     Unclear.
832 pcg 1.3 <member name="channel" type="U16"/>
833 pcg 1.1 </message>
834    
835     <message type="441e" name="teacher_left" recv="yes">
836     Unclear.
837 pcg 1.3 <member name="channel" type="U16"/>
838 pcg 1.1 </message>
839    
840     <message type="4422" name="unknown4422" recv="yes">
841     change teacher? something to do with editing?
842 pcg 1.3 <member name="channel" type="U16"/>
843     <member name="name1" type="username"/>
844     <member name="name2" type="username"/>
845 pcg 1.1 </message>
846    
847     <message type="4433" name="req_result" recv="yes">
848     Unclear.
849 pcg 1.3 <member name="channel" type="U16"/>
850 pcg 1.1 # # recv_result(?)
851     </message>
852    
853     <message type="4434" name="unknown4434" recv="yes">
854 pcg 1.3 <member name="channel" type="U16"/>
855     <member name="b1" type="U8"/>
856 pcg 1.1 ?? !demonstration game??
857     </message>
858    
859     </body>
860     </html>
861