Commit 1e59e342 authored by Per Cederqvist's avatar Per Cederqvist

(Connecting to the Server): New node, containing the first part of the

	"Client-Server Dialog" node. Added a footnote about "Protocol
	A" and "Protocol B".  Added some missing markup.  Don't talk
	about what happens when a protocol other than Protocol A is
	used.  The error message for an unsupported protocol is
	"%%LysKOM unsupported protocol.", not "%%Unsupported
	protocol".  The error message used when no connections are
	available was lacking the trailing dot.
(Client-Server Dialog): Much text moved to "Connecting to the
	Server".  Mention that the client can issue several calls without
	waiting for the replies, but that it must read replies when they
	arrive.  Mention that the replies are sent back in the proper
	order, but that clients are wise not to rely on that.  Renamed
	error-no in the error-reply to error-code, to make the document
	more coherent.  Changed the type of error-code to INT32, and
	removed the types Error-No and error-no.  Added the "insane token
	length" and "insane array size" error messages to protocol-error.
(Error Responses): Node removed.  The old contents were moved into
	"Client-Server Dialog" or discarded because it was redundant.
(Protocol Error Messages): New name for former "Special Errors".
	Removed "%%No connections left.", since that message is only sent
	during connection establishment.
(Error Codes): Refer to error-status, not error-code.
(Future changes): Talk about why giving the server freedom to
	reorder the replies may be beneficial, and how it can be done
	without breaking any clients.
