X-Git-Url: https://git.cworth.org/git?p=ttt;a=blobdiff_plain;f=PROTOCOL;h=91c8545b88ac96f482ca5c27893a3715ce10ba07;hp=519b1bab79dca6e820428ae48ac787b903bf77c6;hb=HEAD;hpb=82b903360548669988e41ffe055bc2215a28b404 diff --git a/PROTOCOL b/PROTOCOL index 519b1ba..91c8545 100644 --- a/PROTOCOL +++ b/PROTOCOL @@ -31,11 +31,11 @@ Document Conventions is one of: - ERROR + ERROR 1. Requests -1.1 Connection setup +1.1. Connection setup The TTTP server has no well defined port; agreement on which port to use must be done through some external mechanism. Once connected, @@ -47,21 +47,37 @@ Document Conventions HELO - Possible errors: INVALIDNAME + Possible errors: INVALID_NAME 1.2. Global commands - 1.2.1 Listing available users + 1.2.1. Listing available users WHO -> - WHO ... + WHO ... - lists connected users and the number of games they've won. + Lists connected users. - 1.2.2. Message + Possible errors: NO_NAME_SET + + 1.2.2. STATISTICS + + STATISTICS + + -> + + STATISTICS " + TICTACTOE WINS + " + + Lists the statistics for the specified user. + + Possible errors: NO_NAME_SET, NO_USER + + 1.2.3. Message MESSAGE @@ -69,15 +85,27 @@ Document Conventions MESSAGE - 1.2.3. Help + Sends a message to all connected users. The text must be a + single token. Use a quoted-string to include spaces in the + message text. + + Possible errors: NO_NAME_SET + + 1.2.4. Help HELP { } + -> + + HELP { } " + + " + Displays help. If is provided, displays more detailed help on a specific command, otherwise displays an overview of all commands. - 1.2.4. Quit + 1.2.5. Quit QUIT @@ -87,7 +115,7 @@ Document Conventions Disconnects the client from the server. - 1.2.5. Version + 1.2.6. Version VERSION @@ -111,7 +139,7 @@ Document Conventions INVITE - Possible errors: NOUSER, BUSY + Possible errors: NO_NAME_SET, NO_USER, BUSY 1.3.2. Accepting an invitation @@ -121,15 +149,40 @@ Document Conventions ACCEPT + Possible errors: NO_NAME_SET, NO_USER, NO_INVITE + + 1.3.3. Retracting an invitiation + + RETRACT + + -> + + RETRACT + + Possible errors: NO_NAME_SET, NO_USER, NO_INVITE + + 1.3.3. Declining an invitation + + DECLINE + + -> + + DECLINE + + Possible errors: NO_NAME_SET, NO_USER, NO_INVITE + 1.4. In-game commands + is a game id generated by the server and first returned in + NOTICE NEWGAME + 1.4.1. Get the game contents - SHOW + SHOW -> - SHOW + SHOW is a quoted multi-line string containing an diagram of the tic-tac-toe board, which is a 3x3 array of @@ -143,28 +196,28 @@ Document Conventions For example: - SHOW " + SHOW " _|X|O _|X|_ X|O|O" - Possible errors: NOTINGAME + Possible errors: NO_NAME_SET, NO_GAME 1.4.2. Part - PART + PART -> PART - Departs the current game + Departs the specified game - Possible errors: NOTINGAME + Possible errors: NO_NAME_SET, NO_GAME 1.4.3. Making a move - MOVE + MOVE -> @@ -173,11 +226,12 @@ Document Conventions indicates a number in the tic-tac-toe grid as follows: - 1|2|3 - 4|5|6 - 7|8|9 + 0|1|2 + 3|4|5 + 6|7|8 - Possible errors: NOTINGAME, NOTYOURMOVE, NOTGRID + Possible errors: NO_NAME_SET, NO_GAME, NOT_PLAYING, + NOT_YOUR_MOVE, NOT_GRID, NOT_VALID_MOVE 2. Asynchronous notification. @@ -205,42 +259,63 @@ Document Conventions NOTICE QUIT 2.1.3. Game invitation + + 2.1.3.1. Invitation is made + + NOTICE INVITE + + 2.1.3.2. Invitation is accepted + + NOTICE ACCEPT + + 2.1.3.3. Invitation is retracted + + NOTICE RETRACT + + 2.1.3.4. Invitation is declined + + NOTICE DECLINE + + The first username listed is the one performing the action. + + 2.1.4. New games + + NOTICE NEWGAME - NOTICE INVITE - - 2.1.4. Terminated games + The first username listed will go first. + + 2.1.5. Terminated games NOTICE DISPOSE - 2.1.5. Message + 2.1.6. Message NOTICE MESSAGE + where is a quoted-string. Quotes escaped with '\"' + 2.2. Game notices These notices are sent to all players and watchers in - the affected game - - 2.2.1. Global game notices - - 2.2.1.1. New game begins + the affected game. - NOTICE NEWGAME + is a game id generated by the server and first returned in + NOTICE NEWGAME - The first username listed will go first + 2.2.1. Global game notices - 2.2.1.2. Game over, and winner + 2.2.1.1. Game over, and winner - NOTICE GAMEOVER + NOTICE GAMEOVER - is either WON in which case indicates + is either WON in which case indicates the winner or CATSGAME in which case is "". 2.2.2. Move notices 2.2.2.1. Move - NOTICE MOVE + NOTICE MOVE 3. Errors @@ -252,15 +327,20 @@ Document Conventions 3.1.1. No name set - ERROR NONAMESET + ERROR NO_NAME_SET - 'helo' must be sent before any command other than 'quit'. + 'helo' must be sent before any command other than 'help', + 'version', 'quit'. + + Possibly returned by: WHO, STATISTICS, MESSAGE, INVITE, + ACCEPT, RETRACT, DECLINE, SHOW, PART, MOVE 3.1.2. Invalid name - ERROR INVALIDNAME + ERROR INVALID_NAME - All names must be of non-zero length and must be unique. + All names must be of non-zero length and must be unique, + though case-insensitive. Possibly returned by: HELO @@ -272,74 +352,95 @@ Document Conventions ERROR COMMAND - An invalid command was specified - + An invalid command was specified. + 3.2.2. Syntax ERROR SYNTAX - A syntax error was detected + A syntax error was detected. 3.2.3. Not number - ERROR NOTNUMBER + ERROR NOT_NUMBER - A non-numeric value was supplied where a number was required + A non-numeric value was supplied where a number was required. + Possibly returned by: MOVE + 3.2.4. Not a grid number - ERROR NOTGRID - - The number specified in the command was not a valid grid number + ERROR NOT_GRID + The number specified in the command was not a valid grid + number. + + Possibly returned by: MOVE + 3.3. Global command errors. - There are no errors from any of the global commands + There are no global command errors from any of the global + commands. 3.4. Game management errors. Errors from game management commands - 3.4.1. No such game + 3.4.1. No invitiation from/for specified user + + ERROR NO_INVITE + + An invitiation action was attempted where no invitation + exists. + + Possibly returned by: ACCEPT, RETRACT, DECLINE + + 3.4.2. No such game - ERROR NOGAME + ERROR NO_GAME - A game name was provided that does not exist. + A game id was provided that does not exist. + + Possibly returned by: SHOW, PART, MOVE 3.5. User information errors 3.5.1. No such user - ERROR NOUSER + ERROR NO_USER A user name was provided that does not exist. + Possibly returned by: STATISTICS, INVITE, ACCEPT, RETRACT, + DECLINE + 3.6. In-game errors 3.6.1. Global game errors - 3.6.1.1. Not in game - - ERROR NOTINGAME - - A game playing command was made, but the user is not a - particpant of any game. - - Possibly returned by: MOVE + 3.6.1.1. Not playing - 3.6.1.2. Not playing - - ERROR NOTPLAYING + ERROR NOT_PLAYING A command was executed by a watching user that is - permitted only to players + permitted only to players. + + Possibly returned by: MOVE 3.6.2. Moving errors 3.6.2.1. Not your turn - ERROR NOTYOURTURN + ERROR NOT_YOUR_TURN - A move was submitted during the other player's turn + A move was submitted during the other player's turn. + + Possibly returned by: MOVE + + 3.6.2.2. Not a valid move + + ERROR NOT_VALID_MOVE + + A move was submitted for a cell that is occupied. Possibly returned by: MOVE