Home Announcements Schedule Assignments Slides Projects Reading

Project 3: Matchmaking with TCP

Due date: Tuesday, Mar 13th, 2012

In this project you will develop a matchmaking service for games. The service will be the 'server' and clients will be able to use a simple text protocol so that they can see who else is available to play a game.

Project Goals and Descriptions

The goals of this project are as follows:

This project will consist of two pieces: the client and the server. You will begin by creating the server because we'll be able to interact with it through telnet before we automate it via the client.

1. The Server

When you start your server, it must read three arguments from the command line:

  1. the IP address to bind to
  2. the port number to bind to and listen on
  3. a timeout value, in seconds, used to decide when to disconnect a player

The server will bind and listen to the port. When a client connects, a new thread will be spawned to handle the socket. You should use pthreads for threading in Linux.

The server will listen to the following commands:

JOIN username

As a server, it will send only one command:


All commands are case-insensitive. When a client wants to join the service, it first connects to the server, and then sends a JOIN command with the username of the player to join. Note, this is all sent as plain ASCII text, thus you will not need any conversions to or from integer representations. Usernames will also only consist of alphanumeric characters and have no spaces or other funny characters.

After a client joins, the server initiates a PING command to the client. The client responds with a PONG. The server records when the PING was sent, and calculates how long it takes to receive the PONG. This value is stored and returned later when the client uses the LIST command. The server may send a PING at any time and the client should respond whenever it gets it.

When a client wants to leave the matchmaking service, they send a LEAVE command. If the client does not send anything for at least TIMEOUT seconds, they are disconnected. Note that TIMEOUT is configured on the command line when starting the server.

If a client wants to know who is currently looking to play a game, they use the LIST command. The server returns a list of all players and their RTTs to the server. Each player and RTT are on individual lines (the lines are separated by newline characters).

2. The Client

To create the client part of the project, we will have a program that takes 3 arguments:

  1. IP address of the server to connect to
  2. Port of the server to connect to
  3. Username to use for JOINs
  4. INTERVAL, in seconds, to send a LIST command to the server with.

The client, when it starts up, will connect to the server and JOIN immediately. Thereafter it will send a LIST command to the server every INTERVAL seconds so that it's not disconnected. It will also need to automatically respond to PING commands. It should echo everything that it receives on its socket from the server to the screen.

3. A Note on Commands

Please note that all commands are terminated with a newline character. You will need to find these in your data streams from the sockets in order to know when the start or end of a command occurs.

Undergraduates: How to Start

Before you start, you should familiarize yourself with the telnet command. You've seen me use this in class to talk to a web server. You will use this to test your server long before you ever write your client. You can simply telnet to the server IP and port and type in the text commands and your server should parse them in the same way that it will with the client you'll be writing after you write the server.

Once you're sure all these are working with telnet and multiple connections, begin writing the client.


Follow the instructions for Undergraduates. In addition, you must allow two servers to be started on different ports. These servers both act just like regular matchmaking servers, but also communicate with each other. They do this by using the following commands:

The SERVER distinguishes the connection from being a server and not a client. Clients may connect to either server. When a player joins one server, the server sends the PLAYERJOIN command to the other server with that player's username and the result of the PING/PONG RTT test in milliseconds. The username and RTT are separated by whitespace. When a player leaves, the server sends a PLAYERLEAVE with the username to the other server.

Note that the point of this is to synchronize their list of players so that now when a client runs LIST, they get an updated list consisting of players from both servers.


What to turn in

You will submit your source under your repository with a new directory for your project called p3. You must include a makefile or an Eclipse project to compile your source into an executable called 'match'. The naming is important because we try to automate as much as possible!