Commit d2901058 authored by Per Cederqvist's avatar Per Cederqvist
Browse files

(Preface): New name for former "Overview".

(Notation): Section moved from "Overview" to "Fundamentals".
(Client-Server Dialog): Section moved from "Introduction" to "Fundamentals".
(Fundamentals): New name for former chapter "Data Types".
(LysKOM Data Types): Moved from "Data Types" to a separate
	chapter.  All subsections moved up one level.
(Name Expansion): All subsections moved up one level -- the level was wrong.
parent 8da0a934
......@@ -13,7 +13,7 @@
@c FIXME: sentence-end-double-space!
@c FIXME: "Foo bar (bar baz.)" or "Foo bar (bar baz)."?
@c
@c $Id: Protocol-A.texi,v 1.133 2001/05/01 18:14:50 ceder Exp $
@c $Id: Protocol-A.texi,v 1.134 2001/05/01 18:51:38 ceder Exp $
@c %**start of header
@setfilename protocol-a.info
@settitle LysKOM Protocol A
......@@ -361,9 +361,10 @@ The most up-to-date version if this document can always be found at
@end ifnottex
@menu
* Overview::
* Preface::
* Introduction::
* Data Types::
* Fundamentals::
* LysKOM Data Types::
* Protocol Requests::
* Asynchronous Messages::
* Error Codes::
......@@ -378,8 +379,8 @@ The most up-to-date version if this document can always be found at
* Index::
@end menu
@node Overview
@chapter Overview
@node Preface
@chapter Preface
@iftex
This document specifies version @value{PROTOVER} of LysKOM Protocol A.
......@@ -414,33 +415,6 @@ Linus Tolke @email{linus@@lysator.liu.se} and
The LysKOM developers can be reached by email to
@email{lyskom@@lysator.liu.se}.
@menu
* Notation::
@end menu
@node Notation
@section Notation
This specification uses a BNF-like grammar to describe the protocol and
its data elements.
Data fields have been given names that start with a lower-case letter.
Fundamental data types have names in all-caps (such as @type{INT32} and
@type{ARRAY}).
Derived data types have names that start with an upper-case letter. (If
the type contains more than one word, all words start with an upper-case
letter, like this: @type{Text-Stat}.) The operator @code{::=} defines
the name to its left.
Comments start with @code{!} (exclamation mark) and alternatives are
separated by a @code{|} (vertical bar.) A @code{;} (semicolon)
terminates statements in the grammar. In some specifications there are
literal strings. There is to be no whitespace before or after literal
strings unless there is whitespace in the literal itself.
@node Introduction
@chapter Introduction
......@@ -455,7 +429,6 @@ conferences and sessions.
* The Aux-Item List::
* Security::
* Membership and Reading::
* Client-Server Dialog::
@end menu
......@@ -1383,119 +1356,8 @@ efficient but perfectly serviceable @reqdlink{get-map} call
instead@linkhere{}.
@node Client-Server Dialog
@section Client-Server Dialog
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
followed by connection information required by that protocol. In
protocol A the connection information is a Hollerith string saying who
the user connecting is followed by a newline character.
The format of the string should be @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.
@example
% telnet kom.lysator.liu.se 4894
Trying 130.236.254.151 ...
Connected to varg.lysator.liu.se.
@c This comment matches the bracket on the next line: [
Escape character is '^]'.
A26Hbyers%kajsa.lysator.liu.se
LysKOM
@end example
Besides the string "LysKOM", the server may respond with "%%Unsupported
protocol" or "%% No connections left.".
The "%%Unsupported protocol" reply is sent if the server does not
understand the requested protocol.
The "%% 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.
After connecting, 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
character (ASCII 0x0A).
@example
server-call ::=
( ref-no : INT32;
request : Protocol-Request;
)
@end example
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.
@example
server-reply ::= ok-reply | error-reply | protocol-error;
ok-reply ::=
( "="
ref-no : INT32;
reply-data;
)
error-reply ::=
( "%"
ref-no : INT32;
error-no : Error-No;
error-status : INT32;
)
error-no ::= INT32;
protocol-error ::= "%% LysKOM protocol error."
@end example
Our notation is not flexible enough to specify the two-way nature of
the communication. @field{ref-no} in the reply is always the same as
@field{ref-no} in the corresponding request. @field{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.
Error reporting is covered in more detail in @ref{Error Codes}.
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
@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.
@node Data Types
@chapter Data Types
@node Fundamentals
@chapter Fundamentals of Protocol A
The data types in protocol A come in two flavors. The first (vanilla)
are the simple data types from which the LysKOM (chocolate) data types
......@@ -1503,10 +1365,34 @@ are built. Simple data types include things like integers and strings
while complex data types include things such as conferences and people.
@menu
* Notation::
* Simple Data Types::
* LysKOM Data Types::
* Client-Server Dialog::
@end menu
@node Notation
@section Notation
This specification uses a BNF-like grammar to describe the protocol and
its data elements.
Data fields have been given names that start with a lower-case letter.
Fundamental data types have names in all-caps (such as @type{INT32} and
@type{ARRAY}).
Derived data types have names that start with an upper-case letter. (If
the type contains more than one word, all words start with an upper-case
letter, like this: @type{Text-Stat}.) The operator @code{::=} defines
the name to its left.
Comments start with @code{!} (exclamation mark) and alternatives are
separated by a @code{|} (vertical bar.) A @code{;} (semicolon)
terminates statements in the grammar. In some specifications there are
literal strings. There is to be no whitespace before or after literal
strings unless there is whitespace in the literal itself.
@node Simple Data Types
@section Simple Data Types
......@@ -1717,8 +1603,119 @@ corresponding @var{type} is its type.
Structures are transmitted as a sequence of their fields.
@node Client-Server Dialog
@section Client-Server Dialog
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
followed by connection information required by that protocol. In
protocol A the connection information is a Hollerith string saying who
the user connecting is followed by a newline character.
The format of the string should be @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.
@example
% telnet kom.lysator.liu.se 4894
Trying 130.236.254.151 ...
Connected to varg.lysator.liu.se.
@c This comment matches the bracket on the next line: [
Escape character is '^]'.
A26Hbyers%kajsa.lysator.liu.se
LysKOM
@end example
Besides the string "LysKOM", the server may respond with "%%Unsupported
protocol" or "%% No connections left.".
The "%%Unsupported protocol" reply is sent if the server does not
understand the requested protocol.
The "%% 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.
After connecting, 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
character (ASCII 0x0A).
@example
server-call ::=
( ref-no : INT32;
request : Protocol-Request;
)
@end example
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.
@example
server-reply ::= ok-reply | error-reply | protocol-error;
ok-reply ::=
( "="
ref-no : INT32;
reply-data;
)
error-reply ::=
( "%"
ref-no : INT32;
error-no : Error-No;
error-status : INT32;
)
error-no ::= INT32;
protocol-error ::= "%% LysKOM protocol error."
@end example
Our notation is not flexible enough to specify the two-way nature of
the communication. @field{ref-no} in the reply is always the same as
@field{ref-no} in the corresponding request. @field{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.
Error reporting is covered in more detail in @ref{Error Codes}.
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
@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.
@node LysKOM Data Types
@section LysKOM Data Types
@chapter LysKOM Data Types
In this section the data types specific to LysKOM are defined. Most of
these will probably make very little sense until you know what calls
......@@ -1728,13 +1725,13 @@ asynchronous messages, even though these are also data types.
Since the types defined here are all based on the simple types, the
definitions are more concise in this section.
@subsection Common Types
@section Common Types
The types defined in this section are fairly simple and used in many of
the more complex data types.
@anchor{Time}
@subsubsection Time
@subsection Time
@tindex Time
@example
......@@ -1766,7 +1763,7 @@ ignores the @field{day-of-week} and @field{day-of-year} fields.
All times are expressed in the time zone of the server.
@anchor{Conf-No}
@subsubsection Conference Numbers
@subsection Conference Numbers
@tindex Conf-No
@example
......@@ -1779,7 +1776,7 @@ This type denotes a conference number.
@anchor{Text-No}
@anchor{Local-Text-No}
@anchor{Text-List}
@subsubsection Text Numbers
@subsection Text Numbers
@tindex Text-No
@tindex Local-Text-No
......@@ -1800,7 +1797,7 @@ global numbers are required.
@anchor{Pers-No}
@anchor{Session-No}
@subsubsection Person and Session Numbers
@subsection Person and Session Numbers
@tindex Pers-No
@tindex Session-No
......@@ -1817,7 +1814,7 @@ sessions.
@anchor{Aux-Item}
@anchor{Aux-Item-Input}
@anchor{Aux-Item-Flags}
@subsection Auxiliary Information
@section Auxiliary Information
@tindex Aux-No
@tindex Aux-Item
......@@ -1917,7 +1914,7 @@ The object the item is set on will not be garbage-collected.
@anchor{Conf-Type}
@anchor{Extended-Conf-Type}
@anchor{Any-Conf-Type}
@subsection Conference Types
@section Conference Types
@tindex Conf-Type
@tindex Extended-Conf-Type
......@@ -1982,7 +1979,7 @@ conference is created these should always be set to zero.
@anchor{Conf-Z-Info}
@subsection Conference Search Results
@section Conference Search Results
@tindex Conf-Z-Info
@example
......@@ -1999,7 +1996,7 @@ conferences based on their names.
@anchor{Garb-Nice}
@anchor{Conference-Old}
@subsection Conference Status Types
@section Conference Status Types
@tindex Garb-Nice
@tindex Conference-Old
......@@ -2127,7 +2124,7 @@ the conference.
@end table
@anchor{Conf-List-Archaic}
@subsection Archaic way to list conferences
@section Archaic way to list conferences
The result of request number 12, lookup-name, cannot be expressed in the
grammar used in this document. This is as close as it gets:
......@@ -2146,7 +2143,7 @@ actually transmitted. See also the example in @ref{lookup-name}.
@anchor{Text-Mapping}
@subsection Mapping Local to Global Text Numbers
@section Mapping Local to Global Text Numbers
@tindex Text-Mapping
@tindex Local-To-Global-Block
......@@ -2212,7 +2209,7 @@ indicate that a certain local text number doesn't exist.
@anchor{Info}
@subsection Server Information
@section Server Information
@tindex Info
@tindex Info-Old
......@@ -2286,7 +2283,7 @@ Human-readable name of the server software version.
@anchor{Person}
@subsection Person Status Types
@section Person Status Types
@tindex Person
@tindex Personal-Flags
......@@ -2396,7 +2393,7 @@ The number of conferences the person is a member of.
@anchor{Membership-Type}
@subsection Membership Information
@section Membership Information
@tindex Membership-Type
@example
......@@ -2531,7 +2528,7 @@ to know about the person.
@anchor{Mark}
@subsection Article Marks
@section Article Marks
@tindex Mark
@example
......@@ -2558,7 +2555,7 @@ values.
@anchor{Misc-Info}
@subsection Article Information
@section Article Information
@tindex Misc-Info
@tindex Text-Stat-Old
......@@ -2669,7 +2666,7 @@ introduced in protocol version 10 or later.
@anchor{Who-Info-Old}
@anchor{Who-Info}
@anchor{Who-Info-Ident}
@subsection Who Information
@section Who Information
@tindex Who-Info-Old
@tindex Who-Info
......@@ -2761,7 +2758,7 @@ at the user's machine or ``unknown'' if Ident was not used.
@anchor{Session-Info}
@anchor{Session-Info-Ident}
@subsection Session Information
@section Session Information
@tindex Session-Info
@tindex Session-Info-Ident
@tindex Static-Session-Info
......@@ -8504,14 +8501,14 @@ specific call.
Names in LysKOM can be expanded according to two rules, regexp matching
or KOM conventions.
@subsection Regexp Matching
@section Regexp Matching
This type of expansion, used by the @reqdlink{re-z-lookup} call and
its predecessors@linkhere{} simply matches @command{ed}(1) style
regular expressions to names in the database to find the list of
matching names. The matching is case sensitive.
@subsection KOM Conventions
@section KOM Conventions
This type of matching is a little more complicated. Patterns consist of
words and parenthesized expressions, and contain implicit wildcards. The
......@@ -8529,7 +8526,7 @@ For example ``L D'' matches ``LysKOM (client, server and protocol)
Discussion (and) Ideas'', but not ``LysKOM Protocol Discussion''.
@subsection Case Conversion
@section Case Conversion
Character case is converted according to a collate table in the server.
The collate table is not really a protocol issue, and in a future
......
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