Copyright 1997-2001 Phil Burk, All Rights Reserved
The Transjam server reponds to messages from its clients. The response
depends on the state of the client and the server.
The messages are in the format of an XML element.
The client is best implemented as an event driven state machine. It
should not wait for specific messages from the server. It should simply
respond to messages from the server whenever they arrive.
The basic types of client/server transactions are described here.
A client must first login to the server by creating a socket and connecting
to the server on a predefined port.
When the client connects to the server, an object is created in the server
to track the client. The server then sends an information packet with the
protocol version, and information about the server. The client is free
to ignore the information. For example:
<info version="1">Evaluation copy for John Smith</info>
The server then puts the client in the top room called "purgatory".
The client must send the server a validation request before logging in.
The exact <validate> message is:
<validate>TransJam - Copyright 2001 Phil
If the validation is OK, then the server sends the client back the exact
same <validate> message.
If the client accepts the server's validation message, then the client
sends a <requestlogin>.
If the maximum number of clients is not exceeded, then the server acknowledges
the request with <grantlogin>. The client should save its userid.
<grantlogin uid="1" />
If the login cannot be granted then the server sends <denylogin/> and
deletes the client.
Joining a Lobby
The client can then select the type of activity by selecting a Lobby. The
choice might be tic-tac-toe or a drumJam. A Lobby is the top room in a
hierarchy of related rooms.
The client sends a request to join a new lobby room. If it already exists,
the client will just join the existing room.
The client is added to the Lobby by the server and sent a <enterroom>
Querying a List of Available Rooms.
Any Room can have a list of sub-Rooms but typically only Lobbies will have
sub-Rooms. The sub-Rooms might be pairs of chess players or chat groups.
Each room must have a unique name which is enforced by the server. The
client can request a list of available sub-rooms and offer a menu to the
The client requests the list of rooms by sending:
The server will respond by sending an <addroom> command for each available
<addroom maxclients="2" numclients="1">bonkers</addroom>
After the last room has been listed, the server will send:
The client can then present the user with the list of rooms that can be
Joining A Room
The user may choose to join an existing seesion.
The client will send a <joinoldroom> message with the room
<joinroom maxclients="6" flags="0">bonkers</joinroom>
If the client can join the room, then the server will send a <enterroom>
Once inside a room, the client can request a list of users in the room
The server will then sent the name of the other users in that room using
<adduser> with an ID and the name. The client can keep a record of which
other clients are in the same room. The list will be terminated with <endlist/>.
Whenever a new user enters the room, the server will send a new <adduser>
Whenever a new user leaves the room, the server will send a new <adduser>
Creating a New Room
If the user does not want to join an existing room then she can create
a new named room using <joinnewroom>.
<joinnewroom maxclients="6" flags="0">bonkers</joinnewroom>
If the server can create the room, then it will send back <enterroom/>.
Chatting or Sending Messages to other Clients
At any time, a user can chat with or send messages to other members of
the same room.
You can send a chat message to all of the members of a room, including
You can send a message to all of the members of a room, including yourself
You can send a message to all of the members of a room, except yourself
You can send a message to a specific client in a room using
You can send a message to yourself as well. This is useful if you want
to send a message from the a GUI Thread to a Thread that is listening to
Requesting a List of Things
Once inside a room, the client can request a list of things in the room
The server will then sent the name of the things in that room using <addthing>.
The current owner will be given using <grantlock>. The current state
of the thing will be described using <modifything>. The client may keep
a record of things in the same room. The list will be terminated with <endlist/>.
Sending them as three messages simplifies the design of a command driven
<addthing name="song" />
<grantlock name="song" uid="1" />
Creating New Things
The server will maintain a list of named objects called Things that can
be shared by members of a room. Things are uniquely identified by their
Things are created using <locknewthing name="name" >state</locknewthing>.
If the thing already exists, then the server will deny the lock.
<denything name="song" />
If the thing does not exist, then the server will create it and lock it,
and set the initial state. It will then send three messages as above.
<addthing name="song" />
<grantlock name="song" uid="1" />
Things can be modified only if a client owns the lock for the thing. Things
are automatically locked by the creator. Ownership can be requested using:
<lockthing name="song" />
If the server owns the thing, then it can immediately grant the lock to
the requester. It will the grant to the requester, as well as anyone else
who has subscribed to the list of things.
<grantlock name="song" uid="2" />
If another client owns the a lock, then a <lockthing> message
is sent from the server to the current owner. The owner can <grantlock>
or <denylock>. If the lock is granted then a <grantlock>
message is sent to all subscribers in the room so they can update their
If the lock is currently being negotiated, the lock request goes
into a queue.
An owner can unlock a Thing at any time using <unlockthing>.