Transjam Protocol

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.

Logging In

A client must first login to the server by creating a socket and connecting to the server on a predefined port.
  1. 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>
  2. The server then puts the client in the top room called "purgatory".

  3.     <enterroom level="0">purgatory</enterroom>
  4. The client must send the server a validation request before logging in. The exact <validate> message is:

  5.     <validate>TransJam - Copyright 2001 Phil Burk</validate>
  6. If the validation is OK, then the server sends the client back the exact same <validate> message.
  7. If the client accepts the server's validation message, then the client sends a <requestlogin>.

  8.     <requestlogin>bob</requestlogin>
  9. If the maximum number of clients is not exceeded, then the server acknowledges the request with <grantlogin>. The client should save its userid.

  10.     <grantlogin uid="1" />
  11. 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.
  1. The client sends a request to join a new lobby room. If it already exists, the client will just join the existing room.

  2.     <joinroom>tictactoe</joinroom>
  3. The client is added to the Lobby by the server and sent a <enterroom> message.

  4.     <enterroom level="1">tictactoe</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 user.
  1. The client requests the list of rooms by sending:

  2.     <listrooms/>
  3. The server will respond by sending an <addroom> command for each available room.

  4.     <addroom maxclients="2" numclients="1">bonkers</addroom>
  5. After the last room has been listed, the server will send:

  6.     <endlist/>
  7. The client can then present the user with the list of rooms that can be joined.

Joining A Room

The user may choose to join an existing seesion.
  1. The client will send a <joinoldroom> message with the room name.

  2.     <joinroom maxclients="6" flags="0">bonkers</joinroom>
  3. If the client can join the room, then the server will send a <enterroom> message.
        <enterroom level="2">bonkers</enterroom>
  4. Once inside a room, the client can request a list of users in the room by sending:
        <listusers />
  5. 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/>.
        <adduser uid="1">bob</adduser>
        <endlist />
  6. Whenever a new user enters the room, the server will send a new <adduser> command.
  7. Whenever a new user leaves the room, the server will send a new <adduser> command.
        <deleteuser uid="1">bob</deleteuser>

Creating a New Room

  1. If the user does not want to join an existing room then she can create a new named room using <joinnewroom>.

  2.     <joinnewroom maxclients="6" flags="0">bonkers</joinnewroom>
  3. If the server can create the room, then it will send back <enterroom/>.

  4.     <enterroom level="2">bonkers</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.

Requesting a List of Things

  1. Once inside a room, the client can request a list of things in the room by sending:
        <listthings />
  2. 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 client.
        <addthing name="song" />
        <grantlock name="song" uid="1" />
        <modifything name="song">220000,36,0,</modifything>

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 name.
  1. Things are created using <locknewthing name="name" >state</locknewthing>.
        <locknewthing name="song">220000,36,0,</locknewthing>
  2. If the thing already exists, then the server will deny the lock.
        <denything name="song" />
  3. 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" />
        <modifything name="song">220000,36,0,</modifything>

Modifying Things

  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" />
  2. 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" />
  3. 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 display.
  4. If the lock is currently being negotiated,  the lock request goes into a queue.
  5. An owner can unlock a Thing at any time using <unlockthing>.