Communication: principles and message formats

Messages are passed between the client and server through a 'socket', which is a link between two programs through a network. The two programs can be on the same computer (I expect you will normally use this mode) or thousands of miles apart. The client/server computer(s) must have TCP/IP installed – the standard protocol for Internet communications. The client connects to the server by opening a connection with a standard port number, which is 3233.

Each message constitutes a single string. This is a very general format, which is why I chose it. Most modern computer languages have no difficulty understanding and manipulating strings, and humans can understand string-based output. If the client or server needs to send a number, it is simply encoded in a string; thus 15 is sent as '1' (ASCII 49) followed immediately by '5' (ASCII 53).

For technical reasons, it is impossible to guarantee that two separate messages do not get concatenated when sent over the network (or that a single message is not split into two). Therefore, each string sent by the server ends in a linefeed (LF; ASCII code 10 decimal, 0A hex, also written as CTRL-J, ^J or \n). When you send commands to the server, you must also end them with a linefeed or carriage return (CR), in case two of your commands become concatenated in transit, or one of your commands is split over two packets. You may also use a semicolon to separate commands.

If you need to pass a parameter that has a space or a semicolon in it, enclose the parameter in inverted commas (""). For example,

Message (↵ denotes carriage return or linefeed)	Interpreted as… (• denotes separation of parameters within one message)
messageone;messagetwo	messageone messagetwo
messageone; messagetwo	messageone messagetwo
messageone↵messagetwo	messageone messagetwo
message param1 param2	message•param1•param2
message x y z	message•x•y•z
message "x y" z	message•x y•z
message x y;z	message•x•y z
message x "y;z"	message•x•y;z
message x"y;z"	message•x•y;z
message x "y↵z"	message•x•y z this last example is probably an error on the part of the client!

The messages are described in the Whisker Command Set documentation. Strings to be quoted literally (in computer-speak, 'string literals') are shown in plain or monospaced type; parameters are shown in <italic> type surrounded by angle brackets ( < > ).

Client commands do not use a colon and are not case-sensitive. The server will accept multiple commands in one packet if they are separated by a carriage return (CR, ^M, CTRL-M, ASCII 13, \r), a linefeed (LF, ^J, CTRL-J, ASCII 10, \n) or a semicolon (; or ASCII 59). Quotes (inverted comma, ", ASCII 34) may be used to surround parameters that include spaces or semicolons, as described above.

Server responses use a colon, and will always give messages as they are described in this manual – CapitalizedWords with no space between them, a colon, a space and the rest of the message. (Exceptions: a colon is not given for Ping and PingAcknowledged commands, which can be sent by either the client or the server.) The server will always terminate each of its messages with a LF (\n, ASCII 10).