Archive‎ > ‎Fall 2009‎ > ‎Course Project‎ > ‎

Client-Server Protocol Specifications


The protocol used to communicate between your client and the server is based on simple messages represented in XML. The server will for most commands reply with a message indicating whether it accepts your message, and will include a reason in case it didn't. The server requires you to authenticate yourself in order to be able to access the various commands that it provides, the credentials will be given to you once the groups are established.

Messages format

Note: Messages are separated by lines, so one message can only take up to one line.

Note: You should gracefully ignore messages that you don't understand, see "Protocol Extensions" for an explanation.

Note: Never will it be the case that the server message contains two replies and never will it be the case that the server's reply is delivered in two messages, i.e. in two lines sent by the server.

Here is a list of the different messages that you'll have to send or receive while communicating with the server:

Authentication & General commands


Upon connection, you'll receive this message from the server:

  <hello salt=".." ></hello>

The salt is necessary to be able to safely authenticate yourself. See Login for more details.


To authenticate yourself, send the following command:

  <auth><login username=".." challenge=".." /></auth>

The parameter username is the one of the usernames you received by email . challenge is composed of the following:

   sha1(sha1(password) + salt)

pass = "plop";
salt = "1234-5678-asddd-asdasd"
sha1(pass) => 64faf5d0b1dc311fd0f94af64f6c296a03045571
sha1(sha1(pass)+salt) => sha1("64faf5d0b1dc311fd0f94af64f6c296a030455711234-5678-asddd-asdasd") => 68956298619dcf787a9f6f9c0fd366890e523533

where password is the password you received by email, and sha1() is the SHA-1 hashing function, returning a 40 chars long hex representation of the hash (+ is the concatenation operator).

Each student will have 5 accounts so as to make testing with multiple friends possible.

Possible replies from the server:
  • <auth><ack ></ack></auth>
  • <auth><nack msg=".." ></nack></auth>


To logout, send the following command:

  <auth><logout /></auth>

Possible replies from the server:
  • <auth><ack ></ack></auth>
  • <auth><nack msg=".." ></nack></auth>


To disconnect from the server, send the following command:

  <quit />

After receiving this, the server will close the socket without sending you anything.



To register your current gps location, send the following command:

  <gps><register long=".." lat=".." /></gps>

long and lat are in microdegrees (degrees * 1E6).

Possible replies from the server:
  • <gps><ack ></ack></gps>
  • <gps><nack msg=".." ></nack></gps>


To retrieve the position of a friend, send the following command:

  <gps><get username=".." /></gps>

Possible replies from the server:

  • <gps><position username=".." long="N/A" lat="N/A" logged=".." /></gps>
  • <gps><position username=".." long=".." lat=".." logged=".." /></gps>
logged informs you about the current status of this username, which tells you if he is currently logged on or not ("yes"/"no").
long and lat are in microdegrees (degrees * 1E6).

For example, EPFL's GPS coordinates are 46.520278 (latitude) and 6.565556 (longitude). To be used both by the server, and the Google Map, the values must be multiplied by 1E6, yielding 46520278 and 6565556.



To send a message:

  <chat username=".."><msg>..</msg></chat>

Possible replies from the server:
  • <chat username=".."><ack ></ack></chat>
  • <chat username=".."><nack msg=".." ></nack></chat>


For Alice to send a message to Bob, she needs to send the following command:

  <chat username="Bob"><msg>Why do we always get used for examples?</msg></chat>

If the server replies with ACK, Bob will receive:

  <chat username="Alice"><msg>Why do we always get used for examples?</msg></chat>


Every chess command is encapsulated into a <chess username="..">..</chess> tag, indicating your opponent.
You cannot play more than one game with the same opponent.

The following operations are defined:

Creating a game

Send the following command to create a game:

      <chess username="..."><create timers="..."></create></chess>

The timers argument represents the time, in minutes, that each players has to complete the game.
The server will then send a message to the opponent, and return ACK, or simply return NACK on error.

The invite message looks like this:

      <chess username="..."><invite timers="..."></invite></chess>

The opponent will have to accept or decline the invitation by sending either:

      <chess username="..."><inviteaccept /></chess>
      <chess username="..."><invitedecline /></chess>

The player asking for a draw will then be notified of the decision.

If the game invitation is accepted:
  • The server will consider the game as started.
  • The host (the player that created the game) will start with the white pieces, and is allowed to do a move right away. The timer of the white player will start it's countdown.
If the game invitation is rejected:

  • The server will discard the game
  • Players can then invite each others with different timers.

Playing a game

During a game, the following operations are allowed:

Moving a piece

In turn, starting with white, each player will be able to move a piece:

      <chess username="..."><move from=".." to=".." /></chess>

The from and to arguments are positions in algebraic notation (e.g. "a6", "b5", "h8"). This move, after validation by the server, will be sent to the other player. The server will automatically remove captured pieces, or handle special moves. The only special move that requires more information is the promotion of a pawn:

      <chess username="..."><movepromote from=".." to=".." promotion=".." /></chess>

The promotion argument is the abbreviation of the piece that will replace the pawn ("Q" for queen, "R" for rook, "B" for bishop and "N" for knight).

Ending a game

You can resign from a game by sending:

      <chess username="..."><resign /></chess>

at this point, the server will send a notification to the opponent:

      <chess username="..."><end winner="white" /></chess>
      <chess username="..."><end winner="black" /></chess>

The same notification will be sent when one player is checkmate.


You can ask the opponent for a draw:

      <chess username="..."><drawask /></chess>

at which point, the other player will be able to accept or deny the draw:

      <chess username="..."><drawaccept /></chess>
      <chess username="..."><drawdecline /></chess>

If accepted, the server will send a draw notification to both clients

      <chess username="..."><draw /></chess>

and end the game.

If declined, the game will go on.


You can synchronize your timers with the one from the server by sending the following command:

      <chess username="..."><timers /></chess>

The server will reply:

      <chess username="..."><timers white=".." black=".." /></chess>

The white and black arguments represent, in seconds, the time left for each player to end the game.

Protocol Extensions

The server is implemented in such a way that it will automatically understand:

  <[sometag] username="[receiver]">..content..</[sometag]>

The username attribute represents the receiver of the message, who is the message addressed to.

If the receiver is found, then the following message will be sent to [receiver]:

  <[sometag] username="[sender]">..content..</[sometag]>

The username attribute represents the sender of the message, who is the message coming from.

Possible replies from the server:
  • <[sometag] username="[receiver]"><ack></ack></[sometag]>
  • <[sometag] username="[receiver]"><nack msg=".."></ack></[sometag]>
This feature allows you to build your own features on top of the required ones.The only limit is your imagination! (and time, maybe)

Order of messages

You should distinguish between two types of incoming messages:
  • Responses to server requests
  • Asynchronous messages coming from the server
You can assume that there is an order between server requests' responses. For example, if you send command A and then command B, and receive "ack" then "nack", you can bind the "ack" to A and the "nack" to B.

However, you have to consider that asynchronous messages might occur between those responses, or anytime, (e.g. chat messages). You will need to correctly dispatch them so that you are still able to identify what the result of a request is.