From 47eadb6f86ae3b7fb0fe78618d07b2014f462be5 Mon Sep 17 00:00:00 2001
From: Max-Wilhelm Bruker <m.bruker@digitalmedia.de>
Date: Tue, 30 Jun 2009 23:26:10 +0200
Subject: [PATCH] started protocol documentation

---
 cockatrice/doc/protocol.txt      | 110 +++++++++++++++++++++++++++++++
 servatrice/src/returnmessage.cpp |   1 -
 servatrice/src/returnmessage.h   |   2 +-
 3 files changed, 111 insertions(+), 2 deletions(-)
 create mode 100644 cockatrice/doc/protocol.txt

diff --git a/cockatrice/doc/protocol.txt b/cockatrice/doc/protocol.txt
new file mode 100644
index 00000000..639437c0
--- /dev/null
+++ b/cockatrice/doc/protocol.txt
@@ -0,0 +1,110 @@
+1. Abstract
+
+The Cockatrice protocol is a client/server protocol intended for communication between
+a card game client and a suitable server. It is designed with the goal in mind to make
+playing card games, such as Magic the Gathering, over a network easy while eliminating
+the possibility of unfair play. Because of that, the server stores all hidden information
+and transmits pieces of it to clients only when necessary.
+
+2. Protocol structure
+
+All communication is done over a TCP/IP connection. The protocol is text based.
+Strings are encoded in UTF-8 and have UNIX-style line endings (\n).
+
+There are four distinct types of messages:
+	- Command (section 3)
+	- Response (section 4)
+	- Event (section 5)
+	- List (section 6)
+
+3. Commands
+
+A command can only be sent from client to server and has the following structure:
+	{ID}|{command}|{parameter1}|{parameter2}...
+"ID" is an arbitrary number to be chosen uniquely for each command.
+"command" is a command identifier (see section 3).
+It depends on the command identifier what has to be passed as parameters.
+
+3.1 ping
+
+Flags:
+	none
+Parameters:
+	none
+Valid response codes:
+	ok
+
+No effect.
+
+3.2 login
+
+Flags:
+	none
+Parameters:
+	User name (string)
+	Password (string)
+Valid response codes:
+	ok
+	password
+
+If the supplied credentials are correct, "ok" is returned and the connection state
+is set to authenticated. (The server is not required to actually check the validity
+of the credentials.)
+Otherwise, "password" is returned.
+
+3.3 list_games
+
+Flags:
+	login needed
+Parameters:
+	none
+Valid response codes:
+	ok
+
+If the connection state is unauthenticated, "login_needed" is returned.
+Otherwise, "ok" is returned and for each game currently, a list_games event XXX is
+sent to the client. The "accepts game list changes" flag of the connection is set.
+
+3.4 create_game
+3.5 join_game
+3.6 leave_game
+3.7 list_players
+3.8 say
+3.9 submit_deck
+3.10 ready_start
+3.11 shuffle
+3.12 draw_cards
+3.13 reveal_card
+3.14 move_card
+3.15 create_token
+3.16 set_card_attr
+3.17 inc_counter
+3.18 add_counter
+3.19 set_counter
+3.20 del_counter
+3.21 list_counters
+3.22 list_zones
+3.23 dump_zone
+3.24 roll_dice
+3.25 set_active_player
+3.26 set_active_phase
+
+4. Responses
+
+After processing any command, the server sends a response to the client, indicating
+whether the command was understood and valid.
+A response can only be sent from server to client and has the following structure:
+	resp|{ID}|{resp-code}
+
+{ID} is the identifier belonging to the command in question.
+{resp-code} contains information about the processing of the command. It can have the
+following values:
+	ok		(Success)
+	login_needed	(Error: Command requires login)
+	syntax		(Error: Invalid command or parameters)
+	context		(Error: Command cannot be applied here)
+	password	(Error: Wrong login data)
+
+The response code "syntax" is valid as a response to any command and is
+hence not explicitly listed in section 3. The response code "login_needed" applies
+to all commands with the "login needed" flag.
\ No newline at end of file
diff --git a/servatrice/src/returnmessage.cpp b/servatrice/src/returnmessage.cpp
index 6fb9a84a..a88e1ce9 100644
--- a/servatrice/src/returnmessage.cpp
+++ b/servatrice/src/returnmessage.cpp
@@ -15,7 +15,6 @@ bool ReturnMessage::send(ReturnCode code)
 		case ReturnSyntaxError: returnCodeString = "syntax"; break;
 		case ReturnContextError: returnCodeString = "context"; break;
 		case ReturnPasswordWrong: returnCodeString = "password"; break;
-		case ReturnNameNotFound: returnCodeString = "name_not_found"; break;
 	}
 	s->msg(QString("resp|%1|%2|%3").arg(msg_id)
 				       .arg(success ? "ok" : "err")
diff --git a/servatrice/src/returnmessage.h b/servatrice/src/returnmessage.h
index 2eaed90c..37837bca 100644
--- a/servatrice/src/returnmessage.h
+++ b/servatrice/src/returnmessage.h
@@ -9,7 +9,7 @@ private:
 	unsigned int msg_id;
 	QString cmd;
 public:
-	enum ReturnCode { ReturnNothing, ReturnOk, ReturnLoginNeeded, ReturnSyntaxError, ReturnContextError, ReturnPasswordWrong, ReturnNameNotFound };
+	enum ReturnCode { ReturnNothing, ReturnOk, ReturnLoginNeeded, ReturnSyntaxError, ReturnContextError, ReturnPasswordWrong };
 	ReturnMessage(QObject *parent = 0) : QObject(parent), msg_id(0) { }
 	unsigned int getMsgId() const { return msg_id; }
 	void setMsgId(unsigned int _msg_id) { msg_id = _msg_id; }