protocol
this page describes the message protocol used for the communication between _chat.pd and server.the message format sent by the client is basically of the form: :
<recipient> <key> <value> [<value> [<value> [...]]];
the message format received from the server is usually just: :
<key> <value> [<value> [<value> [...]]];
those fields are delimited by whitespaces and each message is terminated by a semicolon ;. However, when working in puredata, the semicolon is added automatically and can be omitted (there is no way to create a litteral semicolon in puredata anyway).
recipient
the recipient can be either a number, which represents the socket number of the recipient, or it can be _all in order to send the message to all connected clients. there are also some special recipients. here a list of all valid recipients: :
_all the server forwards the message to all connected clients
<socketnumber> the server forwards the message only to the client with socket <socketnumber>
_test dummy recipient, which does nothing, but can be used to keep connection established
_socketrequest is used to obtain the own socket number the server responses with a message:
ch.socket <socket number>;
the server evaluates the recipient field. depending on its value, the server forwards the message, responds itself with some message or it silently ignores the incoming message at all. in any case, what is received from the server does not have a recipient field anymore. any message with a non-valid recipient is ignored.
key
the key value can be an arbitrary element. because puredata uses a whitespace as a delimiter, it cannot contain whitespaces. there are some reserved keys used by chat: :
ch.msg is used by chat to send chat messages. the format is:
<recipient> ch.msg <nichname> <message> <own_socket>;
the socket number is used here to colorize the message in the chat display.
usually the recipient is _all. an exception is the response to ch.listrequest which uses
the socket number of the requesting client.
ch.listrequest is used to get a list of all connected clients. the format is:
<recipient> ch.listrequest <own_socket>
usually the recipient in this case is '_all'
after having sent such a message, from each client a message of the following
format will be received:
ch.msg <name> _on_socket:_<socket_number>_ <own_socket>;
ch.number is not used by the client. the server sends such message in order to tell clients
the number of all connected clients. the received message looks like this:
ch.number <number_of_connected_clients>;
ch.socket this key is only used by server in order to tell the socket number to the client. the
format of the received message looks like this:
ch.socket <own_socket>;
value
the value can be anything and can also have an arbitrary number of elements. everything that follows a recipient and a key field is considered part of the value field.
log of an example session
telnet netpd.org 3025 :
SERVER ch.number 3; # server sends number of connected clients CLIENT _socketrequest; # request own socket number SERVER ch.socket 6; # own socket number is 6 CLIENT _all ch.listrequest 6; # get a list of all connected clients SERVER ch.listrequest 6; # someone wants to know, who i am CLIENT 6 ch.msg name _on_socket:_6_ 6; # i respond with a ch.msg with my socket number SERVER ch.msg roman _on_socket:_4_ 4; # get response SERVER ch.msg syntax_tn _on_socket:_5_ 5; # "" SERVER ch.msg name _on_socket:_6_ 6; # "" CLIENT _all ch.msg name hello.i.am.new.here 6; # send a chat message SERVER ch.msg name hello.i.am.new.here 6; # receive a chat message CLIENT _all mysynth 64; # touching a slider of mysynth SERVER mysynth 64; # "" CLIENT _all mysynth 65; # "" SERVER mysynth 65; # "" CLIENT _all mysynth 66; # "" SERVER mysynth 66; # ""