ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/kgsueme/doc/protocol.xml
(Generate patch)

Comparing kgsueme/doc/protocol.xml (file contents):
Revision 1.17 by pcg, Fri Jun 13 22:11:50 2003 UTC vs.
Revision 1.18 by pcg, Sat Jun 14 09:19:28 2003 UTC

… …
20 Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 20 Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
21--> 21-->
22</head> 22</head>
23<body> 23<body>
24 24
25<h1>$Revision: 1.17 $</h1> 25<h1>$Revision: 1.18 $</h1>
26 26
27<h1>KGS Protocol Description</h1> 27<h1>KGS Protocol Description</h1>
28 28
29 <p>This XML document describes the KGS protocol. It is also used 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 30 to automatically generate the perl parser for all the messages and
… …
85 <p>All messages have the same header:</p> 85 <p>All messages have the same header:</p>
86 86
87 <struct name="message_header" send="yes" recv="yes"> 87 <struct name="message_header" send="yes" recv="yes">
88 <member name="_unknown" type="U16"/> 88 <member name="_unknown" type="U16"/>
89 <member name="length" type="U16"/> 89 <member name="length" type="U16"/>
90 The length is the length of the full message including the header. 90 <p>The length is the length of the full message including the header.</p>
91 <member name="type" type="U16"/> 91 <member name="type" type="U16"/>
92 If the type is &gt;= 0x4000 this is a message for a specific channel. The channel 92 <p>If the type is &gt;= 0x4000 this is a message for a specific channel. The channel
93 number is always the next U16. 93 number is always the next U16.</p>
94 </struct> 94 </struct>
95 95
96<h2>Primitive types used in the protocol.</h2> 96<h2>Primitive types used in the protocol.</h2>
97 97
98 <p>Apart from the basic types, I need to define some extra types to 98 <p>Apart from the basic types, I need to define some extra types to
… …
106 as a handle to the user.</p> 106 as a handle to the user.</p>
107 107
108 <type name="roomname" type="S" length="25"/><!-- argh, how horribly broken --> 108 <type name="roomname" type="S" length="25"/><!-- argh, how horribly broken -->
109 109
110 <p>Many strings in the protocol are fixed-width for no good reason 110 <p>Many strings in the protocol are fixed-width for no good reason
111 (maybe this is one reason for using compression in enwer versions, as 111 (maybe this is one reason for using compression in newer versions, as
112 the packets itself are wasting lots of space.</p> 112 the packets itself are wasting lots of space.</p>
113 113
114 <type name="realname" type="S" length="50"/> 114 <type name="realname" type="S" length="50"/>
115 <type name="email" type="S" length="70"/> 115 <type name="email" type="S" length="70"/>
116 <type name="userinfo" type="S" length="1000"/> 116 <type name="userinfo" type="S" length="1000"/>
… …
171 171
172<h2>Structs used in send &amp; receive messages</h2> 172<h2>Structs used in send &amp; receive messages</h2>
173 173
174 <struct name="user" class="KGS::User"> 174 <struct name="user" class="KGS::User">
175 175
176 Everywhere a user + flags is required, even used in some places 176 <p>Everywhere a user + flags is required, even used in some places
177 where only a username is required. I see no general rule on when a 177 where only a username is required. I see no general rule on when a
178 complete user and when a partial user is required. 178 complete user and when a partial user is required.</p>
179 179
180 <member name="name" type="username"/> 180 <member name="name" type="username"/>
181 <member name="flags" type="U32" default="1"/> 181 <member name="flags" type="U32" default="1"/>
182 </struct> 182 </struct>
183 183
184 <struct name="rules" class="KGS::Rules"> 184 <struct name="rules" class="KGS::Rules">
185 185
186 This structure is used for challanges as well as in the special 186 <p>This structure is used for challanges as well as in the special
187 TREE "subprotocol". It tightly encodes the game parameters. 187 TREE "subprotocol". It tightly encodes the game parameters.</p>
188 188
189 <member name="ruleset" type="U8"/> 189 <member name="ruleset" type="U8"/>
190 <member name="size" type="U8"/> 190 <member name="size" type="U8"/>
191 <member name="handicap" type="U8"/> 191 <member name="handicap" type="U8"/>
192 <member name="komi" type="komi16"/> 192 <member name="komi" type="komi16"/>
… …
198 periods / moves 198 periods / moves
199 </struct> 199 </struct>
200 200
201<h2>Structs used in send messages</h2> 201<h2>Structs used in send messages</h2>
202 202
203<h2>Send messages</h2>
204
203 <message type="0000" name="login" send="yes"> 205 <message type="0000" name="login" send="yes">
204 206
205 Send on the initial login. The password needs to be set when the 207 <p>Sent to login, usually the first message sent. The password needs to be set when the
206 guest flag is true. 208 guest flag is true.
209 Possible replies: <ref reply="login"/>. Followed by: <ref reply="timewarning_default"/> <ref reply="chal_defaults"/>
210 </p>
207 211
208 <member name="ver_major" type="U32" default="2"/> 212 <member name="ver_major" type="U32" default="2"/>
209 <member name="ver_minor" type="U32" default="4"/> 213 <member name="ver_minor" type="U32" default="4"/>
210 <member name="ver_micro" type="U32" default="67"/> 214 <member name="ver_micro" type="U32" default="67"/>
211 <member name="name" type="username"/> 215 <member name="name" type="username"/>
… …
213 <member name="guest" type="flag" default="1"/> 217 <member name="guest" type="flag" default="1"/>
214 <member name="_unknown3" type="U16" default="0"/> 218 <member name="_unknown3" type="U16" default="0"/>
215 <member name="locale" type="locale" default='"en_US"'/> 219 <member name="locale" type="locale" default='"en_US"'/>
216 <member name="clientver" type="DATA" default='"1.4.1_01:Swing app:Sun Microsystems Inc."'/> 220 <member name="clientver" type="DATA" default='"1.4.1_01:Swing app:Sun Microsystems Inc."'/>
217 The "default" is the java vm version, not exactly he client version. However, 221 The "default" is the java vm version, not exactly he client version. However,
218 you should always send a tetx like "Jonathan's C client bersion 0.6" or somesuch, 222 you should always send a text like "Jonathan's C client bersion 0.6" or somesuch,
219 so the server can, if necessary, block broken clients or client versions. 223 so the server can, if necessary, block broken clients or client versions.
220 </message> 224 </message>
221 225
222 <message type="0007" name="req_userinfo" send="yes"> 226 <message type="0007" name="req_userinfo" send="yes">
223 Request info about a certain user. 227 <p>Request info about a certain user. Possible reply: <ref reply="userinfo"/></p>
224 <member name="name" type="username"/> 228 <member name="name" type="username"/>
225 </message> 229 </message>
226 230
227 <message type="0007" name="req_userinfo" send="yes"> 231 <message type="0007" name="update_userinfo" send="yes">
228 Update user info. Message structure is very similar 232 <p>Update user info. Message structure is very similar
229 to "userinfo". 233 to <ref ref="userinfo"/>.</p>
230 <member name="setpass" type="flag"/> 234 <member name="setpass" type="flag"/>
231 Should the password be updated? 235 Should the password be updated?
232 <member name="password" type="password" default="0"/> 236 <member name="password" type="password" default="0"/>
233 <member name="realname" type="realname"/> 237 <member name="realname" type="realname"/>
234 <member name="email" type="email"/> 238 <member name="email" type="email"/>
… …
236 <member name="homepage" type="url"/> 240 <member name="homepage" type="url"/>
237 <member name="_unused" type="U64" default="0"/> 241 <member name="_unused" type="U64" default="0"/>
238 <member name="_unused" type="U64" default="0"/> 242 <member name="_unused" type="U64" default="0"/>
239 </message> 243 </message>
240 244
241 <message type="0014" name="server_stats" send="yes"> 245 <message type="0014" name="req_stats" send="yes">
242 Request server statistics. 246 <p>Request server statistics. Replied with <ref reply="stats"/></p>
243 </message> 247 </message>
244 248
245 <message type="001e" name="req_usergraph" send="yes"> 249 <message type="001e" name="req_usergraph" send="yes">
246 Request user graph data, (see usergraph). 250 <p>Request user graph data, replied with <ref reply="usergraph"/>.</p>
247 <member name="name" type="username"/> 251 <member name="name" type="username"/>
248 </message> 252 </message>
249 253
250 <message type="001f" name="fetch_memos" send="yes"> 254 <message type="001f" name="fetch_memos" send="yes">
251 Unclear. Fetch all outstanding memos? 255 <p>Unclear. Fetch all outstanding memos? Replied with <ref reply="memo"/></p>
252 </message> 256 </message>
253 257
254 <message type="0021" name="req_pic" send="yes"> 258 <message type="0021" name="req_pic" send="yes">
255 Request a user picture from the server. Results in a userpic-reply 259 <p>Request a user picture from the server. Results in a <ref reply="userpic"/>
256 or a timeout :/. 260 or a timeout.</p>
257 <member name="name" type="username"/> 261 <member name="name" type="username"/>
258 </message> 262 </message>
259 263
260 <message type="0021" name="upload_pic" send="yes"> 264 <message type="0021" name="upload_pic" send="yes">
261 Same code as pic_req, but with an additional data section that 265 Same code as pic_req, but with an additional data section that
… …
263 <member name="name" type="username"/> 267 <member name="name" type="username"/>
264 <member name="data" type="DATA"/> 268 <member name="data" type="DATA"/>
265 </message> 269 </message>
266 270
267 <message type="0100" name="gnotice" send="yes"> 271 <message type="0100" name="gnotice" send="yes">
268 Send a global message. Maybe. Never tried, for obvious reasons :/ 272 <p>Send a global message. Maybe. Never tried, for obvious reasons :/. Results
273 in a <ref reply="gnotice"/> sent to all users.</p>
269 <member name="notice" type="STRING"/> 274 <member name="notice" type="STRING"/>
270 </message> 275 </message>
271 276
272 <message type="0318" name="list_rooms" send="yes"> 277 <message type="0318" name="list_rooms" send="yes">
273 List the rooms in a specific group/category. Results in a upd_rooms message. 278 <p>List the rooms in a specific group/category. Results in a <ref reply="upd_rooms"/> message.</p>
274 <member name="group" type="U8"/> 279 <member name="group" type="U8"/>
275 </message> 280 </message>
276 281
277 <message type="031a" name="new_room" send="yes"> 282 <message type="031a" name="new_room" send="yes">
278 Create a new room. Not verified. 283 Create a new room. Not verified.
… …
287 <member name="flags" type="U8"/> 292 <member name="flags" type="U8"/>
288 0x10 .. private room etc.. see code 293 0x10 .. private room etc.. see code
289 </message> 294 </message>
290 295
291 <message type="0413" name="req_game_record" send="yes"> 296 <message type="0413" name="req_game_record" send="yes">
292 Requests part of the users game record to be sent (game_record reply). 297 <p>Requests part of the users game record to be sent. Results in a <ref reply="game_record"/> or maybe a timeout.</p>
293 <member name="name" type="username"/> 298 <member name="name" type="username"/>
294 <member name="timestamp" type="timestamp"/> 299 <member name="timestamp" type="timestamp"/>
295 If zero, start at the newest games, else only send games 300 If zero, start at the newest games, else only send games
296 before the given timestap. 301 before the given timestap.
297 </message> 302 </message>
298 303
299 <message type="4300" name="join_room" send="yes"> 304 <message type="4300" name="join_room" send="yes">
300 Joins the given room. join_room messages for yourself 305 <p>Joins the given room. <ref reply="join_room"/> messages for yourself
301 and all users in that room, as well as the initial gamelist, are 306 and all users in that room, as well as the initial gamelist, are
302 send if the room exists. If not, timeout... 307 send if the room exists. If not, timeout...</p>
303 <member name="channel" type="U16"/> 308 <member name="channel" type="U16"/>
304 <member name="user" type="user"/> 309 <member name="user" type="user"/>
305 </message> 310 </message>
306 311
307 <message type="4301" name="msg_room" send="yes"> 312 <message type="4301" name="msg_room" send="yes">
… …
511 <member name="i4" type="U32"/> 516 <member name="i4" type="U32"/>
512 Apparently the i3, f2, i4 are zero. 517 Apparently the i3, f2, i4 are zero.
513 </struct> 518 </struct>
514 519
515 <struct name="game_record" class="KGS::GameRecord"> 520 <struct name="game_record" class="KGS::GameRecord">
516 A single game record entry, as seen in userinfo etc. 521 <p>A single game record entry, as seen in <ref ref="userinfo"/>.</p>
517 522
518 <member name="timestamp" type="timestamp"/> 523 <member name="timestamp" type="timestamp"/>
519 Time this game was played. 524 Time this game was played.
520 <member name="flags" type="U8"/> 525 <member name="flags" type="U8"/>
521 High four bits are handicap, low four bits are gametype (encoded strangely? unclear). 526 High four bits are handicap, low four bits are gametype (encoded strangely? unclear).

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines