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.8 by pcg, Thu Jun 5 17:23:05 2003 UTC vs.
Revision 1.9 by pcg, Thu Jun 5 17:54:18 2003 UTC

… …
83 number is always the next U16. 83 number is always the next U16.
84 </struct> 84 </struct>
85 85
86<h2>Primitive types used in the protocol.</h2> 86<h2>Primitive types used in the protocol.</h2>
87 87
88 <p>Baaah... not much yet.</p> 88 <p>Apart from the basic types, I need to define some extra types to
89 deal with fixed-point values (based on integer types) or fixed-length
90 strings (either 7-bit-ascii or more limited (<code>A</code>), or UCS-2
91 based (<code>S</code>)).</p>
89 92
90 <type name="username" type="A" length="12"/> 93 <type name="username" type="A" length="12"/>
94
95 <p>The basic user or login name, used throughout the protocol
96 as a handle to the user.</p>
97
91 <type name="roomname" type="S" length="25"/><!-- argh, how horribly broken --> 98 <type name="roomname" type="S" length="25"/><!-- argh, how horribly broken -->
99
100 <p>Many strings in the protocol are fixed-width for no good reason
101 (maybe this is one reason for using compression in enwer versions, as
102 the packets itself are wasting lots of space.</p>
103
92 <type name="locale" type="A" length="5"/> 104 <type name="locale" type="A" length="5"/>
105
106 <p>A kind of locale specifier. It seems the general format seems to be
107 lowercase language, underscore, uppercase location, e.g. en_US. More
108 fancy specifications don't fit.</p>
109
93 <type name="flag" type="U8" multiplier="1"/> 110 <type name="flag" type="U8" multiplier="1"/>
111
112 <p>Just a simple boolean value. 0 means false, and 1 generally true,
113 but I suggest ccepting != 0 as true.</p>
114
94 <type name="komi16" type="I16" multiplier="2"/> 115 <type name="komi16" type="I16" multiplier="2"/>
95 <type name="komi32" type="I32" multiplier="2"/> 116 <type name="komi32" type="I32" multiplier="2"/>
117
118 <p>Komi values are multiplied by 2 to make them integer in the
119 protocol. Of course, sometimes they are encoded in 16 bits, sometimes
120 in 32. Get used to this.</p>
121
96 <type name="result" type="I32" multiplier="2"/> 122 <type name="result" type="I32" multiplier="2"/>
123
124 <p>The game result is also multiplied by four to give it higher
125 resolution. There are also special values for wins by time etc.</p>
126
97 <type name="score" type="I32" multiplier="4"/> 127 <type name="score" type="I32" multiplier="4"/>
128
129 <p>A score value (used for displaying the score at the end of a game)
130 are multiplied by four for a change. I have not yet seen 0.25 scores,
131 please somebody tell me where they happen, or if they happen.</p>
132
98 <type name="time" type="U32" multiplier="1000"/> 133 <type name="time" type="U32" multiplier="1000"/>
99 134
135 <p>Time values are multiplied by 1000, giving them millisecond
136 accuracy.</p>
137
100<h2>Constants, enumeration and set types used in the protocol.</h2> 138<h2>Constants, enumeration and set types used in the protocol.</h2>
101 139
102 <p>Baaah... not yet.</p> 140 <p>Baaah... not yet.</p>
103 141
104<h2>Structs used in send &amp; receive messages</h2> 142<h2>Structs used in send &amp; receive messages</h2>
105 143
106 <struct name="user" class="KGS::User"> 144 <struct name="user" class="KGS::User">
145
146 Everywhere a user + flags is required, even used in some places
147 where only a username is required. I see no general rule on when a
148 complete user and when a partial user is required.
149
107 <member name="name" type="username"/> 150 <member name="name" type="username"/>
108 <member name="flags" type="U32" default="1"/> 151 <member name="flags" type="U32" default="1"/>
109 </struct> 152 </struct>
110 153
111 <struct name="rules" class="KGS::Rules"> 154 <struct name="rules" class="KGS::Rules">
155
156 This structure is used for challanges as well as in the special
157 TREE "subprotocol". It tightly encodes the game parameters.
158
112 <member name="ruleset" type="U8"/> 159 <member name="ruleset" type="U8"/>
113 <member name="size" type="U8"/> 160 <member name="size" type="U8"/>
114 <member name="handicap" type="U8"/> 161 <member name="handicap" type="U8"/>
115 <member name="komi" type="komi16"/> 162 <member name="komi" type="komi16"/>
116 <member name="timesys" type="U8"/> 163 <member name="timesys" type="U8"/>
… …
122 </struct> 169 </struct>
123 170
124<h2>Structs used in send messages</h2> 171<h2>Structs used in send messages</h2>
125 172
126 <message type="0000" name="login" send="yes"> 173 <message type="0000" name="login" send="yes">
174
175 Send on the initial login. The password needs to be set when the
176 guest flag is true.
177
127 <member name="ver_major" type="U32" default="2"/> 178 <member name="ver_major" type="U32" default="2"/>
128 <member name="ver_minor" type="U32" default="4"/> 179 <member name="ver_minor" type="U32" default="4"/>
129 <member name="ver_micro" type="U32" default="67"/> 180 <member name="ver_micro" type="U32" default="67"/>
130 <member name="name" type="username"/> 181 <member name="name" type="username"/>
131 <member name="password " type="U64" default="0"/> 182 <member name="password " type="U64" default="0"/>
… …
143 <message type="0014" name="server_stats" send="yes"> 194 <message type="0014" name="server_stats" send="yes">
144 Request server statistics. 195 Request server statistics.
145 </message> 196 </message>
146 197
147 <message type="0021" name="pic_req" send="yes"> 198 <message type="0021" name="pic_req" send="yes">
148 Request a user picture from the server. 199 Request a user picture from the server. Results in a userpic-reply
200 or a timeout :/.
149 <member name="name" type="username"/> 201 <member name="name" type="username"/>
150 </message> 202 </message>
151 203
152 <message type="0021" name="pic_upload" send="yes"> 204 <message type="0021" name="pic_upload" send="yes">
153 Same code as pic_req, but with an additional data section that 205 Same code as pic_req, but with an additional data section that
… …
160 Send a global message. Maybe. Never tried, for obvious reasons :/ 212 Send a global message. Maybe. Never tried, for obvious reasons :/
161 <member name="notice" type="STRING"/> 213 <member name="notice" type="STRING"/>
162 </message> 214 </message>
163 215
164 <message type="0318" name="list_rooms" send="yes"> 216 <message type="0318" name="list_rooms" send="yes">
165 List the rooms in a specific group/category. 217 List the rooms in a specific group/category. Results in a upd_rooms message.
166 <member name="group" type="U8"/> 218 <member name="group" type="U8"/>
167 </message> 219 </message>
168 220
169 <message type="031a" name="new_room" send="yes"> 221 <message type="031a" name="new_room" send="yes">
170 Create a new room. Not verified. 222 Create a new room. Not verified.
… …
179 <member name="flags" type="U8"/> 231 <member name="flags" type="U8"/>
180 0x10 .. private room etc.. see code 232 0x10 .. private room etc.. see code
181 </message> 233 </message>
182 234
183 <message type="4300" name="join_room" send="yes"> 235 <message type="4300" name="join_room" send="yes">
236 Joins the given room. join_room messages for yourself
237 and all users in that room, as well as the initial gamelist, are
238 send if the room exists. If not, timeout...
184 <member name="channel" type="U16"/> 239 <member name="channel" type="U16"/>
185 <member name="user" type="user"/> 240 <member name="user" type="user"/>
186 </message> 241 </message>
187 242
188 <message type="4301" name="msg_room" send="yes"> 243 <message type="4301" name="msg_room" send="yes">
189 <member name="channel" type="U16"/> 244 Send a message to the room.
190 <member name="name" type="username"/> 245 <member name="channel" type="U16"/>
246 <member name="name" type="username"/>
247 Must be the login-name of the user.
191 <member name="message" type="STRING"/> 248 <member name="message" type="STRING"/>
192 </message> 249 </message>
193 250
194 <message type="4302" name="part_room" send="yes"> 251 <message type="4302" name="part_room" send="yes">
252 Remove yourself (or maybe others as admin) from a room.
195 <member name="channel" type="U16"/> 253 <member name="channel" type="U16"/>
196 <member name="name" type="username"/> 254 <member name="name" type="username"/>
197 </message> 255 </message>
198 256
199 <message type="4305" name="new_game" send="yes"> 257 <message type="4305" name="new_game" send="yes">
258 Unclear.
200 <member name="channel" type="U16"/> 259 <member name="channel" type="U16"/>
201 <member name="id" type="U16"/> 260 <member name="id" type="U16"/>
202 <member name="gametype" type="U32"/> 261 <member name="gametype" type="U32"/>
203 <member name="rules" type="rules"/> 262 <member name="rules" type="rules"/>
204 <member name="notes" type="STRING"/> 263 <member name="notes" type="STRING"/>
205 </message> 264 </message>
206 265
207 <message type="430b" name="req_games" send="yes"> 266 <message type="430b" name="req_games" send="yes">
208 request to update room game list (send once per minute) 267 Request to update room game list (send this once per minute to get
268 updated). Results in upd_games messages.
209 <member name="channel" type="U16"/> 269 <member name="channel" type="U16"/>
210 </message> 270 </message>
211 271
212 <message type="4319" name="req_desc" send="yes"> 272 <message type="4319" name="req_desc" send="yes">
213 Request room description. 273 Request room description.
214 <member name="channel" type="U16"/> 274 <member name="channel" type="U16"/>
215 </message> 275 </message>
216 276
217 <message type="4400" name="send_chal" send="yes"> 277 <message type="4400" name="send_chal" send="yes">
218 No idea. 278 Unclear.
219 <member name="channel" type="U16"/> 279 <member name="channel" type="U16"/>
220 <member name="black" type="username"/> 280 <member name="black" type="username"/>
221 <member name="white" type="username"/> 281 <member name="white" type="username"/>
222 More following... TREE or challenge. 282 More following... TREE or challenge.
223 </message> 283 </message>
224 284
225 <message type="4403" name="join_game" send="yes"> 285 <message type="4403" name="join_game" send="yes">
286 Join a game. See join_room.
226 <member name="channel" type="U16"/> 287 <member name="channel" type="U16"/>
227 <member name="user" type="user"/> 288 <member name="user" type="user"/>
228 </message> 289 </message>
229 290
230 <message type="4404" name="part_game" send="yes"> 291 <message type="4404" name="part_game" send="yes">
292 Leave (or kick as admin?) a certain user from a game.
231 <member name="channel" type="U16"/> 293 <member name="channel" type="U16"/>
232 <member name="name" type="username"/> 294 <member name="name" type="username"/>
233 </message> 295 </message>
234 296
235 <message type="4405" name="set_tree" send="yes"> 297 <message type="4405" name="set_tree" send="yes">
298 Upload a partial game tree to the server. This is used
299 to send moves and even in-game comments to the server. For the comments,
300 the server prepends the username and rank.
236 <member name="channel" type="U16"/> 301 <member name="channel" type="U16"/>
237 <member name="tree" type="TREE"/> 302 <member name="tree" type="TREE"/>
238 </message> 303 </message>
239 304
240 <message type="4408" name="get_tree" send="yes"> 305 <message type="4408" name="get_tree" send="yes">
306 Request the game tree starting at a given node. This is used
307 when the server only sends a partial tree (with end code "more").
241 <member name="channel" type="U16"/> 308 <member name="channel" type="U16"/>
242 <member name="node" type="U32"/> 309 <member name="node" type="U32"/>
243 </message> 310 </message>
244 311
245 <message type="440c" name="claim_win" send="yes"> 312 <message type="440c" name="claim_win" send="yes">
313 Unclear.
246 <member name="channel" type="U16"/> 314 <member name="channel" type="U16"/>
247 <member name="_byte" type="U8 "/> 315 <member name="_byte" type="U8 "/>
248 Player colour maybe? Unclear. 316 Player colour maybe? Unclear.
249 </message> 317 </message>
250 318
251 <message type="440d" name="add_time" send="yes"> 319 <message type="440d" name="add_time" send="yes">
320 Not checked.
321
252 <member name="channel" type="U16"/> 322 <member name="channel" type="U16"/>
253 <member name="time" type="U32"/> 323 <member name="time" type="U32"/>
254 <member name="player" type="U8"/> 324 <member name="player" type="U8"/>
255 </message> 325 </message>
256 326
257 <message type="440f" name="grant_undo" send="yes"> 327 <message type="440f" name="grant_undo" send="yes">
328 Can be send after a req_undo message was received to grant the undo.
258 <member name="channel" type="U16"/> 329 <member name="channel" type="U16"/>
259 </message> 330 </message>
260 331
261 <message type="4410" name="resign_game" send="yes"> 332 <message type="4410" name="resign_game" send="yes">
333 Resign the game.
262 <member name="channel" type="U16"/> 334 <member name="channel" type="U16"/>
263 <member name="player" type="U8"/> 335 <member name="player" type="U8"/>
264 </message> 336 </message>
265 337
266 <message type="441a" name="set_teacher" send="yes"> 338 <message type="441a" name="set_teacher" send="yes">
339 Change the teacher to somebody else (or possibly yourself == take it).
267 <member name="channel" type="U16"/> 340 <member name="channel" type="U16"/>
268 <member name="name" type="username"/> 341 <member name="name" type="username"/>
269 </message> 342 </message>
270 343
271 <message type="4422" name="add_user" send="yes"> 344 <message type="4422" name="add_user" send="yes">
345 Unclear. Maybe allow users to talk? No idea, really.
346
272 <member name="channel" type="U16"/> 347 <member name="channel" type="U16"/>
273 <member name="othername" type="username"/> 348 <member name="othername" type="username"/>
274 <member name="name" type="username"/>; # gives user access to the game (to what? ;) 349 <member name="name" type="username"/>; # gives user access to the game (to what? ;)
275 </message> 350 </message>
276 351
277 <message type="4423" name="set_privacy" send="yes"> 352 <message type="4423" name="set_privacy" send="yes">
353 Probably sets the "quiet" flag. Not checked.
278 <member name="channel" type="U16"/> 354 <member name="channel" type="U16"/>
279 <member name="private" type="U8"/> 355 <member name="private" type="U8"/>
280 </message> 356 </message>
281 357
282 <message type="4429" name="reject_chal" send="yes"> 358 <message type="4429" name="reject_chal" send="yes">
359 Reject a challenge from a given user. Not checked.
360
283 <member name="channel" type="U16"/> 361 <member name="channel" type="U16"/>
284 <member name="name" type="username"/> 362 <member name="name" type="username"/>
285 </message> 363 </message>
286 364
287 <message type="4433" name="req_result" send="yes"> 365 <message type="4433" name="req_result" send="yes">
366 I forgot.
367
288 <member name="channel" type="U16"/> 368 <member name="channel" type="U16"/>
289 </message> 369 </message>
290 370
291<h2>Structs mainly used in receive messages</h2> 371<h2>Structs mainly used in receive messages</h2>
292 372
293 <struct name="challenge_defaults"> 373 <struct name="challenge_defaults">
374 Send soon after log-in to set the defaults for game challenges.
294 <member name="gametype" type="U32"/> 375 <member name="gametype" type="U32"/>
295 <member name="size" type="U32"/> 376 <member name="size" type="U32"/>
296 <member name="timesys" type="U32"/> 377 <member name="timesys" type="U32"/>
297 <member name="time" type="U32"/> 378 <member name="time" type="U32"/>
298 <member name="byo_time" type="U32"/> 379 <member name="byo_time" type="U32"/>
… …
300 <member name="can_time" type="U32"/> 381 <member name="can_time" type="U32"/>
301 <member name="can_stones" type="U32"/> 382 <member name="can_stones" type="U32"/>
302 </struct> 383 </struct>
303 384
304 <struct name="challenge" class="KGS::Challenge"> 385 <struct name="challenge" class="KGS::Challenge">
386 A challenge.
387
305 <member name="user1" type="user"/> 388 <member name="user1" type="user"/>
306 <member name="user2" type="user"/> 389 <member name="user2" type="user"/>
307 <member name="gametype" type="U32"/> 390 <member name="gametype" type="U32"/>
308 <member name="rules" type="rules"/> 391 <member name="rules" type="rules"/>
309 Maybe the rules" are in TREE format. I forgot. 392 Maybe the rules" are in TREE format. I forgot.
310 </struct> 393 </struct>
311 394
312 <struct name="game" class="KGS::Game"> 395 <struct name="game" class="KGS::Game">
396 Basic information about a game. Used in rooms for the gamelist and
397 in games to detect when a game is saved, changed type (e.g. R => D)
398 etc.
399
313 <member name="channel" type="U16"/> 400 <member name="channel" type="U16"/>
314 <member name="type" type="U32"/> 401 <member name="type" type="U32"/>
315 <member name="user1" type="user"/> 402 <member name="user1" type="user"/>
316 White 403 White
317 <member name="user2" type="user"/> 404 <member name="user2" type="user"/>
… …
328 <member name="saved" type="flag"/> 415 <member name="saved" type="flag"/>
329 <member name="notes" type="STRING" guard-member="handicap" guard-cond="&lt; 0"/> 416 <member name="notes" type="STRING" guard-member="handicap" guard-cond="&lt; 0"/>
330 </struct> 417 </struct>
331 418
332 <struct name="room_obs"> 419 <struct name="room_obs">
420 Obsolete.
421
333 <member name="name" type="roomname"/> 422 <member name="name" type="roomname"/>
334 <member name="channel" type="U16"/> 423 <member name="channel" type="U16"/>
335 <member name="flags" type="U32"/> 424 <member name="flags" type="U32"/>
336 <member name="users" type="U32"/> 425 <member name="users" type="U32"/>
337 </struct> 426 </struct>

Diff Legend

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