Protocol Description

Purpose

The server is the data store system. The server is currently implemented as a Java program, running on a PC. The server is responsible for sending, receiving, and synchronizing user data across all of the various scrap devices. The storage of the data is handled by an SQL database.

Paradigm

todo_app
memo_app
message_app
calendar_app
contact_app


Individual data items themselves are discrete packages. The packages have various components, depending on the data type. All packages of the same type have the same component sets.

Because our data storage is in an SQL database, you should think of the data types as individual tables. Each data package is just a row in one of those tables. The components in a package are the columns within the table. Refer to the Database Draft to see the database organization.

Bootstrap

Communication of user data occurs between the server and devices only. That is, devices don't communicate with other devices. Our medium is ethernet, using TCP/IP. Each device in the infrastructure has a unique IP number. The server exists on an IP address known to all devices.

Communication is initiated by devices always. That is, the server cannot connect to devices. This simplification was done to ease development on the devices. Once a device has created an open socket to the server, the server can reply any necessary data back to the device through the open socket.

Each application is responsible for making their own connection. In another words, we treat all applications as if they are their own device.

In brief, a usual sequence of events, from the application perspective would occur as follows:

• open a socket to the server
• send a logon message
• waits for reply
• receive the logon reply (assume ack true)
• perform any necessary operations during the life of the app.
• send a logoff message
• close the socket

Logon

sent from Device to Server

The logon event is issued by devices to initiate itself as being owned by a specific user. This event should be sent once and only once for every time a scrap device is assigned ownership. The Logon event should be the FIRST thing sent to the server.

to log on, device sends the server the following sequence:

<logon><uid>user ID number</uid></logon>

The sequence should be terminated with a NULL character to indicate the end of the XML stream.

In the logon string, "user ID number" is a 32-bit unsigned integer, uniquely identifying users of the system.

example :

<logon><uid>98195</uid></logon>

Logon Reply

sent from Server to Device

The logon reply is sent by the server to the device to acknowledge or deny the device being associated to the user. This reply comes immediately after the device sends its Logon request. The device should NOT send anything more until this logon reply comes from the server.

The following sequence is returned:

<logon><uid>user ID number</uid><ack>true|false</ack></logon>

This sequence IS NOT NULL terminated.

If the device receives a true ack reply, then it has been successfully associated to the specified user.

If the device receives a false ack reply, then the user has been denied association with the device, and the device should return to a scrap state.

example 1 :	<logon><uid>98195</uid><ack>true</ack></logon>
example 2 :	<logon><uid>98195</uid><ack>false</ack></logon>

Logoff

sent from Device to Server

The logof event is issued by devices to de-associate itself from an owner. This event should be sent once and only once for every time a device is disowned and returned to a scrap state.

to log off, device sends the server the following sequence:

<logoff><uid>user ID number</uid></logoff>

The sequence should be terminated with a NULL character to indicate the end of the XML stream.

In the logon string, "user ID number" is a 32-bit unsigned integer, uniquely identifying users of the system.

Once a device has sent this to the server, the device can assume the server has disassociated the device from the user. The device should close all sockets to the server, and return to scrap state.

example :

<logoff><uid>98195</uid></logoff>

Snapshot Request

sent from Device to Server

This message is sent by an application to request data sets from the server.

<snapshot><application></application></snapshot>

The sequence should be terminated with a NULL character to indicate the end of the XML stream.

The application tag is whatever application you wish to select the snapshot from. In the current implementation, the snapshot processor does not limit the data set selected. That is, there is no way to limit what gets selected within the request message.

example :	<snapshot><todo_app></todo_app></snapshot>
example :	<snapshot><memo_app></memo_app></snapshot>
example :	<snapshot><message_app></message_app></snapshot>
example :	<snapshot><calendar_app></calendar_app></snapshot>
example :	<snapshot><contact_app></contact_app></snapshot>

Snapshot Reply

sent from Server to Device

This is sent by the server to the device in response to a snapshot request.

<snapshot><application>...</application></snapshot>

This sequence IS NOT NULL terminated.

The data that's contained between the application tags is application dependent. However, there are a few invariants which can be held for all content within the application tags. All of the tags and fields will be present. That is, the complete state of the entry is sent. Furthermore, the tags always appear in the same order. More information will be detailed in each application's section. Furthermore, each snapshot return contains only one entry. If there are more than one entries to return, then they will be sent with multiple snapshot replies.

