The primary purpose of libsockio is to pass messages between programs. The content of the messages depends on the specifics of the protocol implemented on top of libsockio, but libsockio does impose some restrictions on this protocol.
Messages passed back-and-forth across the socket are octet (byte) data
with a pre-defined maximum size (defined in the header file as SBUF_SIZE,
currently 32768 bytes)
and are line-based (terminated with '\n' or '\0').
The terminator is added by the library on outgoing messages, and removed
by the library from incoming messages. Neither '\n' nor
'\0' may appear inside the message itself. Trailing
'\r' characters are removed from the end of a message,
if present. This is to allow the alternate "\r\n"
newlines sent by some ``telnet'' clients. All other characters are legal
(as far as libsockio is concerned.) The safest approach is to encode
all bytes less than ASCII 32 (space). Actual encoding of messages is
outside the scope of this library.
Another restriction placed on the protocol is that the each message sent by a client to the server must have a response. The client can never send more than one message at a time, without an intervening message back from the server. The messages from the server to the client can be asynchronous, or multi-line (if your protocol supports it), but communication in the other direction is more limited. These restrictions are a result of the design of libsockio.
As of version 1.4, a new facility has been added to allow a
server to send binary data in response to a client query.
Client and server must negotiate the size of this transfer
as part of their protocol, and the client API provided by
sockio does not handle reading this binary response itself.
Messages from the client-to-server direction are always limited to
single, line-based messages terminated with '\n' or '\0'.
Figure 1 shows each of the C files in the library and the main functions each one exports. A server would typically use the library directly (i.e., it would link with -lsockio) while a client might use a protocol library to facilitate communication with a specific type of server. If this protocol library is built on top of the client-side of libsockio, a client would need to link with both (i.e., -lprotocol -lsockio). See section 1.3 for and example of this.
Figure 2 shows a server (the envserv example in the project directory) and two clients based on a an envserv-specific protocol library called libssenv.a. The clients simply set and get values in the server, by making calls to libssenv. More clients could be created to interact with this server just by using the three calls (ss_initenv, ss_getenv, ss_setenv) in libssenv.a.
