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.59 by pcg, Sat May 29 06:38:27 2004 UTC vs.
Revision 1.60 by pcg, Sun May 30 02:22:24 2004 UTC

… …
21 Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 21 Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
22--> 22-->
23</head> 23</head>
24<body> 24<body>
25 25
26<h1>$Revision: 1.59 $</h1> 26<h1>$Revision: 1.60 $</h1>
27 27
28<h1>KGS Protocol Description</h1> 28<h1>KGS Protocol Description</h1>
29 29
30 <p>This XML document describes the KGS protocol. It is also used 30 <p>This XML document describes the KGS protocol. It is also used
31 to automatically generate the perl parser for all the messages and 31 to automatically generate the perl parser for all the messages and
… …
192 192
193 <p>Password is a number calculated as follows (VERY insecure, basically 193 <p>Password is a number calculated as follows (VERY insecure, basically
194 plaintext!): <code>password = 0; for char in characters do password ← 194 plaintext!): <code>password = 0; for char in characters do password ←
195 password * 1055 + ascii_code (char)</code></p> 195 password * 1055 + ascii_code (char)</code></p>
196 196
197 <type name="clientid" type="U16" multiplier="1"/> 197 <type name="CLIENTID16" type="U16" multiplier="1"/>
198 <type name="CLIENTID8" type="U8" multiplier="1"/>
198 199
199 <p>An id chosen by the client, usually starting at one, to identify 200 <p>An id chosen by the client, usually starting at one, to identify
200 some handshakes initiated by the client, such as new games or memos.</p> 201 some handshakes initiated by the client, such as new games or memos.</p>
201 202
202<h2>Enumeration and set types used in the protocol.</h2> 203<h2>Enumeration and set types used in the protocol.</h2>
… …
364 <message type="0016" name="idle_reset" src="client"> 365 <message type="0016" name="idle_reset" src="client">
365 <p>Send in response to <ref reply="idle_warn"/> to keep the server from disconnecting.</p> 366 <p>Send in response to <ref reply="idle_warn"/> to keep the server from disconnecting.</p>
366 </message> 367 </message>
367 368
368 <message type="001d" name="ping" src="client"> 369 <message type="001d" name="ping" src="client">
369 <p>Wild guess, I send it in <ref ref="idle_warn"/>.</p> 370 <p>No idea. Not used anymore?</p>
370 </message> 371 </message>
371 372
372 <message type="001e" name="req_usergraph" src="client"> 373 <message type="001e" name="req_usergraph" src="client">
373 <p>Request user graph data, replied with <ref reply="usergraph"/>.</p> 374 <p>Request user graph data, replied with <ref reply="usergraph"/>.</p>
374 <member name="name" type="username"/> 375 <member name="name" type="username"/>
… …
387 <member name="data" type="DATA"/> 388 <member name="data" type="DATA"/>
388 </message> 389 </message>
389 390
390 <message type="0023" name="send_memo" src="client"> 391 <message type="0023" name="send_memo" src="client">
391 <member name="name" type="username"/> 392 <member name="name" type="username"/>
392 <member name="cid" type="clientid"/> 393 <member name="cid" type="CLIENTID16"/>
393 <p>A boolean, probably. Always true for me.</p> 394 <p>A boolean, probably. Always true for me.</p>
394 <member name="msg" type="STRING"/> 395 <member name="msg" type="STRING"/>
395 </message> 396 </message>
396 397
397 <message type="0024" name="delete_memos" src="client"> 398 <message type="0024" name="delete_memos" src="client">
… …
477 <message type="4305" name="new_game" src="client"> 478 <message type="4305" name="new_game" src="client">
478 <p>Create a new game.</p> 479 <p>Create a new game.</p>
479 480
480 <member name="channel" type="U16"/> 481 <member name="channel" type="U16"/>
481 <p>The room where to start the new game</p> 482 <p>The room where to start the new game</p>
482 <member name="cid" type="clientid"/> 483 <member name="cid" type="CLIENTID16"/>
483 <member name="type" type="U8"/> 484 <member name="gametype" type="U8"/>
484 <p> 485 <p>
485 GAMETYPE_UPLOAD probably not allowed. GAMETYPE_PRIVATE 486 GAMETYPE_UPLOAD probably not allowed. GAMETYPE_PRIVATE
486 only allowd together with GAMETYPE_TEACHING, GAMETYPE_DEMONSTRATION. 487 only allowd together with GAMETYPE_TEACHING, GAMETYPE_DEMONSTRATION.
487 </p> 488 </p>
488 <member name="flags" type="U8"/> 489 <member name="flags" type="U8"/>
… …
524 </message> 525 </message>
525 526
526 <message type="4400" name="challenge" src="client"> 527 <message type="4400" name="challenge" src="client">
527 <p>Used to send challenges to existing games.</p> 528 <p>Used to send challenges to existing games.</p>
528 <member name="channel" type="U16"/> 529 <member name="channel" type="U16"/>
530 <member name="black" type="user"/>
531 <member name="white" type="user"/>
532 <member name="gametype" type="U8"/>
533 <member name="cid" type="CLIENTID8"/>
534 <p>Possibly an id. No idea. Better echo this from the challenge request.</p>
529 <member name="challenge" type="challenge"/> 535 <member name="rules" type="rules"/>
530 </message> 536 </message>
531 537
532 <message type="4403" name="join_game" src="client"> 538 <message type="4403" name="join_game" src="client">
533 Join a game. See join_room. 539 Join a game. See join_room.
534 <member name="channel" type="U16"/> 540 <member name="channel" type="U16"/>
… …
547 <member name="channel" type="U16"/> 553 <member name="channel" type="U16"/>
548 <member name="tree" type="TREE"/> 554 <member name="tree" type="TREE"/>
549 </message> 555 </message>
550 556
551 <message type="4406" name="upd_tree" src="client"> 557 <message type="4406" name="upd_tree" src="client">
552 Upload a partial game tree to the server. This is used to send moves 558 <p>Upload a partial game tree to the server. This is used to send moves
553 and even in-game comments to the server. For the comments, the 559 and even in-game comments to the server. For the comments, the
554 server prepends the username and rank. 560 server prepends the username and rank.</p>
555 561
556 <member name="channel" type="U16"/> 562 <member name="channel" type="U16"/>
557 <member name="tree" type="TREE"/> 563 <member name="tree" type="TREE"/>
564 </message>
565
566 <message type="4407" name="mark_dead" src="client">
567 <p>Marks stones ad dead (or alive?) by the client. Details unclear</p>
568
569 <member name="channel" type="U16"/>
570 <member name="x" type="U8"/>
571 <member name="y" type="U8"/>
572 <member name="dead" type="flag"/>
573 <p>Possibly true means mark dead and false unmark, but that's just a wild guess.</p>
558 </message> 574 </message>
559 575
560 <message type="4408" name="get_tree" src="client"> 576 <message type="4408" name="get_tree" src="client">
561 Request the game tree starting at a given node. This is used 577 Request the game tree starting at a given node. This is used
562 when the server only sends a partial tree (with end code "more"). 578 when the server only sends a partial tree (with end code "more").
… …
613 Probably sets the "quiet" flag. Not checked. 629 Probably sets the "quiet" flag. Not checked.
614 <member name="channel" type="U16"/> 630 <member name="channel" type="U16"/>
615 <member name="private" type="flag"/> 631 <member name="private" type="flag"/>
616 </message> 632 </message>
617 633
634 <message type="4427" name="move" src="client">
635 <p>Only during playing, moves.</p>
636 <member name="channel" type="U16"/>
637 <member name="x" type="U8"/>
638 <member name="y" type="U8"/>
639 </message>
640
618 <message type="4429" name="reject_challenge" src="client"> 641 <message type="4429" name="reject_challenge" src="client">
619 Reject a challenge from a given user. Not checked. 642 Reject a challenge from a given user. Not checked.
620 643
621 <member name="channel" type="U16"/> 644 <member name="channel" type="U16"/>
622 <member name="name" type="username"/> 645 <member name="name" type="username"/>
646 <member name="gametype" type="U8"/>
647 <member name="cid" type="CLIENTID8"/>
648 <p>Possibly an id. No idea. Better echo this from the challenge request.</p>
649 <member name="rules" type="rules"/>
623 </message> 650 </message>
624 651
625 <message type="442e" name="save_game" src="client"> 652 <message type="442e" name="save_game" src="client">
626 <p>Is send when a game is closed and should be saved on the gamerecord.</p> 653 <p>Is send when a game is closed and should be saved on the gamerecord.</p>
627 654
… …
651 678
652<h2>Structs mainly used in messages send by the server</h2> 679<h2>Structs mainly used in messages send by the server</h2>
653 680
654 <struct name="challenge_defaults"> 681 <struct name="challenge_defaults">
655 Send soon after log-in to set the defaults for game challenges. 682 Send soon after log-in to set the defaults for game challenges.
656 <member name="type" type="U8"/> 683 <member name="gametype" type="U8"/>
657 <member name="ruleset" type="U8"/> 684 <member name="ruleset" type="U8"/>
658 <p>The ruleset member is a pure guess, please verify. it could also be after size for example.</p> 685 <p>The ruleset member is a pure guess, please verify. it could also be after size for example.</p>
659 <member name="size" type="U32"/> 686 <member name="size" type="U32"/>
660 <member name="timesys" type="U32"/> 687 <member name="timesys" type="U32"/>
661 <member name="time" type="U32"/> 688 <member name="time" type="U32"/>
… …
664 <member name="can_time" type="U32"/> 691 <member name="can_time" type="U32"/>
665 <member name="can_stones" type="U32"/> 692 <member name="can_stones" type="U32"/>
666 <member name="notes" type="STRING"/> 693 <member name="notes" type="STRING"/>
667 </struct> 694 </struct>
668 695
669 <struct name="challenge" class="KGS::Challenge">
670 A challenge.
671
672 <member name="user1" type="user"/>
673 <member name="user2" type="user"/>
674 <member name="type" type="U8"/>
675 <member name="id" type="U8"/>
676 <p>Possibly an id. No idea. Better echo this from the cchallenge request.</p>
677 <member name="rules" type="rules"/>
678 </struct>
679
680 <struct name="game" class="KGS::Game"> 696 <struct name="game" class="KGS::Game">
681 Basic information about a game. Used in rooms for the gamelist and 697 Basic information about a game. Used in rooms for the gamelist and
682 in games to detect when a game is saved, changed type (e.g. R => D) 698 in games to detect when a game is saved, changed type (e.g. R => D)
683 etc. 699 etc.
684 700
685 <member name="channel" type="U16"/> 701 <member name="channel" type="U16"/>
686 <member name="type" type="U8"/> 702 <member name="type" type="U8"/>
687 <member name="user1" type="user"/> 703 <member name="black" type="user"/>
688 White 704 White
689 <member name="user2" type="user"/> 705 <member name="white" type="user"/>
690 Black 706 Black
691 <member name="user3" type="user"/> 707 <member name="owner" type="user"/>
692 Owner 708 Owner
693 <member name="size" type="U8"/> 709 <member name="size" type="U8"/>
694 <member name="handicap" type="I8"/> 710 <member name="handicap" type="I8"/>
695 &lt; 0 not fully setup 711 &lt; 0 not fully setup
696 <member name="komi" type="komi16"/> 712 <member name="komi" type="komi16"/>
… …
738 754
739 <member name="timestamp" type="timestamp"/> 755 <member name="timestamp" type="timestamp"/>
740 Time this game was played. 756 Time this game was played.
741 <member name="flags1" type="U8"/> 757 <member name="flags1" type="U8"/>
742 <p>0:3 == handicap, 4:7 == gametype:0:4</p> 758 <p>0:3 == handicap, 4:7 == gametype:0:4</p>
743 <member name="user1" type="user"/> 759 <member name="black" type="user"/>
744 White, flags contain low 8 bits of revision (bits 16-23). 760 White, flags contain low 8 bits of revision (bits 16-23).
745 <member name="user2" type="user"/> 761 <member name="white" type="user"/>
746 Black, flags contain high 8 bits of revision (bits 16-23). 762 Black, flags contain high 8 bits of revision (bits 16-23).
747 <member name="user3" type="user"/> 763 <member name="owner" type="user"/>
748 764
749 <p><p>Owner (or empty)</p> 765 <p><p>Owner (or empty)</p>
750 766
751 <p>The bits 16-24 of user1.flags and user2.flags give the high and 767 <p>The bits 16-24 of black.flags and white.flags give the high and
752 low bits of a revision number in case there are multiple similar 768 low bits of a revision number in case there are multiple similar
753 games.</p></p> 769 games.</p></p>
754 770
755 <member name="flags2" type="U16"/> 771 <member name="flags2" type="U16"/>
756 <p>0:11 == komi / 2, 12:14 == high 3 bits of gametype, 15: == sign bit</p> 772 <p>0:11 == komi / 2, 12:14 == high 3 bits of gametype, 15: == sign bit</p>
… …
863 <member name="bytes_out" type="U64"/> 879 <member name="bytes_out" type="U64"/>
864 <member name="packets_out" type="U64"/> 880 <member name="packets_out" type="U64"/>
865 </message> 881 </message>
866 882
867 <message type="0016" name="idle_warn" src="server"> 883 <message type="0016" name="idle_warn" src="server">
868 idle warning, autologout soon (10 minutes...) 884 <p>idle warning, autologout soon (10 minutes...). Responding with <ref ref="ping"/> usually helps.</p>
869 </message> 885 </message>
870 886
871 <message type="0018" name="login" src="server"> 887 <message type="0018" name="login" src="server">
872 <member name="message" type="CONSTANT" value='logged out: another client logged in with your username'/> 888 <member name="message" type="CONSTANT" value='logged out: another client logged in with your username'/>
873 </message> 889 </message>
… …
919 </message> 935 </message>
920 936
921 <message type="0025" name="memo_error" src="server"> 937 <message type="0025" name="memo_error" src="server">
922 <p>Account unknown.</p> 938 <p>Account unknown.</p>
923 <member name="name" type="username"/> 939 <member name="name" type="username"/>
924 <member name="cid" type="clientid"/> 940 <member name="cid" type="CLIENTID16"/>
925 <member name="message" type="CONSTANT" value='memo send failed: account already exists'/> 941 <member name="message" type="CONSTANT" value='memo send failed: account already exists'/>
926 <member name="subtype" type="CONSTANT" value='25'/> 942 <member name="subtype" type="CONSTANT" value='25'/>
927 </message> 943 </message>
928 944
929 <message type="0026" name="memo_error" src="server"> 945 <message type="0026" name="memo_error" src="server">
930 <p>Just a guess.</p> 946 <p>Just a guess.</p>
931 <member name="name" type="username"/> 947 <member name="name" type="username"/>
932 <member name="cid" type="clientid"/> 948 <member name="cid" type="CLIENTID16"/>
933 <member name="message" type="CONSTANT" value='memo send failed: error 26'/> 949 <member name="message" type="CONSTANT" value='memo send failed: error 26'/>
934 <member name="subtype" type="CONSTANT" value='26'/> 950 <member name="subtype" type="CONSTANT" value='26'/>
935 </message> 951 </message>
936 952
937 <message type="0027" name="memo_error" src="server"> 953 <message type="0027" name="memo_error" src="server">
938 <p>User is currently online, please use chat.</p> 954 <p>User is currently online, please use chat.</p>
939 <member name="name" type="username"/> 955 <member name="name" type="username"/>
940 <member name="cid" type="clientid"/> 956 <member name="cid" type="CLIENTID16"/>
941 <member name="message" type="CONSTANT" value='memo send failed: user is online, use chat'/> 957 <member name="message" type="CONSTANT" value='memo send failed: user is online, use chat'/>
942 <member name="subtype" type="CONSTANT" value='27'/> 958 <member name="subtype" type="CONSTANT" value='27'/>
943 </message> 959 </message>
944 960
945 <message type="0028" name="memo_error" src="server"> 961 <message type="0028" name="memo_error" src="server">
946 <p>Just a guess.</p> 962 <p>Just a guess.</p>
947 <member name="name" type="username"/> 963 <member name="name" type="username"/>
948 <member name="cid" type="clientid"/> 964 <member name="cid" type="CLIENTID16"/>
949 <member name="message" type="CONSTANT" value='memo send failed: error 28'/> 965 <member name="message" type="CONSTANT" value='memo send failed: error 28'/>
950 <member name="subtype" type="CONSTANT" value='28'/> 966 <member name="subtype" type="CONSTANT" value='28'/>
951 </message> 967 </message>
952 968
953 <message type="0029" name="memo" src="server"> 969 <message type="0029" name="memo" src="server">
… …
957 </message> 973 </message>
958 974
959 <message type="002a" name="memo_sent" src="server"> 975 <message type="002a" name="memo_sent" src="server">
960 <p>The memo was sent successfully</p> 976 <p>The memo was sent successfully</p>
961 <member name="name" type="username"/> 977 <member name="name" type="username"/>
962 <member name="cid" type="clientid"/> 978 <member name="cid" type="CLIENTID16"/>
963 </message> 979 </message>
964 980
965 <message type="0100" name="gnotice" src="server"> 981 <message type="0100" name="gnotice" src="server">
966 global notice, sent to everybody 982 global notice, sent to everybody
967 <member name="notice" type="STRING"/> 983 <member name="notice" type="STRING"/>
… …
1091<h3>Game messages</h3> 1107<h3>Game messages</h3>
1092 1108
1093 <message type="4400" name="challenge" src="server"> 1109 <message type="4400" name="challenge" src="server">
1094 Unclear. 1110 Unclear.
1095 <member name="channel" type="U16"/> 1111 <member name="channel" type="U16"/>
1112 <member name="black" type="user"/>
1113 <member name="white" type="user"/>
1114 <member name="gametype" type="U8"/>
1115 <member name="cid" type="CLIENTID8"/>
1116 <p>Possibly an id. No idea. Better echo this from the challenge request.</p>
1096 <member name="challenge" type="challenge"/> 1117 <member name="rules" type="rules"/>
1118 <member name="notes" type="STRING"/>
1119 <p>This field is optional</p>
1097 </message> 1120 </message>
1098 1121
1099 <message type="4401" name="upd_game" src="server"> 1122 <message type="4401" name="upd_game" src="server">
1100 <member name="channel" type="U16"/> 1123 <member name="channel" type="U16"/>
1101 <member name="game" type="game"/> 1124 <member name="game" type="game"/>
… …
1187 <member name="tree" type="TREE"/> 1210 <member name="tree" type="TREE"/>
1188 </message> 1211 </message>
1189 1212
1190 <message type="4429" name="reject_challenge" src="server"> 1213 <message type="4429" name="reject_challenge" src="server">
1191 Reject a challenge by a given user. Not checked. 1214 Reject a challenge by a given user. Not checked.
1215 <!-- should become a record type somehow... -->
1192 1216
1217 <member name="channel" type="U16"/>
1218 <member name="name" type="username"/>
1193 <member name="channel" type="U16"/> 1219 <member name="gametype" type="U8"/>
1220 <member name="cid" type="CLIENTID8"/>
1221 <p>Possibly an id. No idea. Better echo this from the challenge request.</p>
1194 <member name="name" type="username"/> 1222 <member name="rules" type="rules"/>
1195 </message> 1223 </message>
1196 1224
1197 <message type="442f" name="new_game" src="server"> 1225 <message type="442f" name="new_game" src="server">
1198 <p>Notifies the client that a new game has been created. This 1226 <p>Notifies the client that a new game has been created. This
1199 message is sent long *after* upd_games and upd_observers etc. 1227 message is sent long *after* upd_games and upd_observers etc.
1200 have been received. *sigh*</p> 1228 have been received. *sigh*</p>
1201 1229
1202 <member name="channel" type="U16"/> 1230 <member name="channel" type="U16"/>
1203 <p>The newly created game.</p> 1231 <p>The newly created game.</p>
1204 <member name="cid" type="clientid"/> 1232 <member name="cid" type="CLIENTID16"/>
1205 <p>The ID sent to the server in new_game.</p> 1233 <p>The ID sent to the server in new_game.</p>
1206 </message> 1234 </message>
1207 1235
1208 <message type="4433" name="req_result" src="server"> 1236 <message type="4433" name="req_result" src="server">
1209 Unclear. 1237 Unclear.

Diff Legend

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