Commit e98d6e07 authored by David Byers's avatar David Byers
Browse files

Added first working version

parent 5fe9e7af
\input texinfo @c -*-texinfo-*-
@c $Id: Protocol-A.texi,v 1.1 1996/01/13 16:38:27 byers Exp $
@c %**start of header
@setfilename protocol-a.info
@settitle LysKOM Protocol A
@setchapternewpage odd
@c %**end of header
@iftex
@parindent 0pt
@end iftex
@ifinfo
This is the specification of LysKOM Protocol A v. 8.0
Copyright @copyright{} 1995 Lysator ACS.
Permission is granted to make and distribute verbatim copies of this
specification provided the copyright notice and this permission notice
are preserved on all copies.
@end ifinfo
@titlepage
@sp 10
@title{LysKOM Protocol A}
@sp 2
@subtitle{Protocol version 8.0}
@sp 2
@author by the LysKOM Developers
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1995 Lysator ACS
Permission is granted to make and distribute verbatim copies of this document
provided the copyright notice and this permission notice are preserved on all
copies.
Modified versions of this document may be redistributed with the added
condition that all modifications not cleared with the LysKOM development group
are clearly marked and that the entire modified work be redistributed under the
same conditions as the original.
Permission is granted to copy and distribute translations of this manual into
another language under the same conditions as for modified versions.
@end titlepage
@ifinfo
@node Top, Overview, (dir), (dir)
@comment node-name, next, previous, up
This document specifies LysKOM Protocol A, version 8.0
@menu
* Overview::
* Introduction::
* Data Types::
* Protocol Requests::
* Asynchronous Messages::
* Examples::
@end menu
@end ifinfo
@node Overview, Document Revision History, Top, Top
@chapter Overview
LysKOM is a conferencing system@footnote{Or in modern terms, enabling
technology for Computer-Supported Cooperative Work (CSCW).}. Similar systems
were QZ-KOM and PortaCOM@footnote{Also known as ``PottaKOM'' and
``BortaKOM.''}. The LysKOM system is copyrighted by Lysator Academic Computing
Society and distributed under conditions of the GNU Public License. LysKOM and
its documentation is provided ``as is'' without warranty of any kind.
This document specifies version 8.0 of protocol A used between a LysKOM client
and a LysKOM server. Anything described here as ``unspecified'' is liable to
change in future protocol versions.
This specification is the work of several people. The main contributors have
been Per Cederqvist @code{<ceder@@lysator.liu.se>},
@ifinfo
Pär
@end ifinfo
@iftex
P@"ar
@end iftex
Emanuelsson @code{<pell@@lysator.liu.se>}, Thomas Bellman
@code{<bellman@@lysator.liu.se>}, Lars Aronsson
@code{<aronsson@@lysator.liu.se>}, David Byers @code{<byers@@lysator.liu.se>},
Linus Tolke @code{<linus@@lysator.liu.se>} and
@ifinfo
Kent Engström
@end ifinfo
@iftex
Kent Eng@-str@"om@penalty-10000
@end iftex
@code{<kent@@lysator.liu.se>}.
The LysKOM developers can be reached by email to @code{lyskom@@lysator.liu.se}.
@menu
* Document Revision History::
* Protocol Revision History::
* Protocol Design Principles::
* Notation::
@end menu
@node Document Revision History, Protocol Revision History, Overview, Overview
@section Document Revision History
@table @asis
@item 8.0: 1995-11-10
Protocol version 8 is being documented. This specification was translated to
English and converted to Texinfo by David Byers.
@item 7.1: 1995-01-08.
Protocol and document revision history were added by Per Cederqvist. Outline
mode was used to make the document more manageable. This version was
distributed with lyskomd 1.7.1.
@item 7.0: 1994-12-31.
The first specification with a version number. All calls that had been added
since 1991-06-25 were documented. Pell and Per Cederqvist did the deed. This
version was distributed with lyskomd 1.7.0.
@item 1993-05-19.
Linus Tolke wrote comments for some calls that were without comments.
@item 1992-07-06.
Linus Tolke converted the document to ISO 8859-1.
@item 1991-08-12.
Per Cederqvist started using version control for documentation.
@item 1991-06-25.
Lars Aronsson documented the protocol that was in use at the time.
@end table
@node Protocol Revision History, Protocol Design Principles, Document Revision History, Overview
@section Protocol Revision History
@subsection Protocol version 8.0
@table @asis
@item Added Functionality
@itemize @bullet
@item
30=add-recipient: Can change recpt to cc_recpt and vice versa.
@item
21=set-conf-type: Accepts Conf-Type and Extended-Conf-Type.
@item
10=create-conf: Accepts Conf-Type and Extended-Conf-Type.
@end itemize
@item New Commands
@itemize @bullet
@item
77=set-last-read
@item
78=get-uconf-stat
@end itemize
@end table
@subsection Protocol version 7 (first implemented in lyskomd 1.7.0)
@table @asis
@item Added Functionality
@itemize @bullet
@item
53=send-message: Recipient can be a conference or a person.
@end itemize
@item New Commands
@itemize @bullet
@item
74=re-z-lookup
@item
75=get_version_info
@item
76=lookup_z_name
@end itemize
@item Other
@itemize @bullet
@item
Det asynkrona meddelanded 1=i-am-off has been removed
@end itemize
@end table
@subsection Protocol Version 6 (first implemented in lyskomd 1.4.0)
@table @asis
@item New Calls
@itemize @bullet
@item
67=lookup_person
@item
68=lookup_conf
@item
69=set_client_version
@item
70=get_client_name
@item
71=get_client_version
@item
72=mark_text
@item
73=unmark_text
@end itemize
@end table
@subsection Protocol Version 5 (first implemented in lyskomd 1.3.0)
@table @asis
@item New Calls
@itemize @bullet
@item
65=re_lookup_person
@item
66=re_lookup_conf
@end itemize
@end table
@subsection Protocol Version 4 (first implemented in lyskomd 1.1.1)
@table @asis
@item New Calls
@itemize @bullet
@item
62=login
@item
63=who_is_on_ident
@item
64=get_session_info_ident
@end itemize
@end table
@subsection Protocol Version 3 (first implemented in lyskomd 1.1.0)
@table @asis
@item New Calls
@itemize @bullet
@item
61=find_previous_text_no
@item
60=find_next_text_no
@item
59=create_anonymous_text
@item
58=get_last_text
@end itemize
@end table
@subsection Protocol Version 2 (first implemented in lyskomd 0.30.0)
@table @asis
@item New Calls
@itemize @bullet
@item
57=set_user_area
@end itemize
@end table
@subsection Protocol Version 1 (first implemented in lyskomd 0.29.2)
@table @asis
@item New Calls
All calls from 0--56.
@end table
@node Protocol Design Principles, Notation, Protocol Revision History, Overview
@section Transport Protocol Requirements
LysKOM protocol A can be run on top of any reliable, bidirectional,
8-bit data stream. All current implementations use TCP/IP. At Lysator
port 4894 is used on the host @code{kom.lysator.liu.se}.
Data in protocol A is ASCII clear text except within hollerith strings, where
arbitrary eight-bit characters are allowed. Data arguments are separated by
whitespace. The reason for this unorthodox design is that the protocol should
be usable from a text-only terminal, something that is very useful during
server and early client development.
@node Notation, , Protocol Design Principles, Overview
@section Notation
This specification uses a BNF-like grammar to describe the protocol and its
data elements. It does not use ASN.1 because we don't know ASN.1 and probably
wouldn't like it very much even if we did.
Data fields have been given names that start with a lower-case letter. Data
types have names that start with an upper-case letter. The operator @code{::=}
defines the name to its left and @code{:} (a colon) specifies a type. 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, , , Top
@chapter Introduction
This chapter introduces the concepts used in LysKOM, such as articles,
conferences and sessions.
@menu
* Articles ::
* Conferences ::
* Persons and Sessions ::
* The Misc-Info List ::
* Security ::
* Membership and Reading::
* Client-Server Dialog ::
@end menu
@node Articles, Conferences, , Introduction
@section Articles
An article is represented as a value of the type @code{Text-Stat} and a
string containing the article contents. An article will usually have one
or more recipients and may be a comment or footnote to other
articles. Each article is kept in the database until it is older than
the @code{nice} value of each of its recipients and it is not marked by
any user.
Currently there is a structure called a @code{Misc-Info-List} associated with
the @code{Text-Stat}. This list contains information about recipients,
senders, comments and footnotes. In the future the information contained in
the @code{Misc-Info-List} will be integrated into the @code{Text-Stat}.
Every article has at least one number, the global article number. Global
numbers are assigned in ascending order to new articles, and are never
reused. If an article has recipients it will also have a local number for each
recipients. Local numbers are used in some data structures to provide more
compact storage and to provida an ordering of articles for a particular
recipient. Local numbers are assigned in ascending order and are never reused
for a particular recipient, though different recipients will have articles
with the same local numbers.
Occasionally it is necessary to map between local and global numbers. The
server call @code{get-map} does this.
@node Conferences, Persons and Sessions, Articles, Introduction
@section Conferences
Conferences hold articles. They are represented in the protocol as a data type
called @code{Conference}. Each conference has a @emph{creator}, the person who
created the conference, and a @emph{supervisor}, a conference whose members can
modify the conference. If the supervisor is a person, the members of that
person's letterbox are supervisors, which in most cases is only that person.
We have also introduced a type called @code{UConference} (pronounced
micro-conf-stat) which holds a subset of the information contained in the full
@code{Conference} type. Use the @code{UConference} type whenever possible since
it places a much smaller load on the LysKOM server.
Each conference has a type, which is essentially a collection of boolean
flags. Currently the types @code{rd-prot}, @code{letterbox},
@code{secret}, @code{original} and @code{anarchy} are defined.
@table @code
@item rd-prot
The conference is protected from reading by non-members. Persons become
members by having one of the existing members or supervisors add him or
her to the conference. This restriction is enforced by the server.
@item original
Conferences of this type are intended for original articles
only. Comments are to be redirected to the super-conference
instead. This restriction is currently not enforced by the server;
clients must implement this functionality.
@item letterbox
Conferences of this type are connected to persons. Letters to a person are
sent to the letterbox and the name of the letterbox is synchronised with the
person name. It is currently not possible to explicitly set or clear this flag
on a conference.
@item secret
Conferences of this type are secret. The server will not divulge any
information of the existence of the conference to persons who are not
members or supervisors of the conference. If a letterbox is made secret,
that person cannot log in using the person name, but must specify a
person number instead.
@item anarchy
Conferences of this type accept anonymous articles. Other conferences will
reject anonymous articles. This restriction is currently not enforced by the
server, but will be soon.
@end table
@node Persons and Sessions, The Misc-Info List, Conferences, Introduction
@subsection Persons and Sessions
Persons are represented in the protocol by values of the type
@code{Person}. Associated with persons are statistics, a set of personal flags
and a set of privileges (@pxref{Security}.) Persons are also associated with a
conference that has the same number as the person and the @code{letterbox} bit
set.
Connections to the server are represented as values of the type
@code{Session-Info-Ident} or @code{Session-Info}. Sessions have session number
that are unique for each session in the lifetime of the server execution. A
single user can have several sessions running at once. The session is not
released until the network connection is closed; a user can log in and out
repeatedly in a single session.
@node The Misc-Info List, Security, Persons and Sessions, Introduction
@section The Misc-Info List
The @code{Misc-Info} list contains tagged data. The fields are sent in groups
pertaining to a particular type of information: information about recipient;
carbon copy recipient, comment to; footnote to; comment in and footnote in. The
information groups may be sent in any order and there may be any number of
groups. Within each group the elements are always sent in the order listed
below.
@subsubsection Recipient
@table @code
@item recpt
Starts a recipient group. It contains the conference number of a recipient of
the article.
@item loc-no
Always present within a recipient group. It contains the local text number of
the article in the conference specified by the preceding @code{recpt} field.
@item rec-time
If the recipient is a person, this element is added by the server when the
recipient marks the article as read. It contains the time when the text was
read.
@item sent-by
Present when the recipient was added by a person other than the author (after
the article was created.) It contains the person number of the person who added
the recipient.
@item sent-at
Present when the recipient was added after the article was created. It contains
the time when the recipient was added.
@end table
@subsubsection Carbon Copy (CC) Recipient
The carbon-copy recipient group is identical to the recipient group above. The
difference is how new comments to an article with a recipient or carbon-copy
recipient are treated. A comment to an article is sent to all recipients, but
not to carbon-copy recipients of the original article.
@table @code
@item cc-recpt
Starts a carbon-copy recipient group. It contains the conference number of a
carbon-copy recipient of the article.
@item loc-no
Always present in a CC recipient group. It contains the local text number of
the article in the conference specified by the most recent @code{cc-recpt}
field.
@item rec-time
Present after the CC recipient has read the article. It contains the time when
the article was read.
@item sent-by
Present when a CC recipient was added by a person other than the author
after the article had been created. It contains the person number of the
person who added the cc recipient.
@item sent-at
Present when a CC recipient was added after the article had been
created. It is the time when the CC recipient was added.
@end table
@subsubsection Comment To
@table @code
@item comm-to
Always present when the article is a comment to another article.
@item sent-by
Present when the article was added as a comment by a person other than
the author, after the article had been created. It contains the person
number of the person who added the article as a comment.
@item sent-at
Present when the article was added as a comment after the article had
been created. It contains the time when is was added as a comment.
@end table
@subsubsection Footnote To
@table @code
@item foot-to
Always present when the article is a footnote to another article.
@item sent-at
Present when the article was added as a footnote after the article had
been created. It contains the time when is was added as a footnote.
@end table
@subsubsection Comment in
@table @code
@item comm-in
Present when there are comments to this article. It contains the article
number which is a comment to this article.
@end table
@subsubsection Footnote in
@table @code
@item foot-in
Present when there are footnotes to this article. It contains the
article number which is a footnote to this article.
@end table
@node Security, Membership and Reading, The Misc-Info List, Introduction
@subsection Security
Security in LysKOM is based on two components. Each person has a set of
privileges and each session has a security level. Rights in the system
require both the sufficient privileges and a sufficient security
level. The privileges currently available are wheel, admin, statistic,
create-conf, create-pers and change-name. Security levels range from 0
to 255.
@table @code
@item wheel
@emph{Normally not assigned}
@table @asis
@item Level 0
Person may always log in, even when LysKOM is crowded.
@item Level 6
Person may set Priv-Bits for all persons.
@item Level 7
Person may set password for all persons.
@item Level 8
Person acts as supervisor for everything.
@item Level 10
Person can read all articles.
@end table
@item admin
@emph{Normally not assigned}
@table @asis
@item Level 1
Shut down the server@*
Set motd_of_kom@*
Read last_login
@item Level 2
Read status of secret conferences and persons@*
Read the protected parts of person and conference statuses@*
Read the entire text status, even when there are secret recipients
@item Level 3
Change everybody's names
@item Level 4
Add/remove members@*
Add/remove recipients to articles
@item Level 5
Set super-conference@*
Remove articles
@item Level 6
Set administrator
@end table
@item statistic
@emph{Normally not assigned}
@table @asis
@item Level 2
Read the statistics portions of persons, even if protected
@end table
@item create_conf
@emph{Normally assigned}
@table @asis
@item Level 0
Create conferences
@end table
@item create_pers
@emph{Normally assigned}
@table @asis
@item Level 0
Create persons
@end table
@end table
@node Membership and Reading, Client-Server Dialog, Security, Introduction
@section Membership and Reading
Persons' memberships in conferences are represented in the protocol as arrays
of @code{Membership}-typed values. This structure contains a record of what
the person has read in that conference.
The first part of the record is the @code{last-text-read} field. It contains
the highest local text number such that the person has read every text with an
equal or lower local number. The second part of the record is the
@code{read-texts} array, which contains the local text numbers higher than
@code{last-text-read} that are also read.
Finding out which articles a person has read in a particular conference
requires a few calls. Normally, a client will retrieve a batch of perhaps 50
articles at a time. The outline of the process is as follows:
@enumerate
@item Fetch the membership to get the @code{last-text-read}
@item Translate 50 local numbers starting as @code{last-text-read} to global
numbers.
@item Remove the local numbers that are in @code{read-texts} from the result
@item Get and translate more texts as needed.
@end enumerate
The process is complicated because of the translation between local and global
text numbers. In the future there will hopefully be a single call that does
this work in the server.
@node Client-Server Dialog, ,Membership and Reading , Introduction
@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 hewline character.
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.
@example
% telnet kom.lysator.liu.se
Trying 130.236.254.151 ...
Connected to varg.lysator.liu.se.
Escape character is '^]'.
A5Hbyers
LysKOM
@end example
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.
@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;