Node:Client-Server Dialog, Next:, Previous:Connecting to the Server, Up:Fundamentals

Client-Server Dialog

After connecting (see Connecting to the Server), calls to the server can be made. Most calls require the user to log in, but some calls can be made without a log-in. Calls to the server are made by sending a reference number followed by the call as specified. The call must be terminated with a linefeed character (ASCII 0x0A).

        server-call ::=
                ( ref-no        :       INT32;
                  request       :       Protocol-Request;

The client may send several requests without waiting for the replies. However, the server will only buffer a limited amount of replies, so the client must check for pending replies from the server at least each time it sends requests to the server.

At some future point the server will reply with the result of the request or an error code preceded by an indicator and the reference number. The replies will be sent in the same order as the requests1.

        server-reply ::= ok-reply | error-reply | protocol-error;

        ok-reply ::=
                ( "="
                  ref-no        :       INT32;

        error-reply ::=
                ( "%"
                  ref-no        :       INT32;
                  error-code    :       INT32;
                  error-status  :       INT32;

        protocol-error ::= "%% LysKOM protocol error."
                         | "%%Insane token length."
                         | "%%Insane array size."

Our notation is not flexible enough to specify the two-way nature of the communication. ref-no in the reply is always the same as ref-no in the corresponding request. reply-data depends on which request was made and is specified together with each request.

Note that there is no whitespace after the initial indicator in the reply.

Data elements sent from the client to the server are separated by one or more space characters (ASCII 32). An entire call is terminated by a linefeed character (ASCII 10).

Earlier versions of the protocol specified that data elements could be separated by any number of linefeed (ASCII 10), return (ASCII 13), tab (ASCII 9) or space (ASCII 32) characters. Servers should be forgiving and understand requests using the older conventions, but clients must conform to the current convention of separating data elements with spaces and terminating all requests with a linefeed character. The not-implemented error code will not be returned properly unless the client follows this requirement.

The server may return two different types of errors. Normal error-reply errors are replies to syntactically correct calls to the server, while protocol-error are replies to syntactically incorrect calls. See Protocol Error Messages, for more information about protocol-error.

If a call cannot complete successfully, LysKOM will respond with an error-reply. The meaning of error-code and error-status varies depending on the request; see Error Codes, and the documentation for each call, for a list of available error-code values and what they mean.

A client should be prepared for any error code in response to any call, no matter if the response makes any sense or not. The value returned in error-status was more or less undefined before protocol version 10. For protocol version 10, the meaning of error-status is defined in this document.

The meaning of error-status can be modified by any call. In particular the calls that deal with Misc-Info lists set error-status to the index of the misc item that caused the error (if the error was caused by a misc item.)

Client should handle the error messages listed with each call in a graceful manner. In addition, the following error types should always be handled gracefully: temporary-failure, internal-error, feature-disabled, not-implemented, obsolete-call, ldb-error, out-of-memory. Client should also be able to handle any error in any situation without choking completely since bugs might cause the wrong error message to be sent or new errors might be added later on.

The server may send asynchronous messages (see Asynchronous Messages) to the client at any time (but not in the middle of a reply). Two important asynchronous messages are async-new-text (see async-new-text) and async-send-message (see async-send-message).


  1. Client writers are encouraged to write the clients so that they are prepared for replies that are sent out-of-order. See Future changes, for speculations about how that may benefit the client in the future.