example :	<snapshot> <todo_app> <id>123</id> <done>false</done> <priority>1</priority> <text>go to dry cleaners</text> </todo_app> </snapshot>
example :	<snapshot> <todo_app> <id>124</id> <done>false</done> <priority>0</priority> <text>work on 476</text> </todo_app> </snapshot> <snapshot> <todo_app> <id>125</id> <done>false</done> <priority>1</priority> <text>get some sleep</text> </todo_app> </snapshot>
	NOTE! The line breaks are for clarity. The server does not send line breaks or extra spaces between tags.

Update

sent from Device to Server

This is sent by devices when there has been data change. That is, if the user added, modified, or deleted data, then the device should send this message to the server.

<update><mode>add|modify|delete</mode><application>...</application></snapshot>

The sequence should be terminated with a NULL character to indicate the end of the XML stream.

The selection criteria support depends on the application module. However, it can be assumed that the best way to modify is to specifically set the ID of the data entry.

Note that on an add event, the ID value should not be given. The server will pick an appropriate ID value. For all other modes, the ID value most be given.

example :	<update> <mode>add</mode> <memo_app> <id></id> <filename>memo1</filename> <text>a test memo entry</text> </memo_app> </update>
example :	<update> <mode>modify</mode> <memo_app> <id>601</id> <filename>memo2</filename> <text>modified text</text> </memo_app> </update>
example :	<update> <mode>delete</mode> <memo_app> <id>602</id> </memo_app> </update>

Synch

broadcast from Server to all Devices owned by user

This is the parallel to the update message. When the user owns multiple devices, and a data entry somewhere gets modified, this message is sent to all devices notifying them of the change, including the originator of the message.

<synch><mode>add|modify|delete</mode><application>...</application></synch>

This sequence IS NOT NULL terminated.

The data contained within the application tags is always complete. That is, all fields are present, given, and filled in.

MessageApp

To get our system to work without adding more protocol tags, the MessageApp hacks the way the existing protocol is used. This section will hopefully clarify how the MessageApp works.

starting up

When the MessageApp first opens, it should send a snapshot request.

<snapshot><message_app></message_app></snapshot>

The server will then respond with a whole bunch of snapshots. The first set of these snapshots are actually to send the application the list of people on the system. Right afterwards, the server will send more snapshots, but these contain outstanding messages the user has not yet read. Snapshots that have no <id> tag are just for name notification. Snapshots that have the <id> tag are outstanding messages.

Example response from server: This example assumes that user 124 has just logged in. That is, Steve Jobs has opened his instant messanger. The first two snapshot sets have no id tags in them. They are there to notify the app that there are only two users on the system. Bill and Steve. The third and fourth entry contains an id number. This is a message that was sent to Steve by Bill.

<snapshot> <message_app> <fromid>123</fromid> <from>Bill Gates</from> </message_app> </snapshot> <snapshot> <message_app> <fromid>124</fromid> <from>Steve Jobs</from> </message_app> </snapshot> <snapshot> <message_app> <id>90789</id> <fromid>123</fromid> <from>Bill Gates</from> <text>you going to COMDEX?</text> </message_app> </snapshot> <snapshot> <message_app> <id>90790</id> <fromid>123</fromid> <from>Bill Gates</from> <text>nevermind</text> </message_app> </snapshot>

sending a message

to send a message, the application sends an update package with the add mode.

HOWEVER, we overload the usage of the fromid tag. This field becomes the TARGET individual to send the message to.

Example: Steve sending a message to Bill

<update> <mode>add</mode> <message_app> <fromid>123</fromid> <text>you privately use a mac, don't you?<text> </message_app> </update>

getting a message

This message is sent by the server to all devices owned by a user to notify that an instant message has come in.

Example: Bill receiving Steve's message

<synch> <mode>add</mode> <message_app> <id>78945</id> <fromid>123</fromid> <from>Steve Jobs</from> <text>you privately use a mac, don't you?</text> </message_app> </synch>

reading a message

once a user has read a message, the application should send this package to the server to indicate that the message has been read. That allows the server to broadcast that to all other devices owned by that user. Note that the id needs to be provided so that the message that got read can be identified.

Example:

<update> <mode>delete</mode> <message_app> <id>78945</id> </message_app> </update>

synchronizing on message read

This message is sent by the server to all devices owned by the user to notify all devices that a particular message got read. Note that the broadcast includes the device that generated the original 'message read' packet.

Example:

<synch> <mode>delete</mode> <message_app> <id>78945</id> </message_app> </synch>