\input texinfo @c -*-texinfo-*- @c @c FIXME: Explain how the garb works with nice and keep-commented @c @c $Id: Protocol-A.texi,v 1.91 1999/07/23 13:12:59 ceder 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 revision 10.2 of the LysKOM Protocol A specification. It specifies version 10 of the protocol. Copyright @copyright{} 1995-1999 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} @sp 2 @author by the LysKOM Developers @page @vskip 0pt plus 1filll Copyright @copyright{} 1995-1999 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 @top LysKOM Protocol A This document specifies version 10 of LysKOM Protocol A. This is revision 10.2 of the specification. @menu * Overview:: * Introduction:: * Data Types:: * Protocol Requests:: * Asynchronous Messages:: * Error Codes:: * LysKOM Content Types:: * The User Area:: * Writing Clients:: * Importing and Exporting E-Mail:: * Type Index:: * Request Index:: @end menu @end ifinfo @node Overview @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 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 @email{ceder@@lysator.liu.se}, David Byers @email{byers@@lysator.liu.se}, @ifinfo Pär @end ifinfo @iftex P@"ar @end iftex Emanuelsson @email{pell@@lysator.liu.se}, Thomas Bellman @email{bellman@@lysator.liu.se}, Lars Aronsson @email{aronsson@@lysator.liu.se}, Linus Tolke @email{linus@@lysator.liu.se} and @ifinfo Kent Engström @end ifinfo @iftex Kent Eng@-str@"om@penalty-10000 @end iftex @email{kent@@lysator.liu.se}. The LysKOM developers can be reached by email to @email{lyskom@@lysator.liu.se}. @menu * Document Revision History:: * Protocol Version History:: * Notation:: @end menu @node Document Revision History @section Document Revision History @table @asis @item 10.2: 1999-07-23 Some typos and other minor errors were fixed. Distributed with lyskomd 2.0.2. @item 10.1: 1999-07-12 Call @code{sub-comment} was incorrectly marked obsolete. This has been corrected. Regexps are case sensitive. The Info-Type enumeration was introduced in the description of the protocol. (Previous versions of the protocol had broken definitions of add-recipient, async-new-recipient and async-sub-recipient.) Distributed with lyskomd 2.0.1. @item 10.0: 1999-06-27 The specification was translated to English and converted to Texinfo by David Byers. Protocol version 10. Distributed with lyskomd 2.0.0. Note: this revision incorrectly marked the @code{sub-comment} call as obsolete, and stated that regexp lookup was case insensitive. Both statements were wrong, and has since been fixed. @item 9.0: 1996-08-04 Protocol version 9. Distributed with lyskomd 1.9.0. @item 8.0: 1995-11-10 Protocol version 8. Distributed with lyskomd 1.8.0. @item 7.1: 1995-01-08. Protocol and document revision history were added by Per Cederqvist. Outline 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 Version History @section Protocol Version History @subsection Protocol version 10 (first implemented in lyskomd 2.0.0) @table @asis @item Error codes The error codes are now documented. Several error codes were changed to more sane values while documenting the new behaviour. @item New Server Calls These new calls have status Recommended. @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 98=query-read-texts @item 99=get-membership @item 100=add-member @item 101=get-members @item 102=set-membership-type @item 103=local-to-global @item 104=map-created-texts @item 106=set-pers-flags @end itemize These new calls have status Experimental. @itemize @bullet @item 97=set-expire @item 105=set-keep-commented @end itemize @item Name changes @multitable {59=create-anonymous-text} {59=create-anonymous-text-old} @item Old name @tab New name @item 5=create-person @tab 5=create-person-old @item 9=query-read-texts @tab 9=query-read-texts-old @item 10=create-conf @tab 10=create-conf-old @item 13=get-conf-stat-old @tab 13=get-conf-stat-older @item 14=add-member @tab 14=add-member-old @item 26=get-text-stat @tab 26=get-text-stat-old @item 28=create-text @tab 28=create-text-old @item 36=get-info @tab 36=get-info-old @item 46=get-membership @tab 46=get-membership-old @item 48=get-members @tab 48=get-members-old @item 50=get-conf-stat @tab 50=get-conf-stat-old @item 59=create-anonymous-text @tab 59=create-anonymous-text-old @end multitable @item Status change The following calls have change status from Experimental to Recommended. @itemize @bullet @item 58=get-last-text @item 77=set-last-read @item 78=get-uconf-stat @end itemize The following calls have changed status from Recommended or Experimental to Obsolete. @itemize @bullet @item 5=create-person-old @item 9=query-read-texts-old @item 10=create-conf-old @item 14=add-member-old @item 26=get-text-stat-old @item 28=create-text-old @item 36=get-info-old @item 46=get-membership-old @item 47=get-created-texts @item 48=get-members-old @item 50=get-conf-stat-old @item 59=create-anonymous-text-old @end itemize @item New and 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 Renamed Asynchronous Messages A @samp{async-} prefix has been added to the name of all asynchronous messages. In addition, 0=new-text has been renamed to 0=async-new-text-old, and it is now considered obsolete. Clients should use 80=accept-async to listen to 15=async-new-text instead. @item New Asynchronous Messages @itemize @bullet @item 14=async-deleted-text @item 15=async-new-text @item 16=async-new-recipient @item 17=async-sub-recipient @item 18=async-new-membership @end itemize @item Notes @itemize @bullet @item Since protocol version 9 setting a priority of zero for a conference was supposed to indicate passive membership in a conference. It was largely up to the client to implement this. True passive memberships have been introduced in this protocol version through the Membership-type extension to the Membership type. In order to maintain compatibility with clients that interpret priority 0 as passive membership, the old calls @pxref{add-member-old} and @pxref{get-membership-old} perform magic, translating between priorities and membership types. The magic is documented with each call. @end itemize @end table @subsection Protocol version 9 (first implemented in lyskomd 1.9.0) @table @asis @item New functionality @itemize @bullet @item The server shall now reply with error @code{not-implemented} when a client attempts to use an unimplemented call. This feature requires that the client uses newline as call terminator. @end itemize @item Added Commands @itemize @bullet @item 79=set-info: Can change server information. @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 @item Changed names @itemize @bullet @item @code{change-conference} was previously called @code{pepsi}. The name was changed, but not the functionality. @end itemize @item Status change @itemize @bullet @item 63=@code{who-is-on-ident} is now considered obsolete. @item 64=@code{get-session-info-ident} is now considered obsolete. @end itemize @end table @subsection Protocol version 8 (first implemented in lyskomd 1.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 Notation @section Notation This specification uses a BNF-like grammar to describe the protocol and its data elements. Data fields have been given names that start with a lower-case letter. Fundamental data types have names in all-caps (such as @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 @chapter Introduction This chapter introduces the concepts used in LysKOM, such as articles, conferences and sessions. @menu * Articles:: * Conferences:: * The Misc-Info List:: * The Aux-Item List:: * Security:: * Membership and Reading:: * Client-Server Dialog:: @end menu @node Articles @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 @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 mailbox 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}, @code{allow-anonymous} and @code{forbid-secret} 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 mailbox and the name of the mailbox is synchronized with the person name. It is currently not possible to explicitly set or clear this flag on a conference. @item secret Conferences of this type are secret. The server will not divulge any information about the existence of the conference to persons who are not members or supervisors of the conference. If a mailbox 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. @item forbid-secret Conferences of this type do not allow secret members. If a conference is changed to this type, preexisting secret members remain secret. @end table @menu * Persons and Sessions:: @end menu @node Persons and Sessions @subsection Persons and Sessions Persons are represented in the protocol by values of the type @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 @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 to all 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 involved text and the conference status of the involved conference. (That is, as long as the conference isn't secret everybody is allowed to see 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 get-text-stat-old (@pxref{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 it 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 it 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 @section The Aux-Item List The aux-item list is used as a generic extension mechanism in the LysKOM server and in protocol A. @menu * About Aux-Items:: * Predefined Aux-Item Types:: * Client-Specific Aux-Item Types:: * Experimental Aux-Item Types:: * Defining New Aux-Item Types:: @end menu @node About Aux-Items @subsection About Aux-Items Aux-items were introduced in protocol version 10 as a mechanism for extending the conference, text and server information structures without changing the protocol. Persons were excluded since nobody could figure out a case where setting an aux-item on the mailbox 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 @subsection Predefined Aux-Item Types Predefined Aux-Item types are part of Protocol A, and clients should support all of them. As with other parts of the protocol, changes to these definitions will be made backwards-compatible, if possible. Creation and deletion of items with a predefined type can cause arbitrarily complex and wonderous behavior in the server. Furthermore, the server may place constraints on the items with regard to content, flags, who can create them, to what objects they can be attached and so forth. The server may also silently enforce specific values for any field of an item, regardless of what the client requests. 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 (illegal-aux-item.) @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. An item of this type will never be inherited, can always be deleted, is never anonymous and is never secret. @item cross-reference [3] (text, conference) Data is a cross-reference to something else. The contents consist of a letter, a number, a space and a descriptive text. The letter must be one of T, C or P. T specifies that the cross-reference points to a text; C that it points to a conference; and P that it points to a person. The number is the id of the target of the cross reference. The descriptive text is simly that, a text that describes the cross-reference. For example, "T15 Check this out!" is a cross reference to text 15 with a description that reads "Check this out!". The inherit bit is automatically cleared and the item can always be deleted. @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 and inherit 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. Once created an item of this type cannot be deleted. @item redirect [8] (conference) This item indicates that texts should not be sent to the conference, but be directed to some other target instead. Clients should notify users that attempt to send texts to the conference of the redirect and offer to send the text to the target of the redirect instead. A typical use of this item would be a user that does not read LysKOM very often and would like to advise other users to send e-mail instead. 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 mailbox, the person attached to the mailbox. The hide-creator and secret bits are cleared automatically. Only one redirect can be specified. @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 mailbox, the person attached to the mailbox. 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. Note that the server does not match against this name when performing name lookups. Clients should only display alternate names created by the user currently logged on. 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" in PGP 2.6.2 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 +", where @var{n} is the number of the person in the LysKOM server specified in @var{server}. This rule is currently not enforced. 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 mailbox, 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 mailbox is vague. For a conference that is used as to import a mailing list this should be the email address of the list. For other conferences we haven't really defined a sensible use. 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 supervisor of a conference or the server 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). Creating an item of this type automatically causes creation of a faq-for-conf item. This item can only be set by the supervisor or server administrator. The hide-creator, secret, and inherit bits are automatically cleared. @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 mx-author [16] (text) Data is a string containing the name of the author of an imported e-mail. Clients should display this instead of the actual author of the text, which will be an importer ID. @item mx-from [17] (text) Data is the e-mail address extracted from the @code{From} header of an imported e-mail. This field can be used by clients to construct an address for personal (e-mail) replies to an imported message. @item mx-reply-to [18] (text) Data is the e-mail address extracted from the @code{Reply-To} header of an imported e-mail. Clients should use this for constructing replies to imported messages. @item mx-to [19] (text) Data is a single e-mail address, and must be valid as the contents of an e-mail @code{To} header. Multiple @code{mx-to} items may be present. For imported messages, these items contain the @code{To} header of the messages. On messages created by a LysKOM person, the @code{mx-to} items are used by the exporter to determine that the message is to be exported and where to send it. @item mx-cc [20] (text) Same as @code{mx-to}, but applies to the @code{CC} header rather than the @code{To} header. @item mx-date [21] (text) Data is the send data of an imported e-mail. Its format is "YYYY-MM-DD hh:mm:ss TZ". YYYY is the year the message was sent, MM is the month, DD is the day, hh is the hour, mm is the minute and ss is the second. This date and time are given in the timezone where the message was sent. TZ is the timezone the date is valid for. It must be of the form "+hhmm" or "-hhmm", where hh is the number of hours offset from UTC and mm is the number of minutes offset. Symbolic timezones are not permitted. The timezone specification is recommended but optional, since it is not always available. Clients should display this date as the date a text was written since the imported text will have been created at a later date. @item mx-message-id [22] (text) Data is the @code{Message-ID} header of an imported e-mail. This is used by e-mail importers. LysKOM exporters should set the message ID to @code{ ( @var{reply} ) ; @var{call} [@var{n}] ( @var{request} ) -> ( @var{reply} ) ; ) @end example where each @var{call} is the name of a call, @var{n} is the call number, @var{request} is a single data element sent as a request and @var{reply} is a single data element sent in reply from the server. RPC calls are transmitted as @var{n} @var{request} where @var{n} and @var{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 ( @var{name} : @var{type} ; @var{name} : @var{type} ; ... ) @end example where each @var{name} is the name of a data field and the corresponding @var{type} is its type. Structures are transmitted as a sequence of their fields. @node LysKOM 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 modify-system-info (@pxref{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; forbid-secret; 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 forbid-secret If set, secret members cannot be added to the conference. @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 : INT32; ) 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; keep-commented : Garb-Nice; no-of-members : INT16; first-local-no : Local-Text-No; no-of-texts : INT32; 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 mailbox 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 mailbox 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 keep-commented A text that has comments no older than this number of days will not be 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 @var{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 ::= ( range-begin : Local-Text-No; range-end : Local-Text-No; 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 A @code{Text-Mapping} is used when the client needs to look up which global @code{Text-No} that corresponds to a @code{Local-Text-No}. The client uses @code{local-to-global} to ask for information about a few texts starting a a certain local text number, and the server returns the information in a @code{Text-Mapping}. @table @code @item range-begin The first local text number that the client asked about. @item range-end The first local text number that the reply doesn't say anything about. This @code{Text-Mapping} tells the client about all existing texts from @code{range-begin} to (but not including) @code{range-end}. @item later-texts-exists This is true if there are more texts in the conference after this block. @item block The block can be sent i two formats. The server is free to choose which format to use as it pleases; clients must be prepared for any of them. @itemize @bullet @item The @dfn{sparse} format is useful when many local text number no longer exists. It starts with a @code{0} that indicates that the sparse format is used, and is followed by an array of @code{Text-Number-Pair}. The array will always be sorted so that @code{local-number} always increases. @item The @dfn{dense} format is good when most of the local text numbers exist. It starts with a @code{1} that indicates that the dense format is used, and is followed by a @code{Text-List}. The @code{Text-List} contains @code{first-local-no} and an array of @code{Text-No}. The local text number @code{first-local-no} corresponds to the first @code{Text-No} in the array, @code{first-local-no} + 1 corresponds to the second entry in the array, and so on. The array contains a zero to indicate that a certain local text number doesn't exist. @end itemize @end table @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 @var{aa}@var{bb}@var{cc} where @var{aa} is the major version number, @var{bb} the minor number and @var{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. @c 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 a conference. 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 ::= ( position : INT32; 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 position The position of this membership in the membership list. @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 past, priority zero indicated a passive membership. This usage is now obsolete. @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 @tindex Info-Type @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; ) Info-Type ::= ENUMERATION_OF(Misc-Info) Text-Stat-Old ::= ( creation-time : Time; author : Pers-No; no-of-lines : INT32; no-of-chars : INT32; no-of-marks : INT16; misc-info : ARRAY Misc-Info; ) Text-Stat ::= ( creation-time : Time; author : Pers-No; no-of-lines : INT32; no-of-chars : INT32; 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. @c 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 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}. @c 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 : INT32; 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 : INT32; connection-time : Time; ) 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 : INT32; 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 @c FIXME: should this be user-active-call? The number of seconds since the last server call. @item connection-time The time when the connection was initiated. This is not the same as the 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 @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 case sensitive. @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 @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. @emph{Please note:} the documentation for the obsolete calls may be incomplete. Many of them perform compatibility magic to ensure that they never return anything that old clients don't expect. This compatibility magic is often documented, but we may have forgotten to document it in some places. @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 * login-old:: O Log in to LysKOM. Call 62 is preferred (0) * logout:: r Log out. Call 62 to log in again (1) * change-conference:: r Change current conference (2) * change-name:: r Change name of a conference or person (3) * change-what-i-am-doing:: r Change what-am-i-doing in who information (4) * create-person-old:: O Create a person (5) * get-person-stat-old:: O Get person information. Use call 49 (6) * set-priv-bits:: r Set privileges of a person (7) * set-passwd:: r 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:: r 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:: r Remove a member from a conference (15) * set-presentation:: r Set the presentation of a conference (16) * set-etc-motd:: r Set conference notice (17) * set-supervisor:: r Set supervisor of a conference (18) * set-permitted-submitters:: r Set permitted submitters of a conference (19) * set-super-conf:: r Set super-conference of a conference (20) * set-conf-type:: r Set the type of a conference (21) * set-garb-nice:: r Set garb-nice of a conference (22) * get-marks:: r Get marks for a person (23) * mark-text-old:: O Mark a text. Replaced by calls 72 and 73 (24) * get-text:: r Get an article or part of an article (25) * get-text-stat-old:: O Get text status information (26) * mark-as-read:: r Mark an article as read in a conference (27) * create-text-old:: O Create an article (28) * delete-text:: r Delete an article (29) * add-recipient:: r Add a recipient to an article (30) * sub-recipient:: r Remove a recipient from an article (31) * add-comment:: r Add a comment to an article (32) * sub-comment:: r Remove a comment from an article (33) * get-map:: O Map local text nos to global. Use 103 (34) * get-time:: r Get the current time (35) * get-info-old:: O Get server information (36) * add-footnote:: r Add an article as a footnote to another (37) * sub-footnote:: r Remove a footnote from an article (38) * who-is-on-old:: O Get active sessions. Replaced by call 63 (39) * set-unread:: r Set number of unread in a conference (40) * set-motd-of-lyskom:: r Set LysKOM message of the day (41) * enable:: r Set security level (42) * sync-kom:: r Save the database (43) * shutdown-kom:: r Shut LysKOM down (44) * broadcast:: O Broadcast a message. Replaced by call 53 (45) * get-membership-old:: O Get membership for a person. Use call 99 (46) * get-created-texts:: O Get texts created by a user. Use 104 (47) * get-members-old:: O Get members of a conference. Use 101 (48) * get-person-stat:: r 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. Use call 63 (51) * get-unread-confs:: r Get conferences with unread articles (52) * send-message:: r Send a personal message (53) * get-session-info:: O Get session information. Use call 64 (54) * disconnect:: r Disconnect a session (55) * who-am-i:: r Get current session number (56) * set-user-area:: r Set a person's user area (57) * get-last-text:: r Get text created before a certain time (58) * create-anonymous-text-old:: O Create an anonymous text (59) * find-next-text-no:: r Get next text number (60) * find-previous-text-no:: r Get previous text number (61) * login:: r Log in to LysKOM (62) * who-is-on-ident:: r Get current sessions (63) * get-session-info-ident:: r Get session information (64) * re-lookup-person:: O Look up a person based on name (65) * re-lookup-conf:: O Look up a conference based on name (66) * lookup-person:: O Find persons matching abbreviated name (67) * lookup-conf:: O Find conference matching abbrev'd name (68) * set-client-version:: r Set the name and version the client (69) * get-client-name:: r Get the name of the client (70) * get-client-version:: r Get the version of the client (71) * mark-text:: r Mark a text (72) * unmark-text:: r Unmark a text (73) * re-z-lookup:: r Lookup for conferences and persons (74) * get-version-info:: r Get protocol version of server (75) * lookup-z-name:: r Look up an abbreviated name (76) * set-last-read:: r Set text last read in a conference (77) * get-uconf-stat:: r Get abbreviated conference status (78) * set-info:: r Set server information (79) * accept-async:: r Select asynchronous messages to receive (80) * query-async:: r Ask server which async messages are sent (81) * user-active:: r Tell the server that the user is active (82) * who-is-on-dynamic:: r Get a list of active users (83) * get-static-session-info:: r Get static information about a session (84) * get-collate-table:: r Get the current collate table (85) * create-text:: r Create a text (86) * create-anonymous-text:: r Create an anonymous text (87) * create-conf:: r Create a conference (88) * create-person:: r Create a person (89) * get-text-stat:: r Get text status information (90) * get-conf-stat:: r Get conference status information (91) * modify-text-info:: r Add or delete text aux items (92) * modify-conf-info:: r Add or delete conference aux items (93) * get-info:: r Get server information (94) * modify-system-info:: r Add or delete system aux items (95) * query-predefined-aux-items:: r Get list of aux-items the server knows (96) * set-expire:: e Set the expire field of a conference (97) * query-read-texts:: r Get info on what is read (98) * get-membership:: r Get membership for a person (99) * add-member:: r Add a member to a conference (100) * get-members:: r Get members of a conference (101) * set-membership-type:: r Modify the type of conference (102) * local-to-global:: r Map local text numbers to global ones (103) * map-created-texts:: r Map texts created by a person to glogal (104) * set-keep-commented:: e Set how new comments protect old texts (105) * set-pers-flags:: r Set personal flags (106) @end menu @node login-old @section login-old [0] (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}. @unnumberedsubsec 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 @section logout [1] (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. @unnumberedsubsec Error codes This call never fails. @node change-conference @section change-conference [2] (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.) @unnumberedsubsec 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 conference-zero @code{conference} is zero. @item not-member The user currently logged in is not a member of @code{conference}. @end table @node change-name @section change-name [3] (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. @unnumberedsubsec 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 conference-zero @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 @section change-what-i-am-doing [4] (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. @unnumberedsubsec Error codes @table @code @item string-too-long @code{what-i-am-doing} is too long. @end table @node create-person-old @section create-person-old [5] (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. @unnumberedsubsec 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 @section get-person-stat-old [6] (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}. @unnumberedsubsec 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 conference-zero @code{conference} is zero. @end table @node set-priv-bits @section set-priv-bits [7] (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 @unnumberedsubsec 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 @section set-passwd [8] (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''. @unnumberedsubsec 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 @section query-read-texts-old [9] (1) Obsolete (10) @findex query-read-texts-old @example query-read-texts-old [9] (( person : Pers-No; conference : Conf-No; )) -> ( 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 and @code{conference} is the conference in question. 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. @unnumberedsubsec 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 conference-zero @code{conference} is zero. @item not-member @code{person} is not a member of @code{conference}. @end table @node create-conf-old @section create-conf-old [10] (1) Obsolete (10) @findex create-conf-old @example create-conf-old [10] (( name : HOLLERITH; type : Any-Conf-Type; )) -> ( 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. @unnumberedsubsec 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 @section delete-conf [11] (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. If the conference is a mailbox the corresponding person will also be deleted. @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. @unnumberedsubsec 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 conference-zero @code{conference} is zero. @item permission-denied Not supervisor of @code{conf} and not enough privileges enabled. @item undefined-person @code{conf} is a mailbox but does not exist as a person (the database is corrupt.) @end table @node lookup-name @section lookup-name [12] (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 example looks 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.) @unnumberedsubsec Error codes This call always succeeds. @node get-conf-stat-older @section get-conf-stat-older [13] (1) Obsolete @findex get-conf-stat-older @example get-conf-stat-older [13] (( conf-no : Conf-No; mask : INT32 )) -> ( 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. The @code{mask} argument determines if the name is returned or not. If the lowest bit is 1 the name is returned, otherwise the empty string is returned instead of the name. @unnumberedsubsec Error codes @table @code @item undefined-conference @code{conf-no} does not exist or is secret. @item conference-zero @code{conference} is zero. @end table @node add-member-old @section add-member-old [14] (1) Obsolete (10) @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. In protocol version 10, setting the priority to zero sets the passive bit in the membership. The actual priority is not changed. @i{Example:} @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. @unnumberedsubsec 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 conference-zero @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 @section sub-member [15] (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. @unnumberedsubsec 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 conference-zero @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 @section set-presentation [16] (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. @unnumberedsubsec 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 conference-zero @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 mark-limit Adding a mark to text @code{text-no} would cause it to have too many marks. @end table @node set-etc-motd @section set-etc-motd [17] (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. @unnumberedsubsec 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 conference-zero @code{conference} is zero. @item permission-denied Not enough permissions to set the MOTD of conference @code{conf-no}. @item mark-limit Adding a mark to text @code{text-no} would cause it to have too many marks. @end table @node set-supervisor @section set-supervisor [18] (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 mailbox. @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. @unnumberedsubsec 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 conference-zero @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 @section set-permitted-submitters [19] (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. @unnumberedsubsec 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 conference-zero @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 @section set-super-conf [20] (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. @unnumberedsubsec 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 conference-zero @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 @section set-conf-type [21] (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. @unnumberedsubsec 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 conference-zero @code{conference} is zero. @item secret-public @code{type} has @code{secret} bit but not @code{rd-prot}. @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. @item invalid-membership-type Attemt to change to a conference type that is not compatible with one of more members of the conference (for example, attempting to set @code{forbid-secret} on a conference with a secret member.) @code{error-status} is the id of the first person with an incompatible membership type. @end table @node set-garb-nice @section set-garb-nice [22] (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. @unnumberedsubsec 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 conference-zero @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 @section get-marks [23] (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 13020 with 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. @unnumberedsubsec Error codes @table @code @item login-first Login required before issuing this call. @end table @node mark-text-old @section mark-text-old [24] (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. This call can only set mark-type to a value in the range 1 to 255 (inclusive). If mark-type is set to 0 the mark will be removed. @unnumberedsubsec 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 @section get-text [25] (1) Recommended @findex get-text @example get-text [25] (( text : Text-No; start-char : INT32; end-char : INT32; )) -> ( 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. @unnumberedsubsec 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 @section get-text-stat-old [26] (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. For compatibility reasons this call will only return the misc-infos 0=recpt, 1=cc-recpt, 2=comm-to, 3=comm-in, 4=footn-to, 5=footn-in, 6=loc-no, 7=rec-time, 8=sent-by and 9=sent-at. Newer misc-infos will either be removed or converted to a similar one. Specifically, 15=bcc-recpt may (at the servers discretion) be converted to 1=cc-recpt or omitted entirely. @example 1 26 100 @t{=1 7 35 16 15 6 96 1 196 1 14 1 22 1 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. @unnumberedsubsec 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 @section mark-as-read [27] (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. @unnumberedsubsec 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 conference-zero @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 @section create-text-old [28] (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. @unnumberedsubsec 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 @section delete-text [29] (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. @unnumberedsubsec 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 @section add-recipient [30] (1) Recommended @findex add-recipient @example add-recipient [30] (( text-no : Text-No; conf-no : Conf-No; recpt-type : Info-Type; )) -> ( ); @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. @unnumberedsubsec 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 conference-zero @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. @item access-denied Attempt to add a conference as recipient that the person logged on does not have permission to add texts to. The client may have to chase the super conf chain. @end table @node sub-recipient @section sub-recipient [31] (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 @t{=1} 1 26 1 @t{=1 2 22 12 17 6 97 4 197 1 5 4 256 1 0 *} 1 31 1 5 @t{%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. @unnumberedsubsec 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 conference-zero @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 @section add-comment [32] (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. @unnumberedsubsec 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. The error-status is @code{text-no}. @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 @section sub-comment [33] (1) Recommended @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. @unnumberedsubsec 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 not-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 @section get-map [34] (1) Recommended @findex get-map @example get-map [34] (( conf-no : Conf-No; first-local-no : Local-Text-No; no-of-texts : INT32; )) -> ( 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{first-local-no} in the returned @code{Text-List} to the first text that still exists. The size of the returned array will be decreased by the same amount as @code{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{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. @unnumberedsubsec 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 conference-zero @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 @section get-time [35] (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. @unnumberedsubsec Error codes This call always succeeds @node get-info-old @section get-info-old [36] (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. @unnumberedsubsec Error codes This call always succeeds. @node add-footnote @section add-footnote [37] (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. @unnumberedsubsec 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 @section sub-footnote [38] (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. @unnumberedsubsec 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 @section who-is-on-old [39] (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. @unnumberedsubsec Error codes This call always succeeds. @node set-unread @section set-unread [40] (1) Recommended @findex set-unread @example set-unread [40] (( conf-no : Conf-No; no-of-unread : INT32; )) -> ( ); @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. @unnumberedsubsec 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 @section set-motd-of-lyskom [41] (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 a privileged 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. @unnumberedsubsec 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 @section enable [42] (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}. @unnumberedsubsec Error codes @table @code @item login-first Login required before issuing this call. @end table @node sync-kom @section sync-kom [43] (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{:0 7} @t{:0 7} @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. @unnumberedsubsec 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 @section shutdown-kom [44] (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. @unnumberedsubsec 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 @section broadcast [45] (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. @unnumberedsubsec 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 @section get-membership-old [46] (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. Servers that support protocol version 10 will return a priority of zero if the passive bit in the membership record has been set (either by a set-membership-type or by setting the priority of the conference to zero.) @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. @unnumberedsubsec 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 @section get-created-texts [47] (1) Obsolete (10) @findex get-created-texts @example get-created-texts [47] (( person : Pers-No; first : Local-Text-No; no-of-texts : INT32; )) ( Text-List ); @end example This call is obsolete; instead you should use @ref{map-created-texts}. 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. @unnumberedsubsec 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 @section get-members-old [48] (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. @unnumberedsubsec 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 @section get-person-stat [49] (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. @unnumberedsubsec 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 @section get-conf-stat-old [50] (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 mailbox. @unnumberedsubsec Error codes @table @code @item undefined-conference The conference @code{conf-no} does not exist or is secret. @end table @node who-is-on @section who-is-on [51] (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}.) @unnumberedsubsec Error codes This call always succeeds. @node get-unread-confs @section get-unread-confs [52] (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. Passive memberships are never returned. The returned conference numbers will be returned in the same order as they appear on the persons list of memberships. @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. @unnumberedsubsec 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 @section send-message [53] (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. If @code{recipient} is 0, the message is sent to all sessions that are 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 @unnumberedsubsec 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 or there are no viable recipients for a group message. @end table @node get-session-info @section get-session-info [54] (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. @unnumberedsubsec 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 disconnect @section disconnect [55] (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. Session number zero is always interpreted as the session making the call, so the easiest way to disconnect the current session is to disconnect session zero. @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 (disconnection session 0 would have had the same effect.) 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. @unnumberedsubsec 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 @section who-am-i [56] (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. @unnumberedsubsec Error codes This call always succeeds. @node set-user-area @section set-user-area [57] (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. @unnumberedsubsec 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 @section get-last-text [58] (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. This call assumes that all texts are written in chronological order, when the time is expressed in the local time zone of the server. That may not always be the case in real life. When daylight savings time reverts to standard time the same time span will occur twice. The clock of the server may also have been adjusted manually from time to time. This protocol specification does not mandate what the server should do in such cases. @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. @unnumberedsubsec Error codes This call never fails. @node create-anonymous-text-old @section create-anonymous-text-old [59] (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. @unnumberedsubsec 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 @section find-next-text-no [60] (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. @unnumberedsubsec Error codes @table @code @item no-such-text There is no text following text @code{start}. @end table @node find-previous-text-no @section find-previous-text-no [61] (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. @unnumberedsubsec Error codes @table @code @item no-such-text There is no text preceding text @code{start}. @end table @node login @section login [62] (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} if @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. @unnumberedsubsec 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} and does 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 @section who-is-on-ident [63] (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 returns a list of all visible sessions. @unnumberedsubsec Error codes This call always succeeds. @node get-session-info-ident @section get-session-info-ident [64] (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. @unnumberedsubsec 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 @section re-lookup-person [65] (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 returns a list of persons matching the regular expression @code{regexp}. The regexp syntax used is that of the @code{ed}(1) Unix utility. @unnumberedsubsec 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 @section re-lookup-conf [66] (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 returns a list of conferences matching the regular expression @code{regexp}. The regexp syntax used is that of the @code{ed}(1) Unix utility. @unnumberedsubsec 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 @section lookup-person [67] (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 returns a list of persons with names matching the contracted name in @code{name}. See @pxref{Name Expansion} for a description of the matching process. @unnumberedsubsec Error codes This call always succeeds. @node lookup-conf @section lookup-conf [68] (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 returns a list of conferences with names matching the contracted name in @code{name}. See @pxref{Name Expansion} for a description of the matching process. @unnumberedsubsec Error codes This call always succeeds. @node set-client-version @section set-client-version [69] (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. This call should be used exactly once per session. The following names are currently reserved for clients: @multitable @columnfractions .3 .7 @item elisp-client @tab The famous CPU hog. @item nilkom @tab C++ experiment @item tkom @tab C++ experiment @item getmail @tab Postmaster @item ttykom @tab The one and second tty client by Linus @item WinKOM @tab Windows client @item JySKom @tab JSK Web Client @end multitable @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''. @unnumberedsubsec Error codes @table @code @item string-too-long The string @code{client-name} or @code{client-version} is too long. @item client-is-crazy The client attempted to use this call more than once. The error-status is undefined. @end table @node get-client-name @section get-client-name [70] (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. @unnumberedsubsec 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 @section get-client-version [71] (6) Recommended @findex get-client-version @example get-client-version [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. @unnumberedsubsec 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 @section mark-text [72] (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 0 *} 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. @unnumberedsubsec 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 @section unmark-text [73] (6) 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 0 *} @end example This example shows how a user with a mark set on text number 110 removes it using the @code{unmark-text} call. @unnumberedsubsec 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 @section re-z-lookup [74] (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-mailbox conferences. If @code{want-persons} is true, then the result will include mailbox 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.*[cC] 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.*[cC]''. @unnumberedsubsec 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 @section get-version-info [75] (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. @unnumberedsubsec Error codes This call always succeeds. @node lookup-z-name @section lookup-z-name [76] (7) Recommended @findex lookup-z-name @example lookup-z-name [76] (( name : HOLLERITH; want-pers : BOOL; want-confs : 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 mailboxes. If @code{want-pers} is true, then the result will include conferences that are mailboxes. 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 76 0H 1 1 @t{=1 4 @{ 15HTest Conference 0000 10 11HDavid Byers 1001 6} @t{ 21HTrains (-) Discussion 0000 11 4HJohn 1001 9 @}} 2 76 0H 0 1 @t{=1 2 @{ 15HTest Conference 0000 10} @t{ 21HTrains (-) Discussion 0000 11@}} 3 76 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''. @unnumberedsubsec Error codes This call always succeeds. @node set-last-read @section set-last-read [77] (8) Recommended @findex set-last-read @example set-last-read [77] (( conference : Conf-No; last-read : Local-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. @unnumberedsubsec 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 @section get-uconf-stat [78] (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. @unnumberedsubsec Error codes @table @code @item undefined-conference The conference @code{conference} does not exist or is secret. @item conference-zero @code{conference} is zero. @end table @node set-info @section set-info [79] (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-old}. 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. @unnumberedsubsec 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. @item text-zero This error message should never be returned, but lyskomd 1.9.0 erroneously returned this error message if the MOTD text in @code{info} was set to 0. That should mean that there should be no message of the day, and the current implementation of the server does accept MOTD to be 0. @end table @node accept-async @section accept-async [80] (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). @unnumberedsubsec 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.) @item long-array The @code{request-list} was too long. Servers should always accept a @code{request-list} that contains a lot more asynchronous messages than the server sends, so that it can deal with newer clients. This error message should only be returned if the client tries to trigger a buffer overrun. @end table @node query-async @section query-async [81] (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. @unnumberedsubsec Error codes This call always succeeds. @node user-active @section user-active [82] (9) Recommended @findex user-active @example user-active [82] ( ) -> ( ); @end example This call simply notifies the server that the user is active. The server uses the time of the last user-active call to calculate how long a user has been idle. The client should send this to the server every time the user actively does something LysKOM-related, such as reads a texts, writes on a comment, gives a command, de-iconifies the LysKOM window, et c. However, the call should not be issued more than twice per minute, to avoid excessive network and server load. @unnumberedsubsec Error codes This call always succeeds. @node who-is-on-dynamic @section who-is-on-dynamic [83] (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. Only sessions with the desired visibility and activeness are returned. 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 they are both true sessions will be included in the answer regardless of their visibility status. Sessions where no-one is logged in are considered invisible, and the @code{invisible} flag is set in the corresponding @code{Dynamic-Session-Info} that is returned. If @code{active-last} is zero then the result is a list of all sessions with the proper visibility. If @code{active-last} is nonzero then only sessions that have issued an @code{user-active} call within the last @code{active-last} seconds are included in the list. Sessions that have never issued an @code{user-active} call are always included (if they have the proper visibility). @unnumberedsubsec Error codes This call always succeeds. @node get-static-session-info @section get-static-session-info [84] (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}. The returned information cannot change until the session number is reused (and that cannot happen until the server is shut down), so clients are encouraged to cache the information. @unnumberedsubsec 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 @section get-collate-table [85] (10) Recommended @findex get-collate-table @example get-collate-table [85] ( ) -> ( HOLLERITH ); @end example This call returns the collate table being used by the server to match names. If index A and index B in the string are the same character, characters A and B are considered equivalent. An empty collate table indicates that the server considers all characters different. Currently, the lyskomd server only deals with 8-bit characters. Clients should be prepared for collate tables of any length. Characters whose code are greater than the length of the collate table should be considered to be unique. @unnumberedsubsec Error codes This call always succeeds. @node create-text @section create-text [86] (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. @unnumberedsubsec 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 index-out-of-range Attempt to create a text failed because we reached the maximum number of texts permitted. @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 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. @item long-array Too many misc-items or aux-items were specified. @end table @node create-anonymous-text @section create-anonymous-text [87] (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. @unnumberedsubsec 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 @section create-conf [88] (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}). @unnumberedsubsec 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. May also be an attempt to create a conference with the letterbox 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 @section create-person [89] (10) Recommended @findex create-person @example create-person [89] (( name : HOLLERITH; passwd : HOLLERITH; flags : Personal-Flags; 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 mailbox conference. The person flags are set to @code{flags}. 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. Unlike call number 5, this call does not automatically do an automatic login. @unnumberedsubsec 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 person-exists There is already a person 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 mailboxes or whatever. @item aux-item-permission One of the items looks valid but could not be created anyway. @end table @node get-text-stat @section get-text-stat [90] (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. @unnumberedsubsec 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 @section get-conf-stat [91] (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}. @unnumberedsubsec Error codes @table @code @item undefined-conference The conference @code{conf-no} does not exist or is secret. @end table @node modify-text-info @section modify-text-info [92] (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. @unnumberedsubsec 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 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 @section modify-conf-info [93] (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. @unnumberedsubsec 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 @section get-info [94] (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. @unnumberedsubsec Error codes This call always succeeds. @node modify-system-info @section modify-system-info [95] (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. @unnumberedsubsec 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 @section query-predefined-aux-items [96] (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. @unnumberedsubsec Error codes This call always succeeds. @node set-expire @section set-expire [97] (10) Experimental @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. @unnumberedsubsec 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 @section query-read-texts [98] (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 and @code{conference} is the conference in question. Calling @code{query-read-texts} 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. @c FIXME: Is the example correct? Shouldn't there be a time @c after "5" and before "01000000"? / kent 990711 @unnumberedsubsec 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 conference-zero @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 @section get-membership [99] (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 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. 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 } @t{ 49 14 17 13 8 91 5 255 1 00000000 @}} 1 99 5 0 1 1 @t{=1 1 @{ 49 14 17 13 8 91 5 255 1 5 255 0 0 * 5 } @t{ 49 14 17 13 8 91 5 255 1 00000000 @}} 1 99 5 1 4 1 @t{=1 1 @{ 20 14 22 17 6 97 4 197 1 6 100 2 0 * 5 } @t{ 49 14 17 13 8 91 5 255 1 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. @unnumberedsubsec 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 @section add-member [100] (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. @unnumberedsubsec 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 conference-zero @code{conference} is zero. @item undefined-person Person @code{pers-no} does not exist @item access-denied @c FIXME: the "or to change" part is bogus, right? Aren't those @c cirumstances covered by permission-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 @section get-members [101] (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. @unnumberedsubsec 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 @section set-membership-type [102] (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. @unnumberedsubsec Error codes @table @code @item login-first Login required before issuing this call. @item conference-zero @code{conf} is zero. @item undefined-conference The conference @code{conf} does not exist or is secret or the person @code{pers} does not exist or is secret. @item permission-denied Insufficient permissions to change the membership of @code{pers}. @item not-member Person @code{pers} is not a member of conference @code{conf}. @item invalid-membership-type The requested membership type @code{type} was not compatible with restrictions set on the server or on the conference @code{conf} @end table @node local-to-global @section local-to-global [103] (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 : INT32; )) -> ( Text-Mapping ); @end example This call retrieves information that makes it possible to convert @code{no-of-existing-texts} existing local text numbers starting at @code{first-local-no} to global text numbers, provided that there are that many local texts. The @code{conf-no} parameter specifies which conference to look up local numbers in. @code{first-local-no} is the first number that the client is interested in. @code{no-of-existing-texts} is the maximum number of texts the client wants information about. Legal values for @code{no-of-existing-texts} are 1-255 (inclusive). The server will return a sparse or dense Text-Mapping depending on the how many deleted texts there are after @code{first-local-no}. @example 1 103 93 1 5 @t{=1 1 7 1 1 1 6 @{ 1003 1005 1009 1029 0 1034 @}} 2 103 93 1 6 @t{=2 1 63 1 0 6 @{ 1 1003 2 1005 3 1009 4 1029 6 1034 62 1302 @}} 3 103 93 50 10 @t{=3 50 70 0 0 2 @{ 62 1302 69 1006 @}} @end example The above example shows three calls to @code{local-to-global}. (Extra newlines have been inserted in the result of the two final calls to make the result more readable.) The first call requests information about the first five existing texts in conference 93. The result contains information about texts in the range [1-7), and there are more texts. The server uses the dense form of the Text-Mapping. As can be seen from the result, they have local text numbers 1, 2, 3, 4 and 6. The global text number corresponding to local text number 5 is sent as 0, indicating that it doesn't exist. In the second call, the client requests the same information, but one additional text. The result looks dramatically different, since the next existing text in this example has local text number 62. The result contains information about texts in the range [1-63), and there are more texts. The server of course uses the sparse form of the Text-Mapping. The final call shows what happens when @code{first-local-no} doesn't exist. The result contains information about texts in the range [50-70); only local text number 62 and 69 actually exists in that range. 69 is the highest local text number. (Note that local text number 69 corresponds to global text number 1006, which is lower than 1302. Situations like this often occurs when @code{add-recipient} is used.) @unnumberedsubsec Error codes @table @code @item login-first Login required before issuing this call. @item long-array @code{no-of-existing-texts} was larger than 255. @item conf-zero @code{conf-no} was set to 0. @item local-text-zero @code{first-local-no} was set to 0. @item undef-conf The conference does not exist, or the client is not allowed to know that it exists. @item access-denied The conference exists, but the client is not allowed to retrieve information about the texts in the conference. @item no-such-local-text @code{first-local-no} is greater than the highest local text number that ever existed in the conference. @end table @node map-created-texts @section map-created-texts [104] (10) Recommended @findex map-created-texts @example map-created-texts [104] (( author : Pers-No; first-local-no : Local-Text-No; no-of-existing-texts : INT32; )) -> ( Text-Mapping ); @end example Return text numbers for existing texts that @code{author} has written. Just as each conference has a mapping from local text numbers to global text numbers, each person has a mapping from the N:th text written by him to the global text number. This function can be used to retrieve part of that mapping. More information and examples may be found in @ref{local-to-global}. @unnumberedsubsec Error codes @table @code @item login-first Login required before issuing this call. @item long-array @code{no-of-existing-texts} was larger than 255. @item conf-zero @code{conf-no} was set to 0. @item local-text-zero @code{first-local-no} was set to 0. @item undef-pers The conference does not exist, or the client is not allowed to know that it exists. @item no-such-local-text @code{first-local-no} is greater than the highest local text number that ever existed in the conference. @item access-denied The conference exists, but the client is not allowed to retrieve information about the texts in the conference. @end table @node set-keep-commented @section set-keep-commented [105] (10) Experimental @findex set-keep-commented @example set-keep-commented [105] (( conf-no : Conf-No; keep-commented : Garb-Nice; )) -> ( ); @end example Sets the @code{keep-commented} field of the conference @code{conf-no} to @code{keep-commented}. This call can only be issued by a conference's supervisor or a privileged user. @unnumberedsubsec 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 set-pers-flags @section set-pers-flags [106] (10) Recommended @findex set-pers-flags @example set-pers-flags [106] (( pers-no : Pers-no; flags : Personal-Flags; )) -> ( ); @end example Set the flags field of person @code{pers-no} to @code{flags}. This call can only be issued by the person supervisor or a privileged user. @unnumberedsubsec Error Codes @table @code @item login-first Login required before issuing this call. @item conference-zero The @code{pers-no} parameter is zero. @item undefined-person The person does not exist, or the session does not have permission to know about the person. @item permission-denied Person exists, but the session does not have permission to change the flags. @end table @node Asynchronous Messages @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 @pxref{accept-async} call. They can find out which messages are being sent by issuing the @pxref{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 @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 number 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 @ref{accept-async}. @menu * async-new-text-old:: r 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:: r Conference or person changed name (5) * async-i-am-on:: r Client changed i-am-doing string (6) * async-sync-db:: r Server is saving the database (7) * async-leave-conf:: r Person has been removed from a conference (8) * async-login:: r Someone has logged in (9) * async-broadcast:: O Broadcast message (obsolete) (10) * async-rejected-connection:: r LysKOM is full. Log out to make room. (11) * async-send-message:: r Text message to group or person (12) * async-logout:: r A person has logged out (13) * async-deleted-text:: r A text was deleted (14) * async-new-text:: r A text has been created (15) * async-new-recipient:: r A new recipient has been added to a text (16) * async-sub-recipient:: r A recipient has been removed from a text (17) * async-new-membership:: r A user has been added to a conference (18) ------------------------------------------------------------------------------- @end menu @node async-new-text-old @section 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 @section 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 @section 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 @section 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 @section 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}. @c FIXME: can the username change? @node async-sync-db @section 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 @section async-leave-conf (1) Recommended @example async-leave-conf [8] ( conf-no : Conf-No ); @end example This message is sent to a user when the user's membership in the working conference is removed for any reason. The conference the user is being removed from is sent in @code{conf-no}. Earlier versions of the LysKOM Protocol A specifications stated that this message was only sent if the membership was "revoked forcefully". The exact meaning of that phrasing was never specified. The lyskomd implementation has probably always followed the current version of the specification, which means that this message is sent whatever the reason for the removal is. Possible reasons include: @itemize @bullet @item The session issued a @ref{sub-member} call. @item Some other session issued a @ref{sub-member} call. @item The conference was deleted. @item The person was deleted. @end itemize This message is not sent if a membership is transformed from an active to a passive membership. @node async-login @section 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 @section 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, but is no longer used. @node async-rejected-connection @section 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 @section 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 mailbox then the message is personal and is only sent to members of the mailbox conference. @node async-logout @section 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. This message might also be sent when a session disconnects, even if there is nobody logged on in the session. @node async-deleted-text @section 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 @section 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 async-new-recipient @section async-new-recipient (10) Recommended @example async-new-recipient [16] (( text-no : Text-No; conf-no : Conf-No; type : Info-Type; )); @end example This message indicates that a new recipient has been added to text @code{text-no}. The recipient added is @code{conf-no} and the type of recipient is indicated by @code{type}. This message is sent to all recipients of the text that are permitted to know about the new recipient. @node async-sub-recipient @section async-sub-recipient (10) Recommended @example async-sub-recipient [17] (( text-no : Text-No; conf-no : Conf-No; type : Info-Type; )); @end example This message indicates that a recipient has been removed from text @code{text-no}. The recipient removed is @code{conf-no} and the type of recipient is indicated by @code{type}. This message is sent to everybody that were recipients of the text and that were permitted to know about the recipient. @node async-new-membership @section async-new-membership (10) Recommended @example async-new-membership [18] (( pers-no : Pers-No; conf-no : Conf-No; )); @end example This message indicates that the membership for @code{pers-no} in conference @code{conf-no} has been added. This message is currently sent only to @code{pers-no}, but that may change in the future. See also @pxref{async-leave-conf}. @node Error Codes @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 ::= normal-error | special-error normal-error ::= ( "%" ref-no : INT32; error-no : Error-No; error-status : INT32; ) special-error ::= "%% LysKOM protocol error." | "%%Insane token length." | "%%Insane array size." | "%%No connections left." error-no ::= INT32; @end example The server may return two different types of errors. Normal errors are replies to syntactically correct calls to the server. Special errors are replies to syntactically incorrect calls and responses to exceptional conditions. 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. @menu * Special Errors:: * Normal Errors:: @end menu @node Special Errors @section Special Errors Special errors are sent in reply to syntactically incorrect calls to the server. With the exception of the "No connections left" message, these should never appear in the client-server dialog. If they do, there is probably a bug in the client. @table @asis @item "%% LysKOM protocol error." The client has sent a request that does not comply with protocol A. The server will attempt to recover from this error, but additional calls may be silently lost, and the server may send replies that the client does not expect. This error is also returned when the client sends an array that is longer than the maximum allowed by the server. @item "%%No connections left." This error is only sent when the client attempts to connect to the server. It indicates that the server is not accepting additional connections. This error is transient: the client may be able to connect later. Clients should not attempt to connect immediately after receiving this message. @item "%%Insane token length." The client has sent a single token that is insanely long. Typically this means that the client has sent several kilobytes worth of digits, or something similar. This is never returned for long strings. The server will automatically disconnect a client who sends a token with an insane length. @item "%%Insane array size." The client has send an array with a negative length. The server is not easily fooled. The server will automatically disconnect a client who sends an array with an insane length. @end table @node Normal Errors @section Normal Errors Normal errors are sent in reply to syntactically correct calls to the server. The client should accept any error code in response to any call, even if the error code in question is not listed in the description of the call, and even if the error code in question is not defined in the protocol specification yet. @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 unless stated otherwise in the call documentation. @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 @code{secret} bit set and the @code{rd-prot} bit unset. 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 (or Info-Type value) that the server knows nothing about. @code{error-status} is the type. @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 footnotes. @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 or there are no viable recipients for a group message. @code{error-status} is undefined. @item invalid-membership-type (54) A requested membership type was not compatible with restrictions set on the server or on a specific conference. @code{error-status} is undefined unless specifically mentioned in the documentation for a specific call. @end table @node LysKOM Content Types @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) @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) @section The User Area @node Conference Lists (x-kom/conflist) @section Conference Lists @node The User Area @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 completely undocumented, but you'll need a lisp reader to parse it. @item WWW-kom The block created by the web gateway WWW-kom. It has the same syntax as the common block, but the keys and values are not documented. @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 a conference. 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 @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 @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 @subsection What do I have unread Each person has a membership list containing the conferences the person is a member of. Each element is an object of type Membership. Among other things it contains the number of the conference, the priority of the membership, when the person most recently marked a text as read in the conference, and which texts the person has read. The list of read texts consists of two parts: a local text number called @code{last-text-read} and a list of local text numbers called @code{read-texts}. The person has marked all texts up to and including @code{last-text-read} as read, and also the texts listed in @code{read-texts}. All other texts in the conference are unread. Clients can use either the @code{query-read-texts} or @code{get-membership} calls to get membership data. The standard procedure for finding out which texts are unread is the following: @enumerate @item Call @code{get-unread-confs} for the person. This returns a list of conferences in which the person may have unread texts. This call may return conferences that do not contain any unread texts, but it will never forget to return a conference that does contain an unread text. @item Call @code{query-read-texts} for each conference returned in the previous step. This will return the membership data for all the conferences that may contain unread texts. @item Call @code{get-conf-stat} for each conference returned in the first step. The conference status will be needed shortly. Repeat the following steps for each conference. @item Compare the highest existing local number in the conference (from the conference status) with the @code{last-text-read} field for the corresponding membership. If the highest existing local text is higher than @code{last-text-read}, the conference may contain unread texts. @item Get part of the local to global map from the conference starting at @code{last-text-read} and ending at the highest existing local number. Every local number in the map that is not read according to the membership data and that has a mapping to a global number is an unread text. You might say that you remove the read texts from the map to get the unread texts. @end enumerate Take care not to call get-map or get-membership too much since they tend to be expensive operations. Use @code{get-unread-confs} and @code{query-read-texts} to minimize the work. Another point to remember is that the server will send asynchronous messages with information about new texts. Clients need to listen to these messages. @node Only read the most recent N texts @subsection Only read the most recent N texts @node Review the last N by FOO to BAR @subsection Review the last N by FOO to BAR @node Client Conventions @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 @subsection 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 @subsection 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 @subsection Remote control 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 Importing and Exporting E-Mail @chapter Importing and Exporting E-Mail E-mail importing and exporting is not implemented. This chapter contains suggestions for how to do it. The first person to implement a forwarder should rewrite this section based on his or her experiences. There are some holes in this description. For example, it was suggested at some point that it might be possible to use inheritance for automatic export of messages from conferences, so that people could more or less participate in mailing lists but only use the LysKOM interface. Importing and exporting will be implemented through a special client and user. The client can log on periodically and check if any new texts have been created. It should store the last text number it examined, and use the get-next-text call to find any new texts. @section Exporting E-Mail For each text the exporter examines, it has to check if the text needs to be exported. A text will have to be exported if it has an @code{mx-to} aux-item, if the text was not imported or if the item was added after the text was imported. The exportes is responsible for setting the @code{Date}, @code{Message-ID}, @code{From}, @code{Reply-To}, @code{To}, @code{CC} and @code{In-Reply-To} fields in the exported message. @table @code @item Date The date should be set to the date the text was created, not the date the text was exported. @item Message-ID The message ID is to have the format @code{}, where @var{textno} is the text number in the server and @var{server} is the name of the LysKOM server. This allows the importer to figure out how to thread e-mail replies to exported messages. @item From If the message originates with the LysKOM server, the exporter constructs a valid @code{From} address, that when replied to will cause the importer to give the message the correct recipients. If the message originates outside of the LysKOM server (it is imported), the exporter uses the @code{mx-from} item to get the @code{From} header. @item Reply-To If the message originates with the LysKOM server and the author of the text has a @code{redirect} aux-item set, the exporter should use it to construct a @code{Reply-To} header. If the message is imported to LysKOM, the exporter should use the @code{mx-reply-to} item, if there is one, to construct this header. @item To @item CC The @code{mx-to} and @code{mx-cc} aux-items contain the values for these headers. @item In-Reply-To If the message is a comment to an impored message, the exporter is to use the @code{mx-message-id} aux-item of the commented texts for the @code{In-Reply-To} header. If the commented text is not imported, the exporter is to construct a message ID for the commented text using the same method as for the @code{Message-ID} header. @end table For the mail exporter to work, it will need special privileges. @section Importing The main job of the mail importer is to figure out where to deliver mail and how to deal with threading. The importer can find the recipients in the @code{To} and @code{CC} headers of the message. The current (very simple) importer uses addresses like ``p@i{person}@@@i{server}´´, where @i{person} is the number of the recipient and @i{server} is the LysKOM server. The importer should add recipients in the @code{CC} header as carbon-copy-recipients, and recipients in the @code{To} header as regular recipients. The importer needs to be careful not to deliver messages to conferences that do not allow messages, even though the server might not complain. For mail delivery to work, the importer has to run as a privileged user, or it would be unable to deliver mail to secret conferences. A potential problem is that this leaks secret information from the server, so it should probably be possible to configure on a per-conference basis whether it accepts imported e-mail. This is currently not possible, but can easily be implemented, should the implementor of the first good importer want it. @subsection Threading The importer should do its best to thread messages. When the importer sees a new message it needs to look at the @code{In-Reply-To} header to see what the message is a reply to. If a previously imported message or a LysKOM text is in the @code{In-Reply-To} header, the new text should be made a comment to the replied-to text. This means that the importer will probably have to maintain its own database of imported texts that maps the message ID to the text number in the LysKOM database. There is no other way to find the text number for a particular imported text. @section An Algorithm, Sort Of Here's an outline for algorithms for import and export of messages. They're hardly complete, and may not even quite work, but they should give the general idea of how things can work. @example function import-message (message) @{ recipient_list = To header of message cc_list = CC header of message delete recipients from recipient_list that do not want imported mail delete recipients from cc_list that do not want imported mail for each element el in In-Reply-To header of message if el is a LysKOM message ID text_no = text number of el if el is in the imported database text_no = text number from database if text_no is set add text_no to comm_to result = create_text with recipients = recipient_list cc-recipients = cc_list comment-to = comm_to aux-items extracted from header if result is a failure, construct and send a bounce put Message-ID and result into the imported database @} function exporter () @{ text_no = last_examined_text_no while text_no = get-next-text if (text text_no is not imported or text text_no has an mx-to item created after the text) message = get-text text_no message-ID = date = creation-date of message to = mx-to item of text text_no cc = mx-cc item of text text_no add e-mail of LysKOM cc-recipients to text text_no to cc if there is an mx-from item of text text_no from = mx-from item of text text_no else mx-from = e-mail of author in LysKOM send the message @} @end example @node Type Index @chapter Type Index @printindex tp @node Request Index @chapter Request Index @printindex fn @contents @bye