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

Removed all up, next and prev pointers. Makeinfo can figure them out

automatically.  Fixed proper nesting of nodes, and use @Top, so that
this work.  Merge everything in prot-A.txt into this document:
(Document Revision History): This is going to be revision 10.0
	which documents protocol version 10.  9.0 was distributed with
	lyskomd 1.9.0.  8.0 was distributed with lyskomd 1.8.0.
(Protocol Version History): New name for former "Protocol Revision
	History".  Updated the information about version 9.
(Protocol Design Principles): Node removed.  The "Client-Server
	Dialog" node contains the same information.
(Client-Server Dialog): Specify the LysKOM port in the example.
(Simple Data Types): Moved the text about data element separator
	and call terminator to "Client-Server Dialog".
(user-active): Talk more about when clients should send this.
(who-is-on-dynamic): Improved the explanation.
(get-static-session-info): State that the returned information is immutable.
parent 767add0b
......@@ -2,7 +2,7 @@
@c
@c FIXME: Explain how the garb works with nice and keep-commented
@c
@c $Id: Protocol-A.texi,v 1.53 1999/02/05 22:19:28 ceder Exp $
@c $Id: Protocol-A.texi,v 1.54 1999/04/04 20:53:55 ceder Exp $
@c %**start of header
@setfilename protocol-a.info
@settitle LysKOM Protocol A
......@@ -19,7 +19,8 @@
@end iftex
@ifinfo
This is the specification of LysKOM Protocol A v. 9.0
This is specification 10.0 of LysKOM Protocol A. It specifies version
10 of the protocol.
Copyright @copyright{} 1995-1999 Lysator ACS.
......@@ -37,7 +38,7 @@ are preserved on all copies.
@sp 10
@title{LysKOM Protocol A}
@sp 2
@subtitle{Protocol version 10.0}
@subtitle{Protocol version 10}
@sp 2
@author by the LysKOM Developers
......@@ -60,31 +61,33 @@ 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 9.0.
@node Top
@top Top
This document specifies version 10 of LysKOM Protocol A.
The is revision 10.0 of the specification.
FIXME: This document is not yet published. The document you are looking
at has the version numbers all wrong. This will be fixed before
publication.
@menu
* Overview::
* Introduction::
* Data Types::
* Protocol Requests::
* Asynchronous Messages::
* Error Codes::
* LysKOM Content Types::
* The User Area::
* Writing Clients::
* Importing and Exporting E-Mail::
* Type Index::
* Request Index::
* Overview::
* Introduction::
* Data Types::
* Protocol Requests::
* Asynchronous Messages::
* Error Codes::
* LysKOM Content Types::
* The User Area::
* Writing Clients::
* Importing and Exporting E-Mail::
* Type Index::
* Request Index::
@end menu
@end ifinfo
@node Overview, Introduction, Top, Top
@node Overview
@chapter Overview
LysKOM is a conferencing system@footnote{Or in modern terms, enabling
......@@ -123,25 +126,26 @@ Kent Eng@-str@"om@penalty-10000
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::
@menu
* Document Revision History::
* Protocol Version History::
* Notation::
@end menu
@node Document Revision History, Protocol Revision History,, Overview
@node Document Revision History
@section Document Revision History
@table @asis
@item 9.0: @i{In progress}
Protocol version 9 is begin developed and this document needs to be
updated.
@item 10.0: @i{In progress}
The specification was translated to English and converted to Texinfo by
David Byers. Protocol version 10. Distributed with lyskomd 2.0.0.
@item 9.0: 1996-08-04
This version was distributed with lyskomd 1.9.0.
@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.
Protocol version 8. Distributed with lyskomd 1.8.0.
@item 7.1: 1995-01-08.
Protocol and document revision history were added by Per Cederqvist. Outline
......@@ -166,10 +170,11 @@ Per Cederqvist started using version control for documentation.
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
@node Protocol Version History
@section Protocol Version History
@subsection Protocol version 10 (first implemented in lyskomd 2.0.0)
@subsection Protocol version 10.0
@table @asis
@item New Server Calls
@itemize @bullet
......@@ -244,9 +249,15 @@ and membership types. The magic is documented with each call.
@end table
@subsection Protocol version 9.0
@subsection Protocol version 9 (first implemented in lyskomd 1.9.0)
@table @asis
@item New functionality
@itemize @bullet
@item The server shall now reply with error @code{not-implemented} when
a client attempts to use an unimplemented call. This feature requires
that the client uses newline as call terminator.
@end itemize
@item Added Commands
@itemize @bullet
@item 79=set-info: Can change server information.
......@@ -256,9 +267,20 @@ and membership types. The magic is documented with each call.
@item 83=who-is-on-dynamic
@item 84=get-static-session-info
@end itemize
@item Changed names
@itemize @bullet
@item @code{change-conference} was previously called @code{pepsi}. The
name was changed, but not the functionality.
@end itemize
@item Status change
@itemize @bullet
@item @code{63=who-is-on-ident} is now considered obsolete.
@item @code{64=get-session-info-ident} is now considered obsolete.
@item @code{59=create-anonymous-text-old} is now considered obsolete.
@end itemize
@end table
@subsection Protocol version 8.0
@subsection Protocol version 8 (first implemented in lyskomd 1.8.0)
@table @asis
@item Added Functionality
......@@ -294,9 +316,9 @@ and membership types. The magic is documented with each call.
@item
74=re-z-lookup
@item
75=get_version_info
75=get-version-info
@item
76=lookup_z_name
76=lookup-z-name
@end itemize
@item Other
......@@ -312,19 +334,19 @@ The asynchronous message 1=i-am-off has been removed
@item New Calls
@itemize @bullet
@item
67=lookup_person
67=lookup-person
@item
68=lookup_conf
68=lookup-conf
@item
69=set_client_version
69=set-client-version
@item
70=get_client_name
70=get-client-name
@item
71=get_client_version
71=get-client-version
@item
72=mark_text
72=mark-text
@item
73=unmark_text
73=unmark-text
@end itemize
@end table
......@@ -335,9 +357,9 @@ The asynchronous message 1=i-am-off has been removed
@item New Calls
@itemize @bullet
@item
65=re_lookup_person
65=re-lookup-person
@item
66=re_lookup_conf
66=re-lookup-conf
@end itemize
@end table
......@@ -349,9 +371,9 @@ The asynchronous message 1=i-am-off has been removed
@item
62=login
@item
63=who_is_on_ident
63=who-is-on-ident
@item
64=get_session_info_ident
64=get-session-info-ident
@end itemize
@end table
......@@ -361,13 +383,13 @@ The asynchronous message 1=i-am-off has been removed
@item New Calls
@itemize @bullet
@item
61=find_previous_text_no
61=find-previous-text-no
@item
60=find_next_text_no
60=find-next-text-no
@item
59=create_anonymous_text
59=create-anonymous-text
@item
58=get_last_text
58=get-last-text
@end itemize
@end table
......@@ -377,7 +399,7 @@ The asynchronous message 1=i-am-off has been removed
@item New Calls
@itemize @bullet
@item
57=set_user_area
57=set-user-area
@end itemize
@end table
......@@ -389,26 +411,11 @@ 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
@node Notation
@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.
its data elements.
Data fields have been given names that start with a lower-case letter.
......@@ -427,25 +434,24 @@ literal strings. There is to be no whitespace before or after literal
strings unless there is whitespace in the literal itself.
@node Introduction, Data Types, Overview, Top
@node Introduction
@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 ::
* The Aux-Item List ::
* Security ::
* Membership and Reading::
* Client-Server Dialog ::
* Articles::
* Conferences::
* The Misc-Info List::
* The Aux-Item List::
* Security::
* Membership and Reading::
* Client-Server Dialog::
@end menu
@node Articles, Conferences, , Introduction
@node Articles
@section Articles
An article is represented as a value of the type @code{Text-Stat} and a
......@@ -475,7 +481,7 @@ The server call @code{local-to-global} does this.
@node Conferences, Persons and Sessions, Articles, Introduction
@node Conferences
@section Conferences
Conferences hold articles. They are represented in the protocol as a
......@@ -524,7 +530,11 @@ changed to this type, preexisting secret members remain secret.
@node Persons and Sessions, The Misc-Info List, Conferences, Introduction
@menu
* Persons and Sessions::
@end menu
@node Persons and Sessions
@subsection Persons and Sessions
Persons are represented in the protocol by values of the type
......@@ -542,7 +552,7 @@ the network connection is closed; a user can log in and out repeatedly
in a single session.
@node The Misc-Info List, The Aux-Item List, Persons and Sessions, Introduction
@node The Misc-Info List
@section The Misc-Info List
The @code{Misc-Info} list contains tagged data. The fields are sent in
......@@ -691,22 +701,22 @@ article number which is a footnote to this article.
@end table
@node The Aux-Item List, Security, The Misc-Info List, Introduction
@subsection The Aux-Item List
@node The Aux-Item List
@section The Aux-Item List
The aux-item list is used as a generic extension mechanism in the LysKOM
server and in protocol A.
@menu
* About Aux-Items ::
* Predefined Aux-Item Types ::
* Client-Specific Aux-Item Types ::
* Experimental Aux-Item Types ::
* Defining New Aux-Item Types ::
* About Aux-Items::
* Predefined Aux-Item Types::
* Client-Specific Aux-Item Types::
* Experimental Aux-Item Types::
* Defining New Aux-Item Types::
@end menu
@node About Aux-Items, Predefined Aux-Item Types, , The Aux-Item List
@subsubsection About Aux-Items
@node About Aux-Items
@subsection About Aux-Items
Aux-items were introduced in protocol version 10 as a mechanism for
extending the conference, text and server information structures without
......@@ -737,8 +747,8 @@ no understanding of the contents can successfully parse the item anyway
@node Predefined Aux-Item Types, Client-Specific Aux-Item Types, About Aux-Items, The Aux-Item List
@subsubsection Predefined Aux-Item Types
@node Predefined Aux-Item Types
@subsection Predefined Aux-Item Types
Predefined Aux-Item types are part of Protocol A, and clients are
encouraged to support all of them. As with other parts of the protocol,
......@@ -1045,8 +1055,8 @@ forced or cleared.
@end table
@node Client-Specific Aux-Item Types, Experimental Aux-Item Types, Predefined Aux-Item Types, The Aux-Item List
@subsubsection Client-Specific Aux-Item Types
@node Client-Specific Aux-Item Types
@subsection Client-Specific Aux-Item Types
Client-specific items do not cause the server to perform any magic. All
the flags (except the delete flag) are left untouched, the data is not
......@@ -1067,16 +1077,16 @@ If you want a range of numbers, send e-mail to the LysKOM development
group.
@node Experimental Aux-Item Types, Defining New Aux-Item Types, Client-Specific Aux-Item Types, The Aux-Item List
@subsubsection Experimental Aux-Item Types
@node Experimental Aux-Item Types
@subsection Experimental Aux-Item Types
Experimental numbers are free for all. Use 'em any way you want. All
numbers in the range 20000-29999 are for experimental use.
@node Defining New Aux-Item Types, , Experimental Aux-Item Types, The Aux-Item List
@subsubsection Defining New Aux-Item Types
@node Defining New Aux-Item Types
@subsection Defining New Aux-Item Types
If you want a new predefined item type, just document what it does, what
the data format looks like and what the server is to do with the item
......@@ -1101,8 +1111,8 @@ much less painful process than adding new calls.
@node Security, Membership and Reading, The Aux-Item List, Introduction
@subsection Security
@node Security
@section 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
......@@ -1175,7 +1185,7 @@ Create persons
@end table
@node Membership and Reading, Client-Server Dialog, Security, Introduction
@node Membership and Reading
@section Membership and Reading
Persons' memberships in conferences are represented in the protocol as
......@@ -1222,7 +1232,7 @@ global text numbers. If the server does not implement the
efficient but perfectly serviceable @pxref{get-map} call instead.
@node Client-Server Dialog, ,Membership and Reading , Introduction
@node Client-Server Dialog
@section Client-Server Dialog
The client-server dialog consists of two phases, establishing the connection
......@@ -1242,7 +1252,7 @@ protocol-dependent. Protocol A servers will reply with the string
@code{LysKOM} on a single line.
@example
% telnet kom.lysator.liu.se
% telnet kom.lysator.liu.se 4894
Trying 130.236.254.151 ...
Connected to varg.lysator.liu.se.
Escape character is '^]'.
......@@ -1253,8 +1263,8 @@ protocol-dependent. Protocol A servers will reply with the string
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 @i{must} be terminated with a linefeed
character (ASCII 0x0A).
call as specified. The call @emph{must} be terminated with a linefeed
character (ASCII 0x0A).
@example
server-call ::=
......@@ -1296,8 +1306,19 @@ the reply.
Error reporting is covered in more detail in chapter @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.
@node Data Types, Protocol Requests, Introduction, Top
@node Data Types
@chapter Data Types
The data types in protocol A come in two flavors. The first (vanilla)
......@@ -1306,26 +1327,14 @@ are built. Simple data types include things like integers and strings
while complex data types include things such as conferences and people.
@menu
* Simple Data Types::
* LysKOM Data Types::
* Name Expansion::
* Simple Data Types::
* LysKOM Data Types::
* Name Expansion::
@end menu
@node Simple Data Types, LysKOM Data Types, Data Types, Data Types
@node Simple Data Types
@section Simple Data Types
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.
@subsection Integers
@tindex INT32
......@@ -1512,7 +1521,7 @@ corresponding @code{<type>} is its type.
Structures are transmitted as a sequence of their fields.
@node LysKOM Data Types, Name Expansion, Simple Data Types, Data Types
@node LysKOM Data Types
@section LysKOM Data Types
In this section the data types specific to LysKOM are defined. Most of
......@@ -2560,6 +2569,7 @@ A client-supplied string saying what the person is currently doing.
@item username
The name of the ``real'' user (see @code{Who-Info} above.)
@item idle-time
@c FIXME: should this be user-active-call?
The number of seconds since the last server call.
@item connection-time
The time when the connection was initiated. This is not the same as the
......@@ -2653,7 +2663,7 @@ The dynamic session flags (see above.)
What the client is doing. This string is set by the client.
@end table
@node Name Expansion, , LysKOM Data Types, Data Types
@node Name Expansion
@section Name Expansion
Names in LysKOM can be expanded according to two rules, regexp matching
......@@ -2698,7 +2708,7 @@ equivalent according to swascii rules.
@node Protocol Requests, Asynchronous Messages, Data Types, Top
@node Protocol Requests
@chapter Protocol Requests
This chapter documents all calls that can be made to the server. All
......@@ -2729,122 +2739,116 @@ in the example.
@menu
Call Name Status Description Number
-------------------------------------------------------------------------------
* login-old:: O Log in to LysKOM. Call 62 is preferred (0)
* logout:: Log out. Call 62 to log in again (1)
* change-conference:: Change current conference (2)
* change-name:: Change name of a conference or person (3)
* change-what-i-am-doing:: Change what-am-i-doing in who information (4)
* create-person-old:: O Create a person (5)
* get-person-stat-old:: O Get person information. Use call 49 (6)
* set-priv-bits:: Set privileges of a person (7)
* set-passwd:: Set password of a person (8)
* query-read-texts-old:: O Get info on what is read (9)
* create-conf-old:: O Create a conference (10)
* delete-conf:: Delete a conference (11)
* lookup-name:: O Look up a name. Replaced by call 76 (12)
* get-conf-stat-older:: O Get conference information. Use call 50 (13)
* add-member-old:: O Add a member to a conference (14)
* sub-member:: Remove a member from a conference (15)
* set-presentation:: Set the presentation of a conference (16)
* set-etc-motd:: Set conference notice (17)
* set-supervisor:: Set supervisor of a conference (18)
* set-permitted-submitters:: Set permitted submitters of a conference (19)
* set-super-conf:: Set super-conference of a conference (20)
* set-conf-type:: Set the type of a conference (21)
* set-garb-nice:: Set garb-nice of a conference (22)
* get-marks:: Get marks for a person (23)
* mark-text-old:: O Mark a text. Replaced by calls 72 and 73 (24)
* get-text:: Get an article or part of an article (25)
* get-text-stat-old:: O Get text status information (26)
* mark-as-read:: Mark an article as read in a conference (27)
* create-text-old:: O Create an article (28)
* delete-text:: Delete an article (29)
* add-recipient:: Add a recipient to an article (30)
* sub-recipient:: Remove a recipient from an article (31)
* add-comment:: Add a comment to an article (32)
* sub-comment:: Remove a comment from an article (33)
* get-map:: O Map local text numbers to global. Use 103 (34)
* get-time:: Get the current time (35)
* get-info-old:: O Get server information (36)
* add-footnote:: Add an article as a footnote to another (37)
* sub-footnote:: Remove a footnote from an article (38)
* who-is-on-old:: O Get active sessions. Replaced by call 63 (39)
* set-unread:: Set number of unread in a conference (40)
* set-motd-of-lyskom:: Set LysKOM message of the day (41)
* enable:: Set security level (42)
* sync-kom:: Save the database (43)
* shutdown-kom:: Shut LysKOM down (44)
* broadcast:: O Broadcast a message. Replaced by call 53 (45)
* get-membership-old:: O Get membership for a person. Use call 99 (46)
* get-created-texts:: O Get texts created by a user. Use call 104 (47)
* get-members-old:: O Get members of a conference. Use call 101 (48)
* get-person-stat:: Get status information for a person (49)
* get-conf-stat-old:: O Get status information for a conference (50)
* who-is-on:: O Get current sessions. Replaced by call 63 (51)
* get-unread-confs:: Get conferences with unread articles (52)
* send-message:: Send a personal message (53)
* get-session-info:: O Get session information. Use call 64 (54)
* disconnect:: Disconnect a session (55)
* who-am-i:: Get current session number (56)
* set-user-area:: Set a person's user area (57)
* get-last-text:: Get text created before a certain time (58)
* create-anonymous-text-old:: O Create an anonymous text (59)
* find-next-text-no:: Get next text number (60)
* find-previous-text-no:: Get previous text number (61)
* login:: Log in to LysKOM (62)
* who-is-on-ident:: Get current sessions (63)
* get-session-info-ident:: Get session information (64)
* re-lookup-person:: O Look up a person based on name (65)
* re-lookup-conf:: O Look up a conference based on name (66)
* lookup-person:: O Find persons matching abbreviated name (67)
* lookup-conf:: O Find conference matching abbreviated name (68)
* set-client-version:: Set the name and version the client (69)
* get-client-name:: Get the name of the client (70)
* get-client-version:: Get the version of the client (71)
* mark-text:: Mark a text (72)
* unmark-text:: Unmark a text (73)
* re-z-lookup:: Lookup for conferences and persons (74)
* get-version-info:: Get protocol version of server (75)
* lookup-z-name:: Look up an abbreviated name (76)
* set-last-read:: Set text last read in a conference (77)
* get-uconf-stat:: Get abbreviated conference status (78)
* set-info:: Get server information (79)
* accept-async:: Select asynchronous messages to receive (80)
* query-async:: Ask server which async messages are sent (81)
* user-active:: Tell the server that the user is active (82)
* who-is-on-dynamic:: Get a list of active users (83)
* get-static-session-info:: Get static information about a session (84)
* get-collate-table:: Get the current collate table (85)
* create-text:: Create a text (86)
* create-anonymous-text:: Create an anonymous text (87)
* create-conf:: Create a conference (88)
* create-person:: Create a person (89)
* get-text-stat:: Get text status information (90)
* get-conf-stat:: Get conference status information (91)
* modify-text-info:: Add or delete text aux items (92)
* modify-conf-info:: Add or delete conference aux items (93)
* get-info:: Get server information (94)
* modify-system-info:: Add or delete system aux items (95)
* query-predefined-aux-items:: Get list of aux-items the server knows (96)
* set-expire:: Set the expire field of a conference (97)
* query-read-texts:: Get info on what is read (98)
* get-membership:: Get membership for a person (99)
* add-member:: Add a member to a conference (100)
* get-members:: Get members of a conference (101)
* set-membership-type:: Modify the type of conference (102)
* local-to-global:: Map local text numbers to global ones (103)
* map-created-texts:: Map texts created by a person to glogal (104)
* set-keep-commented:: Set how new comments protect old texts (105)
* login-old:: O Log in to LysKOM. Call 62 is preferred (0)
* logout:: r Log out. Call 62 to log in again (1)
* change-conference:: r Change current conference (2)
* change-name:: r Change name of a conference or person (3)
* change-what-i-am-doing:: r Change what-am-i-doing in who information (4)
* create-person-old:: O Create a person (5)
* get-person-stat-old:: O Get person information. Use call 49 (6)