Communication

OOCSI follows a simple client-server communication, usually over established and persistent channels or sockets. The figure below shows how clients can send messages in the OOCSI system from client to client directly, or from a client to multiple client that subscribe to a channel. In the latter case, the OOCSI server will take care of duplicating and dispatching a message to a channel to all subscribing clients in the channel.

Protocol

The OOCSI system uses a simple message-centric communication protocol between client and server which will be explained in the following. All protocol steps can be reproduced via a simple text-based socket session, for instance, using a telnet session. The “code” examples below show excerpts from a telnet session, with CLIENT: and SERVER: prepending the respective responses of client and server in the session.

The handshake

The first step to establishing a connection from a client to an OOCSI server is the handshake procedure: after opening the socket connection, the client is required to send its unique handle.

Trying 100.100.100.100...
Connected to oocsi.example.com.
Escape character is '^]'.
client: clientA
server: welcome clientA

When sending the handle it is possible to also indicate the type of client and the mode of communication that the server should adhere to. Currently there are three different modes that differ in the style of the server messages towards the client.

Java (default)

Data payload of messages from the server will be sent as a Base64-encoded Java serialised Map<String, Object> object that can be deserialised easily by a Java client, but is rather opaque to other clients.

Trying 100.100.100.100...
Connected to oocsi.example.com.
Escape character is '^]'.
client: clientA
server: welcome clientA
server: ...
server: send clientA rO0ABXNyABFqYXZhLnV0aWwuSGFzaE1hcAUH2sHDFmDRAwACRgAKbG9hZEZhY3RvckkACXRocmVzaG9sZHhwP0AAAAAAAAx3CAAAABAAAAABdAAEZGF0YXQABDU1NTV4 1447851994643 clientB

The last row indicates the specific message format for this communication mode.

OSC/PureData/MaxMSP

To start the session in this mode, append a semicolon character (‘;’) to the client handle. Messages from the server will be sent in the format <receiving client> data=<data as String> timestamp=<UNIX TIME> sender=<sending client>.

Trying 100.100.100.100...
Connected to oocsi.example.com.
Escape character is '^]'.
client: clientA;
server: welcome clientA;
server: ...
server: clientA data=5555  timestamp=1447852054913 sender=clientB;

The last row indicates the specific message format for this communication mode.

JSON

To start the session in the mode, append “(JSON)” to the client handle. All responses will be sent back from the server as JSON objects.

Trying 100.100.100.100...
Connected to oocsi.example.com.
Escape character is '^]'.
client: clientA(JSON)
server: {"message" : "welcome clientB"}
server: ...
server: {"data":"5555","recipient":"clientA","timestamp":1447853221846,"sender":"clientB"}

The last row indicates the specific message format for this communication mode.

Sending messages

Sending messages to other clients or channels (and their subscribed clients) is possible via three commands: send, sendraw and sendjson.

Java (default)

The first one is only applicable to Java clients that can encode the data payload as a Base64-encoded Java serialisation of a Map<String, Object> object. The format of the command is send <receiving client handle or channel name> DATA:

Trying 100.100.100.100...
Connected to oocsi.example.com.
Escape character is '^]'.
client: clientA
server: welcome clientA
client: send clientB rO0ABXNyABFqYXZhLnV0aWwuSGFzaE1hcAUH2sHDFmDRAwACRgAKbG9hZEZhY3RvckkACXRocmVzaG9sZHhwP0AAAAAAAAx3CAAAABAAAAABdAAEZGF0YXQABDU1NTV4

OSC/PureData/MaxMSP

Below is the sendraw variant, which allows to submit the data payload in a non-encoded way. The format of the command is sendraw <receiving client handle or channel name> DATA with the data being a string that will be transmitted verbatim.

Trying 100.100.100.100...
Connected to oocsi.example.com.
Escape character is '^]'.
client: clientA
server: welcome clientA
client: sendraw clientB dataisdataisdata:isdata=isdata

JSON

Below is the sendjson variant, which allows to submit the data payload as JSON. The format of the command is sendjson <receiving client handle or channel name> DATA with the data being a JSON string that will be transmitted verbatim.

Trying 100.100.100.100...
Connected to oocsi.example.com.
Escape character is '^]'.
client: clientA
server: welcome clientA
client: sendjson clientB {"dataInt":1,"dataFloat":3.14,"dataString":"hello world"}

The three different send commands will not have a direct response from server.

Subscribing to a channel

Clients can subscribe to a channel by using the subscribe <CHANNEL NAME> command. From that point on, the client will receive (in addition to other messages) all messages sent by others to the given channel. If the client has been already subscribed to this channel, the command has no effect:

Trying 100.100.100.100...
Connected to oocsi.example.com.
Escape character is '^]'.
client: clientA
server: welcome clientA
client: subscribe testchannel

Unsubscribing from a channel

Clients can unsubscribe from a channel by using the unsubscribe <CHANNEL NAME> command. From that point on, the client will not receive anymore messages sent to the given channel. If the client has not been subscribed to this channel, the command has no effect:

Trying 100.100.100.100...
Connected to oocsi.example.com.
Escape character is '^]'.
client: clientA
server: welcome clientA
client: unsubscribe testchannel

Listing all clients, channels or sub-channels on server

All connected clients can be listed by using the clients command:

Trying 100.100.100.100...
Connected to oocsi.example.com.
Escape character is '^]'.
client: clientA
server: welcome clientA
client: clients
server: clientA, clientB

All open channels can be listed by using the channels command:

Trying 100.100.100.100...
Connected to oocsi.example.com.
Escape character is '^]'.
client: clientA
server: welcome clientA
client: channels
server: clientA, clientB, testchannel

All sub-channels of a channel can be listed by using the channels <CHANNEL> command:

Trying 100.100.100.100...
Connected to oocsi.example.com.
Escape character is '^]'.
client: clientA
server: welcome clientA
client: channels testchannel
server: clientA, clientB

Saying good-bye

Use the quit command to quit the current session and end the connection to the OOCSI server. The server will internally remove the channel associated to the client handle and also close previously subscribed to channels if they remain empty after the client has left the server.

Trying 100.100.100.100...
Connected to oocsi.example.com.
Escape character is '^]'.
client: clientA
server: welcome clientA
client: quit
Connection closed by foreign host.

Protocol revision: Nov 21, 2015