parent 34948202
......@@ -24,7 +24,7 @@
@c FIXME: "Review the last N by FOO to BAR" is empty
@c FIXME: "Remote control" contains no information
@c
@c $Id: Protocol-A.texi,v 1.139 2001/05/04 09:06:07 ceder Exp $
@c $Id: Protocol-A.texi,v 1.140 2001/05/05 07:38:55 ceder Exp $
@c %**start of header
@setfilename protocol-a.info
@settitle LysKOM Protocol A
......@@ -1005,7 +1005,9 @@ while complex data types include things such as conferences and people.
@menu
* Notation::
* Simple Data Types::
* Connecting to the Server::
* Client-Server Dialog::
* Protocol Error Messages::
@end menu
@node Notation
......@@ -1241,26 +1243,33 @@ corresponding @var{type} is its type.
Structures are transmitted as a sequence of their fields.
@node Client-Server Dialog
@section Client-Server Dialog
@node Connecting to the Server
@section Connecting to the Server
The client-server dialog consists of two phases, establishing the connection
and the LysKOM session itself.
@subsection Connecting to the Server
A connection to the server is initiated by connecting to the appropriate
network port@footnote{The default port for a LysKOM server is 4894.} and
sending a single letter which is used to select a protocol version
sending a single letter which is used to select a protocol version.
This letter should always be @samp{A}@footnote{In the early 1990s
there was much discussion about the next generation LysKOM protocol,
called ``Protocol B'', and at one point in time it was believed that
``Protocol B'' would arrive at the same time as ``Emacs 19''. ``Emacs
19'' arrived and was obsoleted by new versions. Meanwhile, it was
discovered that ``Protocol A'' was more extensible that first
believed. ``Protocol A'' will continue to evolve, but it is unlikely
that it will ever be superceded by ``Protocol B''.}.
The protocol version letter should be
followed by connection information required by that protocol. In
protocol A the connection information is a Hollerith string saying who
protocol A the connection information is a @type{HOLLERITH} string saying who
the user connecting is followed by a newline character.
The format of the string should be @var{username} % @var{hostname}.
The format of the string should be @samp{@var{username} % @var{hostname}}.
When the server has accepted the connection its reply is
protocol-dependent. Protocol A servers will reply with the string
@code{LysKOM} on a single line if the connection attempt is successful.
When the server has accepted the connection it replies with the string
@code{LysKOM} on a single line.
@example
% telnet kom.lysator.liu.se 4894
......@@ -1272,18 +1281,26 @@ protocol-dependent. Protocol A servers will reply with the string
LysKOM
@end example
Besides the string "LysKOM", the server may respond with "%%Unsupported
protocol" or "%% No connections left.".
Besides the string @samp{LysKOM}, the server may respond with
@samp{%%LysKOM unsupported protocol.} or @samp{%% No connections left.}.
The "%%Unsupported protocol" reply is sent if the server does not
understand the requested protocol.
The @samp{%%LysKOM unsupported protocol.} reply is sent if the server
does not understand the requested protocol, that is, if the first
character is anything but an @samp{A}. The connection will be closed
by the server as soon as this string has been sent.
The "%% No connections left" reply is sent if the server is not
The @samp{%% No connections left.} reply is sent if the server is not
accepting additional connections. This error is transient. The next
connection attempt may succeed. Clients should wait a few seconds before
attempting to make another connection after receiving this error.
The connection will be closed by the server as soon as this string has
been sent.
@node Client-Server Dialog
@section Client-Server Dialog
After connecting, calls to the server can be made. Most calls require
After connecting (@pxref{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 @emph{must} be terminated with a linefeed
......@@ -1296,9 +1313,18 @@ character (ASCII 0x0A).
)
@end example
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.
number. The replies will be sent in the same order as the
requests@footnote{Client writers are encouraged to write the clients
so that they are prepared for replies that are sent out-of-order.
@xref{Future changes}, for speculations about how that may benefit the
client in the future.}.
@example
server-reply ::= ok-reply | error-reply | protocol-error;
......@@ -1312,13 +1338,13 @@ number.
error-reply ::=
( "%"
ref-no : INT32;
error-no : Error-No;
error-code : INT32;
error-status : INT32;
)
error-no ::= INT32;
protocol-error ::= "%% LysKOM protocol error."
| "%%Insane token length."
| "%%Insane array size."
@end example
Our notation is not flexible enough to specify the two-way nature of
......@@ -1330,8 +1356,6 @@ request.
Note that there is no whitespace after the initial indicator in the
reply.
Error reporting is covered in more detail in @ref{Error Responses}.
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).
......@@ -1345,54 +1369,23 @@ spaces and terminating all requests with a linefeed character. The
@errorcode{not-implemented} error code will not be returned properly
unless the client follows this requirement.
If the request is syntactically incorrect, the server will respond with
the string "%% LysKOM protocol error." The server will attempt to
recover from the error, but in some cases complete recovery may not be
possible, which may result in one or more subsequent requests being
lost.
@menu
* Error Responses::
* Special Errors::
@end menu
@node Error Responses
@subsection Error Responses
The server may return two different types of errors. Normal
@type{error-reply} errors are replies to syntactically correct calls
to the server, while @type{protocol-error} are replies to syntactically
incorrect calls. @xref{Protocol Error Messages}, for more information
about @type{protocol-error}.
If a call cannot complete successfully, LysKOM will respond with an
error reply, as defined below and earlier (@pxref{Client-Server
Dialog}).
@example
error-reply ::= normal-error | special-error
normal-error ::=
( "%"
ref-no : INT32;
error-no : Error-No;
error-status : INT32;
)
special-error ::= "%% LysKOM protocol error."
| "%%Insane token length."
| "%%Insane array size."
| "%%No connections left."
error-no ::= INT32;
@end example
The server may return two different types of errors. Normal errors are
replies to syntactically correct calls to the server. Special errors are
replies to syntactically incorrect calls and responses to exceptional
conditions.
@type{error-reply}. The meaning of @field{error-code} and
@field{error-status} varies depending on the request; see @ref{Error
Codes}, and the documentation for each call, for a list of available
@field{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
@field{error-status} was more or less undefined before protocol version
10. For protocol version 10, the meaning of @field{error-status} is
defined below.
defined in this document.
The meaning of @field{error-status} can be modified by any call. In
particular the calls that deal with Misc-Info lists set
......@@ -1411,11 +1404,11 @@ cause the wrong error message to be sent or new errors might be added
later on.
@node Special Errors
@subsection Special Errors
@node Protocol Error Messages
@section Protocol Error Messages
Special errors are sent in reply to syntactically incorrect calls to the
server. With the exception of the "No connections left" message, these
Protocol error messages are sent in reply to syntactically incorrect
calls to the server. These
should never appear in the client-server dialog. If they do, there is
probably a bug in the client.
......@@ -1424,16 +1417,10 @@ probably a bug in the client.
The client has sent a request that does not comply with protocol A. The
server will attempt to recover from this error, but additional calls may
be silently lost, and the server may send replies that the client does
not expect. This error is also returned when the client sends an array
not expect, and in some cases recovery may not be possible.
This error is also returned when the client sends an array
that is longer than the maximum allowed by the server.
@item "%%No connections left."
This error is only sent when the client attempts to connect to the
server. It indicates that the server is not accepting additional
connections. This error is transient: the client may be able to connect
later. Clients should not attempt to connect immediately after
receiving this message.
@item "%%Insane token length."
The client has sent a single token that is insanely long. Typically this
means that the client has sent several kilobytes worth of digits, or
......@@ -7899,7 +7886,7 @@ short explanation. The explanation given below is the default
semantics for the error code. It can be updated by the descriptions
found for a specific call.
@xref{Error Responses}, for more information about error responses,
@xref{Client-Server Dialog}, for more information about error responses,
including the syntax of the error response.
@table @code
......@@ -8089,7 +8076,7 @@ marked, when in fact it is not marked. @field{error-status} indicates the
text in question.
@item temporary-failure (45)
Temporary failure. Try again later. @field{error-code} is undefined.
Temporary failure. Try again later. @field{error-status} is undefined.
@item long-array (46)
An array sent to the server was too long. @field{error-status} is
......@@ -9071,6 +9058,20 @@ no easy way to undo such an operation. You can use
calls to get the desired effect, but it would be nice to have a
@samp{mark-as-unread} call.
@item
If the client issues several request without waiting for a reply, the
replies will nevertheless always arrive in the same order as the
requests were sent in. If a threaded version of the LysKOM server is
ever made, it could possibly process two requests from the same client at
the same time, and the answers could be returned in any order.
However, the current clients are probably not written so that they can
handle such reordering.
In the future, a new call might be added, so that a client can give
the server explicit permission to reorder the replies. The client
would then have to rely on the @field{ref-no} to match each reply to
the corresponding call.
@end itemize
@node Protocol Version History
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment