Node:Client-Server Dialog, Next:Protocol Error Messages, Previous:Connecting to the Server, Up:Fundamentals
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;
reply-data;
)
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 or newer, 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).
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.