Select Git revision
Protocol-A.texi
Protocol-A.texi 247.23 KiB
\input texinfo @c -*-texinfo-*-
@c $Id: Protocol-A.texi,v 1.37 1998/10/11 15:21:32 jsk Exp $
@c %**start of header
@setfilename protocol-a.info
@settitle LysKOM Protocol A
@setchapternewpage odd
@c %**end of header
@iftex
@parindent 0pt
@font@tensltt=cmsltt10
@begin tex
\global\def\rett#1{{\let\t\sltt\tt #1}}
\global\def\sltt#1{{\fam\ttfam\tensltt\let\t\rett #1}}
\global\let\t\sltt
@end tex
@end iftex
@ifinfo
This is the specification of LysKOM Protocol A v. 9.0
Copyright @copyright{} 1995, 1996 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
@dircategory LysKOM
@direntry
* Protocol A: (protocol-a). The LysKOM Protocol A specification.
@end direntry
@titlepage
@sp 10
@title{LysKOM Protocol A}
@sp 2
@subtitle{Protocol version 10.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 9.0.
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::
* Type Index::
* Request Index::
@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 10.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>},
David Byers @code{<byers@@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>},
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 9.0: @i{In progress}
Protocol version 9 is begin developed and this document needs to be
updated.
@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 10.0
@table @asis
@item New Server Calls
@itemize @bullet
@item 85=get-collate-table
@item 86=create-text
@item 87=create-anonymous-text
@item 88=create-conf
@item 89=create-person
@item 90=get-text-stat
@item 91=get-conf-stat
@item 92=modify-text-info
@item 93=modify-conf-info
@item 94=get-info
@item 95=modify-system-info
@item 96=query-predefined-aux-items
@item 97=set-expire
@item 98=query-read-texts
@item 99=get-membership
@item 100=add-member
@item 101=get-members
@end itemize
@item Removed Server Calls
@itemize @bullet
@item 5=create-person
@item 9=query-read-texts
@item 10=create-conf
@item 14=add-member
@item 26=get-text-stat
@item 28=create-text
@item 36=get-info-old
@item 46=get-membership-old
@item 48=get-members-old
@item 50=get-conf-stat
@item 59=create-anonymous-text
@end itemize
@item New and New Modified Structures
@itemize @bullet
@item Aux-Item
@item Aux-Item-Input
@item Conference@item Info
@item Member
@item Membership
@item Membership-Type
@item Misc-Info
@item Text-Stat
@end itemize
@item New Asynchronous Messages
@itemize @bullet
@item async-deleted-text message
@item New async-new-text message
@end itemize
@end table
@subsection Protocol version 9.0
@table @asis
@item Added Commands
@itemize @bullet
@item 79=set-info: Can change server information.
@item 80=accept-async: Can select asynchronous messages to receive.
@item 81=query-async: Can query which messages are being send.
@item 82=user-active
@item 83=who-is-on-dynamic
@item 84=get-static-session-info
@end itemize
@end table
@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
The asynchronous message 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.
Fundamental data types have names in all-caps (such as @code{INT32} and
@code{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: @code{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, , , 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 ::
* The Aux-Item 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 recipient. Local numbers are used in some data structures to
provide more compact storage and to provide 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{local-to-global} 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 flags @code{rd-prot}, @code{letterbox},
@code{secret}, @code{original} and @code{allow-anonymous} 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 synchronized
with the person name. It is currently not possible to explicitly set or
clear this flag on a conference.
@item secretConferences 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 allow-anonymous
Conferences of this type accept anonymous articles. Other conferences
will reject anonymous articles.
@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{Static-Session-Info}, @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, The Aux-Item List, 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; blank 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.
@subsection 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
@subsection 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 toall recipients, but not to carbon-copy recipients of the original
article. This difference is enforced by the clients.
@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. Since only persons can read articles
this will only be seen if the CC recipient is a person.
@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
@subsection Blank Carbon Copy (BCC) Recipient
The blank carbon-copy recipient group is identical to the carbon-copy
recipient group above. The difference is the visibility of the
information. A carbon-copy recipient group is visible to anyone that is
allowed to fetch both the text status of the involed text and the
conference status of the involved conference. (That is, as long as the
conference isn't secret everybody is allowed to se the carbon-copy
recipient group.)
A BCC recipient group is only visible to members and supervisors of the
recipient. This is enforced by the server.
This type of group was introduced in protocol version 10. When
old-style calls such as @code{@xref{get-text-stat-old}} are used this
will be converted to a CC recipient group by the server for the benefit
of clients that don't understand this group.
@table @code
@item bcc-recpt
Starts a blank carbon-copy recipient group. It contains the conference
number of a blank carbon-copy recipient of the article.
@item loc-no
Always present in a BCC recipient group. It contains the local text
number of the article in the conference specified by the most recent
@code{bcc-recpt} field.
@item rec-time
Present after the BCC recipient has read the article. It contains the
time when the article was read. Since only persons can read articles
this will only be seen if the BCC recipient is a person.
@item sent-by
Present when a BCC 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 BCC recipient.
@item sent-at
Present when a BCC recipient was added after the article had been
created. It is the time when the BCC recipient was added.
@end table
@subsection 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
@subsection Footnote To
@table @code
@item footn-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
@subsection 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
@subsection Footnote in
@table @code
@item footn-in
Present when there are footnotes to this article. It contains the
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
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 ::
@end menu
@node About Aux-Items, Predefined Aux-Item Types, , The Aux-Item List
@subsubsection About Aux-Items
Aux-items were introduced in protocol version 10 as a mechanism for
extending the conference, text and server information structures without
changing the protocol. Persons were excluded since nobody could figure
out a case where setting an aux-item on the letterbox wasn't as good as
setting it on the person (another reason was that I was fed up writing
aux-item code by the time they were working on texts and conferences.)
The exact structure of an aux item is specified elsewhere (@pxref{LysKOM
Data Types}). The important fields here are the aux-no, tag and data
fields.
The aux-no field is used to identify an item. The aux-no together with a
text or conference number uniquely identifies a particular aux item.
Items are numbered from one and up within each item list. Once assigned,the aux-no for an item is never changed. New items are guaranteed to
be assigned numbers that have never been used before within a particular
list.
The tag field identifies the type of aux item. It is used by the server
and by clients to figure out how to interpret the data field, and by the
server to decide if the item needs special treatment.
The data field is a simple string. The meaning of the string is
determined by the tag field, but since it is a string, clients that have
no understanding of the contents can successfully parse the item anyway
(in contrast to items in the misc-info list.)
@node Predefined Aux-Item Types, Client-Specific Aux-Item Types, About Aux-Items, The Aux-Item List
@subsubsection 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,
changes to these item types will probably always be
backwards-compatible.
Predefined types can case serious magic to be invoked in the server.
There is no limit to the strangeness that may be associated with this
type of item. The server may also place limits on who may create
predefined items, might verify the data field, and can force any field
in the item to a specific value, no matter what the client specified.
All items with tags in the range 1-9999 and 30000 and up are considered
predefined. If a client attempts to create an item with a tag in this
range, but the server has no idea what that tag means, the server will
return an error (KOM_ILL_AUX.)
@table @samp
@item content-type [1] (text)
Specifies the content type of a text. Data is a valid MIME type of one
of the special LysKOM types (@pxref{LysKOM Content Types}.)
This item may only be set by the author of a text. The inherit, secret
and hide-owner bits are cleared. Only one content-type item can be
created per creator.
@item fast-reply [2] (text)
Data is a string that constitutes a brief comment to the text. This
comment should be displayed immediately after the text body.
The inherit bit is automatically cleared.
@item cross-reference [3] (text, conference)
Data is a cross-reference to something else. The contents must match
"\(T\|C\|P\)\([0-9]+\) \(.*\)", where \1 specifies if the cross
reference leads to a text, conference or person, \2 specified the number
of the target (text-no, conf-no or pers-no) and \3 is simply descriptive
text.
The inherit bit is automatically cleared.
@item no-comments [4] (text)
When this item is set, the author requests that nobody comments the
text. This is advisory only; it is still possible to write comments, but
clients should advise the user that this is contrary to the author's
wishes. Data should be empty.
This item may only be set by the author. The secret, hide-creator andinherit bits are automatically cleared.
@item personal-comment [5] (text)
When this item is set, the author requests only personal comments. This
is advisory only; it is still possible to create regular comments, but
clients should advise the user that the author prefers a personal
comment. Data should be empty.
This item may only be set by the author. The secret, hide-creator and
inherit bits are automatically cleared.
@item request-confirmation [6] (text)
The author requests that everyone who reads the text confirms having
done so by creating read-confirmation items on the text. Clients should
ask users if they wish to confirm having read the text when it is
displayed. Data should be empty.
The hide-creator, secret and inherit bits are automatically cleared.
@item read-confirm [7] (text)
This item can be taken as confirmation that the item creator has read
the text to which the item is attached. Clients should never ever create
this item without an explicit confirmation from the user that the text
has indeed been read.
The hide-creator, secret and inherit bits are automatically cleared.
@item redirect [8] (conference)
When set, messages sent directly to the conference should really be
sent elsewhere. Data is PROTOCOL:ADDRESS where PROTOCOL is either
"E-mail" or "LysKOM", and ADDRESS is either an e-mail address or a
LysKOM conference. Hopefully we'll be able to replace this with a
forwarding mechanism later.
This item can only be set by the conference supervisor or in the case of
a letterbox, the person attached to the letterbox. The hide-creator and
secret bits are cleared automatically. Only one redirect can be
specified.
@c FIXME: who is responsible for the redirect? The client? The server?
@c A magic redirecting client?
@item x-face [9] (conference)
Data is the face of the person in compface format. Cool, innit?
This item can only be set by the conference supervisor or in the case of
a letterbox, the person attached to the letterbox. The hide-creator and
secret bits are cleared automatically.
@item alternate-name [10] (text, conference)
Data is a string that the client may use as an alternate to the name of
a conference or the subject of a text.
The inherit flag is automatically cleared.
@item pgp-signature [11] (text)
Data is a PGP signature of the text. The signature should be the
equivalent of what "pgp -sba" generates.
The secret, hide-creator and inherit bits are automatically cleared.Signatures cannot be deleted once they have been created.
@item pgp-public-key [12] (letterbox)
Data is the public key of the person. It is desirable that the public
key contains a userid of the format "LysKOM <p\([0-9]\)@@\(.*\)>+", where
\1 is the number of the person in the LysKOM server specified in \2.
This item can only be set by the person himself. The hide-creator,
secret and inherit bits are automatically cleared.
@item e-mail-address [13] (conference, letterbox, server)
Data is an RFC 822-style email address. When set on a letterbox, it
should be the email address of the person. If the person has multiple
email addresses he may set serveral e-mail-address aux-items.
The meaning of this aux-item when set on a conference that isn't a
letterbox is... vague. For a conference that is used as to import a
mailing list this should be the email address of the list (or the
subscription address? FIXME.).
When this aux-item is set on the server it shold contain the email
address of the administrator (or administrators).
This aux-item can only be set by the administrator. The creator cannot
be hidden.
@item faq-text [14] (conference, server)
Data is a decimal text number, which is a FAQ for the conference (or
server). This aux-item can only be set by the administrator.
@item creating-software [15] (text)
Data is the name and version number of the client that created the
text. This aux-item can only be set by the author of the text. Once
set, it cannot be removed or changed. A typical value would be
@samp{elisp-client 0.47.3}. Setting the creating-software aux-item is
optional.
The data should be the client name, a space, and the client version used
in the @code{set-client-version} call. The server may enforce this
restriction.
@item x-author [15] (text)
For imported texts using email gateway. Data is a string with
the (readable) name of the author.
Kom clients should show this field instead of the id of the importing kom-id.
@item x-from [16] (text)
Data is a plain email addres, the From: field from an imported email.
Used by the kom client to construct an email reply to an imported text.
@item x-reply-to [17] (text)
Data is a plain email addres, comes from the Reply-To: field
@item x-to [18] (text)
Data is one email address can be in variable format. Multiple text-items
can be present. The format is the same as is allowed in To: fields in
emails. If the text is imported these are the other receivers as seen in
the email. If the text originates from a kom-person (and thus not an
importer) this field is used in constructing an email, if an exporter
is present.
@item x-cc [19] (text)
Data in the same format as for "x-to". Usage the same but will
be a carbon copy instead.
@item x-date [20] (text)
Data is the send-date of a imported email. Can be in free format, even
if a readable format, such as "YYYY-MM-DD hh:mm:ss", is preferred. Kom
client should display this date as originating date, date of the
imported text entity in kom may be different (and can be shown as
received). In case of the text being exported from kom, this date is set
by the exporter.
@item x-msgid [21] (text)
Data is a string which is the message id from the imported email.
Preferably the importer should only add receivers when importing the
same email more times with the same msg-id. When a text is exported,
the x-msgid is constructed as an email address which contains
the kom text number and server in an unique way.
@item x-inreplyto [22] (text)
Data is a string which stores the message id of texts commented.
For each such text a kom (comment) link should be creaeted by the
importer if these referenced emails previously has been imported.
@item x-misc [23] (text)
Data is a string with the rest of the fields from an imported
email. Is set by the importer. The fields are concatenated with
"\n".
@item x-allow-filter [24] (conf)
Data is a regexp string which allows a sender (a field in the
email-header) to import the message. Several can exist, it is enough if
one matches (OR) and none dissallows (AND). Can be set by an organizer
of the conference.
The regexp allows ^[]?* as constructs. The importer is required to check these when
adding recipient of an imported text and comply. Example of usage:
"From:*.liu.se*", "From:*jsk*". Tests are not made on the text-body.
However, if the string starts with a "!" the email will be rejected if
the rest matches, even if one of the filter allowed it. Example:
"!From:*aol*", "!Subject:*money*".
@item x-reject-forward [25] (conf)
Data is a string with either an email name on the format
"E:email@foo.bar" or a kom-conference "C:num" number. The mail is
forwarded if it was rejected by "x-import-filter" to this address.
@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
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
validated in any way, and anyone can create any item. If you need more
server support than this, your item should be on the predefined list.
All tags in the range 10000-19999 are reserved for clients. Blocks of
100 numbers at a time can be assigned to specific clients. A clientshould never create items with tags in a range assigned to another
client or in an unassigned range. Assigned ranges will never change.
Currently, the following ranges are assigned to clients:
@itemize @bullet
@item 10000-10099: The Elisp Client
@end itemize
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
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
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
and send this to the LysKOM development group. We'll assign a number to
your item and put the documentation in this document.
If you're not sure what you want the data to look like yet, make a note
in your documentation that the data format might change. Once you have a
data format you're happy with, update the documentation so others may
use your item.
If you need serious magic in the server (more than can be specified with
the lyskomd configuration file), you'll probably have to write the code
yourself, or hope that the development group thinks your idea is so cool
we do the job for you.
The idea is not to reject any type of item, unless there's already an
item type that does the job just as well. Adding item types should be a
much less painful process than adding new calls.
@node Security, Membership and Reading, The Aux-Item 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 10Person 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 globalnumbers.
@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 newline 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;
ok-reply ::=
( "="
ref-no : INT32;
reply-data;
)
error-reply ::=
( "%"
ref-no : INT32;
error-no : Error-No;
error-status : INT32;
)
error-no ::= INT32;
@end example
Our notation is not flexible enough to specify the two-way nature of the
communication. @code{ref-no} in the reply is always the same as
@code{ref-no} in the corresponding request. @code{reply-data} depends on
which request was made and is specified together with each request.
Please note that there is no whitespace after the initial indicator in
the reply.
Error reporting is covered in more detail in chapter @ref{Error Codes}.
@node Data Types, , , Top
@chapter Data Types
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
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::
@end menu
@node Simple Data Types, LysKOM Data Types, Data Types, Data Types
@section Simple Data Types
Data elements are sent from client to server separated by one or more
ASCII spaces (0x20), tab characters (0x09), line feeds (0x0A) or
carriage returns (0x0D.) In messages from server to client the data
elements are separated by exactly one space character and the entire
message terminated with a line feed.
@subsection Integers
@tindex INT32
@tindex INT16
@tindex INT8
@tindex BOOL
@dfn{INT32}, @dfn{INT16}, @dfn{INT8} and @dfn{BOOL} are non-negative
integers which must fit in 32, 16, 8 and 1 bits, respectively. They are
transmitted to the server in ASCII-encoded decimal notation.
@subsection Strings
@tindex HOLLERITH
@dfn{HOLLERITH} denotes character strings of arbitrary length. They are
transmitted as @code{<n>H<text>} where @code{<text>} is the string and
@code{<n>} is the number of characters in @code{<text>} in decimal
notation. All byte values are allowed in the string itself, including
nulls.
Long live FORTRAN!
@subsection Bit Strings
@tindex BITSTRING
@dfn{BITSTRING} is a string of bits, commonly used for a set of
boolean-valued flags. Bit strings are denoted as
@example
BITSTRING ( name-1; name-2; name-3; ... )@end example
in this specification. They are transmitted as a sequence of ASCII ones
and zeroes in the order the fields are listed.
For instance, given the specification
@example
shape-of-world : BITSTRING (
is-flat;
is-round;
is-2d;
is-3d;
)
@end example
most peoples idea of @code{shape-of-world} would be sent as @code{0101}
(round and three-dimensional.)
@subsection Arrays
@tindex ARRAY
@dfn{ARRAY} is a list of a fixed number of elements of a single type.
The specification for an array is @code{ARRAY <type>} where
@code{<type>} is the type of the array elements.
Arrays are transmitted as an @code{<n> @{ <element> <element> ... @}}
where @code{<n>} is the number of elements and each @code{<element>} is
an element of the array. A special case is when the array is empty, in
which case the server transmits it as @code{0 *}. Note that the client
must always transmit empty arrays as @code{0 @{ @}}.
In some calls the client can ask the server not to send the array
contents, only its length. In these cases the array is transmitted as
@code{<n> *} where @code{<n>} is the number of elements in the array.
@subsection Selection
@tindex SELECTION
@dfn{SELECTION} is tagged data. It consists of an INT32 selector
followed by a tail of an arbitrary type and is specified as
@example
SELECTION (
<n>=<name> <tail> : <type>;
<n>=<name> <tail> : <type>;
...
)
@end example
where each @code{<n>} is the selector value, @code{<name>} the selector
name and @code{<tail>} the name of the selector tail and @code{<type>}
its type.
When transmitted, the selector is transmitted as an INT32 followed by
the tail belonging to that selector. For instance, given the
specification
@example
phrase : SELECTION (
1=hello name : HOLLERITH;
2=howdy ;
)
@end example
two legal messages of the type @code{phrase} are @samp{1 4HJohn} and
@samp{2}.
@subsection RPC
@tindex RPC
@dfn{RPC} is a notation used to specify calls to the server. An RPC
specification has the following form:
@example
RPC (
<call> <<n>> ( <request> ) -> ( <reply> ) ;
<call> <<n>> ( <request> ) -> ( <reply> ) ;
)
@end example
where each @code{<call>} is the name of a call, @code{<n>} is the call
number, @code{<request>} is a single data element sent as a request and
@code{<reply>} is a single data element sent in reply from the server.
RPC calls are transmitted as @code{<n> <request>} where @code{<n>} and
@code{<request>} have the same meaning as above. Note that in the
client-server dialog a reference number must also be supplied with each
request. This reference number is not part of the RPC itself, but is
required for communications @xref{Client-Server Dialog}.
@subsection Structure
Structures are collections of several data items. In the specification
they are written as
@example
( <name> : <type> ;
<name> : <type> ;
...
)
@end example
where each @code{<name>} is the name of a data field and the
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
@section 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
there are. This section does not include the server calls or
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
The types defined in this section are fairly simple and used in many of
the more complex data types.
@subsubsection Time
@tindex Time
@example
Time ::=
( seconds : INT32;
minutes : INT32;
hours : INT32;
day : INT32;
month : INT32; year : INT32;
day-of-week : INT32;
day-of-year : INT32;
is-dst : BOOL;
)
@end example
@code{Time} is used to specify times in several data structures. The
fields @code{seconds}, @code{minutes} and @code{hours} give wall clock
time. @code{day} is the day of month and @code{month} is the current
month, starting with zero for January. @code{year} is the number of
years since 1900. @code{day-of-week} is the current weekday, with zero
used for Sunday. @code{day-of-year} is how many days of the year have
passed starting with zero and @code{is-dst} is true when the time
indicated is daylight savings time.
When the server receives a @code{Time} structure from a client it
ignores the @code{day-of-week} and @code{day-of-year} fields.
All times are expressed in the time zone of the server.
@subsubsection Conference Numbers
@tindex Conf-No
@example
Conf-No ::= INT16;
@end example
This type denotes a conference number.
@subsubsection Text Numbers
@tindex Text-No
@tindex Local-Text-No
@tindex Text-List
@example
Text-No ::= INT32;
Local-Text-No ::= INT32;
Text-List ::=
( first-local-no : Local-Text-No;
texts : ARRAY Text-No;
)
@end example
These three types are used to indicate articles in the LysKOM database.
@code{Text-No} is a global text number and @code{Local-Text-No} a local
text number. @code{Text-List} is used when a mapping from local to
global numbers are required.
@subsubsection Person and Session Numbers
@tindex Pers-No
@tindex Session-No
@example
Pers-No ::= Conf-No;
Session-No ::= INT32;
@end example
@code{Pers-No} is used to indicate a person. @code{Session-No} is used
in a few data structures relating to information about active LysKOM
sessions.
@subsection Auxiliary Information
@tindex Aux-No
@tindex Aux-Item
@tindex Aux-Item-Input
@tindex Aux-Item-Flags
@example Aux-No ::= INT32;
Aux-Item ::=
( aux-no : Aux-No;
tag : INT32;
creator : Pers-No;
created-at : Time;
flags : Aux-Item-Flags;
inherit-limit : INT32;
data : HOLLERITH;
)
Aux-Item-Input ::=
( tag : INT32;
flags : Aux-Item-Flags;
inherit-limit : INT32;
data : HOLLERITH;
)
Aux-Item-Flags ::= BITSTRING
( deleted;
inherit;
secret;
hide-creator;
dont-garb;
reserved2;
reserved3;
reserved4;
)
@end example
Aux-Item-Input contains a subset of the fields of an Aux-Item. It is
used when the client wants to send an Aux-Item to the server, and it
only contains the elements that the client can affect. The fields in
Aux-Item and Aux-Item-Input have the following meaning:
@table @code
@item aux-no
The number of the item within the list where it is found. This number
together with a conference or text number uniquely identifies a
particular aux-item. (There is also a global list of Aux-Items for the
server. That list is manipulated via the @xref{modify-system-info}
request, and when using that request the aux-no is enough to uniquely
identify the aux-item.)
This field is not present in @code{Aux-Item-Input}. It is assigned by
the server.
@item tag
The item tag. The tag determines what the data means.
@item creator
The person who created the item, or zero if the item was created
anonymously or if the owner is being withheld.
This field is not present in @code{Aux-Item-Input}. It is assigned by
the server.
@item created-at
The time when the item was created.
This field is not present in @code{Aux-Item-Input}. It is assigned by
the server.
@item flags
The item flags (see below).
@item inherit-limit
Determines how many times (how deep) an item may be inherited. If zero,
the item is inherited an unlimited number of times. If nonzero it is
@b{one more} than the number of additional times the item may be
inherited. Thus, 1 means that inheritance will be blocked and 2 means
that the item will be inherited only to the next level.
@item data
The item data.@end table
The flags that can be set on an aux-item have the following meaning:
@table @code
@item deleted
The item has been deleted, and should not be used for anything.
@item inherit
The item will be inherited (if the inherit-limit field allows it.)
@item secret
The item will not be revealed to anyone but the item's creator and
supervisors of the creator.
@item hide-creator
The item creator will be withheld from everyone but the item's creator
and supervisors of the creator.
@item dont-garb
The object the item is set on will not be garbage-collected.
@end table
@subsection Conference Types
@tindex Conf-Type
@tindex Extended-Conf-Type
@tindex Any-Conf-Type
@example
Conf-Type ::= BITSTRING
( rd_prot;
original;
secret;
letterbox;
)
Extended-Conf-Type ::= BITSTRING
( rd_prot;
original;
secret;
letterbox;
allow-anonymous;
reserved1;
reserved2;
reserved3;
)
Any-Conf-Type ::= Conf-Type | Extended-Conf-Type;
@end example
These types are used to specify the type of a conference.
@code{Conf-Type} is used in data types and calls that were created
before version 8.0 of the protocol and has been augmented in
@code{Extended-Conf-Type}. The type @code{Any-Conf-Type} is used when
either is admissible.
The bits have the following meaning (@pxref{Conferences}, for more
info.)
@table @code
@item rd_prot
If unset anyone can add themselves as members to the conference.
@item original
If set, comments are not allowed in the conference.
@item secret
If set the conference is secret. It's existence will only be revealed to
members and supervisors.
@item letterbox
Set if the conference is a person's mailbox.
@item allow-anonymous
Set if anonymous articles are allowed in the conference.
@item reserved1
@itemx reserved2
@itemx reserved3
Reserved for future use. The values of these bits should be never be
modified or used by clients who do not know their meaning. When a new
conference is created these should always be set to zero.
@end table
@subsection Conference Search Results
@tindex Conf-Z-Info
@example
Conf-Z-Info ::=
( name : HOLLERITH;
type : Conf-Type;
conf_no : Conf_no;
)
@end example
These types are used for the result of some calls that search for
conferences based on their names.
@subsection Conference Status Types
@tindex Garb-Nice
@tindex Conference-Old
@tindex Conference
@tindex UConference
@example
Garb-Nice ::= INT32;
Conference-Old ::=
( name : HOLLERITH;
type : Conf-Type;
creation-time : Time;
last-written : Time;
creator : Pers-No;
presentation : Text-No;
supervisor : Conf-No;
permitted-submitters : Conf-No;
super-conf : Conf-No;
msg-of-day : Text-No;
nice : Garb-Nice;
no-of-members : INT16;
first-local-no : Local-Text-No;
no-of-texts : INTEGER;
)
Conference ::=
( name : HOLLERITH;
type : Extended-Conf-Type;
creation-time : Time;
last-written : Time;
creator : Pers-No;
presentation : Text-No;
supervisor : Conf-No;
permitted-submitters : Conf-No;
super-conf : Conf-No;
msg-of-day : Text-No;
nice : Garb-Nice;
no-of-members : INT16;
first-local-no : Local-Text-No;
no-of-texts : INTEGER;
expire : Garb-Nice;
aux-items : ARRAY Aux-Item; )
UConference ::=
( name : HOLLERITH;
type : Extended-Conf-Type;
highest-local-no : Local-Text-No;
nice : Garb-Nice;
)
@end example
These three types are used to specify information about a conference.
@code{Garb-Nice} is a quantity used to specify how long articled are
kept in a conference before being removed. @code{Conference} is the full
information about a conference and @code{UConference} is brief
information about a conference.
The fields of @code{Conference} are
@table @code
@item name
The name of this conference.
@item type
The type of the conference.
@item creation-time
The date and time when the conference was created.
@item last-written
The date when something was last written in the conference.
@item creator
The person who created the conference.
@item presentation
The article containing the conference presentation or zero if the
conference has no presentation.
@item supervisor
The conference@footnote{The @code{supervisor} may be a person, in which
case the members of that person's letterbox become supervisors.} who
supervises this conference.
@item permitted-submitters
The conference whose members@footnote{@code{permitted-submitters} can be
a person, in which case all persons who are members of the associated
letterbox are allowed to submit articles to the conference.} may submit
articles to the conference, or zero if anyone may do so.
@item super-conf
The conference that receives comments if this conference does not accept
them. Zero means the author of the comment in question.
@item msg-of-day
The conference notice, if any.
@item nice
The number of days an article should be kept before being removed from
the conference.
@item no-of-members
The number of members of this conference.
@item first-local-no
The local number of the oldest existing article in the conference.
@item no-of-texts
The number of articles in the conference.
@item expire
This field will be used to control when a conference expires.
It is not used at the moment, and should be set to zero for future
compatibility.
@item aux-items
The conference's aux item list.
@end table
The fields of @code{UConference} are
@table @code
@item name
The name of this conference.
@item type
The conference type. Note that this is an extended conference type,unlike the type field of @code{Conference}.
@item highest-local-no
The local number of the newest article in the conference.
@item nice
The number of days an article should be kept before being removed from
the conference.
@end table
@subsection 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:
@tindex Conf-List-Archaic
@example
Conf-List-Archaic ::=
( conf-nos : ARRAY Conf-No;
conf-types : ARRAY Conf-Type; ! Sans <n>; see below
)
@end example
The two arrays @code{conf-nos} and @code{conf-types} are always the same
size. For some obscure reason the size of the second array is not
actually transmitted. See also the example in @ref{lookup-name}.
@subsection Mapping Local to Global Text Numbers
@tindex Text-Mapping
@tindex Local-To-Global-Block
@tindex Text-Number-Pair
@example
Text-Mapping ::=
( later-texts-exists : BOOL;
block : Local-To-Global-Block;
)
Local-To-Global-Block ::= SELECTION
( 0=sparse sparse-block : ARRAY Text-Number-Pair;
1=dense dense-block : Text-List;
)
Text-Number-Pair ::=
( local-number : Local-Text-No;
global-number : Text-No;
)
@end example
FIXME: more text here.
@subsection Server Information
@tindex Info
@tindex Info-Old
@tindex Version-Info
@example
Info ::=
( version : INT32;
conf-pres-conf : Conf-No;
pers-pres-conf : Conf-No;
motd-conf : Conf-No;
kom-news-conf : Conf-No;
motd-of-lyskom : Text-No;
aux-item-list : ARRAY Aux-Item;
)
Info-Old ::=
( version : INT32;
conf-pres-conf : Conf-No; pers-pres-conf : Conf-No;
motd-conf : Conf-No;
kom-news-conf : Conf-No;
motd-of-lyskom : Text-No;
)
Version-Info ::=
( protocol-version : INT32;
server-software : HOLLERITH
software-version : HOLLERITH
)
@end example
These data types contain information about the LysKOM server. The fields
of @code{Info} and @code{Info-Old} are
@table @code
@item version
The server version encoded as a number @code{aabbcc} where @code{aa} is
the major version number, @code{bb} the minor number and @code{cc} the
secondary minor version. For instance, @code{10607} is version 1.6.7 of
the server. If greater than 10699 the @code{get-version-info} should be
used instead.
@item conf-pres-conf
The conference that contains conference presentations.
@item pers-pres-conf
The conference that contains person presentations.
@item motd-conf
The conference that contains conference and person notices.
@item kom-news-conf
The conference that contains news about LysKOM.
@item motd-of-lyskom
The number of an article to display when LysKOM is entered or zero if
there is none.
@item aux-item-list
(Not present in @code{Info-Old}.) A list of aux-items that belong to
the server.
@end table
The fields of @code{Version-Info} are:
@table @code
@item protocol-version
The version of protocol A the server is using. This may be used to
ascertain which calls are available.
@item server-software
Human-readable name of the server software.
@item software-version
Human-readable name of the server software version.
@end table
@subsection Person Status Types
@tindex Person
@tindex Personal-Flags
@tindex Priv-Bits
@example
Person ::=
( username : HOLLERITH;
privileges : Priv-Bits;
flags : Personal-Flags;
last-login : Time;
user-area : Text-No;
total-time-present : INT32;
sessions : INT32;
created-lines : INT32;
created-bytes : INT32;
read-texts : INT32;
no-of-text-fetches : INT32; created-persons : INT16;
created-confs : INT16;
first-created-local-no : INT32;
no-of-created-texts : INT32;
no-of-marks : INT16;
no-of-confs : INT16;
)
Personal-Flags ::= BITSTRING
( unread-is-secret;
flg2;
flg3;
flg4;
flg5;
flg6;
flg7;
flg8;
)
Priv-Bits ::= BITSTRING
( wheel;
admin;
statistic;
create_pers;
create_conf;
change_name;
flg7;
flg8;
flg9;
flg10;
flg11;
flg12;
flg13;
flg14;
flg15;
flg16;
)
@end example
These types are used to specify information about persons. @code{Person}
contains the information about a person, @code{Personal-Flags} contains
flags set by the user and @code{Priv-Bits} contains the person's
privileges.
The fields of @code{Person} are
@table @code
@item username
The name of the user.
FIXME: this is wrong/needs explanation/should be renamed.
@item privileges
The privileges of the person.
@item flags
Flags set by the user.
@item last-login
The time when the person last logged on.
@item user-area
The text number of the person's user area or zero if the person has no
user area.
@item total-time-present
The number of seconds the person has been using LysKOM.
@item sessions
The number of sessions the person has initiated.
@item created-lines
The number of lines of articles the person has written.
@item created-bytes
The number of characters the person has written.
@item read-texts
The number of articles the person has read.@item no-of-text-fetches
The number of texts the person has retrieved from the server.
@item created-persons
The number of other persons this person has created.
@item created-confs
This holds the number of conferences created by the person.
@item first-created-local-no
The local number of the earliest existing article written by the person.
The local number applies to a local-to-global mapping containing all
articles written by the person.
@item no-of-created-texts
This holds the number of articles written by the person.
@item no-of-marks
The number of marked texts this person has.
@item no-of-confs
The number of conferences the person is a member of.
@end table
@subsection Membership Information
@tindex Membership-Type
@example
Membership-Type ::= BITSTRING
( invitation;
passive;
secret;
reserved1;
reserved2;
reserved3;
reserved4;
reserved5;
)
@end example
The @code{Membership-Type} type contains flags that modify a membership.
It is passed as part of both @code{Member} and @code{Membership}. The
flags are:
@table @code
@item invitation
The member has been invited, but has not yet accepted membership.
Clients should set this flag when adding other users as members. The
server may force this flag to be set when adding another person as a
member of a conference.
@item passive
The member is not actively participating in the conference. Passive
members do not receive group messages and should not be displayed as
active members by clients.
@item secret
The member does not wish to disclose the membership. Secret memberships
and members are cleared before being returned to a person who is not a
supervisor of the member or has sufficient privileges enabled.
@end table
The remaining flags in the @code{Membership-Type} structure are reserved
and should be set to false on all new memberships and retained on all
existing memberships.
@tindex Member
@example
Member ::=
( member : Pers-No;
added-by : Pers-No;
added-at : Time;
type : Membership-Type;
)
@end example
The @code{Member} structure encodes information about a member in aconference. It is returned by the @ref{get-members} call. The fields of
a @code{Member} structure are
@table @code
@item member
The person who is a member of the conference.
@item added-by
The person who created the membership. This field is zero only if the
membership was created before protocol version 10 was introduced.
@item added-at
The time when the membership was created. This field is meaningless if
added-by is zero.
@item type
Flags modifying the membership.
@end table
The contents of a @code{Member} structure can be cleared (all fields set
to zero) if the person requesting the record has insufficient privileges
to see the contents of the structure.
@tindex Membership-Old
@tindex Membership
@example
Membership-Old ::=
( last-time-read : Time;
conference : Conf-No;
priority : INT8;
last-text-read : Local-Text-No;
read-texts : ARRAY Local-Text-No;
)
Membership ::=
( last-time-read : Time;
conference : Conf-No;
priority : INT8;
last-text-read : Local-Text-No;
read-texts : ARRAY Local-Text-No;
added-by : Pers-No;
added-at : Time;
type : Membership-Type;
)
@end example
The @code{Membership} structure encodes information about a person's
membership in a conference. It is returned by the @ref{query-read-texts}
and @ref{get-membership} calls.
@table @code
@item last-time-read
The time when the person last read anything from the conference.
@item conference
The conference this membership data pertains to.
@item priority
The priority the person has assigned to the conference. The higher the
number, the higher the priority. In the future, priority zero will be
used to indicate a passive membership.
@item last-text-read
The local number of last text read in the conference.
@item read-texts
Additional texts beyond @code{last-text-read} that have also been read.
@item added-by
The person who created the membership. This field is zero if the
membership was created before protocol version 10 was introduced.
@item added-at
The time when the membership was created. This field is meaningless if
added-by is zero.
@item type
Flags modifying the membership.
@end table
A membership record may be cleared by the server (all fields set to
zero) if the person requesting the membership has insufficient
privileges to see the contents membership, but has sufficient privileges
to know about the person.
@subsection Article Marks
@tindex Mark
@example
Mark ::=
( text-no : Text-No;
type : INT8
)
@end example
This data type hold information about a person's marks on articles.
The fields of @code{Mark} are
@table @code
@item text-no
The text number marked.
@item type
The mark value.
@end table
Before version eight of protocol A, the meaning of the mark value was
unspecified. Work is underway to specify the meaning of certain mark
values.
@subsection Article Information
@tindex Misc-Info
@tindex Text-Stat-Old
@tindex Text-Stat
@example
Misc-Info ::= SELECTION
( 0=recpt recipient : Conf-No;
1=cc-recpt cc-recipient : Conf-No;
2=comm-to comment-to : Text-No;
3=comm-in commented-in : Text-No;
4=footn-to footnote-to : Text-No;
5=footn-in footnoted-in : Text-No;
6=loc-no local-no : Local-Text-No
7=rec-time received-at : Time;
8=sent-by sender : Pers-No;
9=sent-at sent-at : Time;
15=bcc-recpt bcc-recipient : Text-No;
)
Text-Stat-Old ::=
( creation-time : Time;
author : Pers-No;
no-of-lines : INTEGER;
no-of-chars : String-Size;
no-of-marks : INT16;
misc-info : ARRAY Misc-Info;
)
Text-Stat ::=
( creation-time : Time;
author : Pers-No;
no-of-lines : INTEGER;
no-of-chars : String-Size;
no-of-marks : INT16;
misc-info : ARRAY Misc-Info;
aux-items : ARRAY Aux-Item; )
@end example
These two structures contain information about a single article.
@code{Text-Stat} contains core information about the article and
@code{Misc-Info} contains miscellaneous information related to the
article. In the future, @code{Misc-Info} will become obsolete and
@code{Text-Stat} will be extended with more information.
A @code{Text-Stat} consists of the following:
@table @code
@item creation-time
The time when the article was created.
@item author
The author of the article.
@item no-of-lines
The number of lines in the article.
@item no-of-chars
The number of characters in the article.
@item no-of-marks
The number of marks added to this article by persons.
@item misc-info
The @code{Misc-Info} list for this article.
@item aux-items
The list of aux items for this article.
@end table
@code{Misc-Info}, when sent to the client, is sent in a particular order
(@pxref{The Misc-Info List}. The variants @code{Misc-Info} are
(briefly):
@table @code
@item recpt
Used to specify recipients of the article.
@item cc-recpt
Specifies recipients who have received a copy of the article but who
will not receive comments.
@item comm-to
Specifies an article this article is a comment to.
@item comm-in
Specifies an article in which there are comments to this article.
@item footn-to
Specifies an article this article is a footnote to.
@item footn-in
Specifies an article to which this article is a footnote.
@item loc-no
Specifies the local text number of this article in the conference
specified by @code{recpt} or @code{cc-recpt}.
@item rec-time
Specifies the time when this article was received by the conference
specified by @code{recpt} or @code{cc-recpt}.
@item sent-by
Specifies who sent this article to the conference specified by
@code{recpt} or @code{cc-recpt}.
@item sent-at
Specifies when the article was sent to the conference specified by
@code{recpt} or @code{cc-recpt}.
@item bcc-recpt
Specifies a blind carbon copy recipient. This item is only accepted by
protocol version 10 servers and is only sent in responses and messages
introduced in protocol version 10 or later.
@end table
@subsection Who Information
@tindex Who-Info-Old
@tindex Who-Info@tindex Who-Info-Ident
@example
Who-Info-Old ::=
( person : Pers-No;
working-conference : Conf-No;
what-am-i-doing : HOLLERITH;
)
Who-Info ::=
( person : Pers-No;
working-conference : Conf-No;
session : Session-No;
what-am-i-doing : HOLLERITH;
username : HOLLERITH;
)
Who-Info-Ident ::=
( person : Pers-No;
working-conference : Conf-No;
session : Session-No;
what-am-i-doing : HOLLERITH;
username : HOLLERITH;
hostname : HOLLERITH;
ident-user : HOLLERITH;
)
@end example
These structures are used to retrieve and set information on who is
currently using LysKOM. The types marked as ``old'' are obsolete but are
included for completeness. @code{Who-Info-Old} identifies a user who is
currently using LysKOM. @code{Who-Info} is used to set information
about a session and is returned by one obsolete
call. @code{Who-Info-Ident} is the preferred data type to use.
The fields of @code{Who-Info-Old} are
@table @code
@item person
The person the information is about.
@item working-conference
The conference the person is currently in.
@item what-am-i-doing
A client-supplied string saying what the person is doing.
@end table
The fields of @code{Who-Info} are
@table @code
@item person
The person the information is about.
@item working-conference
The conference the person is currently in.
@item session
The person's session number.
@item what-am-i-doing
A client-supplied string saying what the person is doing.
@item username
The name of the ``real'' user constructed from @code{hostname} and
@code{ident-user} (see below) and information from the client.
FIXME: define the format
@end table
The fields of @code{Who-Info-Ident} are
@table @code
@item person
The person the information is about.
@item working-conference
The conference the person is currently in.
@item sessionThe person's session number.
@item what-am-i-doing
A client-supplied string saying what the person is doing.
@item username
The name of the ``real'' user constructed from @code{hostname} and
@code{ident-user}.
FIXME: define the format
@item hostname
The host the connection originated at.
@item ident-user
The user name according to the Ident
@ifinfo
daemon
@end ifinfo
@iftex
d@ae{}mon
@end iftex
at the user's machine or ``unknown'' if Ident was not used.
@end table
@subsection Session Information
@tindex Session-Info
@tindex Session-Info-Ident
@tindex Static-Session-Info
@tindex Session-Flags
@tindex Dynamic-Session-Info
@example
Session-Info ::=
( person : Pers-No;
working-conference : Conf-No;
session : Session-No;
what-am-i-doing : HOLLERITH;
username : HOLLERITH;
idle-time : INTEGER;
connection-time : Time;
)
Session-Info-Ident ::=
( person : Pers-No;
working-conference : Conf-No;
session : Session-No;
what-am-i-doing : HOLLERITH;
username : HOLLERITH;
hostname : HOLLERITH;
ident-user : HOLLERITH;
idle-time : INTEGER;
connection-time : Time;
)
Session-No ::= INTEGER;
Static-Session-Info ::=
(
username : HOLLERITH;
hostname : HOLLERITH;
ident-user : HOLLERITH;
connection-time : Time;
)
Session-Flags ::= BITSTRING
( invisible;
user_active_used;
user_absent;
reserved3;
reserved4;
reserved5;
reserved6;
reserved7; )
Dynamic-Session-Info ::=
( session : Session-No;
person : Pers-No;
working-conference : Conf-No;
idle-time : INTEGER;
flags : Session-Flags;
what-am-i-doing : HOLLERITH;
)
@end example
These data types give information about a particular LysKOM session. The
types @code{Session-Info} and @code{Session-Info-Ident} have been
superseded by @code{Static-Session-Info} and
@code{Dynamic-Session-Info}. The static session info represents
information about a session that does not change during the lifetime of
the session. Therefore static session infos can be aggressively cached by
the client.
The fields of @code{Session-Info} are
@table @code
@item person
The person using this session.
@item working-conference
The conference the session is currently in.
@item session
The number of this session.
@item what-am-i-doing
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
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
amount of time the person has been on.
@end table
The fields of @code{Session-Info-Ident} are
@table @code
@item person
The person using this session.
@item working-conference
The conference the session is currently in.
@item session
The number of this session.
@item what-am-i-doing
A client-supplied string saying what the person is currently doing.
@item username
The name of the ``real'' user (see @code{Who-Info-Ident} above.)
@item hostname
The host the connection originated at.
@item ident-user
The user name according to the Ident
@ifinfo
daemon
@end ifinfo
@iftex
d@ae{}mon
@end iftex
at the user's machine or ``unknown''
if Ident was not used.
@item idle-time
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
amount of time the person has been on.
@end table
The fields of @code{Static-Session-Info} are
@table @code
@item username
The name of the ``real'' user (see @code{Who-Info-Ident} above.)
@item hostname
The host the connection originated at.
@item ident-user
The user name according to the Ident
@ifinfo
daemon
@end ifinfo
@iftex
d@ae{}mon
@end iftex
at the user's machine or ``unknown''
if Ident was not used.
@item connection-time
The time when the connection was initiated. This is not the same as the
amount of time the person has been on.
@end table
The bits in @code{Session-Flags} are:
@table @code
@item invisible
When true, the user requested an invisible session (@pxref{login}).
Sessions where no-one is logged in also have the @code{invisible} flag
set.
@item user_active_used
When true, the user-active (@pxref{user-active}) call has been issued by
the session, which in turn means that @code{idle-time} field in the
@code{Dynamic-Session-Info} is valid.
@item user_absent
This flag is currently not used.
@end table
The fields of a @code{Dynamic-Session-Info} are
@table @code
@item session
The session number of the session.
@item person
The person currently logged on, or zero if the session has not yet
logged on.
@item working-conference
The conference the session is currently in.
@item idle-time
The number of seconds that have passed since the last time user-active
(@pxref{user-active}) was called in the session.
@item flags
The dynamic session flags (see above.)
@item what-am-i-doing
What the client is doing. This string is set by the client.
@end table
@node Name Expansion, , LysKOM Data Types, Data Types
@section Name Expansion
Names in LysKOM can be expanded according to two rules, regexp matching
or KOM conventions.
@subsection Regexp Matching
This type of expansion, used by the @pxref{re-z-lookup} call and its
predecessors simply matches @code{ed(1)} style regular expressions to
names in the database to find the list of matching names. The matching
is done without regard for character case.
@subsection KOM Conventions
This type of matching is a little more complicated. Patterns consist of
words and parenthesized expressions, and contain implicit wildcards. The
@code{lyskomd} program implements an approximation of theses
conventions. Since @code{lyskomd} is the trendsetter, these semantics
are good enough.
The rules are simple. Any parenthesized expressions are removed from the
pattern and the names being checked for matches. Then the words of the
pattern are examined from beginning to end, and if every pattern word
matches the prefix of the corresponding word in the name, the name
matches the pattern.
For example ``L D'' matches ``LysKOM (client, server and protocol)
Discussion (and) Ideas'', but not ``LysKOM Protocol Discussion''.
@subsection 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
protocol version there will be a call to retrieve the collate table from
the server.
The current collate table simply maps ISO 8859-1 uppercase and lowercase
letters to equivalents, and also considered braces and suchlike
equivalent according to swascii rules.
@node Protocol Requests, , , Top
@chapter Protocol Requests
This chapter documents all calls that can be made to the server. All
calls are annotated with the protocol version in which they appeared and
their current status, which is one of
@table @samp
@item Experimental
The call is experimental. No client should rely on the existence of this
call. Experimental calls that are useful will usually become recommended
in future versions.
@item Recommended
The call is a standard call. Clients are recommended to use these calls
rather than experimental or obsolete ones. Servers are required to
implement all recommended calls.
@item Obsolete
The call should no longer be used by clients. Servers should implement
these, or they will be incompatible with old client versions.
@end table
@iftex
@i{A note about the examples:} The examples consist of a number of calls
and replies. Calls are set in a normal typewriter font. Replies are set
in a slanted typewriter font. Upright text in a reply signifies data
elements that will change or have changed as the result of another call
in the example.
@end iftex
@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 (46)
* get-created-texts:: O Get texts created by a user. Use call 104 (47)
* get-members-old:: O Get members of a conference (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:: 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 conference 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)
@end menu
@iftex
@section Available Requests
@end iftex
@node login-old, logout, , Protocol Requests
@subsection login-old (1) Obsolete
@findex login-old
@example
login-old [0] (( person : Pers-No;
passwd : HOLLERITH )) -> ( );
@end example
Log in as a person. This call has been replaced by call 62, @ref{login}.
@unnumberedsubsubsec Error codes
@table @code
@item undefined-person
@code{person} is not an existing person.
@item login-disallowed
Logins are not allowed and @code{person} does not have the @code{wheel}
bit set.
@item invalid-password
@code{passwd} is not the correct password for @code{person}. The
error-status indicates the person number.
@end table
@node logout, change-conference, login-old, Protocol Requests
@subsection logout (1) Recommended
@findex logout
@example
logout [1] ( )
-> ( );
@end example
Log out from LysKOM.
This call does not disconnect the session; use @ref{disconnect} for
that. After issuing a logout call the client can reconnect as the same
or a different person using the @ref{login} command.
For a client that needs to log in as several different users, issuing
multiple logout and login requests during one session is faster and
places less load on the server than does creating new sessions.
@unnumberedsubsubsec Error codes
This call never fails.
@node change-conference, change-name, logout, Protocol Requests
@subsection change-conference (1) Recommended
@findex change-conference
@example
change-conference [2] ( conference : Conf-No )
-> ( ) ;
@end example
Change current conference of a session. This call used to be called
pepsi (the name was a very obscure and not very funny joke.)
@unnumberedsubsubsec Error codes
@table @code
@item login-first
The session is not logged in yet.
@item undefined-conference
Conference @code{conference} does not exist or is secret.
@item zero-conference
@code{conference} is zero.
@item not-member
The user currently logged in is not a member of @code{conference}.
@end table
@node change-name, change-what-i-am-doing, change-conference, Protocol Requests
@subsection change-name (1) Recommended
@findex change-name
@example
change-name [3] (( conference : Conf-No;
new-name : HOLLERITH ))
-> ( ) ;
@end example
This call changes the name of a conference or a person. To change the
name of a conference the session issuing the call must be logged in as a
person who either has special privileges or is the supervisor of the
conference.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
The session is not logged in yet.
@item undefined-conference
Conference @code{conference} does not exist or is secret.
@item zero-conference@code{conference} is zero.
@item permission-denied
Permission denied. The @code{change-name} bit is not set or the user
does not have enough access to @code{conference}.
@item conference-exists
@code{new-name} is already occupied by another conference.
@item string-too-long
@code{new-name} is too long for a valid conference name.
@item bad-name
There are invalid characters in @code{new-name}.
@end table
@node change-what-i-am-doing, create-person-old, change-name, Protocol Requests
@subsection change-what-i-am-doing (1) Recommended
@findex change-what-i-am-doing
@example
change-what-i-am-doing [4] ( what-am-i-doing : HOLLERITH )
-> ( );
@end example
This call tells the server what the logged-in user is doing. The string
is usually displayed when a user requests that a client list who is
using LysKOM. Clients are encouraged to use this call creatively.
@unnumberedsubsubsec Error codes
@table @code
@item string-too-long
@code{what-i-am-doing} is too long.
@end table
@node create-person-old, get-person-stat-old, change-what-i-am-doing, Protocol Requests
@subsection create-person-old (1) Obsolete (10)
@findex create-person-old
@example
create-person-old [5] (( name : HOLLERITH;
passwd : HOLLERITH; )) -> Pers-No;
@end example
This call requests that the server create a new person with the name and
password given as arguments. To create a person the session may have to
be logged in as a person with sufficient privileges, if the server is
configured that way.
If the session was not logged in an automatic visible login to the new
person will be performed.
The new person will be a member of exactly one conference: the
associated mailbox. That membership will have priority 255 and (of
course) position 0. All flags of the membership will be 0.
@i{Example:}
@example
1 5 24HLysKOM Statistics Daemon 6Hsecret
@t{=1 6}
@end example
This example creates a new person named ``LysKOM statistics Daemon''
with the password ``secret.'' The server has returned the person number
six for the person.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
The session is not logged in and the server does not allow person
creation before logging in.
@item permission-denied
The server does not allow anyone to create person and the person
currently logged on does not have the @code{create-pers} bit set.
@item conference-exists
There is already a conference named @code{name}.
@item invalid-password
The string @code{passwd} is not a valid password.
@end table
@node get-person-stat-old, set-priv-bits, create-person-old, Protocol Requests
@subsection get-person-stat-old (1) Obsolete
@findex get-person-stat-old
@example
get-person-stat-old [6] (( person : Pers_No;
mask : INT32 ))
-> Person;
@end example
This call returns information about a person. If the low bit of
@code{mask} is not set, then the name is not returned. This call is
obsolete and has been replaced by call 49 @ref{get-person-stat}.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
This call can't be executed without logging in first.
@item undefined-person
Person @code{person} does not exist.
@item undefined-conference
Conference @code{person} does not exist or is secret.
@item zero-conference
@code{conference} is zero.
@end table
@node set-priv-bits, set-passwd, get-person-stat-old, Protocol Requests
@subsection set-priv-bits (1) Recommended
@findex set-priv-bits
@example
set-priv-bits [7] (( person : Pers-No;
privileges : Priv-Bits; )) -> ( );
@end example
This call sets the privileges of a person (see @ref{Security}.) To
successfully issue this call the session must be logged in as a person
with sufficient privileges.
@i{Example:}
@example
1 7 6 0010000000000000
@t{=1}
@end example
This example sets the privileges of person 6 to nothing but
@code{statistic}. This particular set of privileges might be useful for
a person used by a statistics-collecting
@ifinfo
daemon.
@end ifinfo
@iftex
d@ae{}mon.
@end iftex
@unnumberedsubsubsec Error codes
@table @code
@item login-first
This call can't be executed without logging in first.
@item undefined-person
@code{person} is not a valid person.
@item permission-denied
The person currently logged in does not have the @code{wheel} bit set
and privilege level set to 6 or higher.
@end table
@node set-passwd, query-read-texts-old, set-priv-bits, Protocol Requests
@subsection set-passwd (1) Recommended
@findex set-passwd
@example
set-passwd [8] (( person : Pers-No;
old-pwd : HOLLERITH;
new-pwd : HOLLERITH; )) -> ( );
@end example
This call is used to set the password of a person. Providing
@code{old-pwd} matches @code{person}'s old password, that person's
password is changed to @code{new-pwd}. Any person may set it's own
password. In addition persons with sufficient privileges may ser other
persons' passwords.
@i{Example:}
@example
1 8 5 6Hgazonk 7Ht9go8hw
@t{=1}
@end example
This example sets the password of the LysKOM administrator to ``t9go8hw''
provided that the old password was ``gazonk''.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
This call cannot be executed without logging in.
@item undefined-person
@code{person} is not a valid person.
@item permission-denied
Attempt to change password of another person without being the
supervisor of that person and without the @code{wheel} bit set and
privilege level 7 or higher enabled.
@item invalid-password
@code{old-pwd} is invalid or @code{new-passwd} is invalid as a password.
@end table
@node query-read-texts-old, create-conf-old, set-passwd, Protocol Requests
@subsection query-read-texts-old (1) Obsolete (10)
@findex query-read-texts-old
@example
query-read-texts-old [9] (( person : Pers-No;
conference : Conf-No; ))
-> ( read-texts : Membership-Old );
@end example
This call is used to find the number of unread texts in a conference.
The data it returns is actually a membership structure which specifies
which texts have been read. It is up to the client to transform the data
to a more usable form. @code{person} is the person being queried is to
be made and @code{conference} is the conference in question.
This call may be issued without logging in.
Calling @code{query-read-texts-old} does not require the session to be logged in.
@i{Example:}
@example
1 9 6 1
@t{=1 32 5 11 12 7 93 1 193 1 1 20 133 3 @{ 135 136 137 @}}
@end example
This example finds the read texts for user 6 in conference 1. The
returned data indicates that the user last read conference 1 (the tenth
number) on Monday July 12th, 1993 at 11:05:32 (the first nine numbers),
that the person has assigned priority 20 to the conference (the eleventh
number) and that all articles up to and including local number 133 plus
articles 135, 136 and 137 have been read.
@unnumberedsubsubsec Error codes
@table @code
@item undefined-person
@code{person} does not exist, or no access to person.
@item undefined-conference
Conference @code{conference} does not exist, or is secret.
@item zero-conference
@code{conference} is zero.
@item not-member
@code{person} is not a member of @code{conference}.
@end table
@node create-conf-old, delete-conf, query-read-texts-old, Protocol Requests
@subsection create-conf-old (1) Obsolete (10)
@findex create-conf-old
@example
create-conf-old [10] (( name : HOLLERITH;
type : Any-Conf-Type; ))
-> ( conference : Conf-No );
@end example
This call is used to create new conferences. @code{name} is the name of
the new conference and @code{type} is its type. If successful, the call
returns the conference number of the newly created conference.
To use this call the session must have logged in as a user with
privileges to create conferences (@pxref{Security}).
@i{Example:}@ifinfo
@example
1 50 8
@t{%1 9 0}
1 10 13HInlägg @}t mig 00001000
@t{=1 8}
1 50 8
@t{=1 13HInlägg @}t mig 0000
43 9 17 14 5 96 5 165 1
43 9 17 14 5 96 5 165 1
5 0 5 0 5 0 77 0 1 0}
@end example
@end ifinfo
@iftex
@example
1 50 8
@t{%1 9 0}
1 13HInl@"a{}gg @aa{}t mig 00001000
@t{=1 7}
1 50 8
@t{=1 13HInl@"a{}gg @aa{}t mig 0000
43 9 17 14 5 96 5 165 1
43 9 17 14 5 96 5 165 1
5 0 5 0 5 0 77 0 1 0}
@end example
@end iftex
This example creates a new conference named
@ifinfo
``Inlägg @}t
@end ifinfo
@iftex
``Inl@"a{}gg @}t
@end iftex
mig''@footnote{This conference is a standard Lysator conference. It's
all Padrone's fault.} which accepts all users as members and accepts
anonymous articles. The server returns 7 as the new conference number.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item permission-denied
The server does not allow anyone to create a conference and user does
not have the @code{create-conf} bit set.
@item conference-exists
A conference named @code{name} already exists.
@item bad-name
@code{name} contains invalid characters.
@item string-to-long
@code{name} is too long to be used as a conference name.
@item secret-public
The conference type has the @code{secret} bit set, but the
@code{rd-prot} bit is cleared.
@end table
@node delete-conf, lookup-name, create-conf-old, Protocol Requests
@subsection delete-conf (1) Recommended
@findex delete-conf@example
delete-conf [11] ( conf : Conf-No; ) -> ( );
@end example
This call deletes the conference @code{conf} from the LysKOM
database. Only privileged users and the supervisors of a conference may
delete it. @b{[Is it possible to delete mailboxes?]}
@i{Example:}
@example
1 50 7
@t{=1 4HTest 1001
16 4 19 10 5 96 1 161 1
16 4 19 10 5 96 1 161 1
7 0 7 0 0 0 77 1 1 0}
1 11 7
@t{=1}
1 50 7
@t{%1 9 0}
@end example
This example shows the successful deletion of conference number seven.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-conference
@code{conf} does not exist or is secret.
@item zero-conference
@code{conference} is zero.
@item permission-denied
Not supervisor of @code{conf} and not enough privileges enabled.
@item undefined-person
@code{conf} is a letterbox but does not exist as a person (the database
is corrupt.)
@end table
@node lookup-name, get-conf-stat-older, delete-conf, Protocol Requests
@subsection lookup-name (1) Obsolete
@findex lookup-name
@example
lookup-name [12] ( name : HOLLERITH ) -> ( Conf-List-Archaic );
@end example
This call returns a list of conferences matching the string @code{name}.
lookup-name has been superseded by call 76, @ref{lookup-z-name}.
@i{Example:}
@example
1 12 3Ha d
@t{=1 3 @{ 217 674 1582 @} @{ 0000 1001 0000 @}}
2 12 3H:::
@t{=2 0 * *}
3 76 3Ha d 1 1
@t{=3 3 @{ 31HAlkohol- (och annan) drogdebatt 0000 217
13HAnna Degerman 1001 674
27HAnarchy discussion (import) 0000 1582 @}}
4 76 3H::: 1 1
@t{=4 0 *}
@end example
This example shows two attempts to look up a name. The first examplelooks up @samp{a d} and finds three matches (the middle, number 674, is
a person. The second example looks up @samp{:::} which doesn't match
any conference (or person). Call number 3 and 4 issues the same lookup
using the @ref{lookup-z-name} call. (The return value for call number 3
has been broken into three lines to fit on the page.)
@unnumberedsubsubsec Error codes
This call always succeeds.
@node get-conf-stat-older, add-member-old, lookup-name, Protocol Requests
@subsection get-conf-stat-older (1) Obsolete
@findex get-conf-stat-older
@example
get-conf-stat-older [13] (( conf-no : Conf-No;
mask : INTEGER ))
-> ( Conference-Old );
@end example
This call retrieves the information associated with conference
@code{conf-no} in the LysKOM server. This call should no longer be used;
use call 91, @ref{get-conf-stat} instead.
@unnumberedsubsubsec Error codes
@table @code
@item undefined-conference
@code{conf-no} does not exist or is secret.
@item zero-conference
@code{conference} is zero.
@end table
@node add-member-old, sub-member, get-conf-stat-older, Protocol Requests
@subsection add-member-old (1) Obsolete (10)
@i{Example:}
@findex add-member-old
@example
add-member-old [14] (( conf-no : Conf-No;
pers-no : Pers-No;
priority : INT8;
where : INT16 ))
-> ( );
@end example
Make the person @code{pers-no} a member of conference @code{conf-no}.
The membership priority is set to @code{priority} and its position in
the membership list is set to @code{where}.
This call can be used to change the priority and position of a
conference in the person's membership list if the person is already a
member of the conference.
@example
1 46 119 0 10 0
@t{=1 1 @{ 49 14 17 13 8 91 5 255 1 119 255 0 0 * @}}
1 14 1 119 250 0
@t{=1}
1 46 119 0 10 0
@t{=1 2 @{ 52 30 14 11 5 96 2 162 1 1 250 0 0 *
49 14 17 13 8 91 5 255 1 119 255 0 0 * @}}
@end example
This example makes person 119 (me) a member of conference number 1. The
priority is set to 250 and the conference is placed first in the
membership list. The first and last calls of the example show the
membership list for person 119 before and after the call.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-conference
Conference @code{conf-no} does not exist or is secret.
@item zero-conference
@code{conference} is zero.
@item undefined-person
Person @code{pers-no} does not exist
@item access-denied
Not enough permissions or privileges to add members to conference
@code{conf-no}.
@item permission-denied
Person @code{pers-no} is already a member of conference @code{conf-no},
but the person logged on is not a supervisor and does not have enough
privileges to change the priorities of person @code{pers-no}.
@end table
@node sub-member, set-presentation, add-member-old, Protocol Requests
@subsection sub-member (1) Recommended
@findex sub-member
@example
sub-member [15] (( conf-no : Conf-No;
pers-no : Pers-No; ))
-> ( );
@end example
Removes the person @code{pers-no} from the membership list of conference
@code{conf-no} and remove the conference from the person's list of
memberships.
@i{Example:}
@example
1 46 5 0 100 0
@t{=1 2 @{ 44 14 19 10 5 96 1 161 1 1 0 0 0 *
49 14 17 13 8 91 5 255 1 5 255 0 0 * @}}
1 15 1 5
@t{=1}
1 46 5 0 100 0
@t{=1 1 @{ 49 14 17 13 8 91 5 255 1 5 255 0 0 * @}}
@end example
This example shows how person 5 is removed from conference one. The
calls to get-membership demonstrate the effects on the LysKOM database.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-conferenceConference @code{conf-no} does not exist or is secret.
@item zero-conference
@code{conference} is zero.
@item undefined-person
Person @code{pers-no} does not exist.
@item not-member
Person @code{pers-no} is not a member of conference @code{conf-no}.
@item permission-denied
Not supervisor of conference @code{conf-no} or not supervisor of person
@code{pers-no} and not enough privileges to issue the call anyway.
@end table
@node set-presentation, set-etc-motd, sub-member, Protocol Requests
@subsection set-presentation (1) Recommended
@findex set-presentation
@example
set-presentation [16] (( conf-no : Conf-No;
text-no : Text-No; ))
-> ( );
@end example
This call sets the presentation text of the conference or person
@code{conf-no} to the text @code{text-no}. To remove a presentation, use
a @code{text-no} of zero. This call protects the new presentation from
being deleted automatically and removes such protection from the old
presentation. In lyskomd this is implemented by increasing the mark
count on presentation texts.
@i{Example:}
@example
1 50 6
@t{=1 11HDavid Byers 1001
26 15 11 9 5 96 0 160 1
26 15 11 9 5 96 0 160 1
5 0 5 0 5 0 77 1 1 0}
1 16 6 1
@t{=1}
1 50 6
@t{=1 11HDavid Byers 1001
26 15 11 9 5 96 0 160 1
26 15 11 9 5 96 0 160 1
5 1 5 0 5 0 77 1 1 0}
@end example
This example shows how the presentation of person 6 is being changed. To
start with, the person had no presentation, as is shown by the
@ref{get-conf-stat-old} call. Later, after the set-presentation has been
called, the presentation field has changed.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-conference
Conference @code{conf-no} does not exist or is secret.
@item zero-conference
@code{conference} is zero.
@item permission-denied
Not enough permissions to change presentation of conference
@code{conf-no}.
@item no-such-text
Text @code{text-no} does not exist or no read permission.
@item too-many-marks
Adding a mark to text @code{text-no} would cause it to have too many
marks.
@end table
@node set-etc-motd, set-supervisor, set-presentation, Protocol Requests
@subsection set-etc-motd (1) Recommended
@findex set-etc-motd
@example
set-etc-motd [17] (( conf-no : Conf-No;
text-no : Text-No; ))
-> ( );
@end example
This call sets the message of the day on the conference or person
@code{conf-no} to the article @code{text-no} and removes the old
message. To remove an old message without setting a new one, use a
@code{text-no} of zero. This call protects the new message from
automatic deletion and removes such protection from the old message just
as @ref{set-presentation}.
@i{Example:}
@example
1 50 6
@t{=1 11HDavid Byers 1001
26 15 11 9 5 96 0 160 1
26 15 11 9 5 96 0 160 1
5 0 5 0 5 0 77 1 1 0}
1 17 6 1
@t{=1}
1 50 6
@t{=1 11HDavid Byers 1001
26 15 11 9 5 96 0 160 1
26 15 11 9 5 96 0 160 1
5 0 5 0 5 1 77 1 1 0}
@end example
This example shows how text number one is used as the message of the day
for conference six (which happens to be a mailbox.) The
@ref{get-conf-stat-old} calls before and after demonstrate the change in
the conference structure.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-conference
Conference @code{conf-no} does not exist or is secret.
@item zero-conference
@code{conference} is zero.
@item permission-denied
Not enough permissions to set the MOTD of conference @code{conf-no}.
@item too-many-marks
Adding a mark to text @code{text-no} would cause it to have too many
marks.
@end table
@node set-supervisor, set-permitted-submitters, set-etc-motd, Protocol Requests
@subsection set-supervisor (1) Recommended
@findex set-supervisor
@example
set-supervisor [18] (( conf-no : Conf-No;
admin : Conf-No; ))
-> ( );
@end example
The set-supervisor call changes the supervisor of an existing
conference. The result is that all members of the conference
@code{admin} become supervisors of the conference @code{conf-no}.
Typically, but not always, @code{admin} will be a letterbox.
@i{Example:}
@example
1 50 4
@t{=1 17HNyheter om LysKOM 0000
48 11 17 13 8 91 5 255 1
15 12 11 9 5 96 0 160 1
0 0 0 0 0 0 77 1 1 1}
1 18 4 6
@t{=1}
1 50 4
@t{=1 17HNyheter om LysKOM 0000
48 11 17 13 8 91 5 255 1
15 12 11 9 5 96 0 160 1
0 0 6 0 0 0 77 1 1 1}
@end example
This example makes the members of conference six supervisors of
conference four (which is usually the ``News about LysKOM'' conference).
The change in the conference structure is evident from the
@ref{get-conf-stat-old} calls before and after the set-supervisor call.
Note that the original supervisor was not set. In order to change the
supervisor of such a conference, the session issuing the call must have
administration privileges.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-conference
Conference @code{conf-no} or conference @code{admin} does not exist or
is secret.
@item zero-conference
@code{conference} is zero.
@item permission-denied
Not enough permissions or privileges to change the supervisor of
conference @code{conf-no}.
@end table
@node set-permitted-submitters, set-super-conf, set-supervisor, Protocol Requests
@subsection set-permitted-submitters (1) Recommended
@findex set-permitted-submitters
@example
set-permitted-submitters [19] (( conf-no : Conf-No;
perm-sub : Conf-No; ))
-> ( );
@end example
This call grants the right to send articles to the conference
@code{conf-No} to all members of the conference @code{perm-sub}. The
right to submit articles is per default only granted to the members of
the conference. When a person tries to submit an article but does not
have the right to do so, the client is expected to send the article to
the super-conference instead.
@i{Example:}
@example
1 50 4
@t{=1 17HNyheter om LysKOM 0000
48 11 17 13 8 91 5 255 1
15 12 11 9 5 96 0 160 1
0 0 6 0 0 0 77 1 1 1}
1 19 4 1
@t{=1}
1 50 4
@t{=1 17HNyheter om LysKOM 0000
48 11 17 13 8 91 5 255 1
15 12 11 9 5 96 0 160 1
0 0 6 1 0 0 77 1 1 1}
@end example
This example shows how all members of conference one are given
permission to send articles to conference four. From the beginning, only
members of conference four were permitted to submit articles. The change
is evident from the @ref{get-conf-stat-old} calls before and after the
set-permitted-submitters call.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-conference
Conference @code{conf-no} or conference @code{perm-sub} does not exist
or is secret.
@item zero-conference
@code{conference} is zero.
@item permission-denied
Not enough permissions to change the permitted submitters of conference
@code{conf-no}.
@end table
@node set-super-conf, set-conf-type, set-permitted-submitters, Protocol Requests
@subsection set-super-conf (1) Recommended
@findex set-super-conf
@example
set-super-conf [20] (( conf-no : Conf-No;
super-conf : Conf-No; ))
-> ( );@end example
Makes the conference @code{super-conf} the super-conference of the
conference @code{conf-no}. When an article is submitted to a conference
that does not accept it, it is sent to the super-conference instead.
@i{Example:}
@example
@end example
This example demonstrates how the super-conference of conference 1 is
set to conference 8. The calls to @ref{get-conf-stat-old} demonstrate the
change in the conference structure.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-conference
Conference @code{conf-no} or conference @code{super-conf} does not exist
or is secret.
@item zero-conference
@code{conference} is zero.
@item permission-denied
Not enough permissions to change super-conference of conference
@code{conf-no}.
@end table
@node set-conf-type, set-garb-nice, set-super-conf, Protocol Requests
@subsection set-conf-type (1) Recommended
@findex set-conf-type
@example
set-conf-type [21] (( conf-no : Conf-No;
type : Any-Conf-Type ))
-> ( );
@end example
Sets the conference type of conference @code{conf-no} to @code{type}.
Before protocol version 8, @code{type} could only be four bits. Starting
with protocol version 8, either a four-bit conference type or an
@code{Extended-Conf-Type} is allowed.
@example
1 78 4
@t{=1 17HNyheter om LysKOM 00001000 1 77}
1 21 4 00000000
@t{=1}
1 78 4
@t{=1 17HNyheter om LysKOM 00000000 1 77}
@end example
This example shows a user removing the allow-anonymous bit from
conference four. The @ref{get-uconf-stat} call shows all eight bits of
the conference type before and after the set-conf-type call.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-conference
Conference @code{conf-no} does not exist or is secret.
@item zero-conference
@code{conference} is zero.
@item secret-public@code{type} has both the @code{secret} bit and @code{rd-prot} bits set.
@item permission-denied
Not enough permissions or privileges to change the conference type of
conference @code{conf-no}.
@item letterbox
Attempt to change the @code{letterbox} flag.
@end table
@node set-garb-nice, get-marks, set-conf-type, Protocol Requests
@subsection set-garb-nice (1) Recommended
@findex set-garb-nice
@example
set-garb-nice [22] (( conf-no : Conf-No;
nice : Garb-Nice ))
-> ( );
@end example
Sets the expiration time for articles in conference @code{conf-no} to
@code{nice} days. An article that is older than the maximum expiration
time of each conference it is sent to may be deleted by the LysKOM
server unless it has marks.
@example
1 78 4
@t{=1 17HNyheter om LysKOM 00000000 1 77}
1 22 4 7
@t{=1}
1 78 4
@t{=1 17HNyheter om LysKOM 00000000 1 7}
@end example
This example shows the expiration time of conference four being lowered
from 77 to just seven days.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-conference
Conference @code{conf-no} does not exist or is secret.
@item zero-conference
@code{conference} is zero.
@item permission-denied
Not enough permissions to change the expiration time for conference
@code{conf-no}.
@end table
@node get-marks, mark-text-old, set-garb-nice, Protocol Requests
@subsection get-marks (1) Recommended
@findex get-marks
@example
get-marks [23] ( )
-> ( ARRAY Mark );
@end example
This call returns the list of marks the current user has set.
@example
1 23
@t{=1 3 @{ 13020 100 13043 95 12213 95 @}}
@end example
In this example, the current user has three marks, one on text 13020with mark type 100, one on text 13042 with mark type 95 and one on text
12213 with mark type 95. The maximum number of marks may be arbitrarily
limited in the LysKOM server.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@end table
@node mark-text-old, get-text, get-marks, Protocol Requests
@subsection mark-text-old (1) Obsolete
@findex mark-text-old
@example
mark-text-old [24] (( text : Text-No;
mark-type : INT8 ))
-> ( );
@end example
This call has been replaced by @ref{mark-text} and @ref{unmark-text} and
should no longer be used.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item no-such-text
The text @code{text} does not exist.
@item permission-denied
No read permission on text @code{text}.
@item undefined-person
The person currently logged in does not exist (can't happen error.)
@item too-many-marks
Marking the text would cause the person doing the marking to have too
many marks, or cause the text to have too many marks.
@end table
@node get-text, get-text-stat-old, mark-text-old, Protocol Requests
@subsection get-text (1) Recommended
@findex get-text
@example
get-text [25] (( text : Text-No;
start-char : INTEGER;
end-char : INTEGER; ))
-> ( HOLLERITH );
@end example
Retrieve text number @code{text} from the LysKOM database, starting at
position @code{start-char} and ending at position @code{end-char}. The
first character in the text is numbered 0 and the last can be retrieved
using @ref{get-text-stat}. It is also permitted to request a character
position beyond the actual end of the text, in which case as much text
as is available will be returned.
@example
1 25 100 0 32766
@t{=1 25HYawn^JNothing is happening} 2 25 100 5 32766
@t{=2 20HNothing is happening}
3 25 100 0 3
@t{=3 4HYawn}
@end example
In this example, text 100 is requested three times, first from position
0 to position 32766, then from position 5 to position 32766 and finally
from position 0 to position 4. The first reply contains the entire text,
the following two contain only the requested portion.
@unnumberedsubsubsec Error codes
@table @code
@item no-such-text
The text @code{text} does not exits or no read permission.
This error code will also be used when attempting to fetch any text
except the motd-of-lyskom text without logging in first.
@item text-zero
Attempt to retrieve text number 0.
@item index-out-of-range
@code{start-char} is larger than the length of the text.
@end table
@node get-text-stat-old, mark-as-read, get-text, Protocol Requests
@subsection get-text-stat-old (1) Obsolete (10)
@findex get-text-stat-old
@example
get-text-stat-old [26] ( text-no : Text-No )
-> ( Text-Stat-Old );
@end example
Get information about text number @code{text-no}. The text-stat contains
information about the size of the text, its recipients, comments, author
and more.
@example
1 26 100
=1 7 35 16 15 6 96 1 196 1 14 1 22 1
@t{7 @{ 0 7 6 85 0 15 6 1
8 13 9 12 37 16 15 6 96 1 196 1
3 311 @}}
@end example
In this example, text number 100 was created by person 7 at
approximately 4:35PM on July 15 1996. Its recipients are conferences 7
and 15, and it was sent to conference 15 by person 13 at 16:37 on the
day it was created. The text has a single comment: text 311.
@unnumberedsubsubsec Error codes
@table @code
@item no-such-text
The text @code{text-no} does not exist, or no read access.
This error code will also be used when attempting to fetch any text
except the motd-of-lyskom text without logging in first.
@item text-zero
Attempt to retrieve text number 0.
@end table
@node mark-as-read, create-text-old, get-text-stat-old, Protocol Requests
@subsection mark-as-read (1) Recommended
@findex mark-as-read
@example
mark-as-read [27] (( conference : Conf-No;
text : ARRAY Local-Text-No; ))
-> ( );
@end example
Marks text @code{text} in conference number @code{conference} as read
for the current user. This call updates the membership record for the
user.
@example
1 9 6 7
@t{=1 20 32 11 17 6 96 3 198 1 7 1 240 0 *}
1 78 7
@ifinfo
@t{=1 13HInlägg @}t mig 00001000 241 1}
@end ifinfo
@iftex
@t{=1 13HInl@"a{}gg @}t mig 00001000 241 1}
@end iftex
1 27 7 1 @{ 241 @}
@t{=1}
1 9 6 7
@t{=1 20 32 11 17 6 96 3 198 1 7 1 241 0 *}
@end example
This example shows person 6 marking local text number 241 in conference
7 as read. In the first query-read-texts call the person has read local
text 240, but nothing higher. The mark-as-read call is reflected in the
second query-read-texts call, where the user is seen to have read text
241 in conference 7.
To mark a global text number as read it is necessary to translate it
into local text numbers by looking as the Misc-Info list in the
Text-Stat and calling mark-as-read once for each recipient.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-conference
The conference @code{conference} does not exist or is secret.
@item zero-conference
@code{conference} is zero.
@item not-member
The person logged on is not a member of conference @code{conference}.
@item no-such-local-text
One of the numbers in @code{text} is not a local text number in
@code{conference}. The error argument indicates the index of the invalid
number.
@item local-text-zero
One of the numbers in @code{text} is zero.
@end table
@node create-text-old, delete-text, mark-as-read, Protocol Requests
@subsection create-text-old (1) Obsolete (10)
@findex create-text-old
@example
create-text-old [28] (( text : HOLLERITH; misc-info : ARRAY Misc-Info; ))
-> ( Text-No; );
@end example
Creates a new text with contents from @code{text} and recipients
etc. defined by @code{misc-info} (@pxref{The Misc-Info List}.) In
addition to the result, the server will send an asynchronous message
to all members of any of the recipients of the new text. It is not
defined whether this messages comes before or after the reply to
the create-text message. Clients should be prepared for either
situation.
The text up to the first line feed is considered to be the subject
line. The remaining text is the message body. Although messages with
only a subject are valid, clients should avoid letting users create
such messages.
The only Misc-Info items valid for this call are recpt, cc-recpt,
bcc-recpt (protocol version 10), comm-to and footn-to.
@example
1 28 20HExample\nMessage body 3 @{ 0 5 1 112 2 33467 @}
@t{:16 0 33502 13 16 15 16 6 97 3 196 1 119 1 20 0}
@t{ 5 @{ 0 5 6 148 1 112 6 3438 2 33467 @} }
@t{=1 33502}
@end example
In this example, person 119 creates a text containing a subject and a
one-line body. The recipient of the text is conference five, conference
112 is a CC recipient and the text is a comment to text 33467. The
server reply indicates that the new text has been given number 33502.
Finally there is an asynchronous message sent to all members of
recipient conferences. Note how the message was sent before the reply to
the client. The misc-info list in this message has two additional
fields, the local numbers of the text in each of its recipient
conferences.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item string-too-long
The string @code{text} is longer than the maximum length of a message.
@item temporary-failure
The text could not be created at the moment.
@item no-such-text
Attempt to comment or footnote a non-existent or secret text.
@item not-author
Attempt to footnote a text authored by someone else.
@item footnote-limit
Attempt to footnote a text with the maximum number of footnotes already
set.
@item comment-limit
Attempt to comment a text with the maximum number of comments already
set.
@item access-denied
Attempt to send a text to a conference failed because no access to the
conference or any superconference that will accept a text.
@item anonymous-rejected
Attempt to send an anonymous text to a conference that does not accept
anonymous texts.
@item illegal-misc
Invalid misc-info list. A recipient is listed more than once or there is
an unknown misc item in the misc-info list.
@end table
@node delete-text, add-recipient, create-text-old, Protocol Requests
@subsection delete-text (1) Recommended
@findex delete-text
@example
delete-text [29] ( text : Text-No )
-> ( );
@end example
Deletes the text @code{text} from the LysKOM database, if the person
issuing the command may do so.
@example
1 29 33467
@t{=1}
@end example
This simple example shows the deletion of text number 33467.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item no-such-text
The text @code{text} does not exist or no read access.
@item not-author
The person logged in is not the text author or supervisor of the text
author.
@end table
@node add-recipient, sub-recipient, delete-text, Protocol Requests
@subsection add-recipient (1) Recommended
@findex add-recipient
@example
add-recipient [30] (( text-no : Text-No;
conf-no : Conf-No;
recpt-type : Misc-Info; ))
-> ( );
@end example
Adds @code{conf-no} as recipient to text @code{text-no}. If
@code{recpt-type} is 1, then a cc-recept (@pxref{The Misc-Info List}) is
created; otherwise a recept is created.
Since protocol version 8 this call can also be used to change a
cc_recept into a recept and vice versa by simply adding a recipient
that already exists.
Since protocol version 10 the @code{carbon-copy} parameter is a
@code{Misc-Info}, not a @code{BOOL}. Only infos @code{recpt},
@code{cc-recpt} and @code{bcc-recpt} are accepted.
@example
1 26 1
@t{=1 2 22 12 17 6 97 4 197 1 5 4 256 1 0 *}
1 30 1 5 0
@t{=1}
1 26 1
@t{=1 2 22 12 17 6 97 4 197 1 5 4 256 1}
@t{ 3 @{ 0 5 6 1 9 34 34 17 17 6 97 4 197 1 @}}
1 30 1 5 1
@t{=1}
1 26 1 @t{=1 2 22 12 17 6 97 4 197 1 5 4 256 1}
@t{ 3 @{ 1 5 6 1 9 34 34 17 17 6 97 4 197 1 @}}
@end example
This example show how conference 5 is added first as a recipient of text
1, then changed to a carbon-copy recipient. The misc-info list reflects
these changes.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-conference
The conference @code{conf-no} does not exist.
@item zero-conference
@code{conference} is zero.
@item no-such-text
The text @code{text-no} does not exist.
@item already-recipient
The conference @code{conf-no} is already a recipient of the same type as
@code{recpt-type}.
@code{text-no}.
@item illegal-info-type
@code{carbon-copy} is not @code{recpt}, @code{cc-recpt} or
@code{bcc-recpt}.
@item recipient-limit
The text already has the maximum number of recipients.
@item permission-denied
Attempt to change recipient types of a recipient, but not the author of
the text or supervisor of the recipient.
@end table
@node sub-recipient, add-comment, add-recipient, Protocol Requests
@subsection sub-recipient (1) Recommended
@findex sub-recipient
@example
sub-recipient [31] (( text-no : Text-No;
conf-no : Conf-No; ))
-> ( );
@end example
Removes @code{conf-no} from the list of recipients of text
@code{text-no}. Recipients may be removed by the author of the text or
by the supervisor of the recipients of the text or by the supervisor of
the author.
@example
1 26 1
@t{=1 2 22 12 17 6 97 4 197 1 5 4 256 1}
@t{ 3 @{ 1 5 6 1 9 34 34 17 17 6 97 4 197 1 @}}
1 31 1 5
=1
1 26 1
@t{=1 2 22 12 17 6 97 4 197 1 5 4 256 1 0 *}
1 31 1 5 %1 30 0
@end example
In this example, conference 5 is removed from the recipient list of text
number 5. When the call is repeated, the server simply returns an error
since conference 5 is not a recipient of the text.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item no-such-text
The text @code{text-no} does not exist or is secret.
@item not-recipient
The conference @code{conf-no} is not a recipient of text @code{text-no}.
@item undefined-conference
The conference @code{conf-no} does not exist or is secret.
@item zero-conference
@code{conference} is zero.
@item permission-denied
Not supervisor of text author or conference, and not sender of text to
@code{conf-no} and not enough privileges set and enabled.
@end table
@node add-comment, sub-comment, sub-recipient, Protocol Requests
@subsection add-comment (1) Recommended
@findex add-comment
@example
add-comment [32] (( text-no : Text-No;
comment-to : Text-No; ))
-> ( );
@end example
Add a comment link between the text @code{comment-to} and the text
@code{text-no} (@code{text-no} becomes a comment to the text
@code{comment-to}). This call is used to add comment links after a text
has been created. The normal procedure for creating comments is to add a
@code{comm_to} element to the text's misc-info list when the text is
created (@pxref{The Misc-Info List}.)
@example
1 26 1
@t{=1 2 22 12 17 6 97 4 197 1 5 4 256 1 0 *}
1 26 2
@t{=1 49 49 18 17 6 97 4 197 1 5 1 52 1 2 @{ 0 2 6 1 @}}
1 32 2 1
@t{=1}
1 26 1
@t{=1 2 22 12 17 6 97 4 197 1 5 4 256 1 1 @{ 3 2 @}}
1 26 2
@t{=1 49 49 18 17 6 97 4 197 1 5 1 52 1}
@t{ 4 @{ 0 2 6 1 2 1 9 19 52 18 17 6 97 4 197 1 @}}
@end example
In this example, text number two is added as a comment to text number
one. The change is reflected in the Misc-Info List of the texts.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item index-out-of-range
The texts @code{text-no} and @code{comment-to} are identical.
@item no-such-text
The text @code{text-no} of @code{comment-to} are undefined.
@item comment-limit
The text @code{comment-to} already has the maximum number of comments.
@end table
@node sub-comment, get-map, add-comment, Protocol Requests
@subsection sub-comment (1) Obsolete (10)
@findex sub-comment
@example
sub-comment [33] (( text-no : Text-No;
comment-to : Text-No; ))
-> ( );
@end example
This call removes the text @code{text-no} from @code{comment-to}'s list
of comments.
@example
1 26 1
@t{=1 2 22 12 17 6 97 4 197 1 5 4 256 1 1 @{ 3 2 @}}
1 26 2
@t{=1 49 49 18 17 6 97 4 197 1 5 1 52 1}
@t{ 4 @{ 0 2 6 1 2 1 9 19 52 18 17 6 97 4 197 1 @}}
1 33 2 1
@t{=1}
1 26 1
@t{=1 2 22 12 17 6 97 4 197 1 5 4 256 1 0 *}
1 26 2
@t{=1 49 49 18 17 6 97 4 197 1 5 1 52 1 2 @{ 0 2 6 1 @}}
@end example
In this example text 2 is a comment to text 1, as shown by the misc-info
lists of the two texts. The @code{sub-comment} is called. The misc-info
lists are changed to reflect the change.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item no-such-text
One of the texts @code{text-no} or @code{comment-to} does not exist.
@item no-comment
The text @code{text-no} is not a comment to @code{comment-too}.
@item permission-denied
Not supervisor of author of @code{text-no} or not sender of the
comment and not enough privileges set and enable to complete the call
anyway.
@end table
@node get-map, get-time, sub-comment, Protocol Requests
@subsection get-map (1) Recommended
@findex get-map
@example
get-map [34] (( conf-no : Conf-No;
first-local-no : Local-Text-No;
no-of-texts : INTEGER; ))
-> ( Text-List );
@end example
This call has been superceded by @ref{local-to-global}.
This call retrieves an array mapping local text numbers to global
numbers. It is most often used to get a list of unread texts in a
conference. Clients will usually use the @code{query-read-texts}
(@pxref{query-read-texts}) or @code{get-membership}
(@pxref{get-membership}) calls to find the last local number a user has
read in a particular conference, then use the @code{get-map} call to
retrieve the global numbers of all unread texts in the conference.
The @code{conf-no} parameter specifies which conference to get the map
of. @code{first-local-no} is the local number of the first text returned
by the call. @code{no-of-texts} is the maximum number of text the client
wants.
The result is a list of global text numbers. The first element of the
list is the global number of local number @code{first-local-no},
specified by the call; the second element is the global number of local
number @code{first-local-no} plus one; and so forth. The list returned
by the server is at most @code{no-of-texts} long, but may be shorter if
the call specifies more texts that there are in the conference.
If @code{first-local-no} is higher than the highest local text number,
the server will return an error.
If @code{first-local-no} is lower than the lowest number that still
exists, the server will set @code{result.first-local-no} in the returned
Text-List to the first text that still exists. The size of the returned
array will be decreased by the same amount as
@code{result.first-local-no} is increased. This may result in an empty
array being returned. (This paragraph applies even when
@code{first-local-no} is 0.)
If no texts at all exists in @code{conf-no} the resulting array will be
empty, and @code{result.first-local-no} will be set to the number the
next text to be created will receive.
@example
1 34 119 10 5
@t{=1 10 5 @{ 0 0 466 478 391 @}}
2 34 119 16 5
@t{=2 16 3 @{ 481 0 491 @}}
3 34 119 19 5
@t{%3 16 0}
4 34 120 1 5
@t{=4 4 2 @{ 480 485 @}}
5 34 120 1 2
@t{=5 4 0 *}
@end example
This example shows five @code{get-map} calls. The first retrieves the
mappings of local numbers 10 to 15; the second call returns local
numbers 16 to 18. As this example shows the maps are not necessarily
sorted in ascending order, since texts may be added after their
creation, and the maps may contain zeroes anywhere. These represent
texts that have been removed for some reason.
Since the first example returned two leading zeroes we can be certain
that at least one text with a local text number lower than 10 still
exists. Otherwise the result would have been truncated in the front as
it is in examples 4 and 5.
The third exchange in the example shows what happens when
@code{first-local-no} is too large.
The forth and fifth examples shows what happens when an attempt to
retrieve a mapping from a conference where the first local text numbers
have been deleted. In the example local text numbers 1, 2 and 3 no longer
exist, and 4 corresponds to 480, and 5 to 485.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-conference
Conference @code{conf-no} does not exist or is secret.
@item zero-conference
@code{conf-no} is zero.
@item access-denied
Conference @code{conf-no} is read protected.
@item no-such-local-text
@code{first-local-no} is higher than the highest local text number that
ever has existed in this conference.
@end table
@node get-time, get-info-old, get-map, Protocol Requests
@subsection get-time (1) Recommended
@findex get-time
@example
get-time [35] ( )
-> ( Time );
@end example
This call simply returns the local time according to the server.
@example
1 35
@t{=1 23 47 19 17 6 97 4 197 1}
@end example
This example demonstrates the call. According to the server the time is
19:47:23, Thursday July 17, 1997. The result also shows that it is the
197th day of the year, and that daylight savings time is in effect.
@unnumberedsubsubsec Error codes
This call always succeeds
@node get-info-old, add-footnote, get-time, Protocol Requests
@subsection get-info-old (1) Obsolete (10)
@findex get-info-old
@example
get-info-old [36] ( )
-> ( Info-Old; );
@end example
This call returns the @code{Info} structure for the server
(@pxref{LysKOM Data Types}. Clients should call this in order to find
out which conferences are used for presentations and such.
This call has been superceded by @ref{get-info}.
This call can be issued without logging in.
@example
1 36
@t{=1 10900 1 2 3 4 1}
@end example
In this example, the server version is 1.9, the conference for
presentation of new conferences is conference 1, the conference for
presentation of new persons is conference 2, the conference for door
messages is conference 3, the LysKOM news conference is conference 4 and
the login message is text number 1.
@unnumberedsubsubsec Error codes
This call always succeeds.
@node add-footnote, sub-footnote, get-info-old, Protocol Requests
@subsection add-footnote (1) Recommended
@findex add-footnote
@example
add-footnote [37] (( text-no : Text-No;
footnote-to: Text-No; ))
-> ( );
@end example
Add a footnote link between the text @code{footnote-to} and the text
@code{text-no} (@code{text-no} becomes a footnote to the text
@code{footnote-to}). This call is used to add footnote links after a text
has been created. Only the author of both texts is allowed to add
the footnote link.
@example
1 26 1
@t{=1 2 22 12 17 6 97 4 197 1 5 4 256 1 0 *}
1 26 2
@t{=1 49 49 18 17 6 97 4 197 1 5 1 52 1 2 @{ 0 2 6 1 @}}
1 37 2 1
@t{=1}
1 26 1
@t{=1 2 22 12 17 6 97 4 197 1 5 4 256 1 1 @{ 5 2 @}}
1 26 2
@t{=1 49 49 18 17 6 97 4 197 1 5 1 52 1}
@t{ 4 @{ 0 2 6 1 4 1 9 19 52 18 17 6 97 4 197 1 @}}
@end example
In this example, text number two is added as a footnote to text number
one. The change is reflected in the Misc-Info List of the texts.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item no-such-text
The text @code{text-no} or @code{footnote-to} does not exist or is
secret.
@item index-out-of-range
Maximum number of texts in database already.
@item not-author
Not author of @code{footnote-to}.@item footnote-limit
Text @code{footnote-to} already has the maximum number of footnotes.
@item already-footnote
Text @code{text-no} is already a footnote to @code{footnote-to}.
@end table
@node sub-footnote, who-is-on-old, add-footnote, Protocol Requests
@subsection sub-footnote (1) Recommended
@findex sub-footnote
@example
sub-footnote [38] (( text-no : Text-No;
footnote-to : Text-No; ))
-> ( );
@end example
This call removes the text @code{text-no} from @code{footnote-to}'s list
of footnotes. Only the author of a footnote may remove it.
@example
1 26 1
@t{=1 2 22 12 17 6 97 4 197 1 5 4 256 1 1 @{ 5 2 @}}
1 26 2
@t{=1 49 49 18 17 6 97 4 197 1 5 1 52 1}
@t{ 4 @{ 0 2 6 1 4 1 9 19 52 18 17 6 97 4 197 1 @}}
1 38 2 1
@t{=1}
1 26 1
@t{=1 2 22 12 17 6 97 4 197 1 5 4 256 1 0 *}
1 26 2
@t{=1 49 49 18 17 6 97 4 197 1 5 1 52 1 2 @{ 0 2 6 1 @}}
@end example
In this example text 2 is a footnote to text 1, as shown by the
misc-info lists of the two texts. The @code{sub-footnote} is called.
The misc-info lists are changed to reflect the change.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item no-such-text
The text @code{text-no} or @code{footnote-to} does not exist or is
secret.
@item not-footnote
The text @code{text-no} is not a footnote to @code{footnote-to}.
@item permission-denied
Not supervisor of the author of @code{text-no} and not enough privileges
set and enabled to complete call anyway.
@end table
@node who-is-on-old, set-unread, sub-footnote, Protocol Requests
@subsection who-is-on-old (1) Obsolete
@findex who-is-on-old
@example
who-is-on-old [39] ( )
-> ( ARRAY Who-Info-Old );
@end example
This call is obsolete. Use @ref{get-static-session-info} and
@ref{who-is-on-dynamic} instead. If the server does not support these
calls, use @ref{who-is-on} instead.
The returned list contains all sessions where a person is logged in and
the invisible flag of the session is unset.
@unnumberedsubsubsec Error codes
This call always succeeds.
@node set-unread, set-motd-of-lyskom, who-is-on-old, Protocol Requests
@subsection set-unread (1) Recommended
@findex set-unread
@example
set-unread [40] (( conf-no : Conf-No;
no-of-unread : INTEGER; ))
-> ( );
@end example
Only read the last @code{no-of-unread} in the conference @code{conf-no}.
This call modified the @code{last-text-read} of current person's
membership for the conference. This call is sometimes used to implement
the ``only read last N texts'' command found in many clients. Due to
possible race conditions, this call is usually better implemented using
the @ref{set-last-read} call which explicitly sets
@code{last-text-read} field of the membership.
@example
1 9 5 6
@t{=1 1 34 21 17 6 97 4 197 1 6 100 0 0 *}
1 40 6 0
@t{=1}
1 9 5 6
@t{=1 1 34 21 17 6 97 4 197 1 6 100 4 0 *}
@end example
This example shows that person 5 last read text 0 in conference 6 (and
since 0 is an illegal local text number, that implies that the person
has not read anything in the conference.) After calling set-unread and
asking to have zero unread texts in conference 6, this is reflected by
the call to query-read-texts.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-conference
The conference @code{conf-no} does not exist or is secret.
@item not-member
Not a member of conference @code{conf-no}.
@end table
@node set-motd-of-lyskom, enable, set-unread, Protocol Requests
@subsection set-motd-of-lyskom (1) Recommended
@findex set-motd-of-lyskom
@example
set-motd-of-lyskom [41] ( text-no : Text-No )
-> ( );
@end example
This call sets the login message of LysKOM. It can only be executed by aprivileged person, with the proper privileges enabled. A somewhat less
convenient way of doing this is to use the @ref{set-info} call.
@example
1 36
@t{=1 10900 1 2 3 4 0}
1 41 435
@t{=1}
1 36
@t{=1 10900 1 2 3 4 435}
@end example
This example shows how the login message of LysKOM is set using the
set-motd-of-lyskom call. The results of the @code{get-info} calls
demonstrate the effect.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item permission-denied
Administrator bit not set or privilege level not enabled.
@item no-such-text
The text @code{text-no} does not exist.
@item mark-limit
The text @code{text-no} already has the maximum number of marks.
@end table
@node enable, sync-kom, set-motd-of-lyskom, Protocol Requests
@subsection enable (1) Recommended
@findex enable
@example
enable [42] ( level : INT8 )
-> ( );
@end example
Sets the security level for the current session to @code{level} (@pxref{Security} for details.) The only levels that make any sense right
now are 0 and 255. This call may be issued by any person, but without
the right privilege bits set, it has no effect.
@example
1 41 1
@t{%1 12 0}
1 42 255
@t{=1}
1 41 1
@t{=1}
@end example
This example shows how @code{enable} makes a privileged call possible,
in this case a call to @ref{set-motd-of-lyskom}.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@end table
@node sync-kom, shutdown-kom, enable, Protocol Requests
@subsection sync-kom (1) Recommended
@findex sync-kom
@example sync-kom [43] ( )
-> ( );
@end example
This call instructs the LysKOM server to make sure the permanent copy of
its database is current. Processing of requests is normally blocked
until this call has completed, but the exact details depend on the
server implementation. This call is privileged in most implementations.
@example
1 42 255
@t{=1}
1 43
@t{:7 0}
@t{:7 0}
@t{=1}
@end example
This example shows how the @ref{enable} call is used to enable all
privileges, then the @code{sync-kom} call is used to save the database.
The server responds with two asynchronous messages signaling that the
database is being saved.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item permission-denied
Administrator bit not set or privileges not enabled.
@end table
@node shutdown-kom, broadcast, sync-kom, Protocol Requests
@subsection shutdown-kom (1) Recommended
@findex shutdown-kom
@example
shutdown-kom [44] ( exit-val : INT8 )
-> ( );
@end example
This call instructs the server to save all data and shut down.
@code{exit-val} is currently not used. This call is privileged.
@example
1 42 255
@t{=1}
1 44 0
@t{=1}
@t{:2 13 5 3}
@end example
This example shows the shutdown of a server. The asynchronous message
sent after the call returns is the result of a session being forced to
log out.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item permission-denied
Administrator bit not set or privileges not enabled.
@end table
@node broadcast, get-membership-old, shutdown-kom, Protocol Requests
@subsection broadcast (1) Obsolete
@findex broadcast
@example
broadcast [45] ( message : HOLLERITH )
-> ( );
@end example
This call can been replaced by @ref{send-message}. It is a privileged
call.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item string-too-long
The string @code{message} is too long.
@item feature-disabled
Messages have been disabled.
@end table
@node get-membership-old, get-created-texts, broadcast, Protocol Requests
@subsection get-membership-old (1) Obsolete (10)
@findex get-membership-old
@example
get-membership-old [46] (( person : Pers-No;
first : INT16;
no-of-confs : INT16;
mask : BITSTRING
(
want-read-texts
); ))
-> ( ARRAY Membership-Old );
@end example
This call retrieves the membership record for a list of conferences for
a single person. @code{person} is the person whose memberships are to be
retrieved. @code{first} is the first position in the membership list to
retrieve, numbered from 0 and up. @code{no-of-confs} is the number of
membership records to retrieve. @code{mask} is a set of flags. Currently
the only flag is @code{want-read-texts}, which instructs the server not
to send the @code{read-texts} array of the memberships.
The server will return a membership list that is shorter than
@code{no-of-confs} if @code{no-of-confs} + @code{first} is larger than
the number of conferences the person is a member of.
@example
1 46 5 0 3 1
@t{=1 2 @{ 49 14 17 13 8 91 5 255 1 5 255 0 0 * }
@t{ 20 14 22 17 6 97 4 197 1 6 100 2 0 * @}}
1 46 5 0 1 1
@t{=1 1 @{ 49 14 17 13 8 91 5 255 1 5 255 0 0 * @}}
1 46 5 1 4 1
@t{=1 1 @{ 20 14 22 17 6 97 4 197 1 6 100 2 0 * @}}
@end example
In this example we retrieve the memberships of person 5. The first call
asks for three memberships, starting with number 0. Since this person is
only a member of two conferences, the list returned only contains two
memberships. The next two calls retrieve a single membership each. The
first by asking for only one, and the second by asking for four
memberships, starting with number 1.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-person
The person @code{person} does not exist.
@item undefined-conference
The conference @code{person} does not exist or is secret.
@item index-out-of-range
@code{first} is higher than the index of the first conference in the
person's membership list.
@end table
@node get-created-texts, get-members-old, get-membership-old, Protocol Requests
@subsection get-created-texts (1) Obsolete (10)
@findex get-created-texts
@example
get-created-texts [47] (( person : Pers-No;
first : Local-Text-No;
no-of-texts : INTEGER; ))
( Text-List );
@end example
This call is obsolete; @xref{map-created-texts} should be used instead.
This call returns a list of the texts written by a person.
@code{person} is the person whose created texts are to be
retrieved. @code{first} is the first text to
retrieve. @code{no-of-texts} is the number of texts to retrieve.
This call is essentially the same as @ref{get-map}, but instead of
returning the texts sent to a single conference, it returns the texts
written by a single person to any conference. The number of texts
written by any one person is contained in the Person record for that
person.
If @code{first} is lower than the first text written by @code{person}
that still exists, it will be automatically increased to the first still
existing text written by @code{person}. The @code{get-created-texts}
will still attempt to return information about @code{no-of-texts} texts.
(In this regard @code{get-map} and @code{get-created-texts} differ,
since @code{get-map} will never ever return information about a later
text than specified in the arguments to the call.@footnote{This
difference was not intentional, but it is now too late to change the
semantics of either @code{get-map} or @code{get-created-texts}.
Besides, they are both obsolete calls.})
@example
1 47 5 0 100
@t{=1 1 8 @{ 1 2 3 4 5 6 7 8 @}}
2 47 5 4 2
@t{=2 4 2 @{ 4 5 @}}
3 47 10 8 8
@t{=3 12 8 @{ 309 312 324 327 329 339 0 387 @}}
@end example
In this example we have retrieved all texts written by person five. The
first call asked for 100 texts, but only 8 were returned, which implies
that person number 5 only created a total of 8 texts. We can also see
that person 5 wrote all the first 8 texts in the conference system. The
second call shows how a part of the map can be retrieved.
The third call asks for eight texts written by person 10, starting with
the eighth number. Since the first eleven texts written by that person
no longer exists the server instead returns information about eight
texts staring from the twelfth text person 10 created. One of the eight
texts has been deleted.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-person
The person @code{person} does not exist or is secret.
@item undefined-conference
The conference @code{person} does not exist or is secret.
@item no-such-local-text
@code{first} is higher than the local text number of the last created
text.
@end table
@node get-members-old, get-person-stat, get-created-texts, Protocol Requests
@subsection get-members-old (1) Obsolete (10)
@findex get-members-old
@example
get-members-old [48] (( conf : Conf-No;
first : INT16;
no-of-members : INT16; ))
-> ( ARRAY Pers-No );
@end example
This call returns a list of members of the conference @code{conf-no}.
@code{first} is the first index in the membership to return, numbered
from zero and up. @code{no-of-members} is the maximum number of members
to return.
@example
1 48 1 0 100
@t{=1 4 @{ 7 8 9 10 @}}
1 48 6 0 100
@t{=1 4 @{ 5 7 9 10 @}}
1 48 6 2 2
@t{=1 2 @{ 9 10 @}}
@end example
In this example the client first requests the first 100 members in
conference 1. The second request is for the first 100 members of
conference 6. The last request is for members 2 and 3 in conference 6.
As can be seen from the examples, the returned list is truncated if
there are fewer members than requested.
@unnumberedsubsubsec Error codes
@table @code
@item undefined-conference
The conference @code{conf} does not exist or is secret.
@item index-out-of-range
@code{first} is higher than the number of members in @code{conf}.
@end table
@node get-person-stat, get-conf-stat-old, get-members-old, Protocol Requests
@subsection get-person-stat (1) Recommended
@findex get-person-stat
@example
get-person-stat [49] ( pers-no : Pers-No; )
-> ( Person );
@end example
This call returns the person @code{pers-no}. This call does not return
all the information a client usually needs since the name is not
included in the Person data structure. Use @ref{get-conf-stat} on the
same number to get additional information about the person.
@example
1 49 8
@t{=1 44Hbyers@@lage.lysator.liu.se 0000010000000000 00000000}
@t{ 44 21 19 18 6 97 5 198 1 0 2 3 0 0 0 0 0 0 1 0 0 2}
1 50 8
@t{=1 11HPaul Dekker 1001 8 6 19 18 6 97 5 198 1}
@t{ 8 6 19 18 6 97 5 198 1 8 0 8 0 0 0 77 1 1 0}
@end example
This simple example shows how person number 8 is retrieved from the
server. The second call shows the @code{get-conf-stat-old} call on the same
ID number.
@unnumberedsubsubsec Error codes
@table @code
@item undefined_person
The person @code{pers-no} does not exist.
@item undefined_conference
The conference @code{pers-no} does not exist or is secret.
@end table
@node get-conf-stat-old, who-is-on, get-person-stat, Protocol Requests
@subsection get-conf-stat-old (1) Obsolete (10)
@findex get-conf-stat-old
@example
get-conf-stat-old [50] ( conf-no : Conf-No )
-> ( Conference-Old );
@end example
This call retrieves the conference data structure for conference number
@code{conf-no}.
Important note: This call does not return the extra flag bits that were
introduced in protocol version 8. To get this information, use the
@code{get-uconf-stat} call instead. However, clients should be able to
handle @code{Conference} structures with an arbitrary number of flag
bits since we may decide to change the behavior of this call in the
future.
@example
1 50 1
@ifinfo
@t{=1 27HPresentation (av nya) möten 0000 48 11 17 13 8 91 5 255}
@end ifinfo
@iftex
@t{=1 27HPresentation (av nya) m@"oten 0000 48 11 17 13 8 91 5 255}
@end iftex
@t{ 1 18 34 21 17 6 97 4 197 1 0 0 0 0 0 0 77 0 1 1}
1 50 8
@t{=1 11HPaul Dekker 1001 8 6 19 18 6 97 5 198 1}
@t{ 8 6 19 18 6 97 5 198 1 8 0 8 0 0 0 77 1 1 0}
@end example
This simple example retrieves conferences 1 and 8 from the server.
Conference 1 is a regular conference, and conference 8 is a letterbox.
@unnumberedsubsubsec Error codes
@table @code
@item undefined-conference
The conference @code{conf-no} does not exist or is secret.@end table
@node who-is-on, get-unread-confs, get-conf-stat-old, Protocol Requests
@subsection who-is-on (1) Obsolete (9)
@findex who-is-on
@example
who-is-on [51] ( )
-> ( ARRAY Who-Info );
@end example
This call is obsolete. Please use @ref{who-is-on-dynamic} and
@code{get-static-session-info} instead. Nonetheless, servers should
support this call since many clients still use it.
This call should simply return a list of visible sessions (sessions
where a person is logged in and the invisible flag is unset). The data
structure is described elsewhere (@pxref{LysKOM Data Types}.)
@unnumberedsubsubsec Error codes
This call always succeeds.
@node get-unread-confs, send-message, who-is-on, Protocol Requests
@subsection get-unread-confs (1) Recommended
@findex get-unread-confs
@example
get-unread-confs [52] ( pers-no : Pers-No )
-> ( ARRAY Conf-No );
@end example
This call returns a list of conferences in which the person
@code{pers-no} may have unread texts. This call will return a result for
any valid @code{pers-no}. To retrieve information about secret persons,
or to get information about unread texts in secret conference, the
session must log on as a person with access to that information.
The result is guaranteed to include all conferences where @code{pers-no}
has unread texts. It may also return some extra conferences.
@example
1 52 7
@t{=1 2 @{ 1 6 @}}
1 52 1
@t{%1 10 0}
1 52 1000
@t{%1 10 0}
@end example
This example shows how a session first retrieves the list of conferences
in which person 7 has unread texts. The next request is for the unread
conferences of person 1, but that happens to be a conference. The last
request is for the unread conferences of person 1000, but that person
didn't exist in the test database.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-person
Person @code{pers-no} does not exist or is secret.
@end table
@node send-message, get-session-info, get-unread-confs, Protocol Requests
@subsection send-message (1) Recommended
@findex send-message
@example
send-message [53] (( recipient : Conf-No;
message : HOLLERITH; )
-> ( );
@end example
This call sends the message @code{message} to all members of
@code{recipient} that are currently logged in.
@example
1 53 4 14HThis is a test
@t{=1}
1 53 1 14HThis is a test
@t{:3 12 1 8 14HThis is a test}
@t{=1}
1 53 0 14HThis is a test
@t{:3 12 0 8 14HThis is a test}
@t{=1}
1 53 5 14HThis is a test
@t{%1 16 0}
1 53 3 14HThis is a test
@t{%1 42 0}
@end example
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item string-too-long
The string @code{message} is too long.
@item undefined-conference
Conference @code{recipient} does not exist or is secret.
@item feature-disabled
The message feature has been disabled in the server.
@item message-not-sent
The message was not sent for some other reason. Perhaps the recipient is
not accepting messages.
@end table
@node get-session-info, disconnect, send-message, Protocol Requests
@subsection get-session-info (1) Obsolete
@findex get-session-info
@example
get-session-info [54] ( session-no : Session-No )
-> ( Session-Info );
@end example
This call is obsolete. It has been replaced by
@code{get-session-info-ident}, which in turn is also obsolete. See
@pxref{get-session-info-ident} for more information.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-sessionThe session @code{session-no} does not exist.
@end table
@node disconnect, who-am-i, get-session-info, Protocol Requests
@subsection disconnect (1) Recommended
@findex disconnect
@example
disconnect [55] ( session-no : Session-No )
-> ( );
@end example
This call disconnects the session @code{session-no} from the LysKOM
server. A session can always disconnect itself, even without logging in.
If the session is logged in as user @i{foo} it can also disconnect any
session logged in as a person for which @i{foo} is the supervisor.
@example
1 56
@t{=1 7}
1 55 7
@t{=1}
@t{:2 13 8 7}
@t{Connection closed by foreign host.}
@end example
In this example the client asks for its own session number, then
disconnects itself. The asynchronous message sent just before the
session is disconnected is the logout message for the user that was
logged on in the session. The ``Connection closed by foreign host.'' is
not part of the server output. This message was generated by telnet.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call if @code{session-no} is not the
session issuing the call.
@item permission-denied
Attempt to disconnect another session and not supervisor of person
logged in and not enough privileges set and enabled to complete the call
anyway.
@item undefined-session
The session @code{session-no} does not exist.
@end table
@node who-am-i, set-user-area, disconnect, Protocol Requests
@subsection who-am-i (1) Recommended
@findex who-am-i
@example
who-am-i [56] ( )
-> ( Session-No );
@end example
This call simply returns the session number of the session issuing the
call.
@example
1 56
@t{=1 7}
@end example
In this example the session number of the session issuing the call is
seven.
@unnumberedsubsubsec Error codes
This call always succeeds.
@node set-user-area, get-last-text, who-am-i, Protocol Requests
@subsection set-user-area (2) Recommended
@findex set-user-area
@example
set-user-area [57] (( pers-no : Pers-No;
user-area : Text-No; ))
-> ( );
@end example
This call sets the user-area field for the person @code{pers-no} in the
database to the text @code{user-area}. The user area is used to store
client data for a particular person. See @pxref{The User Area} for more
details.
@example
1 49 7
@t{=1 43Hdavby@@lage.lysator.liu.se 0000010000000000 00000000}
@t{ 6 58 21 19 6 97 6 199 1 0 458 7 3 12 7 12 0 0 3 0 0 4}
1 57 7 11
@t{=1}
1 49 7
@t{=1 43Hdavby@@lage.lysator.liu.se 0000010000000000 00000000}
@t{ 6 58 21 19 6 97 6 199 1 11 458 7 71 2592 7 13 0 0 3 1 0 4}
@end example
In this example the user area of person 7 is set to text number 11. The
original user area was text numbers zero, which means that the person
had no user area.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-person
The person @code{pers-no} does not exist or is secret.
@item permission-denied
Not enough access to person @code{pers-no} to complete the call.
@end table
@node get-last-text, create-anonymous-text-old, set-user-area, Protocol Requests
@subsection get-last-text (3) Recommended
@findex get-last-text
@example
get-last-text [58] ( before : Time )
-> ( Text-No );
@end example
This call returns the number of the last text created before
@code{before}. There is no guarantee that the text is readable by the
person making the request, or that the text even exists.
@example
1 58 49 6 22 19 6 97 6 199 1
@t{=1 11}
1 58 49 6 22 18 6 97 6 199 1
@t{=1 8}
1 58 49 6 22 1 6 97 6 199 1 @t{=1 0}
@end example
In this example the text created most recently before 22:06 on July 19,
1997 was text number 11; the text created most recently before 22:06 on
July 18 was text number 8; and the text created most recently before
22:06 on July 1st was text number 0, which means that there is no text
that old in the database.
@unnumberedsubsubsec Error codes
This call never fails.
@node create-anonymous-text-old, find-next-text-no, get-last-text, Protocol Requests
@subsection create-anonymous-text-old (3) Obsolete (10)
@findex create-anonymous-text-old
@example
create-anonymous-text-old [59] (( text : HOLLERITH;
misc-info : ARRAY Misc-Info; ))
-> ( Text-No );
@end example
Similar to @pxref{create-text-old}, but the text is created the author
field set to zero. Not even the server has a record of who created the
text.
the original intended use for this call was for importing texts from
other sources, such as WWW, FTP or Gopher, but some clients include
explicit support for sending anonymous texts to a server.
It is only possible to send anonymous texts to a conference with the
right flag bit set.
The only Misc-Info items valid for this call are recpt, cc-recpt,
bcc-recpt (protocol version 10) comm-to and footn-to.
@example
1 28 20HExample\nMessage body 3 @{ 0 5 1 112 2 33467 @}
@t{:16 0 33502 13 16 15 16 6 97 3 196 1 0 1 20 0}
@t{ 5 @{ 0 5 6 148 1 112 6 3438 2 33467 @} }
@t{=1 33502}
@end example
In this example, person 119 creates a text containing a subject and a
one-line body. The recipient of the text is conference five, conference
112 is a CC recipient and the text is a comment to text 33467. The
server reply indicates that the new text has been given number 33502.
Finally there is an asynchronous message sent to all members of
recipient conferences. Note how the message was sent before the reply to
the client. The misc-info list in this message has two additional
fields, the local numbers of the text in each of its recipient
conferences.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item string-too-long
The string @code{text} is longer than the maximum length of a message.
@item temporary-failure
The text could not be created at the moment.
@item no-such-text
Attempt to comment or footnote a non-existent or secret text.
@item not-author
Attempt to footnote a text authored by someone else.@item footnote-limit
Attempt to footnote a text with the maximum number of footnotes already
set.
@item comment-limit
Attempt to comment a text with the maximum number of comments already
set.
@item access-denied
Attempt to send a text to a conference failed because no access to the
conference or any superconference that will accept a text.
@item anonymous-rejected
Attempt to send an anonymous text to a conference that does not accept
anonymous texts.
@item illegal-misc
Invalid misc-info list. A recipient is listed more than once or there is
an unknown misc item in the misc-info list.
@end table
@node find-next-text-no, find-previous-text-no, create-anonymous-text-old, Protocol Requests
@subsection find-next-text-no (3) Recommended
@findex find-next-text-no
@example
find-next-text-no [60] ( start : Text-No )
-> ( Text-No );
@end example
This call returns the next readable text in the database created after
text @code{start}. @code{start} does not have to be a valid or readable
text number, as shown in the examples.
@example
1 60 0
@t{=1 2}
1 60 2
@t{=1 4}
@end example
This example shows how to retrieve the first readable text in the LysKOM
database by calling @code{find-next-text} with @code{start} set to zero.
In the example, the first text is number 2. The second example gets the
text following number 2, which happens to be text number 4.
@unnumberedsubsubsec Error codes
@table @code
@item no-such-text
There is no text following text @code{start}.
@end table
@node find-previous-text-no, login, find-next-text-no, Protocol Requests
@subsection find-previous-text-no (3) Recommended
@findex find-previous-text-no
@example
find-previous-text-no [61] ( start : Text-No )
-> ( Text-No );
@end example
This call returns the first readable text in the database created most
recently before @code{start}. @code{start} does not have to be a valid
or readable text number, as shown in the examples.
@example
1 61 134217727
@t{=1 11}
1 61 4 @t{=1 2}
@end example
This example shows that the last readable text in the database is number
11 (unless by some odd coincidence all text from 11 to text number
134217727 have been deleted.) It also shows that the most recent text
before number 4 is text number 2.
@unnumberedsubsubsec Error codes
@table @code
@item no-such-text
There is no text preceding text @code{start}.
@end table
@node login, who-is-on-ident, find-previous-text-no, Protocol Requests
@subsection login (4) Recommended
@findex login
@example
login [62] (( person : Pers-No;
passwd : HOLLERITH;
visibility : BITSTRING
(
is-invisible;
); )
-> ( );
@end example
This call is used to log in. The session is logged in as person number
@code{pers-no} is @code{passwd} is the correct password for that person.
If @code{is-invisible} is true, the session is invisible. It will not be
returned by @code{who-is-on} and @code{who-is-on-ident} and the
invisible flag of the dynamic session info (@pxref{LysKOM Data Types}
will have the invisible flag set.
Invisible sessions are primarily used by software agents that do not act
on the behalf of real users.
@example
1 62 7 6Hgazonk 1
@t{=1}
1 62 7 6Hgazonk 0
@t{:2 9 7 1}
1 62 7 6Hgazonk 0
@t{:2 13 7 1}
@t{:2 9 7 1}
@t{=1}
@end example
This example first shows a session log in as person seven with the
invisible flag set. Because of this the asynchronous login message is
not sent. The second call logs in as person seven again. This time a
login message is sent, but not a logout message since the login was
invisible. The third example shows a third login as person 7, but this
time both the logout and login messages are sent.
@unnumberedsubsubsec Error codes
@table @code
@item undefined-person
The person @code{person} does not exist.
@item login-disallowed
Logins have been disabled and person @code{person} does not have enough
privileges to override.
@item invalid-password
The password @code{passwd} is not the password of @code{person} and the
currently logged in person is not the supervisor of @code{person} anddoes not have enough privileges set and enabled to log in anyway.
@item conference-zero
Attempt to log in as person number 0.
@end table
@node who-is-on-ident, get-session-info-ident, login, Protocol Requests
@subsection who-is-on-ident (4) Obsolete (9)
@findex who-is-on-ident
@example
who-is-on-ident [63] ( )
( ARRAY Who-Info-Ident );
@end example
This call is obsolete. It has been replaced by @pxref{who-is-on-dynamic}
and @pxref{get-static-session-info}. It used to return a list of all
active and visible sessions.
@unnumberedsubsubsec Error codes
This call always succeeds.
@node get-session-info-ident, re-lookup-person, who-is-on-ident, Protocol Requests
@subsection get-session-info-ident (4) Obsolete (9)
@findex get-session-info-ident
@example
get-session-info-ident [64] ( session-no : Session-No )
-> ( Session-Info-Ident );
@end example
This call is obsolete. Use @pxref{who-is-on-dynamic} and
@code{get-static-session-info} instead. It used to return information
about a single session.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-session
The session @code{session-no} does not exist.
@end table
@node re-lookup-person, re-lookup-conf, get-session-info-ident, Protocol Requests
@subsection re-lookup-person (5) Obsolete
@findex re-lookup-person
@example
re-lookup-person [65] ( regexp : HOLLERITH )
( ARRAY Pers-No );
@end example
This call is obsolete. It has been replaced by @pxref{re-z-lookup}. It
used to return a list of persons matching the regular expression
@code{regexp}. The regexp syntax used was that of the @code{ed(1)} Unix
utility.
@unnumberedsubsubsec Error codes
@table @code
@item regexp-error
Error compiling the regexp @code{regexp}. Perhaps the pattern is
not a correct regexp.@end table
@node re-lookup-conf, lookup-person, re-lookup-person, Protocol Requests
@subsection re-lookup-conf (5) Obsolete
@findex re-lookup-conf
@example
re-lookup-conf [66] ( regexp : HOLLERITH )
-> ( ARRAY Conf-No );
@end example
This call is obsolete. It has been replaced by @pxref{re-z-lookup}. It
used to return a list of conferences matching the regular expression
@code{regexp}. The regexp syntax used was that of the @code{ed(1)} Unix
utility.
@unnumberedsubsubsec Error codes
@table @code
@item regexp-error
Error compiling the regexp @code{regexp}. Perhaps the pattern is
not a correct regexp.
@end table
@node lookup-person, lookup-conf, re-lookup-conf, Protocol Requests
@subsection lookup-person (6) Obsolete
@findex lookup-person
@example
lookup-person [67] ( name : HOLLERITH )
-> ( ARRAY Pers-No );
@end example
This call is obsolete. It has been replaced by @pxref{lookup-z-name}.
This call used to return a list of persons with names matching the
contracted name in @code{name}. See @pxref{Name Expansion} for a
description of the matching process.
@unnumberedsubsubsec Error codes
This call always succeeds.
@node lookup-conf, set-client-version, lookup-person, Protocol Requests
@subsection lookup-conf (6) Obsolete
@findex lookup-conf
@example
lookup-conf [68] ( name : HOLLERITH )
-> ( ARRAY Conf-No );
@end example
This call is obsolete. It has been replaced by @pxref{lookup-z-name}.
This call used to return a list of conferences with names matching the
contracted name in @code{name}. See @pxref{Name Expansion} for a
description of the matching process.
@unnumberedsubsubsec Error codes
This call always succeeds.
@node set-client-version, get-client-name, lookup-conf, Protocol Requests@section set-client-version (6) Recommended
@findex set-client-version
@example
set-client-version [69] (( client-name : HOLLERITH;
client-version : HOLLERITH; ))
-> ( );
@end example
This call is used to tell the server which client and which version of
that client is being used. The name of the client is passed in
@code{client-name} and the version in @code{client-version}. The
information sent in this call is made available to other sessions
through the @pxref{get-client-name} and @pxref{get-client-version}
calls.
@example
1 56
@t{=1 7}
2 69 11Helisp-client 4H0.45
@t{=2}
3 70 7
@t{=3 11Helisp-client}
4 71 7
@t{=4 4H0.45}
@end example
In this example the @pxref{who-am-i} call is used to find the ID of the
current session. Next, set-client-version is used to set the name of the
client to ``elisp-client'' and the version to ``0.45''. The third call
is to @pxref{get-client-name}, which returns the string just sent to the
server. Finally @pxref{get-client-version} is used to retrieve the
client version of session number 7, which is, as expected, the string
``0.45''.
@unnumberedsubsubsec Error codes
@table @code
@item string-too-long
The string @code{client-name} or @code{client-version} is too long.
@end table
@node get-client-name, get-client-version, set-client-version, Protocol Requests
@subsection get-client-name (6) Recommended
@findex get-client-name
@example
get-client-name [70] ( session : Session-No )
-> ( HOLLERITH );
@end example
This call returns the name of the client that owns session number
@code{session}. This client name string returned is the one set by the
client using @pxref{set-client-version}. If @code{set-client-version}
has not been issued in session number @code{session}, the empty string
is returned.
See @pxref{set-client-version} for an example of this call.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-session
The session @code{session} does not exist.
@end table
@node get-client-version, mark-text, get-client-name, Protocol Requests@subsection get-client-version (6) Recommended
@findex get-client-version
@example
get-client-name [71] ( session : Session-No )
-> ( HOLLERITH );
@end example
This call returns the version of the client that owns session number
@code{session}. This client version string returned is the one set by
the client using @pxref{set-client-version}. If
@code{set-client-version} has not been issued in session number
@code{session}, the empty string is returned.
See @pxref{set-client-version} for an example of this call.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-session
The session @code{session} does not exist.
@end table
@node mark-text, unmark-text, get-client-version, Protocol Requests
@subsection mark-text (4) Recommended
@findex mark-text
@example
mark-text [72] (( text : Text-No;
mark-type : INT8; ))
-> ( );
@end example
This call associates the mark @code{mark-type} with the text
@code{text}. The list of marks set by a person can be retrieved using
the @pxref{get-marks} call.
Currently, servers do not associate any particular meaning to the
different types of marks, but that may change in the future. Currently,
servers should not delete texts that have marks, except by user request.
@example
1 23
@t{=1 *}
2 72 110 230
@t{=2}
3 23
@t{=3 1 @{ 110 230 @}}
@end example
This example shows how a person with no marks set sets mark 230 on text
number 110. The calls to @pxref{get-marks} show the effect of the call.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item no-such-text
The text @code{text} does not exists or is secret.
@item permission-denied
No read access to text @code{text}.
@item undefined-person
The person currently logged in does not exist (can't happen error.)
@item mark-limit
Already the maximum number of marks on text @code{text}.@end table
@node unmark-text, re-z-lookup, mark-text, Protocol Requests
@subsection unmark-text (4) Recommended
@findex unmark-text
@example
unmark-text [73] ( text-no : Text-No )
-> ( );
@end example
This call removes any marks the logged-in person has set on the text
@code{text-no}.
@example
1 23
@t{=1 1 @{ 110 230 @}}
2 73 110
@t{=2}
3 23
@t{=3 *}
@end example
This example shows how a user with a mark set on text number 110 removes
it using the @code{unmark-text} call.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-person
The person currently logged in does not exist (can't happen error.)
@item not-marked
The text @code{text-no} was not marked.
@end table
@node re-z-lookup, get-version-info, unmark-text, Protocol Requests
@subsection re-z-lookup (7) Recommended
@findex re-z-lookup
@example
re-z-lookup [74] (( regexp : HOLLERITH;
want-persons : BOOL;
want-confs : BOOL; ))
-> ( ARRAY Conf-Z-Info );
@end example
This call returns a list of those conferences and/or persons matching
the regular expression @code{regexp}. If @code{want-confs} is true, then
the result will include non-letterbox conferences. If
@code{want-persons} is true, then the result will include letterbox
conferences.
See also @pxref{lookup-z-name} for an alternative way to look up names.
Refer to @pxref{Name Expansion} for more details on how name lookup
works.
@example
1 74 2H.* 1 1
@t{=1 4 @{ 15HTest Conference 0000 10 11HDavid Byers 1001 6}
@t{ 21HTrains (-) Discussion 0000 11 4HJohn 1001 9 @}}
2 74 2H.* 0 1
@t{=1 2 @{ 15HTest Conference 0000 10} @t{ 21HTrains (-) Discussion 0000 11@}}
3 74 4HT.*C 1 1
@t{=3 2 @{ 15HTest Conference 0000 10}
@t{ 21HTrains (-) Discussion 0000 11@}}
@end example
This example shows three calls to @code{re-z-lookup}. The first call
returns all conferences and persons in the entire database, in this case
two conferences and two persons. The second example uses the same
regular expression, but in this case, the call specifies that the
result is only to contain conferences, so the two persons are not
returned. The third example simply returns all names matching the
pattern ``T.*C''.
@unnumberedsubsubsec Error codes
@table @code
@item regexp-error
Error compiling the regexp @code{regexp}. Perhaps the pattern is
not a correct regexp.
@end table
@node get-version-info, lookup-z-name, re-z-lookup, Protocol Requests
@subsection get-version-info (7) Recommended
@findex get-version-info
@example
get-version-info [75] ( )
-> ( Version-Info );
@end example
This call returns information about the server version. The data
returned by this call are primarily useful for presenting to the user. A
client should not use this call to determine what the server's
capabilities are.
@example
1 75
@t{=1 9 7Hlyskomd 5H1.9.0}
@end example
This example lets us know that the server is lyskomd, version 1.9.0,
which at the time of writing this is the only really usable server.
@unnumberedsubsubsec Error codes
This call always succeeds.
@node lookup-z-name, set-last-read, get-version-info, Protocol Requests
@subsection lookup-z-name (7) Recommended
@findex lookup-z-name
@example
lookup-z-name [76] (( name : HOLLERITH;
want-confs : BOOL;
want-pers : BOOL; ))
-> ( ARRAY Conf-Z-Info );
@end example
This call looks up the name @code{name} in the server, and returns a
list of all matching conferences and/or persons. If @code{want-confs}
is true, then the result will include conferences that are not
letterboxes. If @code{want-pers} is true, then the result will include
conferences that are letterboxes.
See also @pxref{re-z-lookup} for an alternative way to look up names.
Refer to @pxref{Name Expansion} for details on the matching process.
@example
1 74 0H 1 1
@t{=1 4 @{ 15HTest Conference 0000 10 11HDavid Byers 1001 6}
@t{ 21HTrains (-) Discussion 0000 11 4HJohn 1001 9 @}}
2 74 0H 0 1
@t{=1 2 @{ 15HTest Conference 0000 10}
@t{ 21HTrains (-) Discussion 0000 11@}}
3 74 3HT C 1 1
@t{=3 2 @{ 15HTest Conference 0000 10}
@t{ 21HTrains (-) Discussion 0000 11@}}
@end example
This example shows three calls to @code{lookup-z-name}. The first call
retrieves all conferences and persons in the server. The second request
looks up the same name as the first, but this time the result is
restricted to conferences. The final request requests all conferences
and persons matching the pattern ``T C''.
@unnumberedsubsubsec Error codes
This call always succeeds.
@node set-last-read, get-uconf-stat, lookup-z-name, Protocol Requests
@subsection set-last-read (8) Recommended
@findex set-last-read
@example
set-last-read [77] (( conference : Conf-No;
last-read : Text-No; ))
-> ( );
@end example
This call tells the server that the last local text number the person
issuing the call has read in conference @code{conference} is
@code{last-read}. This call is typically used when a user wants to have
a specific number of unread texts in a particular conference.
@example
1 9 7 6
@t{=1 2 4 22 18 6 97 5 198 1 6 100 6 0 *}
2 77 6 3
@t{=2}
3 9 7 6
@t{=3 2 4 22 18 6 97 5 198 1 6 100 3 0 *}
@end example
This example shows how person 7 originally had read everything up to and
including local text number 6 in conference 6. After the call to
@code{set-last=read}, the @pxref{query-read-texts} call reports that
person 7 has read everything up to and including local text number 3.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-conference
The conference @code{conference} does not exist or is secret.
@item not-member
Not a member of conference @code{conference}.
@end table
@node get-uconf-stat, set-info, set-last-read, Protocol Requests
@subsection get-uconf-stat (8) Recommended
@findex get-uconf-stat
@example
get-uconf-stat [78] ( conference : Conf-No )
-> ( UConference );
@end example
This call returns some information about conference @code{conference}.
The information it returns is sufficient for most uses of conference
information, and this call should be used instead of
@pxref{get-conf-stat} wherever possible. It uses less bandwidth and the
lyskomd server always keeps all @code{UConferences} in memory, so this
call is significantly faster than @pxref{get-conf-stat}.
This is also currently the only way to get all the flag bits of the
conference.
@example
1 50 6
@t{=1 8HTestconf 0000 1 34 21 17 6 97 4 197 1}
@t{ 37 3 22 18 6 97 5 198 1 5 4 5 0 5 0 77 4 1 6}
2 78 6
@t{=2 8HTestconf 00001000 6 77}
3 50 7
@t{=3 11HDavid Byers 1111 13 4 19 18 6 97 5 198 1}
@t{ 13 4 19 18 6 97 5 198 1 7 0 7 0 0 0 77 1 1 0}
4 78 7
@t{=4 11HDavid Byers 11111000 0 77}
@end example
This example shows the difference between @pxref{get-conf-stat-old} and
@code{get-uconf-stat}. In the first two examples conference 6 is
retrieved, and in the second two, conference 7, which happens to be a
person, is retrieved. Note the difference in length of the flag field.
@unnumberedsubsubsec Error codes
@table @code
@item undefined-conference
The conference @code{conference} does not exist or is secret.
@item zero-conference
@code{conference} is zero.
@end table
@node set-info, accept-async, get-uconf-stat, Protocol Requests
@subsection set-info (9) Recommended
@findex set-info
@example
set-info [79] ( info : Info-Old ) -> ( )
@end example
This call sets the server information retrieved by @ref{get-info}. The
version number in the info structure is ignored (but must be present);
all other fields are stored permanently in the LysKOM database. This is
a privileged call.
@i{Example:}
@example
1 79 10901 1 2 3 4 1080
@t{=1}
@end example
This example sets the conference presentation conference to one, the
user presentation conference to two, the motd conference to three and
the news conference to four. It also sets the login message to text
1080. It also attempts to set the version number to 1.9.1, but that
number is silently ignored by the server.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item permission-denied
Administrator bit not set or privileges not enabled.
@item undefined-conference
One of the conferences in @code{info} does not exist.
@item no-such-text
The MOTD text in @code{info} does not exist.
@item mark-limit
The MOTD text in @code{info} already has the maximum number of marks.
@end table
@node accept-async, query-async, set-info, Protocol Requests
@subsection accept-async (9) Recommended
@findex accept-async
@example
accept-async [80] ( request-list : ARRAY INT32 ) -> ( )
@end example
This call advises the server that the client wants to receive the
asynchronous messages listed in @code{request-list}. The server must
send these messages to the client when applicable, but may also send
other types of messages if it so desires. The list of currently
requested asynchronous messages may be retrieved using the
@ref{query-async} call.
Don't forget that message type 12 is personal, group and global
text messages. Most users will not want these turned off.
@i{Example:}
@example
1 80 2 @{ 7 9 @}
@t{=1}
@end example
This example tells the server that the client wants to receive
asynchronous messages when the database is being synched (message 7) and
when someone logs in (message 9).
@unnumberedsubsubsec Error codes
If the client requests a message that the server does not send, the
server will reply with an error message saying which message number it
does not support. The call will succeed anyway. This mechanism is useful
for clients that want new versions of some messages, but need to be
compatible with older servers.
@table @code
@item unknown-async
At least one of the numbers in @code{request-list} is not the number of
an async message the server knows about. The error-status indicates the
first offending number.
Please note that a bug in lyskomd 1.9.0 prevented the server from
sending this error message (frankly, we simply forgot about it.)
@end table
@node query-async, user-active , accept-async, Protocol Requests
@subsection query-async (9) Recommended
@findex query-async
@example
query-async [81] ( ) -> ( ARRAY INT32 )
@end example
This call queries the server for which asynchronous messages the client
is receiving. Note that the client may not be able to turn off all
messages returned in this list since the server may consider some
messages to be mandatory. Also note that the client may still receive
messages that are not listed in the result of this call. Even though
those messages are turned off, the server may decide to send them under
certain circumstances.
@i{Example:}
@example
1 81
@t{=1 7 @{ 0 5 7 9 11 12 13 @}}
@end example
In this example the client is receiving seven types of asynchronous
messages: messages about new articles, changed names, database synching,
new logins, rejected connections, personal messages and logouts. This
particular set was the default for new connections to lyskomd 1.9
servers. @xref{Asynchronous Messages}, for the currently recommended
list of asynchronous messages that servers should preselect.
@unnumberedsubsubsec Error codes
This call always succeeds.
@node user-active, who-is-on-dynamic, query-async, Protocol Requests
@subsection user-active (9) Recommended
@findex user-active
@example
user-active [82] ( )
-> ( );
@end example
This call simply notifies the server that the session is active. The
server uses the time of the last user-active call to calculate how long
a session has been idle.
@unnumberedsubsubsec Error codes
This call always succeeds.
@node who-is-on-dynamic, get-static-session-info, user-active, Protocol Requests
@subsection who-is-on-dynamic (9) Recommended
@findex who-is-on-dynamic
@example
who-is-on-dynamic [83] (( want-visible : BOOL;
want-invisible : BOOL;
active-last : INT32; ))
-> ( ARRAY Dynamic-Session-Info );
@end example
This call returns a list of information about sessions. If
@code{want-visible} is true then information about visible sessions is
returned. If @code{want-invisible} is true then information about
invisible sessions is returned. If @code{active-last} is zero then the
result is a list of all sessions. If @code{active-last} is
nonzero then the result is a list of all sessions that have issued an
@code{user-active} call within the last @code{active-last} seconds or
that have never issued an @code{user-active} call.
Sessions where no-one is logged in are considered invisible, and the
@code{invisible} flag is always set in the corresponding
@code{Dynamic-Session-Info} that is returned.
@unnumberedsubsubsec Error codes
This call always succeeds.
@node get-static-session-info, get-collate-table, who-is-on-dynamic, Protocol Requests
@subsection get-static-session-info (9) Recommended
@findex get-static-session-info
@example
get-static-session-info [84] ( session-no : Session-No )
-> ( Static-Session-Info );
@end example
This call returns information about session number @code{session-no}.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-session
The session @code{session-no} does not exist.
@end table
@node get-collate-table, create-text, get-static-session-info, Protocol Requests
@subsection get-collate-table (10) Recommended
@findex get-collate-table
@example
get-collate-table [85] ( )
-> ( HOLLERITH );
@end example
@unnumberedsubsubsec Error codes
This call always succeeds.
@node create-text, create-anonymous-text, get-collate-table, Protocol Requests
@subsection create-text (10) Recommended
@findex create-text
@example
create-text [86] (( text : HOLLERITH;
misc-info : ARRAY Misc-Info;
aux-items : ARRAY Aux-Item-Input; ))
-> ( Text-No );
@end example
Creates a new text with contents from @code{text} and recipients
etc. defined by @code{misc-info} (@pxref{The Misc-Info List}.) In
addition to the result, the server will send an asynchronous message
to all members of any of the recipients of the new text. It is not
defined whether this messages comes before or after the reply to
the create-text message. Clients should be prepared for either
situation.
The text up to the first line feed is considered to be the subject
line. The remaining text is the message body. Although messages with
only a subject are valid, clients should avoid letting users create
such messages.
The items in @code{aux-items} are attached to the new text.
The only Misc-Info items valid for this call are recpt, cc-recpt,
bcc-recpt (protocol version 10), comm-to and footn-to.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item string-too-long
The string @code{text} is longer than the maximum length of a message.
@item temporary-failure
The text could not be created at the moment.
@item no-such-text
Attempt to comment or footnote a non-existent or secret text.
@item not-author
Attempt to footnote a text authored by someone else.
@item footnote-limit
Attempt to footnote a text with the maximum number of footnotes already
set.
@item comment-limit
Attempt to comment a text with the maximum number of comments already
set.
@item access-denied
Attempt to send a text to a conference failed because no access to the
conference or any superconference that will accept a text.
@item anonymous-rejected
Attempt to send an anonymous text to a conference that does not accept
anonymous texts.
@item illegal-misc
Invalid misc-info list. A recipient is listed more than once or there is
an unknown misc item in the misc-info list.
@item illegal-aux-item
One of the aux-items in @code{aux-items} is illegal. The tag might be
out of range, the item not applicable to texts or whatever
@item aux-item-permission
One of the items looks valid but could not be created anyway.
@end table
@node create-anonymous-text, create-conf, create-text, Protocol Requests
@subsection create-anonymous-text (10) Recommended
@findex create-anonymous-text
@example
create-anonymous-text [87] (( text : HOLLERITH;
misc-info : ARRAY Misc-Info;
aux-items : ARRAY Aux-Item-Input; ))
-> ( Text-No );
@end example
Similar to @pxref{create-text}, but the text is created the author
field set to zero. Not even the server has a record of who created the
text.
the original intended use for this call was for importing texts from
other sources, such as WWW, FTP or Gopher, but some clients include
explicit support for sending anonymous texts to a server.
It is only possible to send anonymous texts to a conference with the
right flag bit set.
The only Misc-Info items valid for this call are recpt, cc-recpt,
bcc-recpt (protocol version 10) comm-to and footn-to.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.@item string-too-long
The string @code{text} is longer than the maximum length of a message.
@item temporary-failure
The text could not be created at the moment.
@item no-such-text
Attempt to comment or footnote a non-existent or secret text.
@item not-author
Attempt to footnote a text authored by someone else.
@item footnote-limit
Attempt to footnote a text with the maximum number of footnotes already
set.
@item comment-limit
Attempt to comment a text with the maximum number of comments already
set.
@item access-denied
Attempt to send a text to a conference failed because no access to the
conference or any superconference that will accept a text.
@item anonymous-rejected
Attempt to send an anonymous text to a conference that does not accept
anonymous texts.
@item illegal-misc
Invalid misc-info list. A recipient is listed more than once or there is
an unknown misc item in the misc-info list.
@item illegal-aux-item
One of the aux-items in @code{aux-items} is illegal. The tag might be
out of range, the item not applicable to texts or whatever
@item aux-item-permission
One of the items looks valid but could not be created anyway.
@end table
@node create-conf, create-person, create-anonymous-text, Protocol Requests
@subsection create-conf (10) Recommended
@findex create-conf
@example
create-conf [88] (( name : HOLLERITH;
type : Any-Conf-Type;
aux-items : ARRAY Aux-Item-Input; ))
-> ( Conf-No );
@end example
This call is used to create new conferences. @code{name} is the name of
the new conference and @code{type} is its type. If successful, the call
returns the conference number of the newly created conference. The list
@code{aux-items} contains the aux items to attach to the conference.
To use this call the session must have logged in as a user with
privileges to create conferences (@pxref{Security}).
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item permission-denied
The server does not allow anyone to create a conference and user does
not have the @code{create-conf} bit set.
@item conference-exists
A conference named @code{name} already exists.
@item bad-name
@code{name} contains invalid characters.
@item string-to-long@code{name} is too long to be used as a conference name.
@item secret-public
The conference type has the @code{secret} bit set, but the
@code{rd-prot} bit is cleared.
@item illegal-aux-item
One of the aux-items in @code{aux-items} is illegal. The tag might be
out of range, the item not applicable to conferences or whatever
@item aux-item-permission
One of the items looks valid but could not be created anyway.
@end table
@node create-person, get-text-stat, create-conf, Protocol Requests
@subsection create-person (10) Recommended
@findex create-person
@example
create-person [89] (( name : HOLLERITH;
passwd : HOLLERITH;
aux-items : ARRAY Aux-Item-Input; ))
-> ( Pers-No );
@end example
This call requests that the server create a new person with the name and
password given as arguments. To create a person the session must be
logged in as a person with sufficient privileges. The list
@code{aux-items} contains the aux items that are to be attached to the
new person's letterbox conference.
The new person will be a member of exactly one conference: the
associated letterbox. That membership will have priority 255 and (of
course) position 0. All flags of the membership will be 0.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
The session is not logged in and the server does not allow person
creation before logging in.
@item permission-denied
The server does not allow anyone to create person and the person
currently logged on does not have the @code{create-pers} bit set.
@item conference-exists
There is already a conference named @code{name}.
@item invalid-password
The string @code{passwd} is not a valid password.
@item illegal-aux-item
One of the aux-items in @code{aux-items} is illegal. The tag might be
out of range, the item not applicable to conferences or letterboxes or
whatever.
@item aux-item-permission
One of the items looks valid but could not be created anyway.
@end table
@node get-text-stat, get-conf-stat, create-person, Protocol Requests
@subsection get-text-stat (10) Recommended
@findex get-text-stat
@example
get-text-stat [90] ( text-no : Text-No )
-> ( Text-Stat );
@end example
Get information about text number @code{text-no}. The text-stat contains
information about the size of the text, its recipients, comments, author
and more.
@unnumberedsubsubsec Error codes
@table @code
@item no-such-text
The text @code{text-no} does not exist, or no read access.
This error code will also be used when attempting to fetch any text
except the motd-of-lyskom text without logging in first.
@item text-zero
Attempt to retrieve text number 0.
@end table
@node get-conf-stat, modify-text-info, get-text-stat, Protocol Requests
@subsection get-conf-stat (10) Recommended
@findex get-conf-stat
@example
get-conf-stat [91] ( conf-no : Conf-No )
-> ( Conference );
@end example
This call retrieves the conference data structure for conference number
@code{conf-no}.
@unnumberedsubsubsec Error codes
@table @code
@item undefined-conference
The conference @code{conf-no} does not exist or is secret.
@end table
@node modify-text-info, modify-conf-info, get-conf-stat, Protocol Requests
@subsection modify-text-info (10) Recommended
@findex modify-text-info
@example
modify-text-info [92] (( text : Text-No;
delete : ARRAY Aux-No;
add : ARRAY Aux-Item-Input; ))
-> ( );
@end example
This call deletes the aux-items listed in @code{delete} from the text
@code{text} and then adds the ones listed in @code{add} to the text.
Either list may be empty, and the call is guaranteed to either
completely fail or completely succeed.
@unnumberedsubsubsec Error codes
@table @code
@item login-firstLogin required before issuing this call.
@item no-such-text
The text @code{text} does not exist or is secret.
@item aux-item-permission
No permission to delete one or more of the items in @code{delete}, or
not enough permissions to add one or more of the items in @code{add}.
@item illegal-aux-item
One of the items in @code{add} is illegal for some reason.
@end table
@node modify-conf-info, get-info, modify-text-info, Protocol Requests
@subsection modify-conf-info (10) Recommended
@findex modify-conf-info
@example
modify-conf-info [93] (( conf : Conf-No;
delete : ARRAY Aux-No;
add : ARRAY Aux-Item-Input; ))
-> ( );
@end example
This call deleted the aux-items listed in @code{delete} from the
conference @code{conference} and then adds the ones listed in @code{add}
to the text. Either list may be empty, and the call is guaranteed to
either completely fail or completely succeed.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-conference
The conference @code{conference} does not exist or is secret.
@item aux-item-permission
No permission to delete one or more of the items in @code{delete}, or
not enough permissions to add one or more of the items in @code{add}.
@item illegal-aux-item
One of the items in @code{add} is illegal for some reason.
@end table
@node get-info, modify-system-info, modify-conf-info, Protocol Requests
@subsection get-info (10) Recommended
@findex get-info
@example
get-info [94] ( )
-> ( Info );
@end example
This call returns the @code{Info} structure for the server
(@pxref{LysKOM Data Types}. Clients should call this in order to find
out which conferences are used for presentations and such.
It can be issued without logging in.
@unnumberedsubsubsec Error codes
This call always succeeds.
@node modify-system-info, query-predefined-aux-items, get-info, Protocol Requests
@subsection modify-system-info (10) Recommended
@findex modify-system-info
@example
modify-system-info [95] (( items-to-delete : ARRAY Aux-No;
items-to-add : ARRAY Aux-Item-Input; ))
-> ( );
@end example
This call modifies the aux-item list of the server information (which
can be retrieved using @ref{get-info}.) It only succeeds when issued by
a person with the admin bit set and privileges enabled.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login requires before issuing this call.
@item permission-denied
Admin bit not set or privileges not enabled.
@item illegal-aux-item
Attempt to create an invalid aux item.
@item aux-item-permission
Attempt to delete an undeletable item or create an uncreateable item.
@end table
@node query-predefined-aux-items, set-expire, modify-system-info, Protocol Requests
@subsection query-predefined-aux-items (10) Recommended
@findex query-predefined-aux-items
@example
query-predefined-aux-items [96] ( )
-> ( ARRAY INT32 );
@end example
Returns the list of aux-items that have specific definitions in the
server. These items are the only items within the restricted tag ranges
that can be created. The meanings of the various item types are defined
in this document.
@unnumberedsubsubsec Error codes
This call always succeeds.
@node set-expire, query-read-texts, query-predefined-aux-items, Protocol Requests
@subsection set-expire (10) Recommended
@findex set-expire
@example
set-expire [97] (( conf-no : Conf-No;
expire : Garb-Nice; ))
-> ( );
@end example
This call sets the @code{expire} field of the conference @code{conf-no}
to @code{expire}. This call can only be issued by the conference's
supervisor or a privileged user.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-conference
The conference @code{conf-no} does not exist or is secret.
@item permission-denied
Not supervisor of conference @code{conf-no} and not privileged enough to
complete the call anyway.@end table
@node query-read-texts, get-membership, set-expire, Protocol Requests
@subsection query-read-texts (10) Recommended
@findex query-read-texts
@example
query-read-texts [98] (( person : Pers-No;
conference : Conf-No; ))
-> ( Membership );
@end example
This call is used to find the number of unread texts in a conference.
The data it returns is actually a membership structure which specifies
which texts have been read. It is up to the client to transform the data
to a more usable form. @code{person} is the person being queried is to
be made and @code{conference} is the conference in question.
This call may be issued without logging in.
Calling @code{query-read-texts-old} does not require the session to be logged in.
@i{Example:}
@example
1 98 6 1
@t{=1 32 5 11 12 7 93 1 193 1 1 20 133}
@t{ 3 @{ 135 136 137 @} 5 01000000}
@end example
This example finds the read texts for user 6 in conference 1. The
returned data indicates that the user last read conference 1 (the tenth
number) on Monday July 12th, 1993 at 11:05:32 (the first nine numbers),
that the person has assigned priority 20 to the conference (the eleventh
number) and that all articles up to and including local number 133 plus
articles 135, 136 and 137 have been read. The membership was added by
person 5, and it is passive.
@unnumberedsubsubsec Error codes
@table @code
@item undefined-person
@code{person} does not exist, or no access to person.
@item undefined-conference
Conference @code{conference} does not exist, or is secret.
@item zero-conference
@code{conference} is zero.
@item not-member
@code{person} is not a member of @code{conference} or insufficient
privileges to find out if @code{person} is a member.
@end table
@node get-membership, add-member, query-read-texts, Protocol Requests
@subsection get-membership (10) Recommended
@findex get-membership
@example
get-membership [99] (( person : Pers-No;
first : INT16;
no-of-confs : INT16;
mask : BITSTRING
(
want-read-texts
); ))
-> ( ARRAY Membership );
@end example
This call retrieves the membership record for a list of conferences for
a single person. @code{person} is the person whose memberships are to beretrieved. @code{first} is the first position in the membership list to
retrieve, numbered from 0 and up. @code{no-of-confs} is the number of
membership records to retrieve. @code{mask} is a set of flags. Currently
the only flag is @code{want-read-texts}, which instructs the server not
to send the @code{read-texts} array of the memberships.
The server will return a membership list that is shorter than
@code{no-of-confs} if @code{no-of-confs} + @code{first} is larger than
the number of conferences the person is a member of. Elements of the
member list that the person requesting the list does not have sufficient
privileges to see may be cleared. Cleared elements simply have all
fields set to zero.
@example
1 99 5 0 3 1
@t{=1 2 @{ 49 14 17 13 8 91 5 255 1 5 255 0 0 * 5 00000000}
@t{ 20 14 22 17 6 97 4 197 1 6 100 2 0 * 5 00000000 @}}
1 99 5 0 1 1
@t{=1 1 @{ 49 14 17 13 8 91 5 255 1 5 255 0 0 * 5 00000000 @}}
1 99 5 1 4 1
@t{=1 1 @{ 20 14 22 17 6 97 4 197 1 6 100 2 0 * 5 00000000 @}}
@end example
In this example we retrieve the memberships of person 5. The first call
asks for three memberships, starting with number 0. Since this person is
only a member of two conferences, the list returned only contains two
memberships. The next two calls retrieve a single membership each. The
first by asking for only one, and the second by asking for four
memberships, starting with number 1.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-person
The person @code{person} does not exist.
@item undefined-conference
The conference @code{person} does not exist or is secret.
@item index-out-of-range
@code{first} is higher than the index of the first conference in the
person's membership list.
@end table
@node add-member, get-members, get-membership, Protocol Requests
@subsection add-member (10) Recommended
@findex add-member
@example
add-member [100] (( conf-no : Conf-No;
pers-no : Pers-No;
priority : INT8;
where : INT16;
type : Membership-Type; ))
-> ( );
@end example
Make the person @code{pers-no} a member of conference @code{conf-no}.
The membership priority is set to @code{priority} and its position in
the membership list is set to @code{where}.
This call can be used to change the priority, position and flags of a
conference in the person's membership list if the person is already a
member of the conference. The person doing this must either be a
supervisor of the affected person, or have sufficient privileges
enabled.
@example
1 99 119 0 10 0 @t{=1 1 @{ 49 14 17 13 8 91 5 255 1 119 255 0 0 * 119 00001111 @}}
1 100 1 119 250 0 10000000
@t{=1}
1 100 119 119 251 1 00000000
@t{=1}
1 99 119 0 10 0
@t{=1 2 @{ 52 30 14 11 5 96 2 162 1 1 250 0 0 * 119 00000000
49 14 17 13 8 91 5 251 1 119 255 0 0 * 10000000 @}}
@end example
This example makes person 119 (me) a member of conference number 1 and
changes the priority and some flags of the preexisting membership in
conference 119. The priority is set to 250 and the conference is placed
first in the membership list. The first and last calls of the example
show the membership list for person 119 before and after the calls.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-conference
Conference @code{conf-no} does not exist or is secret.
@item zero-conference
@code{conference} is zero.
@item undefined-person
Person @code{pers-no} does not exist
@item access-denied
Not enough permissions or privileges to add members to conference or to
change privileges, position or type of a preexisting membership.
@code{conf-no}.
@item permission-denied
Person @code{pers-no} is already a member of conference @code{conf-no},
but the person logged on is not a supervisor and does not have enough
privileges to change the priorities of person @code{pers-no}.
@end table
@node get-members, set-membership-type, add-member, Protocol Requests
@subsection get-members (10) Recommended
@findex get-members
@example
get-members [101] (( conf : Conf-No;
first : INT16;
no-of-members : INT16; ))
-> ( ARRAY Member );
@end example
This call returns a list of members of the conference @code{conf-no}.
@code{first} is the first index in the membership to return, numbered
from zero and up. @code{no-of-members} is the maximum number of members
to return.
Some of the elements of the result may be cleared if the person
requesting the information does not have sufficient privileges to see
the contents. Cleared elements simply have all fields set to zero.
@example
1 101 1 0 100
@t{=1 4 @{ 7 7 00000000 8 8 00000000 9 8 00000000 } @t{ 10 10 00000000 @}}
1 101 6 0 100
@t{=1 4 @{ 5 5 01000000 7 7 01000000 9 8 10000000 }
@t{ 10 10 00000000 @}}
1 101 6 2 2
@t{=1 2 @{ 9 8 10000000 10 10 00000000@}}
@end example
In this example the client first requests the first 100 members in
conference 1. The second request is for the first 100 members of
conference 6. The last request is for members 2 and 3 in conference 6.
@unnumberedsubsubsec Error codes
@table @code
@item undefined-conference
The conference @code{conf} does not exist or is secret.
@item index-out-of-range
@code{first} is higher than the number of members in @code{conf}.
@end table
@node set-membership-type, local-to-global, get-members, Protocol Requests
@subsection set-membership-type (10) Recommended
@findex set-membership-type
@example
set-membership-type [102] (( pers : Pers-No;
conf : Conf-No;
type : Membership-Type; ))
-> ( );
@end example
This call modifies the type of a membership. The person @code{pers}
membership in conference @code{conf} is affected. The server may impose
arbitrary restrictions on how the membership type may be changed.
Typically it will only be possible to clear the @code{invitation} bit.
It is possible that the server will not permit the @code{secret} bit to
be set. Attempting to set a membership type that does not agree with
the server's restrictions will result in an error.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@c FIXME: more codes here
@end table
@node local-to-global, map-created-texts, set-membership-type, Protocol Requests
@subsection local-to-global (10) Recommended
@findex local-to-global
@example
local-to-global [103] (( conf-no : Conf-No;
first-local-no : Local-Text-No;
no-of-existing-texts : INTEGER; ))
-> ( Text-Mapping );
@end example
FIXME: more text here
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@c FIXME: more codes here
@end table
@node map-created-texts, , local-to-global, Protocol Requests
@subsection map-created-texts (10) Recommended
@findex map-created-texts
@example
map-created-texts [104] (( author : Pers-No;
first-local-no : Local-Text-No;
no-of-existing-texts : INTEGER; ))
-> ( Text-Mapping );
@end example
Return information about existing texts that @code{author} has written.
FIXME: more text here
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@c FIXME: more codes here
@end table
@node Asynchronous Messages, , , Top
@chapter Asynchronous Messages
Asynchronous messages are information messages sent from the server to
the client. Clients can select which messages to receive by issuing an
@code{@ref{accept-async}} call. They can find out which messages are
being sent by issuing the @code{@ref{query-async}} call. Note that the
server can send other messages as well. For example, a broadcast message
from a person with admin bits set may get through even if the client has
not requests broadcast messages.
When a connection is opened some messages are selected by default.
Clients should use the @code{@ref{accept-async}} call to select which
messages they want. Servers are encouraged to preselect the
@code{new-text-old}, @code{new-name}, @code{sync-db}, @code{leave-conf},
@code{login}, @code{rejected-connection}, @code{send-message} and
@code{logout} messages. These correspond to the useful messages that
were sent prior to the introduction of @code{accept-async}.
An asynchronous message is sent as a colon immediately followed by the
number of message parameters, the message numbers and the message
parameters. For example, message number 5 could be sent as
@example
:3 5 119 11HDavid Byers 13HDavid C Byers
@end example
The parameters of each message are listed in the same format as server
calls.
The messages with status "O" are included here for historical purposes
only. Servers are not required to handle them, and are encouraged to
reject them if a client uses it as an argument to
@code{@ref{accept-async}}.
@menu
Message Name Status Description Number
-------------------------------------------------------------------------------
* async-new-text-old:: A text has been created (0)
* async-i-am-off:: O Logged off (obsolete) (1)* async-i-am-on-obsolete:: O Client changed i-am-on string (obsolete) (2)
* async-new-name:: Conference or person changed name (5)
* async-i-am-on:: Client changed i-am-doing string (6)
* async-sync-db:: Server is saving the database (7)
* async-leave-conf:: Person has been removed from a conf while in (8)
* async-login:: Someone has logged in (9)
* async-broadcast:: O Broadcast message (obsolete) (10)
* async-rejected-connection:: LysKOM is full. Log out to make room. (11)
* async-send-message:: Text message to group or person (12)
* async-logout:: A person has logged out (13)
* async-deleted-text:: A text was deleted (14)
* async-new-text:: A text has been created (15)
-------------------------------------------------------------------------------
@end menu
@node async-new-text-old, async-i-am-off, , Asynchronous Messages
@subsection async-new-text-old (1) Obsolete (10)
@example
async-new-text-old [0] (( text-no : Text-No;
text-stat : Text-Stat-Old; ));
@end example
This message is sent when a text is created. The text number of the text
is sent in @code{text-no} and the text stat in @code{text-stat}. This
message is sent to all logged-in members of any recipient of the text.
In protocol version 10 this call has been superceded by @ref{async-new-text}.
@node async-i-am-off, async-i-am-on-obsolete, async-new-text-old, Asynchronous Messages
@subsection async-i-am-off (1) Obsolete
@example
async-i-am-off [1] ( person : Pers-No );
@end example
This message was sent when a person logged off. It has been replaced by
call @code{Async logout}.
@node async-i-am-on-obsolete, async-new-name, async-i-am-off, Asynchronous Messages
@subsection async-i-am-on-obsolete (1) Obsolete
@example
async-i-am-on-obsolete [2] (( person : Pers-No;
conference : Conf-No;
what-am-i-doing : HOLLERITH; ));
@end example
This message was sent when a user changed his what-i-am-doing string or
working conference. It has been replaced by call number 6,
@ref{async-i-am-on}.
@node async-new-name, async-i-am-on, async-i-am-on-obsolete, Asynchronous Messages
@subsection async-new-name (1) Recommended
@example
async-new-name [5] (( conf-no : Conf-No;
old-name : HOLLERITH;
new-name : HOLLERITH; ));
@end example
This message is sent when a person or conference changes names. The
conference whose name is being changed is sent in @code{conf-no}, the
old name in @code{old-name} and the new name in @code{new-name}.
@node async-i-am-on, async-sync-db, async-new-name, Asynchronous Messages
@subsection async-i-am-on (1) Recommended
@example
async-i-am-on [6] ( info : Who-Info );
@end example
This message is sent when a session's working conference,
what-i-am-doing string or username changes. The new information is sent
in @code{info}.
FIXME: can the username change?
@node async-sync-db, async-leave-conf, async-i-am-on, Asynchronous Messages
@subsection async-sync-db (1) Recommended
@example
async-sync-db [7] ( );
@end example
This message is sent once just before the server blocks to save its
database and once just after it blocks. There is no good way to tell the
difference between the two cases.
@node async-leave-conf, async-login, async-sync-db, Asynchronous Messages
@subsection async-leave-conf (1) Recommended
@example
async-leave-conf [8] ( conf-no : Conf-No );
@end example
This message is sent to a user if the user's membership in the working
conference is forcefully revoked. The conference the user is being
removed from is sent in @code{conf-no}.
@node async-login, async-broadcast, async-leave-conf, Asynchronous Messages
@subsection async-login (1) Recommended
@example
async-login [9] ( pers-no : Pers-No;
session-no : Session-No; );
@end example
This message is sent when someone logs in. The identity of the person
logging in is sent in @code{pers-no}.
@node async-broadcast, async-rejected-connection, async-login, Asynchronous Messages
@subsection async-broadcast (1) Obsolete
@example
async-broadcast [10] (( sender : Pers-No;
message : HOLLERITH; ));
@end example
This message has been superceded by @code{send-message} which is more
flexible. It used to be sent when the administrator broadcast a string
to all LysKOM users.
@node async-rejected-connection, async-send-message, async-broadcast, Asynchronous Messages
@subsection async-rejected-connection (1) Recommended
@example
async-rejected-connection [11] ( );
@end example
This message is sent when someone fails to log in because the maximum
number of allowed connections has been reached. Some clients may take
this as a signal to log out. Administrators should take it as a signal
to allow more connections.
@node async-send-message, async-logout, async-rejected-connection, Asynchronous Messages
@subsection async-send-message (1) Recommended
@example
async-send-message [12] (( recipient : Conf-No;
sender : Pers-No;
message : HOLLERITH; ));
@end example
This message is sent when someone sends a message string. The recipient
of the message is sent in @code{recipient}. If it is zero, then the
message was sent to all connections. If it is a conference, then the
message is being sent to all logged-in members of that conference. If it
is a letterbox then the message is personal and is only sent to members
of the letterbox conference.
@node async-logout, async-deleted-text, async-send-message, Asynchronous Messages
@subsection async-async-logout (1) Recommended
@example
async-logout [13] (( pers-no : Pers-No;
session-no : Session-No; ));
@end example
This message is sent when someone logs out. @code{pers-no} is the person
logging out and @code{session-no} is the session in which the person is
logging out.
@node async-deleted-text, async-new-text, async-logout, Asynchronous Messages
@subsection async-deleted-text (10) Recommended
@example
async-deleted-text [14] (( text-no : Text-No;
text-stat : Text-Stat; ));
@end example
This message is sent when a text is deleted and the currently logged-in
person is a member of one of the recipients. The text number being
deleted is sent in @code{text-no} and the text stat in @code{text-stat.}
@node async-new-text, , async-deleted-text, Asynchronous Messages
@subsection async-new-text (10) Recommended
@example
async-new-text [15] (( text-no : Text-No;
text-stat : Text-Stat; ));
@end example
This message indicates that a new text has been created. The text has
number @code{text-no}, and the text stat is @code{text-stat}. The
message is sent to all logged-in members of any recipient of the text.
@node Error Codes, , , Top
@chapter Error Codes
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 ::=
( "%"
ref-no : INT32;
error-no : Error-No;
error-status : INT32;
)
error-no ::= INT32;
@end example
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
@code{error-status} was more or less undefined before protocol version
10. For protocol version 10, the meaning of @code{error-status} is
defined below.
The meaning of @code{error-status} can be modified by any call. In
particular the calls that deal with Misc-Info lists set
@code{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: @code{temporary-failure}, @code{internal-error},
@code{feature-disabled}, @code{not-implemented}, @code{obsolete-call},
@code{ldb-error}, @code{feature-disabled}, @code{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.
@table @code
@item no-error (0)
No error has occurred. @code{error-status} is undefined. This should
never happen, but it might.
@item not-implemented (2)
The call has not been implemented yet. @code{error-status} is undefined.
@item obsolete-call (3)
The call is obsolete and no longer implemented. @code{error-status} is
undefined.
@item invalid-password (4)
Attempt to set a password containing illegal characters, or to use an
incorrect password.
@item string-too-long (5)
A string was too long (see descriptions of each call.)
@code{error-status} indicates the maximum string length.
@item login-first (6)Login is required before issuing the call. @code{error-status} is
undefined.
@item login-disallowed (7)
The system is in single-user mode. You need to be privileged to log in
despite this. @code{error-status} is undefined.
@item conference-zero (8)
Attempt to use conference number 0. @code{error-status} is undefined.
@item undefined-conference (9)
Attempt to access a non-existent or secret conference.
@code{error-status} contains the conference number in question.
@item undefined-person (10)
Attempt to access a non-existent or secret person.
@code{error-status} contains the person number in question.
@item access-denied (11)
No read/write access to something. This might be returned in response to
an attempt to create a text, when the recipient conference and its super
conferences are read-only, or when attempting to add a member to a
conference without enough permission to do so. @code{error-status}
indicates the object to which we didn't have enough permissions to.
@item permission-denied (12)
Not enough permissions to do something. The exact meaning of this
response depends on the call. @code{error-status} indicated the object
for which permission was lacking, or zero.
@item not-member (13)
The call requires the caller to be a member of some conference that the
caller is not a member of. @code{error-status} indicates the conference
in question.
@item no-such-text (14)
Attempt to access a text that either does not exist or is secret in some
way. @code{error-status} indicates the text number in question.
@item text-zero (15)
Attempt to use text number 0. @code{error-status} is undefined.
@item no-such-local-text (16)
Attempt to access a text using a local text number that does not
represent an existing text. @code{error-status} indicates the offending
number.
@item local-text-zero (17)
Attempt to use local text number zero. @code{error-status} is undefined.
@item bad-name (18)
Attempt to use a name that's too long, too short or contains invalid
characters. @code{error-status} is undefined.
@item index-out-of-range (19)
Attempt to use a number that's out of range. The range and meaning of
the numbers depends on the call issued. @code{error-status} is
undefined.
@item conference-exists (20)
Attempt to create a conference or person with a name that's already
occupied. @code{error-status} is undefined.
@item person-exists (21)
Attempt to create a person with a name that's already occupied.
@code{error-status} is undefined. This error code is probably not used,
but you never know for sure.
@item secret-public (22)
Attempt to give a conference a type with both the @code{secret} and@code{rd-prot} bits set at the same time. This is an error since such a
conference type is inconsistent. @code{error-status} is undefined.
@item letterbox (23)
Attempt to change the @code{letterbox} flag of a conference.
@code{error-status} indicates the conference number.
@item ldb-error (24)
Database is corrupted. @code{error-status} is an internal code.
@item illegal-misc (25)
Attempt to create an illegal misc item. @code{error-status} contains the
index of the illegal item.
@item illegal-info-type (26)
Attempt to use a Misc-Info type that the server knows nothing about.
@code{error-status} is undefined.
@item already-recipient (27)
Attempt to add a recipient that is already a recipient of the same type.
@code{error-status} contains the recipient that already is.
@item already-comment (28)
Attempt to add a comment to a text twice over. @code{error-status}
contains the text number of the text that already is a comment.
@item already-footnote (29)
Attempt to add a footnote to a text twice over. @code{error-status}
contains the text number of the text that already is a footnote.
@item not-recipient (30)
Attempt to remove a recipient that isn't really a recipient.
@code{error-status} contains the conference number in question.
@item not-comment (31)
Attempt to remove a comment link that does not exist.
@code{error-status} contains the text number that isn't a comment.
@item not-footnote (32)
Attempt to remove a footnote link that does not exist.
@code{error-status} contains the text number that isn't a footnote.
@item recipient-limit (33)
Attempt to add a recipient to a text that already has the maximum number
of recipients. @code{error-status} is the text that has the maximum
number of recipients.
@item comment-limit (34)
Attempt to add a comment to a text that already has the maximum number
of comments. @code{error-status} is the text with the maximum number of
comments.
@item footnote-limit (35)
Attempt to add a footnote to a text that already has the maximum number
of footnote. @code{error-status} is the text with the maximum number of
footnote.
@item mark-limit (36)
Attempt to add a mark to a text that already has the maximum number
of marks. @code{error-status} is the text with the maximum number of
marks.
@item not-author (37)
Attempt to manipulate a text in a way that required the user to be the
author of the text, when not in fact the author. @code{error-status}
contains the text number in question.
@item no-connect (38)
Currently unused.
@item out-of-memory (39)
The server ran out of memory.
@item server-is-crazy (40)
Currently unused.
@item client-is-crazy (41)
Currently unused.
@item undefined-session (42)
Attempt to access a session that does not exist. @code{error-status}
contains the offending session number.
@item regexp-error (43)
Error using a regexp. The regexp may be invalid or the server unable to
compile it for other reasons. @code{error-status} is undefined.
@item not-marked (44)
Attempt to manipulate a text in a way that requires the text to be
marked, when in fact it is not marked. @code{error-status} indicates the
text in question.
@item temporary-failure (45)
Temporary failure. Try again later. @code{error-code} is undefined.
@item long-array (46)
An array sent to the server was too long. @code{error-status} is
undefined.
@item anonymous-rejected (47)
Attempt to send an anonymous text to a conference that does not accept
anonymous texts. @code{error-status} is undefined.
@item illegal-aux-item (48)
Attempt to create an invalid aux-item. Probably the tag or data are
invalid. @code{error-status} contains the index in the aux-item list
where the invalid item appears.
@item aux-item-permission (49)
Attempt to manipulate an aux-item without enough permissions. This
response is sent when attempting to delete an item set by someone else
or an item that can't be deleted, and when attempting to create an item
without permissions to do so. @code{error-status} contains the index at
which the item appears in the aux-item list sent to the server.
@item unknown-async (50)
Sent in response to a request for an asynchronous message the server
does not send. The call succeeds, but this is sent as a warning to the
client. @code{error-status} contains the message type the server did not
understand.
@item internal-error (51)
The server has encountered a possibly recoverable internal error.
@code{error-status} is undefined.
@item feature-disabled (52)
Attempt to use a feature that has been explicitly disabled in the
server. @code{error-status} is undefined.
@item message-not-sent (53)
Attempt to send an asynchronous message failed for some reason. Perhaps
the recipient is not accepting messages at the moment.
@code{error-status} is undefined.
@end table
@node LysKOM Content Types, , , Top
@chapter LysKOM Content Types
LysKOM defines a few special content types for texts. They are all
described in this chapter. In addition to these, clients must support
text/plain, should support text/enriched and are encouraged to support
text/html.
@menu
* Reformattable Text (x-kom/basic) ::
* The User Area (x-kom/user-area) ::
* Conference Lists (x-kom/conflist) ::
@end menu
@node Reformattable Text (x-kom/basic), The User Area (x-kom/user-area),, LysKOM Content Types
@section Reformattable Text
This type of content corresponds to the mime type x-kom/basic. It is raw
text that can be reformatted by the client without ill effects, but
that can be legibly displayed on a text terminal without formatting.
@itemize @bullet
@item Lines must be no longer than 70 characters.
@item Each line is terminated by a single newline character.
@item Two newline characters in succession signal the end of the paragraph.
@item There must be no whitespace or newlines after the last character
@end itemize
The following rules apply when reformatting:
@itemize @bullet
@item The indentation of the first line of a paragraph is to be applied
to all lines in the paragraph.
@item If the first line of a paragraph matches ">+ *" then the string
that matched that regexp is to be prefixed to all lines of the
paragraph.
@end itemize
@node The User Area (x-kom/user-area), Conference Lists (x-kom/conflist), Reformattable Text (x-kom/basic), LysKOM Content Types
@section The User Area
@node Conference Lists (x-kom/conflist), , The User Area (x-kom/user-area), LysKOM Content Types
@section Conference Lists
@node The User Area, , , Top
@chapter The User Area
The user area is a regular text that is used to store client-specific
information in the server. Most clients use this to store settings a
user has made that are specific to a particular server. There are also
provisions to store settings that are shared between clients.
The user-area is divided into several sub-blocks. The common block is
shared by all clients, and its formats and contents dictated by this
protocol specification. Clients may also create one or more blocks.
The entire user-area is coded as a @code{HOLLERITH}. This string in turn
contains a list of pairs of @code{HOLLERITH} strings. Each pair consists
of one string containing the block name and one containing the data. This
format ensures that clients can copy or read past other clients' blocks
without knowing their structure.
The following block names have been defined:
@table @code
@item common
The common block shared by all clients. The format of the common block is
described below.
@item elisp
The block created by the Emacs list client. The format is completelyundocumented, but you'll need a lisp reader to parse it.
@end table
If you're writing a client that uses the user-area, please let us know
what you name your client's block.
@section The Common Block
This defines the theoretical structure of the common block. The real
world probably does not agree entirely with this, and it is likely to
change just as soon as I have time to define something better. In the
mean while you're probably better off ignoring the common block and
storing all your settings in a client block. The Emacs lisp client uses
the common block, but I have a feeling that it might store data that
other clients can't read.
The common block contains a list of variable settings. Each variable
setting consists of a name, some whitespace, and a value. Settings are
separated by a line feed character. As of protocol version 10, values
can be integers, strings, booleans or lists. The encoding is such that a
value is encoded as a single protocol A token. That means that strings
and lists are both encoded as HOLLERITHs. The reason for this is to
simplify for clients that need to ignore the value, and so it is
possible to add new value types without confusing old clients (new types
will be encoded as HOLLERITHs.)
The grammar below sort of defines the syntax of the common block.
@example
common-block : settings
settings : settings setting
| /* empty */
setting : variable ' ' value '\n'
variable : [A-Za-z-_0-9]+
value : boolean
| HOLLERITH
| list
| integer
boolean : 1 | 0
integer : -?[0-9]+
list : integer elems // Encoded in a HOLLERITH
elems : elems value
| empty
@end example
Currently the following variables are used, but more may be added, and
as of protocol version 10, clients should be able to cope with variables
they know nothing of in the common block, as long as they are of one of
the types above. Pre-protocol version 10 clients can't deal with
HOLLERITHs in the common block.
As of protocol 10 the following variables are stored in the common
block:
@table @code
@item created-texts-are-read
True if the user wants texts s/he creates to be marked as read
automatically. Boolean.
@item dashed-lines
True if the user wants dashed lines around the text body when it's
displayed. Boolean.
@item presence-messages
True if the user wants messages about people logging in and logging out
of LysKOM. Boolean.
@item print-number-of-unread-on-entrance
True if the user wants to see the number of unread texts when entering aconference. Boolean.
@item read-depth-first
True if the user wants to read text in depth-first order. Boolean.
@item reading-puts-comments-in-pointers-last
True if the user wants the client to display comment links after the
text body. Boolean.
@item confirm-multiple-recipients
True if the user wants the client to ask for confirmation before sending
a text to many conferences.
@item default-mark
The default mark to set on marked texts.
@end table
@node Writing Clients, , , Top
@chapter Writing Clients
This chapter is not really part of the protocol specification, but
it contains some information that may be useful for client writers.
@menu
* Common Commands:: Common commands and how they're implemented.
* Client Conventions:: Conventions clients should follow.
@end menu
@node Common Commands, Client Conventions, , Writing Clients
@section Common Commands
Most clients will implement certain commands. This main purpose of this
section is to get client writers started on some of these commands, and
to answer some questions that seem to come up over and over again.
@menu
* What do I have unread::
* Only read the most recent N texts::
* Review the last N by FOO to BAR::
@end menu
@node What do I have unread, Only read the most recent N texts,,Common Commands
@node Only read the most recent N texts, Review the last N by FOO to BAR, What do I have unread, Common Commands
@node Review the last N by FOO to BAR,,Only read the most recent N texts, Common Commands
@node Client Conventions, , Common Commands, Writing Clients
@section Client Conventions
There are certain conventions that most clients follow, and that users
expect. These are not part of the protocol and are subject to change. In
particular those conventions that address deficiencies in the protocol
will go away when the protocol is updated to correct these deficiencies.
@menu
* Text formatting:: The format of texts in the database.
* Content type specification:: Clients can tag the content type of a text.
* Remote control:: Some clients can be remotely controlled.
@end menu
@node Text formatting, Content type specification, , Client Conventions
@subsubsection Text formatting
Traditionally the only clients for LysKOM were text-based and only
displayed texts exactly as they were stored in the server. Although
there are a number of clients now that can wrap lines automatically,
texts should still be stored in preformatted style, suitable for display
in a monospaced font.
If the client accepts texts from the user and then reformats them, such
as a client with an editor with a variable-width font, it should ensure
that it follows the following simple rules:
@itemize @bullet
@item Lines should be no longer than 72 characters.
@item Lines are terminated with a single newline character.
@item Paragraphs are separated by two newlines in succession.
@item There are no empty lines at the end of the text.
@end itemize
Clients that include editors but do not alter the text before sending it
to the server should attempt to ensure that texts confirm to the above
conventions.
The same conventions apply to messages sent with the
@pxref{send-message} call.
@node Content type specification, Remote control, Text formatting, Client Conventions
@subsubsection Content type specification
This convention is understood by all popular clients. If the first line
is one of a few predefined strings, then this string specifies the type
of text. Currently only the strings ``html:'' and ``enriched:'' are
supported, specifying text/html and text/enriched respectively.
Starting with protocol version 10, this ugly workaround is obsolete. Use
aux-items to specify content type instead.
@node Remote control, Type Index, Content type specification, Client Conventions
This convention is only implemented by the Emacs-Lisp client, but since
I work on that client, I'm free to write about it. This is a subprotocol
between clients, transferred by messages sent using
@pxref{send-message}.
@node Type Index, Request Index, Remote control, Top
@chapter Type Index
@printindex tp
@node Request Index, , Type Index, Top
@chapter Request Index
@printindex fn
@bye