Transjam Protocol

Introduction

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.

Transactions

Logging In

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".

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

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

    <requestlogin>bob</requestlogin>
6. 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" />
7. If the login cannot be granted then the server sends <denylogin/> and deletes the client.

Joining a Lobby

1. The client sends a request to join a new lobby room. If it already exists, the client will just join the existing room.

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

    <enterroom level="1">tictactoe</enterroom>

Querying a List of Available Rooms.

1. The client requests the list of rooms by sending:

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

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

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

Joining A Room

1. The client will send a <joinoldroom> message with the room name.

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

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

    <enterroom level="2">bonkers</enterroom>

Chatting or Sending Messages to other Clients

• You can send a chat message to all of the members of a room, including yourself using
      <chat>message</chat>
• You can send a message to all of the members of a room, including yourself using
      <sendall>message</sendall>
• You can send a message to all of the members of a room, except yourself using
      <sendothers>message</sendothers>
• You can send a message to a specific client in a room using
      <send uid="#">message</send>
• 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 the server.
          <sendself>message</sendself>

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

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>.