This is protocol-a.info, produced by makeinfo version 4.8 from Protocol-A.texi. This is the LysKOM Protocol A specification, edition 11.1. It specifies version 11 of the protocol. It was first distributed with version 2.1.2 of lyskomd. Copyright (C) 1995-2005 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. 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. INFO-DIR-SECTION LysKOM START-INFO-DIR-ENTRY * Protocol A: (protocol-a). The LysKOM Protocol A specification. END-INFO-DIR-ENTRY  File: protocol-a.info, Node: async-rejected-connection, Next: async-send-message, Prev: async-broadcast, Up: Asynchronous Messages 7.11 async-rejected-connection [11] (1) Recommended =================================================== async-rejected-connection [11] ( ); 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.  File: protocol-a.info, Node: async-send-message, Next: async-logout, Prev: async-rejected-connection, Up: Asynchronous Messages 7.12 async-send-message [12] (1) Recommended ============================================ async-send-message [12] (( recipient : Conf-No; sender : Pers-No; message : HOLLERITH )); This message is sent when someone (the `sender') sends a message string (the `message'). The recipient of the message is sent in `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. The `passive' and `passive-message-invert' bits of the membership influence if this message is sent. *Note Membership-Type::.  File: protocol-a.info, Node: async-logout, Next: async-deleted-text, Prev: async-send-message, Up: Asynchronous Messages 7.13 async-logout [13] (1) Recommended ====================================== async-logout [13] (( pers-no : Pers-No; session-no : Session-No )); This message is sent when someone logs out. `pers-no' is the person logging out and `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.  File: protocol-a.info, Node: async-deleted-text, Next: async-new-text, Prev: async-logout, Up: Asynchronous Messages 7.14 async-deleted-text [14] (10) Recommended ============================================= async-deleted-text [14] (( text-no : Text-No; text-stat : Text-Stat )); This message is sent when a text is deleted and the currently logged-in person is a member of one of the recipients, or a recipient of any text that is linked to this text via a comment or footnote link. The text number being deleted is sent in `text-no' and the text stat in `text-stat'.  File: protocol-a.info, Node: async-new-text, Next: async-new-recipient, Prev: async-deleted-text, Up: Asynchronous Messages 7.15 async-new-text [15] (10) Recommended ========================================= async-new-text [15] (( text-no : Text-No; text-stat : Text-Stat )); This message indicates that a new text has been created. The text has number `text-no', and the text stat is `text-stat'. The message is sent to all logged-in members of any recipient of the text, any text it is a comment of, and any text it is a footnote of.  File: protocol-a.info, Node: async-new-recipient, Next: async-sub-recipient, Prev: async-new-text, Up: Asynchronous Messages 7.16 async-new-recipient [16] (10) Recommended ============================================== async-new-recipient [16] (( text-no : Text-No; conf-no : Conf-No; type : Info-Type )); This message indicates that a new recipient has been added to text `text-no'. The recipient added is `conf-no' and the type of recipient is indicated by `type'. This message is sent to all recipients of the text (of any text that is linked to this text via a comment or footnote link) that are permitted to know about the new recipient.  File: protocol-a.info, Node: async-sub-recipient, Next: async-new-membership, Prev: async-new-recipient, Up: Asynchronous Messages 7.17 async-sub-recipient [17] (10) Recommended ============================================== async-sub-recipient [17] (( text-no : Text-No; conf-no : Conf-No; type : Info-Type )); This message indicates that a recipient has been removed from text `text-no'. The recipient removed is `conf-no' and the type of recipient is indicated by `type'. This message is sent to everybody that were recipients of the text (or any text that is linked to this text via a comment or footnote link) and that were permitted to know about the recipient.  File: protocol-a.info, Node: async-new-membership, Next: async-new-user-area, Prev: async-sub-recipient, Up: Asynchronous Messages 7.18 async-new-membership [18] (10) Recommended =============================================== async-new-membership [18] (( pers-no : Pers-No; conf-no : Conf-No )); This message indicates that the membership for `pers-no' in conference `conf-no' has been added. This message is currently sent only to `pers-no', but that may change in the future. See also *Note async-leave-conf::.  File: protocol-a.info, Node: async-new-user-area, Next: async-new-presentation, Prev: async-new-membership, Up: Asynchronous Messages 7.19 async-new-user-area [19] (11) Recommended ============================================== async-new-user-area [19] (( pers-no : Pers-No; old-user-area : Text-No; new-user-area : Text-No )); This message indicates that the user-area of `pers-no' has changed from `old-user-area' to `new-user-area'. This message is sent to all supervisors of `pers-no' (which of course includes `pers-no' himself).  File: protocol-a.info, Node: async-new-presentation, Next: async-new-motd, Prev: async-new-user-area, Up: Asynchronous Messages 7.20 async-new-presentation [20] (11) Recommended ================================================= async-new-presentation [20] (( conf-no : Conf-No; old-presentation : Text-No; new-presentation : Text-No )); This message indicates that the presentation of `conf-no' has changed from `old-presentation' to `new-presentation'. This message is sent to everybody who is allowed to see `conf-no'. If the conference had no presentation, `old-presentation' will be 0. Likewise, if the presentation of the conference was removed, `new-presentation' will be 0.  File: protocol-a.info, Node: async-new-motd, Next: async-text-aux-changed, Prev: async-new-presentation, Up: Asynchronous Messages 7.21 async-new-motd [21] (11) Recommended ========================================= async-new-motd [21] (( conf-no : Conf-No; old-motd : Text-No; new-motd : Text-No )); This message indicates that the `msg-of-day' of `conf-no' has changed from `old-motd' to `new-motd'. This message is sent to everybody who is allowed to see `conf-no'. If the conference had no message-of-the-day, `old-motd' will be 0. Likewise, if the motd of the conference was removed, `new-motd' will be 0.  File: protocol-a.info, Node: async-text-aux-changed, Next: async-text-read, Prev: async-new-motd, Up: Asynchronous Messages 7.22 async-text-aux-changed [22] (11) Recommended ================================================= async-text-aux-changed [22] (( text-no : Text-No; deleted : ARRAY Aux-Item; added : ARRAY Aux-Item )); This message indicates that the aux-items of text `text-no' have been changed. (This message is not sent when the text is created or deleted.) `deleted' is a list of the deleted items, and `added' is a list of the added items. At least one of the arrays will be non-empty. Please note that all items in `deleted' will have the `deleted' bit of the `flags' field set.  File: protocol-a.info, Node: async-text-read, Next: async-invalidate-text-read, Prev: async-text-aux-changed, Up: Asynchronous Messages 7.23 async-text-read [23] (12) Experimental =========================================== async-text-read [23] ( read : ARRAY Text-Id ); This message indicates that the currently logged on person has marked texts as read as specified by `read' in another session. (This message is not sent to the session that marks a text as read.) Clients that listen for this message should also listen for `async-invalidate-text-read' (*note async-invalidate-text-read::). See that description for more information on how they interact.  File: protocol-a.info, Node: async-invalidate-text-read, Prev: async-text-read, Up: Asynchronous Messages 7.24 async-invalidate-text-read [24] (12) Experimental ====================================================== async-invalidate-text-read [24] ( conf-no : Conf-No ); This message indicates that the currently logged on person changed which texts that are marked as read in the `conf-no' conference in another session. (This message is not send to the session that performs the modification.) A client that receives this async message should make a note that it no longer can trust its locally cached information about what is unread. However, it should not immediately recompute what is unread, unless the user is interactively using the client. Instead, it should wait a while. This will help reducing the burden on the server. How long the client should wait is a topic for future research. To wait a time that is proportional to how long the user has been idle might be a good heuristic. Clients that listen for this message should also listen for `async-text-read' (*note async-text-read::). The server is free to choose when to use `async-invalidate-text-read' and `async-text-read'. It should attempt to use a heuristic that minimizes the work it needs to perform and the network traffic. The server can know a lot about what the client knows. For instance, if the client has performed a `query-read-texts' (*note query-read-texts::) request for a certain conference, it knows something about what is unread in that conference. If the server later sends an `async-invalidate-text-read' asynchronous message, it knows that the client knows nothing. Until the client issues a new `query-read-texts' request (or any other request that informs it about what is unread in the conference) there is no need for the server to send more `async-invalidate-text-read' or `async-text-read' messages about that conference. If the server actually performs this kind of optimizations is an implementation detail.  File: protocol-a.info, Node: Error Codes, Next: Aux-Item Types, Prev: Asynchronous Messages, Up: Top 8 Error Codes ************* 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. This table lists the currently defined error codes together with a short explanation. The explanation given below is the default semantics for the error code. It can be updated by the descriptions found for a specific call. *Note Client-Server Dialog::, for more information about error responses, including the syntax of the error response. `no-error (0)' No error has occurred. `error-status' is undefined. This should never happen, but it might. `not-implemented (2)' The call has not been implemented yet. `error-status' is undefined. `obsolete-call (3)' The call is obsolete and no longer implemented. `error-status' is undefined. `invalid-password (4)' Attempt to set a password containing illegal characters, or to use an incorrect password. `string-too-long (5)' A string was too long (see descriptions of each call.) `error-status' indicates the maximum string length. `login-first (6)' Login is required before issuing the call. `error-status' is undefined. `login-disallowed (7)' The system is in single-user mode. You need to be privileged to log in despite this. `error-status' is undefined. `conference-zero (8)' Attempt to use conference number 0. `error-status' is undefined. `undefined-conference (9)' Attempt to access a non-existent or secret conference. `error-status' contains the conference number in question. `undefined-person (10)' Attempt to access a non-existent or secret person. `error-status' contains the person number in question. `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. `error-status' indicates the object to which we didn't have enough permissions to. `permission-denied (12)' Not enough permissions to do something. The exact meaning of this response depends on the call. `error-status' indicated the object for which permission was lacking, or zero. `not-member (13)' The call requires the caller to be a member of some conference that the caller is not a member of. `error-status' indicates the conference in question. `no-such-text (14)' Attempt to access a text that either does not exist or is secret in some way. `error-status' indicates the text number in question. `text-zero (15)' Attempt to use text number 0. `error-status' is undefined. `no-such-local-text (16)' Attempt to access a text using a local text number that does not represent an existing text. `error-status' indicates the offending number. `local-text-zero (17)' Attempt to use local text number zero. `error-status' is undefined. `bad-name (18)' Attempt to use a name that's too long, too short or contains invalid characters. `error-status' is undefined. `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. `error-status' is undefined unless stated otherwise in the call documentation. `conference-exists (20)' Attempt to create a conference or person with a name that's already occupied. `error-status' is undefined. `person-exists (21)' Attempt to create a person with a name that's already occupied. `error-status' is undefined. This error code is probably not used, but you never know for sure. `secret-public (22)' Attempt to give a conference a type with `secret' bit set and the `rd-prot' bit unset. This is an error since such a conference type is inconsistent. `error-status' is undefined. `letterbox (23)' Attempt to change the `letterbox' flag of a conference. `error-status' indicates the conference number. `ldb-error (24)' Database is corrupted. `error-status' is an internal code. `illegal-misc (25)' Attempt to create an illegal misc item. `error-status' contains the index of the illegal item. `illegal-info-type (26)' Attempt to use a Misc-Info type (or Info-Type value) that the server knows nothing about. `error-status' is the type. `already-recipient (27)' Attempt to add a recipient that is already a recipient of the same type. `error-status' contains the recipient that already is. `already-comment (28)' Attempt to add a comment to a text twice over. `error-status' contains the text number of the text that already is a comment. `already-footnote (29)' Attempt to add a footnote to a text twice over. `error-status' contains the text number of the text that already is a footnote. `not-recipient (30)' Attempt to remove a recipient that isn't really a recipient. `error-status' contains the conference number in question. `not-comment (31)' Attempt to remove a comment link that does not exist. `error-status' contains the text number that isn't a comment. `not-footnote (32)' Attempt to remove a footnote link that does not exist. `error-status' contains the text number that isn't a footnote. `recipient-limit (33)' Attempt to add a recipient to a text that already has the maximum number of recipients. `error-status' is the text that has the maximum number of recipients. `comment-limit (34)' Attempt to add a comment to a text that already has the maximum number of comments. `error-status' is the text with the maximum number of comments. `footnote-limit (35)' Attempt to add a footnote to a text that already has the maximum number of footnote. `error-status' is the text with the maximum number of footnotes. `mark-limit (36)' Attempt to add a mark to a text that already has the maximum number of marks. `error-status' is the text with the maximum number of marks. `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. `error-status' contains the text number in question. `no-connect (38)' Currently unused. `out-of-memory (39)' The server ran out of memory. `server-is-crazy (40)' Currently unused. `client-is-crazy (41)' The client used an illegal call sequence, such as calling `set-client-version' more than once. `undefined-session (42)' Attempt to access a session that does not exist. `error-status' contains the offending session number. `regexp-error (43)' Error using a regexp. The regexp may be invalid or the server unable to compile it for other reasons. `error-status' is undefined. `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. `error-status' indicates the text in question. `temporary-failure (45)' Temporary failure. Try again later. `error-status' is undefined. `long-array (46)' An array sent to the server was too long. `error-status' is undefined. `anonymous-rejected (47)' Attempt to send an anonymous text to a conference that does not accept anonymous texts. `error-status' is undefined. `illegal-aux-item (48)' Attempt to create an invalid aux-item. Probably the tag or data are invalid. `error-status' contains the index in the aux-item list where the invalid item appears. `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. `error-status' contains the index at which the item appears in the aux-item list sent to the server. `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. `error-status' contains the message type the server did not understand. `internal-error (51)' The server has encountered a possibly recoverable internal error. `error-status' is undefined. `feature-disabled (52)' Attempt to use a feature that has been explicitly disabled in the server. `error-status' is undefined. `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 members in the recipient of the message. `error-status' is undefined. `invalid-membership-type (54)' A requested membership type was not compatible with restrictions set on the server or on a specific conference. `error-status' is undefined unless specifically mentioned in the documentation for a specific call. `invalid-range (55)' The lower limit of a supplied range is greater than the upper limit. `error-status' is undefined. `invalid-range-list (56)' The lower limit of a supplied range is not greater than the upper limit of the previous range in the list. `error-status' is undefined. `undefined-measurement (57)' A request for a measurement that the server doesn't make has been made. `error-status' is undefined. `priority-denied (58)' You don't have enough privileges to lower your priority. `error-status' indicates the lowest priority that you have access to. `weight-denied (59)' You don't have enough privileges to set the specified weight. `weight-zero (60)' The scheduling weight must be non-zero. `error-status' is undefined. `bad-bool (61)' An argument of type `BOOL' was given a value that is neither `0' nor `1'. `error-status' is undefined.  File: protocol-a.info, Node: Aux-Item Types, Next: Name Expansion, Prev: Error Codes, Up: Top 9 Aux-Item Types **************** The following list includes all predefined aux-items. Client writers can expect that the definitions of these items will not change unless explicitly stated. Each listing is of the form `name [tag] (types)', where `name' is the name of the aux-item, `tag' is the aux-item tag and `types' is a comma-separated list of object types the aux-item may be attached to. The possible types are: `text' Indicates that the aux-item may be attached to texts. `create text' Indicates that the aux-item may be attached to texts, but only when the text is being created; once the text exists, the item may not be added. `conference' Indicates that the aux-item may be attached to conferences that do not have the `letterbox' flag set. `letterbox' Indicates that the aux-item may be attached to conferences that have the `letterbox' flag set. `server' Indicates that the aux-item may be attached to the server itself. Some of the aux-items below (mostly the ones that begin with "mx-") are used by mail importers. `content-type [1] (text)' Specifies the content type of a text. Data is a valid MIME type or one of the special LysKOM types (*note 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. `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. `cross-reference [3] (text, conference, letterbox)' Data is a cross-reference to something else. The contents consist of a letter, a number, and optionally 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 simply 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!", and "T17" is a cross reference without a description. The inherit bit is automatically cleared and the item can always be deleted. `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. `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. `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. `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. `redirect [8] (conference, letterbox)' 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 number. 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. `x-face [9] (conference, letterbox, server)' 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. This is obsolete. Don't use it. Anybody interested in using this should define a new aux-item type that uses a PNG image instead. The compface format is broken. `alternate-name [10] (text, conference, letterbox)' 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. `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. `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 N is the number of the person in the LysKOM server specified in 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. `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 several 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 should 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. `faq-text [14] (conference, letterbox, server)' Data is a decimal text number, which is a FAQ for the conference, letterbox 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. `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 `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 `set-client-version' (*note set-client-version::) call. The server may enforce this restriction. `mx-author [16] (create text)' Data is a string containing the name of the author of an imported e-mail, extracted from the `From' header. This aux-item may be missing, if the mail address in the `From' header consists of just the `addr-spec' (see the next aux-item). Clients should display this instead of the actual author of the text (which will be an importer ID) even if an mx-from aux-item is not present. Sample contents: `Joe Q. Public' which may come from a `From' header containing `"Joe Q. Public" '. `mx-from [17] (text)' Data is the proper e-mail address (called `addr-spec' in the mail standards) extracted from the `From' header of an imported e-mail. Clients should display this address together with the `mx-author', preferably inside angles. If `mx-author' is not present, this address should be shown anyway. It can also be used by clients to construct an address for personal (e-mail) replies to an imported message. Sample contents: `john.q.public@example.com' which may come from a `From' header containing `john.q.public@example.com' or something like `"Joe Q. Public" '. `mx-reply-to [18] (text)' Data is the proper e-mail address (called `addr-spec' in the mail standards) extracted from the `Reply-To' header of an imported e-mail. Clients should use this for constructing replies to imported messages. `mx-to [19] (text)' Data is a single e-mail address from an email `To' header. Multiple `mx-to' items may be present when multiple recipients are specified in the header. Clients should display these items along with the normal LysKOM recipient headers. Sample contents: Both `john.q.public@example.com' and `"Joe Q. Public" ' are valid. `mx-cc [20] (text)' Same as `mx-to', but applies to the `CC' header rather than the `To' header. `mx-date [21] (text)' Data is the date and time from the `Date' header of an imported email. 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 information as the date and time a text was written, since the imported text will have been created at a later time. The date and time when the message was imported would then be displayed elsewhere or not at all. `mx-message-id [22] (text)' Data is the `Message-ID' header of an imported e-mail, with whitespace and comments removed. The Message-ID should contain the surrounding angles. `mx-in-reply-to [23] (text)' Data is a string containing one item of the same form as the mx-message-id item described above. This is the Message-ID of another mail the current text is a comment to. Hopefully, this information comes from the `In-Reply-To' header of the imported e-mail, but it could also have been picked from the end of the `References' header line. If the text really comments more than one other text directly, it is allowed to attach more than one `mx-in-reply-to' items to it. `mx-misc [24] (text)' Data is a string that contains all of the headers of an imported email, including `Subject', and including those that are redundantly stored in other aux-items. The headers are concatenated with "\n". In other words, this item contains all headers of an imported e-mail as they appear in the message. Clients are encouraged to provide a command to display this information. `mx-allow-filter [25] (conference, letterbox)' This aux-item has been declared obsolete. It was intended to supply the importer with information on how to filter incoming messages based on regular expressions matching header lines. `mx-reject-forward [26] (conference, letterbox)' This aux-item has been declared obsolete. It was intended to supplement mx-allow-filter by telling where rejected mails should be sent. `notify-comments [27] (letterbox)' Data is a decimal text number that the user is interested in. Clients should monitor this text for unread comments and present these to the user in some convenient manner. This is typically used by users that want to read comments to some text of theirs as soon as they arrive, rather than in the normal reading order. This item can only be set by the owner of the letterbox. No flags are forced or cleared. `faq-for-conf [28] (text)' Data is a decimal number specifying the conference a certain text is a FAQ for. The special number zero denotes that the text is a FAQ for the entire system. Items of this kind can only be created by the LysKOM server itself. Texts with this item are protected from garbage collection. `recommended-conf [29] (server)' Data is a decimal number specifying a conference that new members should automatically be added to, optionally followed by a space and a recommended priority, optionally followed by a space and a membership type. In the future, additional data may be defined; clients should be prepared to accept and ignore a space and any trailing data that may follow the membership type. A few examples might clarify what the data may look like: `1' Conference number 1. `2 32' Conference number 2, with priority 32. `3 250 11100000' Conference number 3, with priority 250. The membership should be secret, passive and have the invitation bit set. `4 253 01000000 garbage' Conference number 4, with priority 253. The membership should be passive. The client should ignore the trailing garbage; it is reserved for future extensions. Note that clients are not allowed to create aux-items of this format, but they should be prepared to handle them correctly. This is a recommendation only; it is up to the client that creates a new person to also add him to the conferences that are specified via `recommended-conf'. `allowed-content-type [30] (conference, letterbox, server)' Data is a non-negative decimal priority number, followed by a space, followed by a LysKOM content type glob pattern. Clients should send texts to a conference only if the content-type matches any of the `allowed-content-type' glob patterns of that conference. If the conference doesn't have any `allowed-content-type', the `allowed-content-type' items of the server should be used. If the server also has no `allowed-content-type' aux-items, it should be interpreted as if a single `allowed-content-type' aux-item with the value `1 text/plain' exists. If there are `allowed-content-type' aux-items with different priority numbers, it is a hint to the client about which content-type is most desirable. Content-types that matches a lower priority number are preferred. As an example, consider a conference with the following four `allowed-content-type' aux-items: 1 text/plain 2 text/x-kom-basic 2 text/enriched 3 text/* These aux-items taken together means that `text/plain' is preferred, that `text/x-kom-basic' and `text/enriched' can be used if there is a reason why `text/plain' is inadequate, and that any text type (such as `text/html') is acceptable. Other content types, such as `x-kom/user-area', should not be used. The server does not currently enforce the above restriction on the content type of new texts. This mechanism is currently a hint to the client (or to the author of a new text). This may change in the future, if experience shows that it is desirable to have the server enforce the content type. If a message is a composition of several different MIME types, for example MIME multipart, each and every included content-type must be checked against the `allowed-content-type' aux-items recursively. For instance, consider a MIME multipart/mixed message with the following structure: (multipart/mixed)-+-(multipart/alternative)-+-(text/plain) | | | +-(text/html) +-(image/gif) For this message to be allowed, all five content types must be checked against, and accepted by, the `allowed-content-type' aux-item(s). For a conference to accept such a message, it is thus not enough to have an `allowed-content-type' aux-item set to, for example, `1 multipart/*'. It must also include all included content-types. The following `allowed-content-type' aux-items would allow this kind of message: 1 text/* 1 multipart/* 1 image/* `canonical-name [31] (server)' This should be set to the official domain name of the server, optionally followed by a colon and the port number. The port number should only be used if a non-standard port is used. Examples: `kom.lysator.liu.se:8300', `kom.lysator.liu.se'. The intent is that the `canonical-name' should be globally unique among all LysKOM servers. Only a single aux-item of this type can be set on the server. This aux-item can be used by clients that wish to do certain things only when connected to a specific server. `mx-list-name [32] (conference)' This item should only be used if the main purpose of the conference is to import a single external mailing list. The data should be the email address that is used to post to the list, such as `bug-lyskom@lysator.liu.se'. `send-comments-to [33] (letterbox)' Normally, when a comment is created, the LysKOM client adds the author of the commented text to the recipient list if he isn't a member of any of the recipients of the comment. By setting this aux-item on the letterbox, a person can request different treatment. Data is a decimal integer (a conference number) optionally followed by a space character and a decimal number (a recipient type). In the future, additional data may be defined; clients must be prepared to accept and ignore a space and any trailing data that may follow the recipient type. Clients must be prepared to accept items of this type that contain only the conference number. Comments should be sent to the specified conference number instead of to the author. The value `0' is special and means that the comment should not be sent to any special conference, even though that means that the author of the commented text will never see the comment. (The value `0' is useful for mail importers and other similar robots.) The recipient type is the type of recipient to add. If the recipient type is missing, clients should either assume recipient type zero (`recpt') or ask the user. Legal recipient types are `0' for `recpt', `1' for `cc-recpt' and `15' for `bcc-recpt' (these are the values used in `Info-Type'). Additional recipient types may be added in the future. Clients should treat unknown or invalid recipient types as if they were missing (i.e. treat them as zero or ask the user). *Note Recipients of comments::, for more information about how the client should select the conferences that a comment should be sent to. This aux-item can only be set by the supervisor of the person. `world-readable [34] (text)' Texts that has this aux-item set on them can be read by everybody. It is not even necessary to log in. Only the author of the text can set this item. The data must be the empty string. The hide-creator, secret, dont-garb and inherit bits are automatically cleared. `mx-refuse-import [35] (conference, letterbox)' This item tells the importer under what circumstances mail should be imported to the conference or letterbox. If no aux-item of this type is present, there are no limitations on import to this conference or letterbox. If the data is the string `all', the importer will never add this conference or letterbox as a recipient. If the data is the string `spam', the importer will not add this conference or letterbox as a recipient if the mail is considered to be spam according to some importer specific criteria (such as the presence of SpamAssassin flags). If the data is the string `html', the importer will not add this conference or letterbox as a recipient if the mail is considered to be in HTML format. In the future, other alternatives in addition to the above may be defined for this aux-item. An importer should silently ignore unrecognized ones. If more than one aux-item of this type is present, they will be combined in the most restrictive way, i.e. the recipient will not be added if any of the aux-items forbids import. Clients are encouraged to provide commands to manage aux-items of this type for conferences and letterboxes. `mx-mime-belongs-to [10100] (text)' Data is a decimal text number that this text is an attachment to. Most likely, the current text is also a comment (or perhaps a footnote) to the text mentioned in the aux-item. A client can use this aux-item to alter the display format of the text (stating that this is an attachment, not a normal comment). `mx-mime-part-in [10101] (text)' Data is a decimal text number of a text that is an attachment to the current one. In other words: this is the converse of mx-mime-belongs-to. A client can use this aux-item to know which comments to mark as attachments; the remaining comments are assumed to be normal. `mx-mime-misc [10102] (text)' Data is a string that contains all of the MIME headers for the current text. It is set by the importer. The fields are concatenated with "\n". Clients are encouraged to provide a command to display this. `mx-envelope-sender [10103] (text)' Data is the envelope sender of an imported text. The mail server is supposed to pass this information to the importer, for inclusion here. `mx-mime-file-name [10104] (text)' Data is the file name of an attachment. Most likely, the importer gets this information from a `name' parameter on a `Content-Type' MIME header line. Clients are encouraged to use this file name as the default file name when the user chooses to save the text. See also *Note Some Client-specific Aux-Item Types::, for information about some non-standardized aux-item types.  File: protocol-a.info, Node: Name Expansion, Next: LysKOM Content Types, Prev: Aux-Item Types, Up: Top 10 Name Expansion ***************** Names in LysKOM can be expanded according to two rules, regexp matching or KOM conventions. 10.1 Regexp Matching ==================== This type of expansion, used by the `re-z-lookup' call and its predecessors(*note re-z-lookup::) simply matches `ed'(1) style regular expressions to names in the database to find the list of matching names. The matching is case sensitive. 10.2 KOM Conventions ==================== This type of matching is a little more complicated. Patterns consist of words and parenthesized expressions, and contain implicit wildcards. The `lyskomd' program implements an approximation of theses conventions. Since `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". The matching is case insensitive. Character case is converted according to a collate table in the server. The collate table can be retrieved from the server with the `get-collate-table' call(*note get-collate-table::). 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.  File: protocol-a.info, Node: LysKOM Content Types, Next: The User Area, Prev: Name Expansion, Up: Top 11 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'. Lines are separated by a single linefeed (ASCII 10) character. The linefeed character is used as a line separator, not as a line terminator. In other words, there should be no linefeed after the last line. * Menu: * Reformattable Text (text/x-kom-basic):: * The User Area (x-kom/user-area):: * Multipart (multipart/mixed):: * MHTML (message/rfc822;x-lyskom-variant=rfc2557)::  File: protocol-a.info, Node: Reformattable Text (text/x-kom-basic), Next: The User Area (x-kom/user-area), Up: LysKOM Content Types 11.1 Reformattable Text ======================= This type of content corresponds to the mime type `text/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. * Lines must be no longer than 70 characters. * Each line, except the last, is terminated by a single linefeed character. * Two linefeed characters in succession signal the end of the paragraph. * There must be no whitespace or linefeeds after the last character. * The end of the last line also signals the end of the paragraph. The following rules apply when reformatting: * The indentation of the first line of a paragraph is to be applied to all lines in the paragraph. * 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. This content type was previously erroneously called `x-kom/basic', but as far as we know no client ever created texts that were labeled with that name. Please use the new name `text/x-kom-basic' instead. Historical note: version 0.46.1 and earlier of the elisp client created texts labeled with `x-kom/text'. Clients may treat that content type as `text/x-kom-basic' for improved interoperability.  File: protocol-a.info, Node: The User Area (x-kom/user-area), Next: Multipart (multipart/mixed), Prev: Reformattable Text (text/x-kom-basic), Up: LysKOM Content Types 11.2 The User Area ================== This content type indicates that the article contains a user area. *Note The User Area::.  File: protocol-a.info, Node: Multipart (multipart/mixed), Next: MHTML (message/rfc822;x-lyskom-variant=rfc2557), Prev: The User Area (x-kom/user-area), Up: LysKOM Content Types 11.3 Multipart articles ======================= Multipart can be used where the complexity of MHTML is not desired. In the common case that the user wants to post a text containing an image and a descriptive text (aside from the subject), there is usually no need for advanced markup nor image references from within the text body. In that situation, it is useful to instead create a multipart article with the following structure: (multipart/mixed)-+-(text/x-kom-basic) +-(image/jpeg) +-(image/jpeg) ... It is recommended that the text part comes first. For the image parts, it is recommended for the image parts to have the `Content-Disposition' header set to `inline' if the user wants to display all parts simultaneously. A client that encounters such a part should attempt to display it inline with the rest of the message, if feasible. If `Content-Disposition' is lacking or set to `attachment', a client should show those parts as accessible by user interaction or likewise. Clients are encouraged to use `text/x-kom-basic' instead of `text/plain', as in the above example.  File: protocol-a.info, Node: MHTML (message/rfc822;x-lyskom-variant=rfc2557), Prev: Multipart (multipart/mixed), Up: LysKOM Content Types 11.4 MHTML articles =================== MHTML is a standard for encapsulating a HTML page in its entirety, with images and other related resources, into a single MIME message. The MIME type of this message is `message/rfc822', plus the parameter `x-lyskom-variant' set to `rfc2557'. This allows a LysKOM client to distinguish MHTML from conventional `message/rfc822' articles, while retaining the possibility to treat the text as a regular e-mail (for example, pass it to an e-mail application for external interpretation). MHTML is specified in RFC 2557. The following should be considered when writing an MHTML-capable LysKOM client: * Care should be taken to compare the `allowed-content-type' aux-item for all recipients of the article. Note that each part of the MIME article must be accepted in order for the article to be allowed in its entirety. For example, an MHTML article containing an HTML text and a PNG image should check that the conference allows all four content types embedded: `message/rfc822', `multipart/related', `text/html' and `image/png' (see `allowed-content-type' in *note Aux-Item Types::). * While not technically wrong, clients are discouraged from creating MHTML article with only one part, for example a single image. Instead, the article's content-type should be set to that one parts content-type, and the article's contents the part's raw binary data. * When displaying HTML, great care should be taken to minimize the risk for the end-user, for example by disabling all scripting possibilities and automatic access to external resources. This may be done by parsing the HTML and filtering out anything but a specified subset of HTML tags and only harmless attributes of those tags. * Clients should allow the creation of `multipart/alternative' parts containing both `text/plain' and `text/html' when the user posts MHTML texts. In accordance with the MIME and MHTML specification, the "plainest" part should be first. * When creating the different parts in an MHTML article, make sure to include a `Content-Location' header specifying the name as used in the HTML, for all parts referenced to in the HTML part. * The `content-transfer-encoding' should be set to `binary'; however, clients should be prepared to decode other encodings as defined by the MIME standard.  File: protocol-a.info, Node: The User Area, Next: Membership visibility, Prev: LysKOM Content Types, Up: Top 12 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 are dictated by this protocol specification. Clients may also create one or more other blocks. In normal texts, everything up to the first linefeed is considered to be the subject line. The user area is an exception: it does not contain any subject line. Each block is encoded as a `HOLLERITH' string. A table of contents is also encoded as a `HOLLERITH' string and added first in the user area. There must be at last one space between each string, and there might be spaces at the beginning and/or end of the user-area. Thus, a user-area made up of three blocks will contain four `HOLLERITH'-encoded strings, each separated by at least one space, and maybe with extra spaces at the beginning or end of the text. The table of contents consists of one `HOLLERITH'-encoded string for each block in the user-area. Each string contains the name of the corresponding block. There is at least one space between each string, and there may be spaces before the first string and after the last string. Clients must never create two or more blocks with the same name. This format ensures that clients can copy or read past other clients' blocks without knowing their structure. Example: 13H7Hblock-a 1Hb 4Hasdf 5H hjkl In the above example, there are two blocks: `block-a' and `b'. `block-a' contains four bytes, `asdf', while `b' contains five bytes: ` hjkl' (note the leading space). Below are a few other ways to encode the same user-area: 14H 7Hblock-a 1Hb 4Hasdf 5H hjkl 16H 7Hblock-a 1Hb 4Hasdf 5H hjkl 13H1Hb 7Hblock-a 5H hjkl 4Hasdf The first two examples embed extra (redundant) spaces, and the last swaps the order of the two blocks. The following block names have been defined: `common' The common block shared by all clients. The format of the common block is described below. `elisp' The block created by the Emacs lisp client. The format is completely undocumented, but you'll need a lisp reader to parse it. `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. `rkom' Used by Anders Magnusson . If you're writing a client that uses the user-area, please let us know what you name your client's block. 12.1 The Common Block ===================== This defines the structure of the common block. 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 linefeed character. The values can be of several different types (such as integers, strings, booleans, lists of stuff) but they are all 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. The grammar below defines the syntax of the common block. common-block : settings settings : settings setting | /* empty */ setting : variable ' ' value '\n' variable : [A-Za-z-_0-9]+ value : HOLLERITH The values contain structure within the HOLLERITH. The following grammar defines the data types that are currently used. Clients must be prepared to ignore values that have other data types. boolean : 1 | 0 integer : -?[0-9]+ string-list : string-list ' ' HOLLERITH | HOLLERITH Currently the following variables are used, but more may be added, and clients must cope with variables they know nothing of in the common block. (Doing so is easy, as all values are encoded as HOLLERITHs.) `created-texts-are-read' True if the user wants texts s/he creates to be marked as read automatically. `boolean'. `dashed-lines' True if the user wants dashed lines around the text body when it's displayed. `boolean'. `presence-messages' True if the user wants messages about people logging in and logging out of LysKOM. `boolean'. `print-number-of-unread-on-entrance' True if the user wants to see the number of unread texts when entering a conference. `boolean'. `read-depth-first' True if the user wants to read text in depth-first order. `boolean'. `reading-puts-comments-in-pointers-last' True if the user wants the client to display comment links after the text body. `boolean'. `confirm-multiple-recipients' True if the user wants the client to ask for confirmation before sending a text to many conferences. `boolean'. `default-mark' The default mark to set on marked texts. `integer'. `language' Preferred languages, in priority order. `string-list'. This contains a list of ISO 639 language codes. ISO 639-2 should be used for languages that have a 2-character language code. For other languages, ISO 639-1 should be used. `http://lcweb.loc.gov/standards/iso639-2/langcodes.html' contains a list of the current language codes. The client should configure its user interface to use the first language in the list that it supports. Example: a client that supports English and Swedish would use: * Swedish if the list is `2Hfr 2Hsv 2Hen' * English if the list is `2Hen 2Hsv 2Hfr' * either if the list is `2Hes 2Hfr'  File: protocol-a.info, Node: Membership visibility, Next: Garb, Prev: The User Area, Up: Top 13 Membership visibility ************************ The details of the security model isn't properly documented. Much information can be extracted from various parts of the protocol specification, but there is no complete overview. In time, this chapter may become such an overview. For now, it only defines when a membership is visible. The various requests that return information about a membership can be grouped into three categories: * Category 1: given a conference, list (some of) the members. * `get-members' (*note get-members::) * `get-members-old' (*note get-members-old::) These requests fail if the conference is secret and you don't have access to it, even if a membership should be visible to you according to the rules below. * Category 2: given a person, list (some of) the conferences that the person is a member of. * `get-membership' (*note get-membership::) * `get-membership-10' (*note get-membership-10::) * `get-membership-old' (*note get-membership-old::) * `get-unread-confs' (*note get-unread-confs::) These requests fail if the person is secret and you don't have access to it, even if a membership should be visible to you according to the rules below. * Category 3: given a person and a conference, return the membership. * `query-read-texts' (*note query-read-texts::) * `query-read-texts-10' (*note query-read-texts-10::) * `query-read-texts-old' (*note query-read-texts-old::) These requests follows the rules below exactly. The rules for membership visibility are given below. In the explanation, the variables C, P and V are used like this: * a conference C * a person P who is a member of the conference C * a viewer V who wants to find out about P:s membership in C. The following flags also influences how much V can see: * the `unread-is-secret' flag of P * the `secret' flag of P:s membership in C The following rules determines if a membership is visible to V. The first rule that matches is used. * If V is supervisor of P, then the membership is visible. Both the `unread-is-secret' and `secret' flags are ignored. * If V is supervisor of C, then the membership is visible. The `secret' flag is ignored. The `unread-is-secret' flag is honored. * If V is allowed to see both P and C, and if `secret' is unset, then the membership is visible. The `unread-is-secret' flag is honored. * Otherwise, V is not allowed to se the membership.  File: protocol-a.info, Node: Garb, Next: Measured Properties, Prev: Membership visibility, Up: Top 14 Automatic text removal (the garb) ************************************ Old texts are automatically removed by a process known as "the garb". By default, the garb will remove all texts when it looks at them. There are several things that can save a text from removal: - if the server is configured to never remove any texts. - if text is marked. See `mark-text' (*note mark-text::). - if the text is presentation of a conference. See `set-presentation' (*note set-presentation::). - if the text is message of the day for a conference. See `set-etc-motd' (*note set-etc-motd::). - if the text is message of the day for the system. See `set-motd-of-lyskom' (*note set-motd-of-lyskom::). - if the text is message of the user area of a person. See `set-user-area' (*note set-user-area::). - if the text is less than 24 hours old. - if the text has an aux-item with the `dont-garb' bit set. See *Note Aux-Item-Flags::. - if the text is less than `nice' days old, for any of the recipients. `nice' is part of the `Conference' status. `set-garb-nice' (*note set-garb-nice::). All recipient types, `recpt', `cc-recpt' and `bcc-recpt', counts. If the text was added to the conference after its creation, the check is made against the addition time instead of the creation time. See `set-garb-nice' (*note set-garb-nice::). - if the text was added as a comment or footnote to a text within the last 24 hours. See `add-comment' (*note add-comment::) and `add-footnote' (*note add-footnote::). - for each comment and footnote to the text, the time when it became a comment or a footnote of the text is considered. If it is less than 24 hours, the text is saved. If it is less than the `keep-commented' field of any of the recipients of the text and the comment/footnote, it is saved. All recipient types, `recpt', `cc-recpt' and `bcc-recpt', counts. See `set-keep-commented' (*note set-keep-commented::). Other texts will be removed. It is an implementation detail of the server exactly when texts will be removed.  File: protocol-a.info, Node: Measured Properties, Next: Extracted grammar, Prev: Garb, Up: Top 15 Measured Properties ********************** The server measures a number of properties, and can return information about them to a client via the `get-stats' request(*note get-stats::). A server implementation may include experimental properties, whose name should begin with `X-'. All other properties should be defined in this chapter. Some of the properties that are suggested here might prove to be too hard to measure efficiently, or might prove to expose too much information. In that case, a server may select to not implement them. Clients must be prepared to receive a `feature-disabled' or `undefined-measurement' error if they call `get-stats' with a value that wasn't received from `get-stats-description' (*note get-stats-description::). For each measured value, both the levels and the ascent and descent rates are returned. *Note Stats::, for more information. Ascent and descent rates are always normalized to a number of events per 100 seconds. `run-queue-length' The number of clients that the server is currently refusing to serve since its time for the server to process other clients for a while. `pending-dns' The number of pending DNS requests. `pending-ident' The number of pending IDENT requests. `clients' The number of connected clients. `reqs' The number of Protocol A requests that is being processed. In the current implementation, this will always be a number between 0 and 1, but that might change in the future. `texts' The number of existing texts. `confs' The number of existing conferences (including letterboxes). `persons' The number of existing persons. `send-queue-bytes' `recv-queue-bytes' The number of bytes waiting in the send and receive queues.  File: protocol-a.info, Node: Extracted grammar, Next: Writing Clients, Prev: Measured Properties, Up: Top Appendix A Extracted grammars (informative) ******************************************* The file `Protocol-A.texi' is the authoritative standard for protocol A. However, it has a two problems: * The Texinfo markup makes it hard for a program to extract information-and once a program is written, we might change the Texinfo markup, so that the program has to be updated. * We often rename requests and data types, in order to have good names for the most recommended functions and types. However, a program that uses a data type might fail if that type suddenly is altered. To overcome these problems, and better server client writers that want to generate the protocol-level code automatically from the specification, a few variants of the grammar is available as separate files. In some of these files, the names have been changed to "stable" names that will not change as the protocol evolves. Currently, these three grammars exists: `protocol-a-full.txt' The full Protocol A specification, with stable names. `protocol-a-recommended.txt' The recommended requests and asynchronous messages, and all types they need, with stable names. `protocol-a-current.txt' The recommended requests and asynchronous messages, with the names used in this specification. The files are generated by `doc/checkargs.py' in the lyskom-server distribution. Adding more output formats is fairly easy. Let us know, preferably via Bugzilla, if a new output format would be useful for you. It is the intention that the format of the above-mentioned files will not change. The file format should be self-explanatory once you have read the protocol specification. It does contain some comments that should be useful. The stable names are generated by this process: * Don't modify builtin types such as `INT32'. * Remove the suffixes `-old', `-older' and `-Old', unless that would introduce an ambiguity. * Unless the name already has a version suffix, add one. All files mentioned above are reachable via `http://www.lysator.liu.se/lyskom/protocol/'.  File: protocol-a.info, Node: Writing Clients, Next: Importing and Exporting E-Mail, Prev: Extracted grammar, Up: Top Appendix B Writing Clients (informative) **************************************** This appendix 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.  File: protocol-a.info, Node: Common Commands, Next: Client Conventions, Up: Writing Clients B.1 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:: How to figure out which articles to present.  File: protocol-a.info, Node: What do I have unread, Up: Common Commands B.1.1 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 a list of ranges. Since a typical reader reads texts more-or-less in order from oldest to newest, this will result in a reasonably compact data structure. The server will automatically grow the ranges when adjacent texts are removed(1), and if the gap between two ranges disappears the ranges will of course be merged. All texts that are not included in any of the ranges are unread. Clients can use either the `query-read-texts' (*note query-read-texts::) or `get-membership' (*note get-membership::) calls to get membership data. The standard procedure for finding out which texts are unread is the following: 1. Call `get-unread-confs' for the person(*note get-unread-confs::). 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. 2. Call `query-read-texts' (*note 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. 3. Call `get-uconf-stat' (*note get-uconf-stat::) for each conference returned in the first step. The `highest-local-no' field in the result is the highest existing local text number in the conference, and it will be needed shortly. Repeat the following steps for each conference. 4. Compute the set of possibly unread texts. This can be done by creating the interval 1...`highest-local-no' and then removing all intervals in the result from `query-read-texts'. If the resulting set is non-empty, the conference may contain unread texts. 5. Use the `local-to-global' request(*note local-to-global::) to get the parts of the local to global map that are present in the set. Unless you have an extremely long round-trip time, it is best to only have a single pending pending `local-to-global' request per conference, as it may return a sparse mapping. 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. Take care not to call `get-map' or `get-membership' too much since they tend to be expensive operations. Use `get-unread-confs' and `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. ---------- Footnotes ---------- (1) but not right away, so clients must handle the case when a text doesn't exist  File: protocol-a.info, Node: Client Conventions, Prev: Common Commands, Up: Writing Clients B.2 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. * Client-side name expansion:: By number, by word, by regexp. * Recipients of comments:: Where comments should be sent. * Order of misc-info groups:: Footnotes, comments, recipients.  File: protocol-a.info, Node: Text formatting, Next: Content type specification, Up: Client Conventions B.2.1 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: * Lines should be no longer than 72 characters. * Lines are terminated with a single linefeed character. * Paragraphs are separated by two linefeeds in succession. * There are no empty lines at the end of the text. 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 `send-message' call(*note send-message::).  File: protocol-a.info, Node: Content type specification, Next: Client-side name expansion, Prev: Text formatting, Up: Client Conventions B.2.2 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.  File: protocol-a.info, Node: Client-side name expansion, Next: Recipients of comments, Prev: Content type specification, Up: Client Conventions B.2.3 Client-side name expansion -------------------------------- When a client needs to prompt the user for a conference (or person), it could offer the user several ways of specifying the conference: * By conference number * By name, using the `lookup-z-name' call(*note lookup-z-name::). * By name, using the `re-z-lookup' call(*note re-z-lookup::). * By name, transforming the string to a case insensitive regular expression, and then using the `re-z-lookup' call. It is beyond the scope of this document to specify how the client interacts with the user. The client should offer the user all the methods of specifying a conference listed above. At the very least, the two first methods should be supported.  File: protocol-a.info, Node: Recipients of comments, Next: Order of misc-info groups, Prev: Client-side name expansion, Up: Client Conventions B.2.4 Recipients of comments ---------------------------- When a user writes a comment, the user should have full control over which conferences and/or letterboxes the comment is sent to. By default, the recipient list should be all `recpt' recipients. `cc-recpt' and `bcc-recpt' recipients should not be included. Conferences in the recipient list that have the `original' bit set, and a non-zero `super-conf', should be replaced by the `super-conf'. If the author of the commented text isn't a member of any of the new recipients, the client should check if the author has a `send-comments-to' aux item. If it is `0', nothing should be done. Otherwise, `send-comments-to' should be a valid conference number, and that conference should be added as a `recpt' recipient. If there is no `send-comments-to' aux-item, the user should be prompted to add the author of the commented text as a `recpt' or `cc-recpt' recipient. If the author of the new comment is not a member of any of the recipients, the client should check if the author has a `send-comments-to' aux item. If it is `0' nothing should be done. Otherwise, `send-comments-to' should be a valid conference number, and the user should be prompted to add that conference as a `recpt' or `cc-recpt' recipient. If there is no `send-comments-to', or `send-comments-to' is invalid, the user should be prompted to add his letterbox as a `recpt' or `cc-recpt' recipient. If a recipient is present more than once, all duplicates should be removed.  File: protocol-a.info, Node: Order of misc-info groups, Prev: Recipients of comments, Up: Client Conventions B.2.5 Order of misc-info groups ------------------------------- The ordering of the groups of `Misc-Info' items are not defined by this protocol. However, when creating a new text, clients are recommended to use this order: * any `footn-to' items * any `comm-to' items * any `recpt' items * any `cc-recpt' items * any `bcc-recpt' items This is the order that the elisp-client normally uses, and users have come to expect that order.  File: protocol-a.info, Node: Importing and Exporting E-Mail, Next: Some Client-specific Aux-Item Types, Prev: Writing Clients, Up: Top Appendix C Importing and Exporting E-Mail (informative) ******************************************************* E-mail import has been implemented using various programs since the first LysKOM server became operational. Protocol version 10 introduces a lot of aux-items, a large part of which are intended for use by mail importers to enhance the functionality. As of this moment, there is one mail importer (`komimportmail') that is designed to take full advantage of all the new aux-items. E-mail export has never been used seriously. The first person to design and implement an exporter gets to rewrite this appendix based on his or her experiences. C.1 Importing e-mail ==================== The main job of the mail importer is to figure out where to deliver mail, how to handle MIME coding and/or structure and how to deal with threading. During this, it creates one or more texts and a lot of aux-items. C.1.1 Recipients ---------------- Although a mail message contains `To' and `CC' headers, they are not really useful when importing as it is the envelope recipients, not the header recipients, that should be used. To understand this, consider a mail where the `To' header contains a personal mail address. The mail is received using a tool like `procmail' and forwarded to the LysKOM importer. The envelope address will be correct, but the `To' header will still contain the personal address. The `komimportmail' importer uses addresses like "NUMBER@SERVER", where NUMBER is the number of the recipient and SERVER is the mail domain reserved for the LysKOM importer. For backwards compatibility with earlier importers, it is allowed to prepend a "p" before the number. Instead of the number, `komimportmail' can accept a name, as long as the name can be resolved to exactly one conference or letterbox. Before looking up the name, any underscore or period is translated into a space. Care should be taken when a mail is received more than once. This can happen if a mail is addressed to more than one address. For example, assume that a mail is sent to `john.q.public@example.com' and `sven.svensson@exempel.se'. Two different mail servers handle the two recipients, but both eventually decide to forward the mail to the LysKOM importer (but for different conferences). The LysKOM importer will receive the mail twice, with different envelope recipients. A solution is to keep a database containing a mapping from `Message-ID' to LysKOM text number for imported messages. If a message is seen more than once, the message is not imported. Instead, recipients are added to the existing text. On the other hand, that will introduce a security hole, where a person who knows the `Message-ID' of an interesting imported mail can add himself or some open conference as a recipient. Perhaps the importer should check for matching contents before adding 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. Limitations on what messages a conference accepts are defined by aux-items. See *Note The Aux-Item List:: and *Note Aux-Item Types::, in particular `redirect', `allowed-content-type' and `mx-refuse-import' for more information. For mail delivery to work for any conference, the importer has to use a privileged person, or it will be unable to deliver mail to secret conferences. A potential problem is that this leaks secret information from the server. For the time being, the `komimportmail' importer avoids this problem by using an unprivileged person and requiring the members of secret conferences to invite the importer if they want e-mail import to work. C.1.2 Threading --------------- The importer should do its best to thread messages. When the importer sees a new message it needs to look at the `In-Reply-To' header to see what the message is a reply to. If the `In-Reply-To' header does not exist, or if it exists but does not contain a valid Message-ID, the last valid Message-ID of a `References' header may be used instead. If the Message-ID of a previously imported e-mail is found, the new text should be made a comment of the replied-to text. If the Message-ID is of the form defined below (*note Message-ID::), and it refers to a text exported from this server, the new text should be made a comment of 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. Fortunately, this is exactly the same database we need to solve the multiple reception problem described above. It has been noted that messages on some mailing lists arrive in peculiar order, with replies before the original messages. Perhaps this is due to moderation. A smart importer should be prepared to handle this, by adding a comment link when the original message eventually arrives. One possible solution is to add a new kind of entry to the Message-ID database, mapping a Message-ID to a list of text numbers that should become comments to the message when it is imported. C.1.3 MIME issues ----------------- An importer should try to handle e-mail messages containing MIME appendices as smart as possible. As the current LysKOM model lacks hierarchical structuring inside articles, appendices should probably be imported as comments or footnotes to the main message. One would think that it is easy to convert the hierarchical MIME structure to a corresponding LysKOM comment tree. However, this would require creating empty interior nodes to attach some comments to. Therefore, the `komimportmail' importer currently uses a rather naive algorithm: All leaf parts are found. The first one gets to be the main text, and the rest are included as comments to it. Appendices encoded with Base64 or Quoted-Printable should be decoded. When creating aux-items like `mx-author', text coded using the method in RFC 2047 should be decoded. C.2 Exporting e-mail ==================== As of this writing, an experimental e-mail exporter exists, but it is a fairly recent creation. The author of this document knows very little about how it works, so this section contains very little information. C.2.1 Message-ID ---------------- A standard for Message-ID creation has been established. The general format is: TEXT-NO.PORT.EXPORTER.RANDOMNESS@SERVER The different parts are explained below: TEXT-NO The text number of the text that was exported. PORT SERVER The `canonical-name' aux item defines a unique name for the LysKOM system that the text was exported from. The SERVER and PORT fields are set from it. If no port is specified in the `canonical-name', the PORT part is set to the empty string. EXPORTER The name of the software that exported the text. RANDOMNESS A string that ensures that the Message-ID is unique even if the same text is exported several times. This could contain a random string, a sequence number, or something else that makes the Message-ID unique.  File: protocol-a.info, Node: Some Client-specific Aux-Item Types, Next: Future changes, Prev: Importing and Exporting E-Mail, Up: Top Appendix D Some Client-specific Aux-Item Types (informative) ************************************************************ This appendix contains some contributed information from client writers about some of the aux-item types that they use. This information may be updated at any time by the client writers. How much the client writer cares about backward compatibility when they make changes to these aux-item types may be beyond the control of the authors of the Protocol A specification. If any of the aux-item types defined here becomes widely used by different clients, they should probably be standardized and moved to the *Note Aux-Item Types:: chapter. `elisp-client-read-faq [10000] (letterbox)' This item indicates FAQs that the user has read. Data is a decimal number indicating the conference for which a FAQ has been read, followed by a space character and a second decimal number indicating the text number of the FAQ. In the future, additional data may be defined; clients should be prepared to accept and ignore a space and any trailing data that may follow the second number. Note that aux-items of this type should always be secret since they may contain information about texts of conferences that are not publicly visible. A few examples might clarify what the data may look like: `459 11215' FAQ in text 11215 for conference 459 has been read. `459 11215 garbage' FAQ in text 11215 has been read. Clients must ignore the trailing garbage. Note that clients are not allowed to create aux-items of this format, but they should be prepared to handle them correctly. This aux-item is specific to the elisp client. Other clients are not required to use or understand this item type. `elisp-client-rejected-recommendation [10001] (letterbox)' This item indicates a rejected membership recommendation. Data is a decimal number indicating the conference for which the recommendation was rejected. In the future, additional data may be defined; clients should be prepared to accept and ignore a space and any trailing data that may follow the second number. Note that aux-items of this type should always be secret since future extensions may contain sensitive data. A few examples might clarify what the data may look like: `459' A recommendation for conference 459 has been rejected. `459 garbage' A recommendation for conference 459 has been rejected. Clients must ignore the trailing garbage. Note that clients are not allowed to create aux-items of this format, but they should be prepared to handle them correctly. This aux-item is specific to the elisp client. Other clients are not required to use or understand this item type.  File: protocol-a.info, Node: Future changes, Next: Protocol Version History, Prev: Some Client-specific Aux-Item Types, Up: Top Appendix E Future changes (speculative) *************************************** While useful and stable, this protocol is far from perfect. Here is a short list of things the current developers would like to change in future versions of the protocol. The list is not sorted. All changes will be made in a backwards compatible way. Clients will still be able to use the old requests. * Cryptography! LysKOM is sometimes used for sensitive information. It is unacceptable that everything is sent in the clear. Should we use TLS? This area needs further study. (This is bug 133 (http://bugzilla.lysator.liu.se/show_bug.cgi?id=133).) * The information contained in the `Misc-Info' array should be integrated into the `Text-Stat'. There should be one array of recipients, one of texts that comments this text, and so on. This would make the `Misc-Info' type obsolete. (This is bug 134 (http://bugzilla.lysator.liu.se/show_bug.cgi?id=134).) * The aux-items can be very large. It was a mistake to include them in the `Text-Stat'. They should probably be separated from the `Text-Stat'; retrieving the `Text-Stat' should only indicate which aux-items that exists. (This is bug 135 (http://bugzilla.lysator.liu.se/show_bug.cgi?id=135).) * The super conference is used for two purposes: to indicate where followups of original conferences should be sent, and to indicate where articles created by persons that are not permitted submitters should be sent. Occasionally one wants to send followups to one conference and unauthorized original articles to another conference. One way to fix this is to remove the `original' bit and introduce a `followups-to' field in the `Conference'. Doing this in a backwards-compatible way requires some thought... (This is bug 136 (http://bugzilla.lysator.liu.se/show_bug.cgi?id=136).) * The security system is too complex, yet unable to do many useful things, and should be rethought. (This is bug 137 (http://bugzilla.lysator.liu.se/show_bug.cgi?id=137).) * If the client issues several request without waiting for a reply, the replies will nevertheless always arrive in the same order as the requests were sent in. If a threaded version of the LysKOM server is ever made, it could possibly process two requests from the same client at the same time, and the answers could be returned in any order. However, the current clients are probably not written so that they can handle such reordering. In the future, a new call might be added, so that a client can give the server explicit permission to reorder the replies. The client would then have to rely on the `ref-no' to match each reply to the corresponding call. (This is bug 138 (http://bugzilla.lysator.liu.se/show_bug.cgi?id=138).) For more information about potential future changes, see Bugzilla @ Lysator (http://bugzilla.lysator.liu.se/). The above list is in no way complete.  File: protocol-a.info, Node: Protocol Version History, Next: Document Edition History, Prev: Future changes, Up: Top Appendix F Protocol Version History (informative) ************************************************* F.1 Protocol version 11 (first implemented in lyskomd 2.1.0) ============================================================ New Server Calls These new calls have status Recommended. * 107=query-read-texts * 108=get-membership * 109=mark-as-unread * 110=set-read-ranges * 111=get-stats-description * 112=get-stats * 113=get-boottime-info * 114=first-unused-conf-no * 115=first-unused-text-no * 116=find-next-conf-no * 117=find-previous-conf-no * 120=set-connection-time-format * 121=local-to-global-reverse * 122=map-created-texts-reverse These new calls have status Experimental. * 118=get-scheduling * 119=set-scheduling Status change The following calls have change status from Experimental to Recommended. * 105=set-keep-commented The following calls have changed status from Recommended or Experimental to Obsolete. * 98=query-read-texts-10 * 99=get-membership-10 New and Modified Types * Read-Range * Membership * Membership-Type * Stats * Stats-Description * Static-Server-Info * FLOAT New Asynchronous Messages * 19=async-new-user-area * 20=async-new-presentation * 21=async-new-motd * 22=async-text-aux-changed New aux-items *Note Document Edition History::, as new aux-items are added between protocol versions. New error codes *Note Document Edition History::. Notes * The `reserved1' bit of `Membership-Type' has been renamed to `passive-message-invert'. *Note Membership Information::. This affects `async-send-message' (*note async-send-message::) and `send-message' (*note send-message::). * The following requests can no longer be used until you have logged in: `get-last-text' (*note get-last-text::), `find-next-text-no' (*note find-next-text-no::) and `find-previous-text-no' (*note find-previous-text-no::). * You can now modify the type of a recipient with the `add-recipient' (*note add-recipient::) call if you are the supervisor of either the author, recipient or sender. The check used to be more restrictive. * The following asynchronous messages are also sent to recipients of texts linked to the relevant text via comment or footnote links: `async-new-text-old' (*note async-new-text-old::), `async-deleted-text' (*note async-deleted-text::), `async-new-text' (*note async-new-text::), `async-new-recipient' (*note async-new-recipient::) and `async-sub-recipient' (*note async-sub-recipient::). * All requests that take a `BOOL' argument now return the error `bad-bool' if the argument is anything but `0' or `1'. F.2 Protocol version 10 (first implemented in lyskomd 2.0.0) ============================================================ Error codes The error codes are now documented. Several error codes were changed to more sane values while documenting the new behavior. New Server Calls These new calls have status Recommended. * 85=get-collate-table * 86=create-text * 87=create-anonymous-text * 88=create-conf * 89=create-person * 90=get-text-stat * 91=get-conf-stat * 92=modify-text-info * 93=modify-conf-info * 94=get-info * 95=modify-system-info * 96=query-predefined-aux-items * 98=query-read-texts * 99=get-membership * 100=add-member * 101=get-members * 102=set-membership-type * 103=local-to-global * 104=map-created-texts * 106=set-pers-flags These new calls have status Experimental. * 97=set-expire * 105=set-keep-commented Name changes Old name New name 5=create-person 5=create-person-old 9=query-read-texts 9=query-read-texts-old 10=create-conf 10=create-conf-old 13=get-conf-stat-old 13=get-conf-stat-older 14=add-member 14=add-member-old 26=get-text-stat 26=get-text-stat-old 28=create-text 28=create-text-old 36=get-info 36=get-info-old 46=get-membership 46=get-membership-old 48=get-members 48=get-members-old 50=get-conf-stat 50=get-conf-stat-old 59=create-anonymous-text 59=create-anonymous-text-old Status change The following calls have change status from Experimental to Recommended. * 58=get-last-text * 77=set-last-read * 78=get-uconf-stat The following calls have changed status from Recommended or Experimental to Obsolete. * 5=create-person-old * 9=query-read-texts-old * 10=create-conf-old * 14=add-member-old * 26=get-text-stat-old * 28=create-text-old * 36=get-info-old * 46=get-membership-old * 47=get-created-texts * 48=get-members-old * 50=get-conf-stat-old * 59=create-anonymous-text-old New and Modified Structures * Aux-Item * Aux-Item-Input * Conference * Info * Member * Membership * Membership-Type * Misc-Info * Text-Stat Renamed Asynchronous Messages A `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. New Asynchronous Messages * 14=async-deleted-text * 15=async-new-text * 16=async-new-recipient * 17=async-sub-recipient * 18=async-new-membership Notes * 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 `add-member-old' (*note add-member-old::) and `get-membership-old' (*note get-membership-old::) perform magic, translating between priorities and membership types. The magic is documented with each call. F.3 Protocol version 9 (first implemented in lyskomd 1.9.0) =========================================================== New functionality * The server shall now reply with error `not-implemented' when a client attempts to use an unimplemented call. This feature requires that the client uses linefeed as call terminator. Added Commands * 79=set-info: Can change server information. * 80=accept-async: Can select asynchronous messages to receive. * 81=query-async: Can query which messages are being send. * 82=user-active * 83=who-is-on-dynamic * 84=get-static-session-info Changed names * `change-conference' was previously called `pepsi'. The name was changed, but not the functionality. Status change * 63=`who-is-on-ident' is now considered obsolete. * 64=`get-session-info-ident' is now considered obsolete. F.4 Protocol version 8 (first implemented in lyskomd 1.8.0) =========================================================== Added Functionality * 30=add-recipient: Can change `recpt' to `cc-recpt' and vice versa. * 21=set-conf-type: Accepts `Conf-Type' and `Extended-Conf-Type'. * 10=create-conf: Accepts `Conf-Type' and `Extended-Conf-Type'. New Commands * 77=set-last-read * 78=get-uconf-stat F.5 Protocol version 7 (first implemented in lyskomd 1.7.0) =========================================================== Added Functionality * 53=send-message: Recipient can be a conference or a person. New Commands * 74=re-z-lookup * 75=get-version-info * 76=lookup-z-name Other * The asynchronous message 1=i-am-off has been removed F.6 Protocol Version 6 (first implemented in lyskomd 1.4.0) =========================================================== New Calls * 67=lookup-person * 68=lookup-conf * 69=set-client-version * 70=get-client-name * 71=get-client-version * 72=mark-text * 73=unmark-text F.7 Protocol Version 5 (first implemented in lyskomd 1.3.0) =========================================================== New Calls * 65=re-lookup-person * 66=re-lookup-conf F.8 Protocol Version 4 (first implemented in lyskomd 1.1.1) =========================================================== New Calls * 62=login * 63=who-is-on-ident * 64=get-session-info-ident F.9 Protocol Version 3 (first implemented in lyskomd 1.1.0) =========================================================== New Calls * 61=find-previous-text-no * 60=find-next-text-no * 59=create-anonymous-text * 58=get-last-text F.10 Protocol Version 2 (first implemented in lyskomd 0.30.0) ============================================================= New Calls * 57=set-user-area F.11 Protocol Version 1 (first implemented in lyskomd 0.29.2) ============================================================= New Calls All calls from 0-56.  File: protocol-a.info, Node: Document Edition History, Next: Index, Prev: Protocol Version History, Up: Top Appendix G Document Edition History (informative) ************************************************* 11.1: 2003-08-30 _Modified aux-item:_ `mx-refuse-import' [35] now supports the value `html'. *Note Aux-Item Types::. _Previously undocumented stuff:_ *Note Garb::, for information about how the garb works. _New appendix:_ *Note Extracted grammar::, for information about machine-readable grammars extracted from this specification. _Typographic improvements:_ The section heading of all asynchronous messages now contains the async number. _Fixed errors:_ In the info manual, the status codes in the menus of request and asynchronous messages were set to `r' instead of `O' for `who-is-on-ident', `get-session-info-ident' and `async-new-text-old'. Several section headings for obsolete requests was missing information about when the request became obsolete. Distributed with lyskomd 2.1.2. 11.0: 2003-08-24 _New aux-items:_ `mx-refuse-import' [35]. *Note Aux-Item Types::. _New types:_ `Read-Range' and `Membership' (the old `Membership' was renamed to `Membership-10'). *Note Membership Information::. `Stats' and `Stats-Description'. *Note Statistics::. `Static-Server-Info'. *Note Server Information::. `FLOAT'. *Note Simple Data Types::. _Status change:_ The `query-read-texts-10' (*note query-read-texts-10::) and `get-membership-10' (*note get-membership-10::) requests are now obsolete. The `set-keep-commented' (*note set-keep-commented::) request is now recommended. _New calls:_ * `query-read-texts' (*note query-read-texts::) * `get-membership' (*note get-membership::) * `mark-as-unread' (*note mark-as-unread::) * `set-read-ranges' (*note set-read-ranges::) * `get-stats-description' (*note get-stats-description::) * `get-stats' (*note get-stats::) * `get-boottime-info' (*note get-boottime-info::) * `first-unused-conf-no' (*note first-unused-conf-no::) * `first-unused-text-no' (*note first-unused-text-no::) * `find-next-conf-no' (*note find-next-conf-no::) * `find-previous-conf-no' (*note find-previous-conf-no::) * `get-scheduling' (*note get-scheduling::) * `set-scheduling' (*note set-scheduling::) * `set-connection-time-format' (*note set-connection-time-format::) * `local-to-global-reverse' (*note local-to-global-reverse::) * `map-created-texts-reverse' (*note map-created-texts-reverse::) _New error codes:_ `invalid-range', `invalid-range-list', `priority-denied', `weight-denied', `weight-zero', `undefined-measurement' and `bad-bool'. _New async messages:_ * `async-new-user-area' (*note async-new-user-area::) * `async-new-presentation' (*note async-new-presentation::) * `async-new-motd' (*note async-new-motd::) * `async-text-aux-changed' (*note async-text-aux-changed::) _Protocol change:_ Renamed the `reserved1' bit of `Membership-Type' to `passive-message-invert'. *Note Membership Information::. This affects `async-send-message' (*note async-send-message::) and `send-message' (*note send-message::). The following requests can no longer be used until you have logged in: `get-last-text' (*note get-last-text::), `find-next-text-no' (*note find-next-text-no::) and `find-previous-text-no' (*note find-previous-text-no::). You can now modify the type of a recipient with the `add-recipient' (*note add-recipient::) call if you are the supervisor of either the author, recipient or sender. The check used to be more restrictive. Aux-item tags 10200-10299 are now reserved for private test use. *Note Client-Specific Aux-Item Types::. The following asynchronous messages are also sent to recipients of texts linked to the relevant text via comment or footnote links: `async-new-text-old' (*note async-new-text-old::), `async-deleted-text' (*note async-deleted-text::), `async-new-text' (*note async-new-text::), `async-new-recipient' (*note async-new-recipient::) and `async-sub-recipient' (*note async-sub-recipient::). Two requests can now return more error codes than they used to: `add-comment' (*note add-comment::) `already-comment' and `already-footnote'. `add-footnote' (*note add-footnote::) `already-comment'. The field `later-texts-exists' in `Text-Mapping' has been renamed to `more-texts-exists', as this name is more meaningful for the new requests `local-to-global-reverse' (*note local-to-global-reverse::) and `map-created-texts-reverse' (*note map-created-texts-reverse::). _Fixed errors:_ The description of the error `index-out-of-range' was wrong for `add-footnote' (*note add-footnote::),missing for `create-person-old' (*note create-person-old::), `create-person' (*note create-person::), `create-conf-old' (*note create-conf-old::), `create-conf' (*note create-conf::) and `create-text-old' (*note create-text-old::), and incomplete for `create-text' (*note create-text::). `async-leave-conf' (*note async-leave-conf::) is not sent when the person is deleted, so don't say that it is. Distributed with lyskomd 2.1.0. 10.7: 2002-11-03 _Fixed errors:_ The description of common block of the user area was just plain wrong. *Note The User Area::, for the updated specification. The documentation for no-of-created-texts in the `Person' structure was wrong. *Note Person::. The documentation for the privilege bits `create-conf' and `create-pers' stated that they are by default on. In fact, they are by default ignored, but off. *Note Security::. The example for `re-z-lookup' (*note re-z-lookup::) was wrong. An example for `lookup-z-name' (*note lookup-z-name::) was wrong. _Protocol change:_ Added a new "language" value to the common block of the user area. *Note The User Area::. _New aux-items:_ `world-readable' [34]. *Note Aux-Item Types::. `elisp-client-read-faq' [10000] and `elisp-client-rejected-recommendation' [10001]. *Note Some Client-specific Aux-Item Types::. _Modified aux-item:_ `send-comments-to' [33] may now also contain an optional recipient type. *Note Aux-Item Types::. _Previously undocumented stuff:_ The rules for when a membership is visible are now documented. *Note Membership visibility::. Documented the `unread-is-secret' flag of `Person'. *Note Personal-Flags::. The documentation for `get-person-stat-old' was improved(*note get-person-stat-old::). The Message-ID of exported texts is now documented. *Note Message-ID::. A client should offer to add the author as a recipient of a text he is creating if he isn't a member of any of the recipients. *Note Recipients of comments::. There should be no linefeed after the last line of a text. *Note LysKOM Content Types::. *Note Reformattable Text (text/x-kom-basic)::. Added a recommendation for how groups of `Misc-Info' items should be sorted. *Note Order of misc-info groups::. _Editorial changes:_ Several spelling errors, typos, et c were fixed. Distributed with lyskomd 2.0.7. 10.6: 2002-03-29 _Fixed errors:_ The format of the user area was plain wrong. The examples for `query-read-texts-10' and `get-membership-10' were wrong. The `idle-time' field is only affected by the `user-active' request, not by all activity (*note Session Information::). _Protocol change:_ Expanded the documentation of `super-conf'. *Note Conference Status Types::. Simplified the rules for `super-conf'; a setting of 0 no longer means anything. A new section contains a summary of how a client should decide where to send a comment, and it contains the new rules. *Note Recipients of comments::. Most clients already implemented the new rules; the old rules were overly complex. _New aux-item:_ `send-comments-to' [33]. _Modified aux-item:_ `faq-text' [14] may now be set on a letterbox. _Previously undocumented stuff:_ Expanded the documentation of `permitted-submitters'. *Note set-permitted-submitters::. Clarify that a person is a supervisor of himself, except for the `set-supervisor' call; see *Note Conferences::. Document the `change-name' privilege bit; see *Note Security::. Document that `last-login' is also updated on logout; see *Note Person Status Types::. Clarify that the address part of `redirect' [8] is a conference number. _Compatibility info:_ Mention that the elisp client used to enter texts as `x-kom/text' instead of `text/x-kom-basic'. _Administrativia:_ Updated "Future changes" (*note Future changes::), and mention that we now use Bugzilla to keep track of bugs and feature requests. _Editorial changes:_ Added some of Texinfo markup and cross references. Several spelling errors, typos, et c were fixed. Distributed with lyskomd 2.0.6. 10.5: 2001-09-30 A new section (*note Client-side name expansion::) in the informative Client Conventions appendix was written. Distributed with lyskomd 2.0.5. 10.4: 2001-05-24 _Fixed errors:_ Fixed the description of the `old-pwd' argument to `set-passwd' (*note set-passwd::). The content-type `x-kom/basic' was renamed to `text/x-kom-basic'. _Previously undocumented stuff:_ Documented several previously undocumented aspects of the protocol: the hello string used during connection establishment, the `items-to-delete' and `items-to-add' arguments of `modify-system-info', the `type' argument of `add-member' (including the fact that the invitation membership flag is automatically set in some circumstances), that a client can issue many requests at once (and that the replies are sent back in order). _New stuff:_ Registered the "rkom" user-area block. _New aux-items:_ The following predefined aux-items were added: `canonical-name' [31], `mx-list-name' [32] `mx-mime-belongs-to' [10100], `mx-mime-part-in' [10101], `mx-mime-misc' [10102], `mx-envelope-sender' [10103] and `mx-mime-file-name' [10104]. Those aux-items with a number higher than 10000 were previously documented in this document, but they now have the status of predefined aux-items. _Editorial changes:_ Lots of editorial changes needed to publish an online version on the web at `http://www.lysator.liu.se/lyskom/protocol/'. Many minor syntax errors corrected, and much missing Texinfo markup added. The document now makes heavy use of Texinfo macros. Due to bugs in the current version of `texinfo.tex' this file cannot currently be typeset using TeX. (All bugs are reported to the Texinfo maintainers.) `get-membership-old', `get-membership-10' and `login' used to take an argument of type `BITSTRING(A-SINGLE-FIELD)'. The type has now been changed to `BOOL' instead, to simplify the description. The encoding of the protocol is unchanged. The indices are now joined into a single index. More terms have been added to it. Many sections of text were moved around to make it easier to find information. Some non-normative information was moved to appendices. Removed a few non-normative empty sections. This edition was published on the web; no lyskomd release was imminent when the edition was finished. Future editions will also be published on the web; most of them will likely be published at the same time as a lyskomd release is made. They will continue to be included in the lyskomd releases. 10.3: 2000-09-09 Several aux-items can be set on letterboxes and not only conferences. A few can now be set on the server. The `allowed-content-type' and `recommended-conf' aux-items were added. The `mx-allow-filter' and `mx-reject-forward' aux-items are marked obsolete. Text regarding mail import was improved, based on actual experience in writing an email importer. Reserved a range of aux-items for komimportmail. Several minor corrections and clarifications made. Distributed with lyskomd 2.0.4. 10.2: 1999-07-23 Some typos and other minor errors were fixed. Distributed with lyskomd 2.0.2. 10.1: 1999-07-12 Call `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. 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 edition incorrectly marked the `sub-comment' call as obsolete, and stated that regexp lookup was case insensitive. Both statements were wrong, and has since been fixed. 9.0: 1996-08-04 Protocol version 9. Distributed with lyskomd 1.9.0. 8.0: 1995-11-10 Protocol version 8. Distributed with lyskomd 1.8.0. 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. 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. 1993-05-19. Linus Tolke wrote comments for some calls that were without comments. 1992-07-06. Linus Tolke converted the document to ISO 8859-1. 1991-08-12. Per Cederqvist started using version control for documentation. 1991-06-25. Lars Aronsson documented the protocol that was in use at the time.  File: protocol-a.info, Node: Index, Prev: Document Edition History, Up: Top Index ***** [index] * Menu: * accept-async: accept-async. (line 6) * add-comment: add-comment. (line 6) * add-footnote: add-footnote. (line 6) * add-member: add-member. (line 6) * add-member-old: add-member-old. (line 6) * add-recipient: add-recipient. (line 6) * Any-Conf-Type: Conference Types. (line 6) * ARRAY: Simple Data Types. (line 116) * async-broadcast: async-broadcast. (line 6) * async-deleted-text: async-deleted-text. (line 6) * async-i-am-off: async-i-am-off. (line 6) * async-i-am-on: async-i-am-on. (line 6) * async-i-am-on-obsolete: async-i-am-on-obsolete. (line 6) * async-invalidate-text-read: async-invalidate-text-read. (line 6) * async-leave-conf: async-leave-conf. (line 6) * async-login: async-login. (line 6) * async-logout: async-logout. (line 6) * async-new-membership: async-new-membership. (line 6) * async-new-motd: async-new-motd. (line 6) * async-new-name: async-new-name. (line 6) * async-new-presentation: async-new-presentation. (line 6) * async-new-recipient: async-new-recipient. (line 6) * async-new-text: async-new-text. (line 6) * async-new-text-old: async-new-text-old. (line 6) * async-new-user-area: async-new-user-area. (line 6) * async-rejected-connection: async-rejected-connection. (line 6) * async-send-message: async-send-message. (line 6) * async-sub-recipient: async-sub-recipient. (line 6) * async-sync-db: async-sync-db. (line 6) * async-text-aux-changed: async-text-aux-changed. (line 6) * async-text-read: async-text-read. (line 6) * Aux-Item: Auxiliary Information. (line 6) * Aux-Item-Flags: Auxiliary Information. (line 6) * Aux-Item-Input: Auxiliary Information. (line 6) * Aux-No: Auxiliary Information. (line 6) * BITSTRING: Simple Data Types. (line 53) * BOOL: Simple Data Types. (line 9) * broadcast: broadcast. (line 6) * change-conference: change-conference. (line 6) * change-name: change-name. (line 6) * change-what-i-am-doing: change-what-i-am-doing. (line 6) * character set: Simple Data Types. (line 33) * Conf-List-Archaic: Archaic way to list conferences. (line 9) * Conf-No: Common Types. (line 42) * Conf-Type: Conference Types. (line 6) * Conf-Z-Info: Conference Search Results. (line 6) * Conference: Conference Status Types. (line 6) * Conference-Old: Conference Status Types. (line 6) * create-anonymous-text: create-anonymous-text. (line 6) * create-anonymous-text-old: create-anonymous-text-old. (line 6) * create-conf: create-conf. (line 6) * create-conf-old: create-conf-old. (line 6) * create-person: create-person. (line 6) * create-person-old: create-person-old. (line 6) * create-text: create-text. (line 6) * create-text-old: create-text-old. (line 6) * delete-conf: delete-conf. (line 6) * delete-text: delete-text. (line 6) * disconnect: disconnect. (line 6) * Dynamic-Session-Info: Session Information. (line 6) * enable: enable. (line 6) * ENUMERATION: Simple Data Types. (line 76) * Extended-Conf-Type: Conference Types. (line 6) * find-next-conf-no: find-next-conf-no. (line 6) * find-next-text-no: find-next-text-no. (line 6) * find-previous-conf-no: find-previous-conf-no. (line 6) * find-previous-text-no: find-previous-text-no. (line 6) * first-unused-conf-no: first-unused-conf-no. (line 6) * first-unused-text-no: first-unused-text-no. (line 6) * FLOAT: Simple Data Types. (line 16) * Garb-Nice: Conference Status Types. (line 6) * get-boottime-info: get-boottime-info. (line 6) * get-client-name: get-client-name. (line 6) * get-client-version: get-client-version. (line 6) * get-collate-table: get-collate-table. (line 6) * get-conf-stat: get-conf-stat. (line 6) * get-conf-stat-old: get-conf-stat-old. (line 6) * get-conf-stat-older: get-conf-stat-older. (line 6) * get-created-texts: get-created-texts. (line 6) * get-info: get-info. (line 6) * get-info-old: get-info-old. (line 6) * get-last-text: get-last-text. (line 6) * get-map: get-map. (line 6) * get-marks: get-marks. (line 6) * get-members: get-members. (line 6) * get-members-old: get-members-old. (line 6) * get-membership: get-membership. (line 6) * get-membership-10: get-membership-10. (line 6) * get-membership-old: get-membership-old. (line 6) * get-person-stat: get-person-stat. (line 6) * get-person-stat-old: get-person-stat-old. (line 6) * get-scheduling: get-scheduling. (line 6) * get-session-info: get-session-info. (line 6) * get-session-info-ident: get-session-info-ident. (line 6) * get-static-session-info: get-static-session-info. (line 6) * get-stats: get-stats. (line 6) * get-stats-description: get-stats-description. (line 6) * get-text: get-text. (line 6) * get-text-stat: get-text-stat. (line 6) * get-text-stat-old: get-text-stat-old. (line 6) * get-time: get-time. (line 6) * get-uconf-stat: get-uconf-stat. (line 6) * get-unread-confs: get-unread-confs. (line 6) * get-version-info: get-version-info. (line 6) * HOLLERITH: Simple Data Types. (line 26) * Info: Server Information. (line 6) * Info-Old: Server Information. (line 6) * Info-Type: Article Information. (line 6) * INT16: Simple Data Types. (line 9) * INT32: Simple Data Types. (line 9) * INT8: Simple Data Types. (line 9) * Local-Text-No: Common Types. (line 49) * local-to-global: local-to-global. (line 6) * Local-To-Global-Block: Mapping Local to Global Text Numbers. (line 6) * local-to-global-reverse: local-to-global-reverse. (line 6) * login: login. (line 6) * login-old: login-old. (line 6) * logout: logout. (line 6) * lookup-conf: lookup-conf. (line 6) * lookup-name: lookup-name. (line 6) * lookup-person: lookup-person. (line 6) * lookup-z-name: lookup-z-name. (line 6) * map-created-texts: map-created-texts. (line 6) * map-created-texts-reverse: map-created-texts-reverse. (line 6) * Mark: Article Marks. (line 6) * mark-as-read: mark-as-read. (line 6) * mark-as-unread: mark-as-unread. (line 6) * mark-text: mark-text. (line 6) * mark-text-old: mark-text-old. (line 6) * Member: Membership Information. (line 50) * Membership: Membership Information. (line 80) * Membership-10: Membership Information. (line 80) * Membership-Old: Membership Information. (line 80) * Membership-Type: Membership Information. (line 6) * Misc-Info: Article Information. (line 6) * modify-conf-info: modify-conf-info. (line 6) * modify-system-info: modify-system-info. (line 6) * modify-text-info: modify-text-info. (line 6) * Pers-No: Common Types. (line 64) * Person: Person Status Types. (line 6) * Personal-Flags: Person Status Types. (line 6) * Priv-Bits: Person Status Types. (line 6) * query-async: query-async. (line 6) * query-predefined-aux-items: query-predefined-aux-items. (line 6) * query-read-texts: query-read-texts. (line 6) * query-read-texts-10: query-read-texts-10. (line 6) * query-read-texts-old: query-read-texts-old. (line 6) * re-lookup-conf: re-lookup-conf. (line 6) * re-lookup-person: re-lookup-person. (line 6) * re-z-lookup: re-z-lookup. (line 6) * Read-Range: Membership Information. (line 80) * RPC: Simple Data Types. (line 161) * Scheduling-Info: Session Information. (line 6) * SELECTION: Simple Data Types. (line 133) * send-message: send-message. (line 6) * Session-Flags: Session Information. (line 6) * Session-Info: Session Information. (line 6) * Session-Info-Ident: Session Information. (line 6) * Session-No: Common Types. (line 64) * set-client-version: set-client-version. (line 6) * set-conf-type: set-conf-type. (line 6) * set-connection-time-format: set-connection-time-format. (line 6) * set-etc-motd: set-etc-motd. (line 6) * set-expire: set-expire. (line 6) * set-garb-nice: set-garb-nice. (line 6) * set-info: set-info. (line 6) * set-keep-commented: set-keep-commented. (line 6) * set-last-read: set-last-read. (line 6) * set-membership-type: set-membership-type. (line 6) * set-motd-of-lyskom: set-motd-of-lyskom. (line 6) * set-passwd: set-passwd. (line 6) * set-permitted-submitters: set-permitted-submitters. (line 6) * set-pers-flags: set-pers-flags. (line 6) * set-presentation: set-presentation. (line 6) * set-priv-bits: set-priv-bits. (line 6) * set-read-ranges: set-read-ranges. (line 6) * set-scheduling: set-scheduling. (line 6) * set-super-conf: set-super-conf. (line 6) * set-supervisor: set-supervisor. (line 6) * set-unread: set-unread. (line 6) * set-user-area: set-user-area. (line 6) * shutdown-kom: shutdown-kom. (line 6) * Static-Server-Info: Server Information. (line 6) * Static-Session-Info: Session Information. (line 6) * Stats: Statistics. (line 6) * Stats-Description: Statistics. (line 6) * sub-comment: sub-comment. (line 6) * sub-footnote: sub-footnote. (line 6) * sub-member: sub-member. (line 6) * sub-recipient: sub-recipient. (line 6) * sync-kom: sync-kom. (line 6) * Text-Id: Membership Information. (line 177) * Text-List: Common Types. (line 49) * Text-Mapping: Mapping Local to Global Text Numbers. (line 6) * Text-No: Common Types. (line 49) * Text-Number-Pair: Mapping Local to Global Text Numbers. (line 6) * Text-Stat: Article Information. (line 6) * Text-Stat-Old: Article Information. (line 6) * Time: Common Types. (line 12) * UConference: Conference Status Types. (line 6) * Unicode: Simple Data Types. (line 33) * unmark-text: unmark-text. (line 6) * user-active: user-active. (line 6) * Version-Info: Server Information. (line 6) * who-am-i: who-am-i. (line 6) * Who-Info: Who Information. (line 6) * Who-Info-Ident: Who Information. (line 6) * Who-Info-Old: Who Information. (line 6) * who-is-on: who-is-on. (line 6) * who-is-on-dynamic: who-is-on-dynamic. (line 6) * who-is-on-ident: who-is-on-ident. (line 6) * who-is-on-old: who-is-on-old. (line 6)