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.15 by pcg, Tue Jun 10 08:30:11 2003 UTC vs.
Revision 1.16 by pcg, Fri Jun 13 21:20:59 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.15 $</h1> 25<h1>$Revision: 1.16 $</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
… …
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 enwer 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"/>
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
114 <type name="locale" type="A" length="5"/> 121 <type name="locale" type="A" length="5"/>
115 122
116 <p>A kind of locale specifier. It seems the general format seems to be 123 <p>A kind of locale specifier. It seems the general format seems to be
117 lowercase language, underscore, uppercase location, e.g. en_US. More 124 lowercase language, underscore, uppercase location, e.g. en_US. More
118 fancy specifications don't fit.</p> 125 fancy specifications don't fit.</p>
… …
144 151
145 <type name="time" type="U32" multiplier="1000"/> 152 <type name="time" type="U32" multiplier="1000"/>
146 153
147 <p>Time values are multiplied by 1000, giving them millisecond 154 <p>Time values are multiplied by 1000, giving them millisecond
148 accuracy.</p> 155 accuracy.</p>
156
157 <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>
149 161
150<h2>Constants, enumeration and set types used in the protocol.</h2> 162<h2>Constants, enumeration and set types used in the protocol.</h2>
151 163
152 <p>Baaah... not yet.</p> 164 <p>Baaah... not yet.</p>
153 165
… …
240 <member name="group" type="U8" default="1"/> 252 <member name="group" type="U8" default="1"/>
241 <member name="name" type="STRING"/> 253 <member name="name" type="STRING"/>
242 <member name="description" type="STRING"/> 254 <member name="description" type="STRING"/>
243 <member name="flags" type="U8"/> 255 <member name="flags" type="U8"/>
244 0x10 .. private room etc.. see code 256 0x10 .. private room etc.. see code
257 </message>
258
259 <message type="0413" name="game_record" send="yes">
260 Requests part of the users game record to be sent (game_record reply).
261 <member name="name" type="username"/>
262 <member name="timestamp" type="timestamp"/>
263 If zero, start at the newest games, else only send games
264 before the given timestap.
245 </message> 265 </message>
246 266
247 <message type="4300" name="join_room" send="yes"> 267 <message type="4300" name="join_room" send="yes">
248 Joins the given room. join_room messages for yourself 268 Joins the given room. join_room messages for yourself
249 and all users in that room, as well as the initial gamelist, are 269 and all users in that room, as well as the initial gamelist, are
… …
458 <member name="komi" type="komi32"/> 478 <member name="komi" type="komi32"/>
459 <member name="i4" type="U32"/> 479 <member name="i4" type="U32"/>
460 Apparently the i3, f2, i4 are zero. 480 Apparently the i3, f2, i4 are zero.
461 </struct> 481 </struct>
462 482
483 <struct name="game_record" class="KGS::GameRecord">
484 A single game record entry, as seen in userinfo etc.
485
486 <member name="timestamp" type="timestamp"/>
487 Time this game was played.
488 <member name="flags" type="U8"/>
489 High four bits are handicap, low four bits are gametype (encoded strangely? unclear).
490 <member name="user1" type="user"/>
491 White, flags contain low 8 bits of revision (bits 16-23).
492 <member name="user2" type="user"/>
493 Black, flags contain high 8 bits of revision (bits 16-23).
494 <member name="user3" type="user"/>
495 Owner (or empty)
496 <member name="komi" type="komi16"/>
497 <member name="score" type="score16"/>
498 <member name="status" type="U8"/>
499 0x80 inprogress
500 </struct>
501
463<h2>Receive messages</h2> 502<h2>Receive messages</h2>
464 503
465 <message type="0001" name="login" recv="yes"> 504 <message type="0001" name="login" recv="yes">
466 <member name="result" type="CONSTANT" default='"login ok"'/> 505 <member name="result" type="CONSTANT" default='"login ok"'/>
467 <member name="success" type="CONSTANT" default="1"/> 506 <member name="success" type="CONSTANT" default="1"/>
… …
488 </message> 527 </message>
489 528
490 <message type="0006" name="login" recv="yes"> 529 <message type="0006" name="login" recv="yes">
491 <member name="result" type="CONSTANT" default='"user exists"'/> 530 <member name="result" type="CONSTANT" default='"user exists"'/>
492 ** maybe more following? ** 531 ** maybe more following? **
532 </message>
533
534 <message type="0008" name="user_record" recv="yes">
535 User record.
536 <member name="user" type="user"/>
537 <member name="u64" type="timestamp"/>
538 Maybe some time.
539 <member name="realname" type="realname"/>
540 <member name="email" type="email"/>
541 <member name="info" type="userinfo"/>
542 <member name="homepage" type="url"/>
543 <member name="regdate" type="timestamp"/>
544 When the user registered (0 == never registered).
545 <member name="lastlogin" type="timestamp"/>
546 When the user logged in for the last time.
547 <!-- maybe more? -->
493 </message> 548 </message>
494 549
495 <message type="0018" name="login" recv="yes"> 550 <message type="0018" name="login" recv="yes">
496 <member name="result" type="CONSTANT" default='"login error 18"'/> 551 <member name="result" type="CONSTANT" default='"login error 18"'/>
497 ** maybe more following? ** 552 ** maybe more following? **
… …
511 566
512 <message type="0015" name="stats" recv="yes"> 567 <message type="0015" name="stats" recv="yes">
513 <member name="ver_major" type="U16"/> 568 <member name="ver_major" type="U16"/>
514 <member name="ver_minor" type="U16"/> 569 <member name="ver_minor" type="U16"/>
515 <member name="ver_micro" type="U16"/> 570 <member name="ver_micro" type="U16"/>
516 <member name="boot_time" type="U64"/> 571 <member name="boot_time" type="timestamp"/>
517 <member name="users_cur" type="U32"/> 572 <member name="users_cur" type="U32"/>
518 <member name="users_max" type="U32"/> 573 <member name="users_max" type="U32"/>
519 <member name="users_lim" type="U32"/> 574 <member name="users_lim" type="U32"/>
520 <member name="accts_cur" type="U32"/> 575 <member name="accts_cur" type="U32"/>
521 <member name="accts_max" type="U32"/> 576 <member name="accts_max" type="U32"/>
… …
551 <message type="001c" name="idle_err" recv="yes"> 606 <message type="001c" name="idle_err" recv="yes">
552 autologout 607 autologout
553 </message> 608 </message>
554 609
555 <message type="001d" name="ping" recv="yes"> 610 <message type="001d" name="ping" recv="yes">
611 Sent by the server regularly, but not answering them
612 isn't valid. Strange form of keepalive?
556 </message> 613 </message>
557 614
558 <message type="0021" name="userpic" recv="yes"> 615 <message type="0021" name="userpic" recv="yes">
559 <member name="name" type="username"/> 616 <member name="name" type="username"/>
560 Reply to pic_req, contains an image in jpeg format. 617 Reply to pic_req, contains an image in jpeg format.
… …
562 </message> 619 </message>
563 620
564 <message type="0100" name="gnotice" recv="yes"> 621 <message type="0100" name="gnotice" recv="yes">
565 global notice, sent to everybody 622 global notice, sent to everybody
566 <member name="notice" type="STRING"/> 623 <member name="notice" type="STRING"/>
567 </message>
568
569
570 <message type="0310" name="priv_room" recv="yes">
571 "permission denied" when joining a room
572 <member name="name" type="STRING"/>
573 </message>
574
575 <message type="0318" name="upd_rooms" recv="yes">
576 <member name="rooms" type="room" array="yes"/>
577 </message>
578
579 <message type="041c" name="upd_game2" recv="yes">
580 <member name="channel_junk" type="U16"/>
581 <member name="game" type="game"/>
582 </message> 624 </message>
583 625
584 <message type="0202" name="upd_user" recv="yes"> 626 <message type="0202" name="upd_user" recv="yes">
585 # loc 0" type="chat(?) loc 1 => gameinfo?, loc 2 => game result (more data) 627 # loc 0" type="chat(?) loc 1 => gameinfo?, loc 2 => game result (more data)
586 <member name="location" type="U32"/> 628 <member name="location" type="U32"/>
587 <member name="user" type="user"/> 629 <member name="user" type="user"/>
588 <member name="lotsofinfo" type="DATA" guard-member="location" guard-cond="== 2"/> 630 <member name="lotsofinfo" type="DATA" guard-member="location" guard-cond="== 2"/>
589 </message> 631 </message>
590 632
633 <message type="0310" name="priv_room" recv="yes">
634 "permission denied" when joining a room
635 <member name="name" type="STRING"/>
636 </message>
637
638 <message type="0318" name="upd_rooms" recv="yes">
639 <member name="rooms" type="room" array="yes"/>
640 </message>
641
642 <message type="0411" name="chal_defaults" recv="yes">
643 <member name="channel" type="U16"/>
644 <member name="defaults" type="challenge_defaults"/>
645 </message>
646
647 <message type="0414" name="game_record" recv="yes">
648 The users game record.
649 <member name="name" type="username"/>
650 <member name="more" type="flag"/>
651 Wether more games are available (must be requested manually)
652 <member name="games" type="game_record" array="yes"/>
653 </message>
654
655 <message type="041c" name="upd_game2" recv="yes">
656 <member name="channel_junk" type="U16"/>
657 <member name="game" type="game"/>
658 </message>
659
591<h3>Room messages</h3> 660<h3>Room messages</h3>
592 661
593 <p>Not all room messages are for rooms only, and rooms need to parse 662 <p>Not all room messages are for rooms only, and rooms need to parse
594 not only these messages. Orthogonality, what for?</p> 663 not only these messages. Orthogonality, what for?</p>
595 664
… …
609 <member name="user" type="user"/> 678 <member name="user" type="user"/>
610 </message> 679 </message>
611 680
612 <message type="4303" name="del_room" recv="yes"> 681 <message type="4303" name="del_room" recv="yes">
613 <member name="channel" type="U16"/> 682 <member name="channel" type="U16"/>
614
615 </message> 683 </message>
616 684
617 <message type="4304" name="upd_games" recv="yes"> 685 <message type="4304" name="upd_games" recv="yes">
618 <member name="channel" type="U16"/> 686 <member name="channel" type="U16"/>
619 <member name="games" type="game" array="yes"/> 687 <member name="games" type="game" array="yes"/>
… …
621 689
622 <message type="4319" name="desc_room" recv="yes"> 690 <message type="4319" name="desc_room" recv="yes">
623 <member name="channel" type="U16"/> 691 <member name="channel" type="U16"/>
624 <member name="owner" type="username"/> 692 <member name="owner" type="username"/>
625 <member name="description" type="STRING"/> 693 <member name="description" type="STRING"/>
626 </message>
627
628
629 <message type="0411" name="chal_defaults" recv="yes">
630 <member name="channel" type="U16"/>
631 <member name="defaults" type="challenge_defaults"/>
632 </message> 694 </message>
633 695
634<h3>Game messages</h3> 696<h3>Game messages</h3>
635 697
636 <message type="4400" name="upd_chal" recv="yes"> 698 <message type="4400" name="upd_chal" recv="yes">

Diff Legend

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