diff --git a/doc/Protocol-A.texi b/doc/Protocol-A.texi index 22b1ca7ff5b43bc9e8ca8ff4ee2db8108a235cf1..f20052159e07b12a2f424469c97297ef8982596b 100644 --- a/doc/Protocol-A.texi +++ b/doc/Protocol-A.texi @@ -1,25 +1,19 @@ \input texinfo @c -*-texinfo-*- @c -@c FIXME: Things ceder are about to fix: -@c FIXME: -@c FIXME: sentence-end-double-space! -@c FIXME: "Foo bar (bar baz.)" or "Foo bar (bar baz)."? -@c FIXME: "Aux-Item Types" borders on being too long -@c FIXME: @c FIXME: Things that require a resolution in the WG: -@c FIXME: +@c FIXME: @c FIXME: "x-kom/basic" should be "text/x-kom-basic" (6435471) @c FIXME: get rid of "komimportmail Aux-Item Types" (6435520) @c FIXME: Explain how the garb works with nice and keep-commented -@c FIXME: +@c FIXME: @c FIXME: Nodes ceder are about to remove: -@c FIXME: +@c FIXME: @c FIXME: "Conference Lists (x-kom/conflist)" is empty (6435528) @c FIXME: "Only read the most recent N texts" is empty @c FIXME: "Review the last N by FOO to BAR" is empty @c FIXME: "Remote control" contains no information @c -@c $Id: Protocol-A.texi,v 1.143 2001/05/05 21:21:41 ceder Exp $ +@c $Id: Protocol-A.texi,v 1.144 2001/05/05 21:44:53 ceder Exp $ @c %**start of header @setfilename protocol-a.info @settitle LysKOM Protocol A @@ -362,7 +356,7 @@ This document specifies version @value{PROTOVER} of LysKOM Protocol A. This is edition @value{PROTOEDITION} of the specification. It corresponds to version @value{VERSION} of lyskomd. -The most up-to-date version if this document can always be found at +The most up-to-date version if this document can always be found at @uref{http://www.lysator.liu.se/lyskom/protocol/}. @end ifnottex @@ -399,22 +393,22 @@ the web at @uref{http://www.lysator.liu.se/lyskom/protocol/}. @end iftex LysKOM is a conferencing system@footnote{Or in modern terms, enabling -technology for Computer-Supported Cooperative Work (CSCW).}. Similar +technology for Computer-Supported Cooperative Work (CSCW).}. Similar systems were QZ-KOM and PortaCOM@footnote{Also known as ``PottaKOM'' and -``BortaKOM.''}. The LysKOM system is copyrighted by Lysator Academic +``BortaKOM.''}. The LysKOM system is copyrighted by Lysator Academic Computing Society and distributed under conditions of the GNU Public -License. LysKOM and its documentation is provided ``as is'' without +License. LysKOM and its documentation is provided ``as is'' without warranty of any kind. Anything described here as ``unspecified'' is liable to change in future protocol versions. -This specification is the work of several people. The main contributors have +This specification is the work of several people. The main contributors have been -Per Cederqvist @email{ceder@@lysator.liu.se}, +Per Cederqvist @email{ceder@@lysator.liu.se}, David Byers @email{byers@@lysator.liu.se}, @value{Pell} @email{pell@@lysator.liu.se}, -Thomas Bellman @email{bellman@@lysator.liu.se}, +Thomas Bellman @email{bellman@@lysator.liu.se}, Lars Aronsson @email{aronsson@@lysator.liu.se}, Linus Tolke @email{linus@@lysator.liu.se} and @value{Kent} @email{kent@@lysator.liu.se}. @@ -426,7 +420,7 @@ The LysKOM developers can be reached by email to @chapter Concepts used in LysKOM This chapter introduces the concepts used in LysKOM, such as articles, -conferences and sessions. +conferences and sessions. @menu * Articles:: @@ -443,7 +437,7 @@ conferences and sessions. @section Articles An article is represented as a value of the type @type{Text-Stat} and a -string containing the article contents. An article will usually have one +string containing the article contents. An article will usually have one or more recipients and may be a comment or footnote to other articles. Each article is kept in the database until it is older than the @field{nice} value of each of its recipients and it is not marked by any @@ -473,48 +467,48 @@ The server call @reqdlink{local-to-global} does this@linkhere{}. @node Conferences @section Conferences -Conferences hold articles. They are represented in the protocol as a -data type called @type{Conference}. Each conference has a +Conferences hold articles. They are represented in the protocol as a +data type called @type{Conference}. Each conference has a @dfn{creator}, the person who created the conference, and a @dfn{supervisor}, a conference whose members can modify the conference. If the supervisor is a person, the members of that person's mailbox -are supervisors, which in most cases is only that person. We have also +are supervisors, which in most cases is only that person. We have also introduced a type called @type{UConference} (pronounced micro-conf-stat) which holds a subset of the information contained in the full -@type{Conference} type. Use the @type{UConference} type whenever +@type{Conference} type. Use the @type{UConference} type whenever possible since it places a much smaller load on the LysKOM server. Each conference has a type, which is essentially a collection of -boolean flags. Currently the flags @conftype{rd-prot}, +boolean flags. Currently the flags @conftype{rd-prot}, @conftype{letterbox}, @conftype{secret}, @conftype{original}, @conftype{allow-anonymous} and @conftype{forbid-secret} are defined. @table @conftype @item rd-prot -The conference is protected from reading by non-members. Persons become +The conference is protected from reading by non-members. Persons become members by having one of the existing members or supervisors add him or -her to the conference. This restriction is enforced by the server. +her to the conference. This restriction is enforced by the server. @item original Conferences of this type are intended for original articles only. -Comments are to be redirected to the super-conference instead. This +Comments are to be redirected to the super-conference instead. This restriction is currently not enforced by the server; clients must implement this functionality. @item letterbox -Conferences of this type are connected to persons. Letters to a person +Conferences of this type are connected to persons. Letters to a person are sent to the mailbox and the name of the mailbox is synchronized -with the person name. It is currently not possible to explicitly set or +with the person name. It is currently not possible to explicitly set or clear this flag on a conference. @item secret -Conferences of this type are secret. The server will not divulge any +Conferences of this type are secret. The server will not divulge any information about the existence of the conference to persons who are not -members or supervisors of the conference. If a mailbox is made secret, +members or supervisors of the conference. If a mailbox is made secret, that person cannot log in using the person name, but must specify a person number instead. @item allow-anonymous -Conferences of this type accept anonymous articles. Other conferences +Conferences of this type accept anonymous articles. Other conferences will reject anonymous articles. @item forbid-secret -Conferences of this type do not allow secret members. If a conference is +Conferences of this type do not allow secret members. If a conference is changed to this type, preexisting secret members remain secret. @end table @@ -524,16 +518,16 @@ changed to this type, preexisting secret members remain secret. @section Persons and Sessions Persons are represented in the protocol by values of the type -@type{Person}. Associated with persons are statistics, a set of personal -flags and a set of privileges (@pxref{Security}). Persons are also +@type{Person}. Associated with persons are statistics, a set of personal +flags and a set of privileges (@pxref{Security}). Persons are also associated with a conference that has the same number as the person and the @conftype{letterbox} bit set. Connections to the server are represented as values of the type @type{Static-Session-Info}, @type{Session-Info-Ident} or -@type{Session-Info}. Sessions have session number that are unique for -each session in the lifetime of the server execution. A single user can -have several sessions running at once. The session is not released until +@type{Session-Info}. Sessions have session number that are unique for +each session in the lifetime of the server execution. A single user can +have several sessions running at once. The session is not released until the network connection is closed; a user can log in and out repeatedly in a single session. @@ -541,34 +535,34 @@ in a single session. @node The Misc-Info List @section The Misc-Info List -The @type{Misc-Info} list contains tagged data. The fields are sent in +The @type{Misc-Info} list contains tagged data. The fields are sent in groups pertaining to a particular type of information: information about recipient; carbon copy recipient; blank carbon copy recipient; comment to; footnote to; comment in -and footnote in. The information groups may be sent in any order and -there may be any number of groups. Within each group the elements are +and footnote in. The information groups may be sent in any order and +there may be any number of groups. Within each group the elements are always sent in the order listed below. @subsection Recipient @table @misc @item recpt -Starts a recipient group. It contains the conference number of a +Starts a recipient group. It contains the conference number of a recipient of the article. @item loc-no -Always present within a recipient group. It contains the local text +Always present within a recipient group. It contains the local text number of the article in the conference specified by the preceding @misc{recpt} field. @item rec-time If the recipient is a person, this element is added by the server when -the recipient marks the article as read. It contains the time when the +the recipient marks the article as read. It contains the time when the text was read. @item sent-by Present when the recipient was added by a person other than the author (after the article was created.) It contains the person number of the person who added the recipient. @item sent-at -Present when the recipient was added after the article was created. It +Present when the recipient was added after the article was created. It contains the time when the recipient was added. @end table @@ -576,38 +570,38 @@ contains the time when the recipient was added. @subsection Carbon Copy (CC) Recipient The carbon-copy recipient group is identical to the recipient group -above. The difference is how new comments to an article with a recipient -or carbon-copy recipient are treated. A comment to an article is sent to +above. The difference is how new comments to an article with a recipient +or carbon-copy recipient are treated. A comment to an article is sent to all recipients, but not to carbon-copy recipients of the original -article. This difference is enforced by the clients. +article. This difference is enforced by the clients. @table @misc @item cc-recpt -Starts a carbon-copy recipient group. It contains the conference number +Starts a carbon-copy recipient group. It contains the conference number of a carbon-copy recipient of the article. @item loc-no -Always present in a CC recipient group. It contains the local text +Always present in a CC recipient group. It contains the local text number of the article in the conference specified by the most recent @misc{cc-recpt} field. @item rec-time -Present after the CC recipient has read the article. It contains the -time when the article was read. Since only persons can read articles +Present after the CC recipient has read the article. It contains the +time when the article was read. Since only persons can read articles this will only be seen if the CC recipient is a person. @item sent-by Present when a CC recipient was added by a person other than the author -after the article had been created. It contains the person number of the +after the article had been created. It contains the person number of the person who added the CC recipient. @item sent-at Present when a CC recipient was added after the article had been -created. It is the time when the CC recipient was added. +created. It is the time when the CC recipient was added. @end table @subsection Blank Carbon Copy (BCC) Recipient The blank carbon-copy recipient group is identical to the carbon-copy -recipient group above. The difference is the visibility of the -information. A carbon-copy recipient group is visible to anyone that is +recipient group above. The difference is the visibility of the +information. A carbon-copy recipient group is visible to anyone that is allowed to fetch both the text status of the involved text and the conference status of the involved conference. (That is, as long as the conference isn't secret everybody is allowed to see the carbon-copy @@ -628,23 +622,23 @@ to se the blank carbon copy.) @table @misc @item bcc-recpt -Starts a blank carbon-copy recipient group. It contains the conference +Starts a blank carbon-copy recipient group. It contains the conference number of a blank carbon-copy recipient of the article. @item loc-no -Always present in a BCC recipient group. It contains the local text +Always present in a BCC recipient group. It contains the local text number of the article in the conference specified by the most recent @misc{bcc-recpt} field. @item rec-time -Present after the BCC recipient has read the article. It contains the -time when the article was read. Since only persons can read articles +Present after the BCC recipient has read the article. It contains the +time when the article was read. Since only persons can read articles this will only be seen if the BCC recipient is a person. @item sent-by Present when a BCC recipient was added by a person other than the author -after the article had been created. It contains the person number of the +after the article had been created. It contains the person number of the person who added the BCC recipient. @item sent-at Present when a BCC recipient was added after the article had been -created. It is the time when the BCC recipient was added. +created. It is the time when the BCC recipient was added. @end table @@ -655,11 +649,11 @@ created. It is the time when the BCC recipient was added. Always present when the article is a comment to another article. @item sent-by Present when the article was added as a comment by a person other than -the author, after the article had been created. It contains the person +the author, after the article had been created. It contains the person number of the person who added the article as a comment. @item sent-at Present when the article was added as a comment after the article had -been created. It contains the time when it was added as a comment. +been created. It contains the time when it was added as a comment. @end table @@ -670,7 +664,7 @@ been created. It contains the time when it was added as a comment. Always present when the article is a footnote to another article. @item sent-at Present when the article was added as a footnote after the article had -been created. It contains the time when it was added as a footnote. +been created. It contains the time when it was added as a footnote. @end table @@ -678,7 +672,7 @@ been created. It contains the time when it was added as a footnote. @table @misc @item comm-in -Present when there are comments to this article. It contains the article +Present when there are comments to this article. It contains the article number which is a comment to this article. @end table @@ -687,7 +681,7 @@ number which is a comment to this article. @table @misc @item footn-in -Present when there are footnotes to this article. It contains the +Present when there are footnotes to this article. It contains the article number which is a footnote to this article. @end table @@ -696,7 +690,7 @@ article number which is a footnote to this article. @section The Aux-Item List The aux-item list is used as a generic extension mechanism in the LysKOM -server and in protocol A. +server and in protocol A. @menu * About Aux-Items:: @@ -711,28 +705,28 @@ server and in protocol A. Aux-items were introduced in protocol version 10 as a mechanism for extending the conference, text and server information structures without -changing the protocol. Persons were excluded since nobody could figure +changing the protocol. Persons were excluded since nobody could figure out a case where setting an aux-item on the mailbox wasn't as good as setting it on the person (another reason was that I was fed up writing aux-item code by the time they were working on texts and conferences.) The exact structure of an aux item is specified elsewhere -(@pxref{Auxiliary Information}). The important fields here are the +(@pxref{Auxiliary Information}). The important fields here are the @field{aux-no}, @field{tag} and @field{data} fields. -The @field{aux-no} field is used to identify an item. The +The @field{aux-no} field is used to identify an item. The @field{aux-no} together with a text or conference number uniquely identifies a particular aux item. Items are numbered from one and up -within each item list. Once assigned, the @field{aux-no} for an item -is never changed. New items are guaranteed to be assigned numbers that +within each item list. Once assigned, the @field{aux-no} for an item +is never changed. New items are guaranteed to be assigned numbers that have never been used before within a particular list. -The @field{tag} field identifies the type of aux item. It is used by +The @field{tag} field identifies the type of aux item. It is used by the server and by clients to figure out how to interpret the data field, and by the server to decide if the item needs special treatment. -The @field{data} field is a simple string. The meaning of the string +The @field{data} field is a simple string. The meaning of the string is determined by the @field{tag} field, but since it is a string, clients that have no understanding of the contents can successfully parse the item anyway (in contrast to items in the misc-info list.) @@ -743,18 +737,18 @@ parse the item anyway (in contrast to items in the misc-info list.) @subsection Predefined Aux-Item Types Predefined Aux-Item types are part of Protocol A, and clients should -support all of them. As with other parts of the protocol, changes to +support all of them. As with other parts of the protocol, changes to these definitions will be made backwards-compatible, if possible. Creation and deletion of items with a predefined type can cause -arbitrarily complex and wonderous behavior in the server. Furthermore, +arbitrarily complex and wonderous behavior in the server. Furthermore, the server may place constraints on the items with regard to content, flags, who can create them, to what objects they can be attached and -so forth. The server may also silently enforce specific values for any +so forth. The server may also silently enforce specific values for any field of an item, regardless of what the client requests. All items with tags in the range 1-9999 and 30000 and up are considered -predefined. If a client attempts to create an item with a tag in this +predefined. If a client attempts to create an item with a tag in this range, but the server has no idea what that tag means, the server will return an error (illegal-aux-item.) @@ -762,15 +756,15 @@ return an error (illegal-aux-item.) @node Client-Specific Aux-Item Types @subsection Client-Specific Aux-Item Types -Client-specific items do not cause the server to perform any magic. All +Client-specific items do not cause the server to perform any magic. All the flags (except the delete flag) are left untouched, the data is not -validated in any way, and anyone can create any item. If you need more +validated in any way, and anyone can create any item. If you need more server support than this, your item should be on the predefined list. -All tags in the range 10000-19999 are reserved for clients. Blocks of -100 numbers at a time can be assigned to specific clients. A client +All tags in the range 10000-19999 are reserved for clients. Blocks of +100 numbers at a time can be assigned to specific clients. A client should never create items with tags in a range assigned to another -client or in an unassigned range. Assigned ranges will never change. +client or in an unassigned range. Assigned ranges will never change. Currently, the following ranges are assigned to clients: @itemize @bullet @@ -798,7 +792,7 @@ These aux-items are documented here: 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 +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). @@ -806,26 +800,26 @@ attachment, not a normal comment). @item 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. +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. @item 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 +text. It is set by the importer. The fields are concatenated with "\n". Clients are encouraged to provide a command to display this. @item mx-envelope-sender [10103] (text) -Data is the envelope sender of an imported text. The mail server is +Data is the envelope sender of an imported text. The mail server is supposed to pass this information to the importer, for inclusion here. @item mx-mime-file-name [10104] (text) -Data is the file name of an attachment. Most likely, the importer gets +Data is the file name of an attachment. Most likely, the importer gets this information from a @code{name} parameter on a @code{Content-Type} MIME header line. @@ -837,8 +831,8 @@ when the user chooses to save the text. @node Experimental Aux-Item Types @subsection Experimental Aux-Item Types -Experimental numbers are free for all. Use 'em any way you want. All -numbers in the range 20000-29999 are for experimental use. +Experimental numbers are free for all. Use 'em any way you want. All +numbers in the range 20000-29999 are for experimental use. @@ -847,11 +841,11 @@ numbers in the range 20000-29999 are for experimental use. If you want a new predefined item type, just document what it does, what the data format looks like and what the server is to do with the item -and send this to the LysKOM development group. We'll assign a number to -your item and put the documentation in this document. +and send this to the LysKOM development group. We'll assign a number to +your item and put the documentation in this document. If you're not sure what you want the data to look like yet, make a note -in your documentation that the data format might change. Once you have a +in your documentation that the data format might change. Once you have a data format you're happy with, update the documentation so others may use your item. @@ -861,7 +855,7 @@ yourself, or hope that the development group thinks your idea is so cool we do the job for you. The idea is not to reject any type of item, unless there's already an -item type that does the job just as well. Adding item types should be a +item type that does the job just as well. Adding item types should be a much less painful process than adding new calls. @@ -871,12 +865,12 @@ much less painful process than adding new calls. @node Security @section Security -Security in LysKOM is based on two components. Each person has a set -of privileges and each session has a security level. Rights in the +Security in LysKOM is based on two components. Each person has a set +of privileges and each session has a security level. Rights in the system require both the sufficient privileges and a sufficient -security level. The privileges currently available are @priv{wheel}, +security level. The privileges currently available are @priv{wheel}, @priv{admin}, @priv{statistic}, @priv{create-conf}, @priv{create-pers} -and @priv{change-name}. Security levels range from 0 to 255. +and @priv{change-name}. Security levels range from 0 to 255. @table @priv @item wheel @@ -945,45 +939,45 @@ Create persons @section Membership and Reading Persons' memberships in conferences are represented in the protocol as -arrays of @type{Membership}-typed values. This structure contains +arrays of @type{Membership}-typed values. This structure contains information about how and when the membership was created and which texts have been read in the conference. -There are two kinds of memberships. An active membership indicates that -the person is actively participating in the conference, wants to know if +There are two kinds of memberships. An active membership indicates that +the person is actively participating in the conference, wants to know if there are unread texts and wants to receive messages send to the -conference. A passive membership is similar to no membership at all. The +conference. A passive membership is similar to no membership at all. The person is still a member but will not receive messages sent to the -conference and will not be notified when there are new texts. From the +conference and will not be notified when there are new texts. From the user's perspective, passive membership should be like no membership at all, but the server still remembers what the user has read in the -conference while he or she was an active member. Since protocol version +conference while he or she was an active member. Since protocol version 10 a bit in the membership type field of the membership structure -indicates the type of membership. Previously the server did not support +indicates the type of membership. Previously the server did not support passive memberships, but there was a convention that clients should treat the priority level zero as a passive membership. The membership record indicates which texts have been read through the -@field{last-text-read} and @field{read-texts} fields. All texts with local -numbers up to @field{last-text-read} have been read. In addition, all +@field{last-text-read} and @field{read-texts} fields. All texts with local +numbers up to @field{last-text-read} have been read. In addition, all texts with local numbers contained in the @field{read-texts} array have been read. Finding out which articles a person has read in a particular conference -requires a few calls. Normally, a client will retrieve a batch of -perhaps 50 articles at a time. The outline of the process is as follows: +requires a few calls. Normally, a client will retrieve a batch of +perhaps 50 articles at a time. The outline of the process is as follows: @enumerate @item Fetch the membership to get the @field{last-text-read} @item Use @reqlink{local-to-global} to translate a number of local numbers to global numbers. -@item Remove the global numbers corresponding to local numbers contained +@item Remove the global numbers corresponding to local numbers contained in @field{read-texts} from the result. @item Get and translate more texts as needed. @end enumerate The process is complicated because of the translation between local -and global text numbers. If the server does not implement the +and global text numbers. If the server does not implement the @reqdlink{local-to-global} call@linkhere{}, it is possible to use the less efficient but perfectly serviceable @reqdlink{get-map} call instead@linkhere{}. @@ -992,9 +986,9 @@ instead@linkhere{}. @node Fundamentals @chapter Fundamentals of Protocol A -The data types in protocol A come in two flavors. The first (vanilla) +The data types in protocol A come in two flavors. The first (vanilla) are the simple data types from which the LysKOM (chocolate) data types -are built. Simple data types include things like integers and strings +are built. Simple data types include things like integers and strings while complex data types include things such as conferences and people. @menu @@ -1016,15 +1010,15 @@ Data fields have been given names that start with a lower-case letter. Fundamental data types have names in all-caps (such as @type{INT32} and @type{ARRAY}). -Derived data types have names that start with an upper-case letter. (If +Derived data types have names that start with an upper-case letter. (If the type contains more than one word, all words start with an upper-case letter, like this: @type{Text-Stat}.) The operator @code{::=} defines the name to its left. Comments start with @code{!} (exclamation mark) and alternatives are separated by a @code{|} (vertical bar.) A @code{;} (semicolon) -terminates statements in the grammar. In some specifications there are -literal strings. There is to be no whitespace before or after literal +terminates statements in the grammar. In some specifications there are +literal strings. There is to be no whitespace before or after literal strings unless there is whitespace in the literal itself. @@ -1042,7 +1036,7 @@ strings unless there is whitespace in the literal itself. @tindex INT8 @tindex BOOL @type{INT32}, @type{INT16}, @type{INT8} and @type{BOOL} are non-negative -integers which must fit in 32, 16, 8 and 1 bits, respectively. They are +integers which must fit in 32, 16, 8 and 1 bits, respectively. They are transmitted to the server in ASCII-encoded decimal notation. @@ -1050,10 +1044,10 @@ transmitted to the server in ASCII-encoded decimal notation. @subsection Strings @tindex HOLLERITH -@type{HOLLERITH} denotes character strings of arbitrary length. They are +@type{HOLLERITH} denotes character strings of arbitrary length. They are transmitted as @code{@var{n}H@var{text}} where @var{text} is the string and @var{n} is the number of characters in @var{text} in decimal -notation. All byte values are allowed in the string itself, including +notation. All byte values are allowed in the string itself, including nulls. Long live FORTRAN! @@ -1065,13 +1059,13 @@ Long live FORTRAN! @tindex BITSTRING @type{BITSTRING} is a string of bits, commonly used for a set of -boolean-valued flags. Bit strings are denoted as +boolean-valued flags. Bit strings are denoted as @example BITSTRING ( name-1; name-2; name-3; @dots{} ) @end example -in this specification. They are transmitted as a sequence of ASCII ones +in this specification. They are transmitted as a sequence of ASCII ones and zeroes in the order the fields are listed. For instance, given the specification @@ -1093,16 +1087,16 @@ most peoples idea of @code{shape-of-world} would be sent as @code{0101} @subsection Enumerations @tindex ENUMERATION -@type{ENUMERATION} is an integer constant. It is transmitted as an INT32, -but only fixed values are permitted. Clients should be prepared to +@type{ENUMERATION} is an integer constant. It is transmitted as an INT32, +but only fixed values are permitted. Clients should be prepared to receive numbers outside the enumeration and either handle this gracefully as an error or use a reasonable default value in place of an invalid enumeration value. -An enumeration is specified as +An enumeration is specified as @example - ENUMERATION ( + ENUMERATION ( name-1=value-1; name-2=value-2; name-3=value-3; @@ -1112,7 +1106,7 @@ An enumeration is specified as This specification states that name-1 is represented by the integer value-1, name-2 is represented by value-2 and name-3 is represented by -value-3. +value-3. An enumeration can also be inherited from a SELECTION datatype: @@ -1149,13 +1143,13 @@ The specification for an array is @code{ARRAY @var{type}} where Arrays are transmitted as an @code{@var{n} @{ @var{element} @var{element} @dots{} @}} where @var{n} is the number of elements and -each @var{element} is an element of the array. A special case is when -the array is empty, in which case the server transmits it as @code{0 *}. +each @var{element} is an element of the array. A special case is when +the array is empty, in which case the server transmits it as @code{0 *}. Note that the client must always transmit empty arrays as @code{0 @{ @}}. In some calls the client can ask the server not to send the array -contents, only its length. In these cases the array is transmitted as +contents, only its length. In these cases the array is transmitted as @code{@var{n} *} where @var{n} is the number of elements in the array. @@ -1163,7 +1157,7 @@ contents, only its length. In these cases the array is transmitted as @subsection Selection @tindex SELECTION -@type{SELECTION} is tagged data. It consists of an INT32 selector +@type{SELECTION} is tagged data. It consists of an INT32 selector followed by a tail of an arbitrary type and is specified as @example @@ -1180,7 +1174,7 @@ its type. @var{name} and @var{tail} are often very similar, such as @samp{sent-by} and @samp{sender}. When transmitted, the selector is transmitted as an INT32 followed by -the tail belonging to that selector. For instance, given the +the tail belonging to that selector. For instance, given the specification @example @@ -1198,7 +1192,7 @@ two legal messages of the type @code{description} are @samp{1 4HJohn} and @subsection RPC @tindex RPC -@type{RPC} is a notation used to specify calls to the server. An RPC +@type{RPC} is a notation used to specify calls to the server. An RPC specification has the following form: @example @@ -1213,16 +1207,16 @@ number, @var{request} is a single data element sent as a request and @var{reply} is a single data element sent in reply from the server. RPC calls are transmitted as @var{n} @var{request} where @var{n} and -@var{request} have the same meaning as above. Note that in the +@var{request} have the same meaning as above. Note that in the client-server dialog a reference number must also be supplied with each -request. This reference number is not part of the RPC itself, but is +request. This reference number is not part of the RPC itself, but is required for communications; see @ref{Client-Server Dialog}. @subsection Structure -Structures are collections of several data items. In the specification +Structures are collections of several data items. In the specification they are written as @example @@ -1257,7 +1251,7 @@ believed. ``Protocol A'' will continue to evolve, but it is unlikely that it will ever be superceded by ``Protocol B''.}. The protocol version letter should be -followed by connection information required by that protocol. In +followed by connection information required by that protocol. In protocol A the connection information is a @type{HOLLERITH} string saying who the user connecting is followed by a newline character. @@ -1270,7 +1264,7 @@ When the server has accepted the connection it replies with the string % telnet kom.lysator.liu.se 4894 Trying 130.236.254.151 ... Connected to varg.lysator.liu.se. -@c This comment matches the bracket on the next line: [ +@c This comment matches the bracket on the next line: [ Escape character is '^]'. A26Hbyers%kajsa.lysator.liu.se LysKOM @@ -1285,8 +1279,8 @@ character is anything but an @samp{A}. The connection will be closed by the server as soon as this string has been sent. The @samp{%% No connections left.} reply is sent if the server is not -accepting additional connections. This error is transient. The next -connection attempt may succeed. Clients should wait a few seconds before +accepting additional connections. This error is transient. The next +connection attempt may succeed. Clients should wait a few seconds before attempting to make another connection after receiving this error. The connection will be closed by the server as soon as this string has been sent. @@ -1296,9 +1290,9 @@ been sent. After connecting (@pxref{Connecting to the Server}), calls to the server can be made. Most calls require -the user to log in, but some calls can be made without a log-in. Calls +the user to log in, but some calls can be made without a log-in. Calls to the server are made by sending a reference number followed by the -call as specified. The call @emph{must} be terminated with a linefeed +call as specified. The call @emph{must} be terminated with a linefeed character (ASCII 0x0A). @example @@ -1343,8 +1337,8 @@ client in the future.}. @end example Our notation is not flexible enough to specify the two-way nature of -the communication. @field{ref-no} in the reply is always the same as -@field{ref-no} in the corresponding request. @field{reply-data} +the communication. @field{ref-no} in the reply is always the same as +@field{ref-no} in the corresponding request. @field{reply-data} depends on which request was made and is specified together with each request. @@ -1352,19 +1346,19 @@ Note that there is no whitespace after the initial indicator in the reply. Data elements sent from the client to the server are separated by one or -more space characters (ASCII 32). An entire call is terminated by a -linefeed character (ASCII 10). +more space characters (ASCII 32). An entire call is terminated by a +linefeed character (ASCII 10). Earlier versions of the protocol specified that data elements could be separated by any number of linefeed (ASCII 10), return (ASCII 13), tab -(ASCII 9) or space (ASCII 32) characters. Servers should be forgiving +(ASCII 9) or space (ASCII 32) characters. Servers should be forgiving and understand requests using the older conventions, but clients must conform to the current convention of separating data elements with spaces and terminating all requests with a linefeed character. The @errorcode{not-implemented} error code will not be returned properly unless the client follows this requirement. -The server may return two different types of errors. Normal +The server may return two different types of errors. Normal @code{error-reply} errors are replies to syntactically correct calls to the server, while @code{protocol-error} are replies to syntactically incorrect calls. @xref{Protocol Error Messages}, for more information @@ -1377,23 +1371,23 @@ Codes}, and the documentation for each call, for a list of available @field{error-code} values and what they mean. A client should be prepared for any error code in response to any call, -no matter if the response makes any sense or not. The value returned in +no matter if the response makes any sense or not. The value returned in @field{error-status} was more or less undefined before protocol version -10. For protocol version 10, the meaning of @field{error-status} is +10. For protocol version 10, the meaning of @field{error-status} is defined in this document. -The meaning of @field{error-status} can be modified by any call. In +The meaning of @field{error-status} can be modified by any call. In particular the calls that deal with Misc-Info lists set @field{error-status} to the index of the misc item that caused the error (if the error was caused by a misc item.) Client should handle the error messages listed with each call in a -graceful manner. In addition, the following error types should always +graceful manner. In addition, the following error types should always be handled gracefully: @errorcode{temporary-failure}, @errorcode{internal-error}, @errorcode{feature-disabled}, @errorcode{not-implemented}, @errorcode{obsolete-call}, @errorcode{ldb-error}, @errorcode{feature-disabled}, -@errorcode{out-of-memory}. Client should also be able to handle any +@errorcode{out-of-memory}. Client should also be able to handle any error in any situation without choking completely since bugs might cause the wrong error message to be sent or new errors might be added later on. @@ -1403,29 +1397,29 @@ later on. @section Protocol Error Messages Protocol error messages are sent in reply to syntactically incorrect -calls to the server. These -should never appear in the client-server dialog. If they do, there is -probably a bug in the client. +calls to the server. These +should never appear in the client-server dialog. If they do, there is +probably a bug in the client. @table @asis @item "%% LysKOM protocol error." -The client has sent a request that does not comply with protocol A. The -server will attempt to recover from this error, but additional calls may +The client has sent a request that does not comply with protocol A. The +server will attempt to recover from this error, but additional calls may be silently lost, and the server may send replies that the client does not expect, and in some cases recovery may not be possible. This error is also returned when the client sends an array that is longer than the maximum allowed by the server. @item "%%Insane token length." -The client has sent a single token that is insanely long. Typically this +The client has sent a single token that is insanely long. Typically this means that the client has sent several kilobytes worth of digits, or -something similar. This is never returned for long strings. The server +something similar. This is never returned for long strings. The server will automatically disconnect a client who sends a token with an insane length. @item "%%Insane array size." -The client has send an array with a negative length. The server is not -easily fooled. The server will automatically disconnect a client who +The client has send an array with a negative length. The server is not +easily fooled. The server will automatically disconnect a client who sends an array with an insane length. @end table @@ -1434,9 +1428,9 @@ sends an array with an insane length. @node LysKOM Data Types @chapter LysKOM Data Types -In this section the data types specific to LysKOM are defined. Most of +In this section the data types specific to LysKOM are defined. Most of these will probably make very little sense until you know what calls -there are. This section does not include the server calls or +there are. This section does not include the server calls or asynchronous messages, even though these are also data types. Since the types defined here are all based on the simple types, the @@ -1483,12 +1477,12 @@ the more complex data types. ) @end example -@type{Time} is used to specify times in several data structures. The +@type{Time} is used to specify times in several data structures. The fields @field{seconds}, @field{minutes} and @field{hours} give wall clock -time. @field{day} is the day of month and @field{month} is the current -month, starting with zero for January. @field{year} is the number of -years since 1900. @field{day-of-week} is the current weekday, with zero -used for Sunday. @field{day-of-year} is how many days of the year have +time. @field{day} is the day of month and @field{month} is the current +month, starting with zero for January. @field{year} is the number of +years since 1900. @field{day-of-week} is the current weekday, with zero +used for Sunday. @field{day-of-year} is how many days of the year have passed starting with zero and @field{is-dst} is true when the time indicated is daylight savings time. @@ -1528,7 +1522,7 @@ This type denotes a conference number. These three types are used to indicate articles in the LysKOM database. @type{Text-No} is a global text number and @type{Local-Text-No} a local -text number. @type{Text-List} is used when a mapping from local to +text number. @type{Text-List} is used when a mapping from local to global numbers are required. @anchor{Pers-No} @@ -1597,7 +1591,7 @@ Aux-Item and Aux-Item-Input have the following meaning: @table @field @item aux-no -The number of the item within the list where it is found. This number +The number of the item within the list where it is found. This number together with a conference or text number uniquely identifies a particular aux-item. (There is also a global list of Aux-Items for the server. That list is manipulated via the @@ -1607,7 +1601,7 @@ the @field{aux-no} is enough to uniquely identify the aux-item.) This field is not present in @type{Aux-Item-Input}. It is assigned by the server. @item tag -The item tag. The tag determines what the data means. +The item tag. The tag determines what the data means. @item creator The person who created the item, or zero if the item was created anonymously or if the owner is being withheld. @@ -1622,10 +1616,10 @@ the server. @item flags The item flags (see below). @item inherit-limit -Determines how many times (how deep) an item may be inherited. If zero, -the item is inherited an unlimited number of times. If nonzero it is +Determines how many times (how deep) an item may be inherited. If zero, +the item is inherited an unlimited number of times. If nonzero it is @emph{one more} than the number of additional times the item may be -inherited. Thus, 1 means that inheritance will be blocked and 2 means +inherited. Thus, 1 means that inheritance will be blocked and 2 means that the item will be inherited only to the next level. @item data The item data. @@ -1683,7 +1677,7 @@ The object the item is set on will not be garbage-collected. These types are used to specify the type of a conference. @type{Conf-Type} is used in data types and calls that were created before version 8.0 of the protocol and has been augmented in -@type{Extended-Conf-Type}. The type @type{Any-Conf-Type} is used when +@type{Extended-Conf-Type}. The type @type{Any-Conf-Type} is used when either is admissible. The bits have the following meaning (@pxref{Conferences}, for more @@ -1697,7 +1691,7 @@ If unset anyone can add themselves as members to the conference. If set, comments are not allowed in the conference. @item secret -If set the conference is secret. It's existence will only be revealed to +If set the conference is secret. It's existence will only be revealed to members and supervisors. @item letterbox @@ -1711,8 +1705,8 @@ If set, secret members cannot be added to the conference. @itemx reserved2 @itemx reserved3 -Reserved for future use. The values of these bits should be never be -modified or used by clients who do not know their meaning. When a new +Reserved for future use. The values of these bits should be never be +modified or used by clients who do not know their meaning. When a new conference is created these should always be set to zero. @end table @@ -1723,7 +1717,7 @@ conference is created these should always be set to zero. @anchor{Conf-Z-Info} @tindex Conf-Z-Info @example - Conf-Z-Info ::= + Conf-Z-Info ::= ( name : @lt{HOLLERITH}; type : @lt{Conf-Type}; conf-no : @lt{Conf-No}; @@ -1746,7 +1740,7 @@ conferences based on their names. @example Garb-Nice ::= @lt{INT32}; - Conference-Old ::= + Conference-Old ::= ( name : @lt{HOLLERITH}; type : @lt{Conf-Type}; creation-time : @lt{Time}; @@ -1764,7 +1758,7 @@ conferences based on their names. ) @anchor{Conference} - Conference ::= + Conference ::= ( name : @lt{HOLLERITH}; type : @lt{Extended-Conf-Type}; creation-time : @lt{Time}; @@ -1795,7 +1789,7 @@ conferences based on their names. These three types are used to specify information about a conference. @type{Garb-Nice} is a quantity used to specify how long articled are -kept in a conference before being removed. @type{Conference} is the full +kept in a conference before being removed. @type{Conference} is the full information about a conference and @type{UConference} is brief information about a conference. @@ -1826,9 +1820,9 @@ mailbox are allowed to submit articles to the conference.} may submit articles to the conference, or zero if anyone may do so. @item super-conf The conference that receives comments if this conference does not accept -them. Zero means the author of the comment in question. +them. Zero means the author of the comment in question. @item msg-of-day -The conference notice, if any. +The conference notice, if any. @item nice The number of days an article should be kept before being removed from the conference. @@ -1842,11 +1836,11 @@ The local number of the oldest existing article in the conference. @item no-of-texts The number of articles in the conference. @item expire -This field will be used to control when a conference expires. +This field will be used to control when a conference expires. It is not used at the moment, and should be set to zero for future compatibility. @item aux-items -The conference's aux item list. +The conference's aux item list. @end table The fields of @type{UConference} are @@ -1855,7 +1849,7 @@ The fields of @type{UConference} are @item name The name of this conference. @item type -The conference type. Note that this is an extended conference type, +The conference type. Note that this is an extended conference type, unlike the type field of @type{Conference}. @item highest-local-no The local number of the newest article in the conference. @@ -1959,7 +1953,7 @@ indicate that a certain local text number doesn't exist. @tindex Info-Old @tindex Version-Info @example - Info ::= + Info ::= ( version : @lt{INT32}; conf-pres-conf : @lt{Conf-No}; pers-pres-conf : @lt{Conf-No}; @@ -1970,7 +1964,7 @@ indicate that a certain local text number doesn't exist. ) @anchor{Info-Old} - Info-Old ::= + Info-Old ::= ( version : @lt{INT32}; conf-pres-conf : @lt{Conf-No}; pers-pres-conf : @lt{Conf-No}; @@ -1987,15 +1981,15 @@ indicate that a certain local text number doesn't exist. ) @end example -These data types contain information about the LysKOM server. The fields +These data types contain information about the LysKOM server. The fields of @type{Info} and @type{Info-Old} are @table @field @item version The server version encoded as a number @var{aa}@var{bb}@var{cc} where @var{aa} is the major version number, @var{bb} the minor number and -@var{cc} the secondary minor version. For instance, @code{10607} is -version 1.6.7 of the server. If greater than 10699 the +@var{cc} the secondary minor version. For instance, @code{10607} is +version 1.6.7 of the server. If greater than 10699 the @reqlink{get-version-info} should be used instead. @item conf-pres-conf The conference that contains conference presentations. @@ -2017,7 +2011,7 @@ The fields of @type{Version-Info} are: @table @field @item protocol-version -The version of protocol A the server is using. This may be used to +The version of protocol A the server is using. This may be used to ascertain which calls are available. @item server-software Human-readable name of the server software. @@ -2055,7 +2049,7 @@ Human-readable name of the server software version. ) @anchor{Personal-Flags} - Personal-Flags ::= BITSTRING + Personal-Flags ::= BITSTRING ( unread-is-secret; flg2; flg3; @@ -2068,7 +2062,7 @@ Human-readable name of the server software version. @anchor{Priv-Bits} - Priv-Bits ::= BITSTRING + Priv-Bits ::= BITSTRING ( wheel; admin; statistic; @@ -2088,7 +2082,7 @@ Human-readable name of the server software version. ) @end example -These types are used to specify information about persons. @type{Person} +These types are used to specify information about persons. @type{Person} contains the information about a person, @type{Personal-Flags} contains flags set by the user and @type{Priv-Bits} contains the person's privileges. @@ -2109,7 +2103,7 @@ The time when the person last logged on. The text number of the person's user area or zero if the person has no user area. @item total-time-present -The number of seconds the person has been using LysKOM. +The number of seconds the person has been using LysKOM. @item sessions The number of sessions the person has initiated. @item created-lines @@ -2156,21 +2150,21 @@ The number of conferences the person is a member of. @end example The @type{Membership-Type} type contains flags that modify a membership. -It is passed as part of both @type{Member} and @type{Membership}. The +It is passed as part of both @type{Member} and @type{Membership}. The flags are: @table @field @item invitation The member has been invited, but has not yet accepted membership. -Clients should set this flag when adding other users as members. The +Clients should set this flag when adding other users as members. The server may force this flag to be set when adding another person as a member of a conference. @item passive -The member is not actively participating in the conference. Passive +The member is not actively participating in the conference. Passive members do not receive group messages and should not be displayed as active members by clients. @item secret -The member does not wish to disclose the membership. Secret memberships +The member does not wish to disclose the membership. Secret memberships and members are cleared before being returned to a person who is not a supervisor of the member or has sufficient privileges enabled. @end table @@ -2191,17 +2185,17 @@ existing memberships. @end example The @type{Member} structure encodes information about a member in a -conference. It is returned by the @reqdlink{get-members} call@linkhere{}. The +conference. It is returned by the @reqdlink{get-members} call@linkhere{}. The fields of a @type{Member} structure are @table @field @item member The person who is a member of the conference. @item added-by -The person who created the membership. This field is zero only if the +The person who created the membership. This field is zero only if the membership was created before protocol version 10 was introduced. @item added-at -The time when the membership was created. This field is meaningless if +The time when the membership was created. This field is meaningless if added-by is zero. @item type Flags modifying the membership. @@ -2239,7 +2233,7 @@ to see the contents of the structure. @end example The @type{Membership} structure encodes information about a person's -membership in a conference. It is returned by the +membership in a conference. It is returned by the @reqlink{query-read-texts} and @reqdlink{get-membership} calls@linkhere{}. @table @field @@ -2250,18 +2244,18 @@ The time when the person last read anything from the conference. @item conference The conference this membership data pertains to. @item priority -The priority the person has assigned to the conference. The higher the -number, the higher the priority. In the past, priority zero indicated a -passive membership. This usage is now obsolete. +The priority the person has assigned to the conference. The higher the +number, the higher the priority. In the past, priority zero indicated a +passive membership. This usage is now obsolete. @item last-text-read The local number of last text read in the conference. @item read-texts Additional texts beyond @field{last-text-read} that have also been read. @item added-by -The person who created the membership. This field is zero if the +The person who created the membership. This field is zero if the membership was created before protocol version 10 was introduced. @item added-at -The time when the membership was created. This field is meaningless if +The time when the membership was created. This field is meaningless if added-by is zero. @item type Flags modifying the membership. @@ -2279,7 +2273,7 @@ to know about the person. @anchor{Mark} @tindex Mark @example - Mark ::= + Mark ::= ( text-no : @lt{Text-No}; type : @lt{INT8}; ) @@ -2297,7 +2291,7 @@ The mark value. @end table Before version eight of protocol A, the meaning of the mark value was -unspecified. Work is underway to specify the meaning of certain mark +unspecified. Work is underway to specify the meaning of certain mark values. @@ -2375,7 +2369,7 @@ The list of aux items for this article. @end table @type{Misc-Info}, when sent to the client, is sent in a particular order -(@pxref{The Misc-Info List}). The variants @type{Misc-Info} are +(@pxref{The Misc-Info List}). The variants @type{Misc-Info} are (briefly): @table @misc @@ -2405,7 +2399,7 @@ Specifies who sent this article to the conference specified by Specifies when the article was sent to the conference specified by @misc{recpt} or @misc{cc-recpt}. @item bcc-recpt -Specifies a blind carbon copy recipient. This item is only accepted by +Specifies a blind carbon copy recipient. This item is only accepted by protocol version 10 servers and is only sent in responses and messages introduced in protocol version 10 or later. @end table @@ -2447,11 +2441,11 @@ introduced in protocol version 10 or later. @end example These structures are used to retrieve and set information on who is -currently using LysKOM. The types marked as ``old'' are obsolete but are +currently using LysKOM. The types marked as ``old'' are obsolete but are included for completeness. @type{Who-Info-Old} identifies a user who is -currently using LysKOM. @type{Who-Info} is used to set information +currently using LysKOM. @type{Who-Info} is used to set information about a session and is returned by one obsolete -call. @type{Who-Info-Ident} is the preferred data type to use. +call. @type{Who-Info-Ident} is the preferred data type to use. The fields of @type{Who-Info-Old} are @@ -2516,7 +2510,7 @@ at the user's machine or ``unknown'' if Ident was not used. @tindex Session-Flags @tindex Dynamic-Session-Info @example - Session-Info ::= + Session-Info ::= ( person : @lt{Pers-No}; working-conference : @lt{Conf-No}; session : @lt{Session-No}; @@ -2526,7 +2520,7 @@ at the user's machine or ``unknown'' if Ident was not used. connection-time : @lt{Time}; ) - Session-Info-Ident ::= + Session-Info-Ident ::= ( person : @lt{Pers-No}; working-conference : @lt{Conf-No}; session : @lt{Session-No}; @@ -2570,12 +2564,12 @@ at the user's machine or ``unknown'' if Ident was not used. ) @end example -These data types give information about a particular LysKOM session. The +These data types give information about a particular LysKOM session. The types @type{Session-Info} and @type{Session-Info-Ident} have been superseded by @type{Static-Session-Info} and -@type{Dynamic-Session-Info}. The static session info represents +@type{Dynamic-Session-Info}. The static session info represents information about a session that does not change during the lifetime of -the session. Therefore static session infos can be aggressively cached by +the session. Therefore static session infos can be aggressively cached by the client. The fields of @type{Session-Info} are @@ -2594,7 +2588,7 @@ The name of the ``real'' user (see @type{Who-Info} above.) @c FIXME: should this be user-active-call? The number of seconds since the last server call. @item connection-time -The time when the connection was initiated. This is not the same as the +The time when the connection was initiated. This is not the same as the amount of time the person has been on. @end table @@ -2619,7 +2613,7 @@ if Ident was not used. @item idle-time The number of seconds since the last server call. @item connection-time -The time when the connection was initiated. This is not the same as the +The time when the connection was initiated. This is not the same as the amount of time the person has been on. @end table @@ -2635,7 +2629,7 @@ The user name according to the Ident d@ae{}mon at the user's machine or ``unknown'' if Ident was not used. @item connection-time -The time when the connection was initiated. This is not the same as the +The time when the connection was initiated. This is not the same as the amount of time the person has been on. @end table @@ -2661,7 +2655,7 @@ The fields of a @type{Dynamic-Session-Info} are The session number of the session. @item person The person currently logged on, or zero if the session has not yet -logged on. +logged on. @item working-conference The conference the session is currently in. @item idle-time @@ -2670,13 +2664,13 @@ The number of seconds that have passed since the last time @item flags The dynamic session flags (see above.) @item what-am-i-doing -What the client is doing. This string is set by the client. +What the client is doing. This string is set by the client. @end table @node Protocol Requests @chapter Protocol Requests -This chapter documents all calls that can be made to the server. All +This chapter documents all calls that can be made to the server. All calls are annotated with the protocol version in which they appeared and their current status. @@ -2832,17 +2826,17 @@ The status of a call can be any of: @table @samp @item Experimental -The call is experimental. No client should rely on the existence of this -call. Experimental calls that are useful will usually become recommended +The call is experimental. No client should rely on the existence of this +call. Experimental calls that are useful will usually become recommended in future versions. @item Recommended -The call is a standard call. Clients are recommended to use these calls -rather than experimental or obsolete ones. Servers are required to +The call is a standard call. Clients are recommended to use these calls +rather than experimental or obsolete ones. Servers are required to implement all recommended calls. @item Obsolete -The call should no longer be used by clients. Servers should implement +The call should no longer be used by clients. Servers should implement these, or they will be incompatible with old client versions. @emph{Please note:} the documentation for the obsolete calls may be incomplete. Many of them perform compatibility magic to ensure that @@ -2852,9 +2846,9 @@ document it in some places. @end table @i{A note about the examples:} The examples consist of a number of calls -and replies. +and replies. @iftex -Calls are set in a normal typewriter font. Replies are set in a +Calls are set in a normal typewriter font. Replies are set in a slanted typewriter font. @end iftex Extra newlines are sometimes inserted in the examples to avoid overly @@ -2869,7 +2863,7 @@ long lines. passwd : @lt{HOLLERITH} )) -> ( ); @end example -Log in as a person. This call has been replaced by @reqlink{login}. +Log in as a person. This call has been replaced by @reqlink{login}. @subheading Error codes @@ -2896,7 +2890,7 @@ bit set. -> ( ); @end example -Log out from LysKOM. +Log out from LysKOM. This call does not disconnect the session; use @reqdlink{disconnect} for that@linkhere{}. @@ -2922,7 +2916,7 @@ This call never fails. -> ( ) ; @end example -Change current conference of a session. This call used to be called +Change current conference of a session. This call used to be called pepsi (the name was a very obscure and not very funny joke.) @subheading Error codes @@ -2952,7 +2946,7 @@ The user currently logged in is not a member of @rarg{conference}. -> ( ) ; @end example -This call changes the name of a conference or a person. To change the +This call changes the name of a conference or a person. To change the name of a conference the session issuing the call must be logged in as a person who either has special privileges or is the supervisor of the conference. @@ -2971,7 +2965,7 @@ Conference @rarg{conference} does not exist or is secret. @rarg{conference} is zero. @item permission-denied -Permission denied. The @priv{change-name} bit is not set or the user +Permission denied. The @priv{change-name} bit is not set or the user does not have enough access to @rarg{conference}. @item conference-exists @@ -2994,9 +2988,9 @@ There are invalid characters in @rarg{new-name}. -> ( ); @end example -This call tells the server what the logged-in user is doing. The string +This call tells the server what the logged-in user is doing. The string is usually displayed when a user requests that a client list who is -using LysKOM. Clients are encouraged to use this call creatively. +using LysKOM. Clients are encouraged to use this call creatively. @subheading Error codes @@ -3018,7 +3012,7 @@ using LysKOM. Clients are encouraged to use this call creatively. @end example This call requests that the server create a new person with the name and -password given as arguments. To create a person the session may have to +password given as arguments. To create a person the session may have to be logged in as a person with sufficient privileges, if the server is configured that way. @@ -3070,8 +3064,8 @@ The string @rarg{passwd} is not a valid password. -> ( @lt{Person} ); @end example -This call returns information about a person. If the low bit of -@rarg{mask} is not set, then the name is not returned. This call is +This call returns information about a person. If the low bit of +@rarg{mask} is not set, then the name is not returned. This call is obsolete and has been replaced by @reqlink{get-person-stat}. @subheading Error codes @@ -3084,7 +3078,7 @@ This call can't be executed without logging in first. Person @rarg{person} does not exist. @item undefined-conference -Conference @rarg{person} does not exist or is secret. +Conference @rarg{person} does not exist or is secret. @item conference-zero @rarg{person} is zero. @@ -3100,7 +3094,7 @@ Conference @rarg{person} does not exist or is secret. @end example This call sets the privileges of @rarg{person} to -@rarg{privileges}. @xref{Security}. To successfully issue this call the +@rarg{privileges}. @xref{Security}. To successfully issue this call the session must be logged in as a person with sufficient privileges. @reqexample @@ -3110,7 +3104,7 @@ session must be logged in as a person with sufficient privileges. @end example This example sets the privileges of person 6 to nothing but -@priv{statistic}. This particular set of privileges might be useful +@priv{statistic}. This particular set of privileges might be useful for a person used by a statistics-collecting d@ae{}mon. @@ -3139,10 +3133,10 @@ and privilege level set to 6 or higher. new-pwd : @lt{HOLLERITH} )) -> ( ); @end example -This call is used to set the password of a person. Providing +This call is used to set the password of a person. Providing @rarg{old-pwd} matches @rarg{person}'s old password, that person's -password is changed to @rarg{new-pwd}. Any person may set it's own -password. In addition persons with sufficient privileges may ser other +password is changed to @rarg{new-pwd}. Any person may set it's own +password. In addition persons with sufficient privileges may ser other persons' passwords. @reqexample @@ -3188,8 +3182,8 @@ privilege level 7 or higher enabled. This call is used to find the number of unread texts in a conference. The data it returns is actually a membership structure which specifies -which texts have been read. It is up to the client to transform the data -to a more usable form. @rarg{person} is the person being queried +which texts have been read. It is up to the client to transform the data +to a more usable form. @rarg{person} is the person being queried and @rarg{conference} is the conference in question. Calling @req{query-read-texts-old} does not require the session to be @@ -3201,7 +3195,7 @@ logged in. @t{=1 32 5 11 12 7 93 1 193 1 1 20 133 3 @{ 135 136 137 @}} @end example -This example finds the read texts for user 6 in conference 1. The +This example finds the read texts for user 6 in conference 1. The returned data indicates that the user last read conference 1 (the tenth number) on Monday July 12th, 1993 at 11:05:32 (the first nine numbers), that the person has assigned priority 20 to the conference (the eleventh @@ -3214,7 +3208,7 @@ articles 135, 136 and 137 have been read. @table @errorcode @item undefined-person @rarg{person} does not exist, or no access to person. -@item undefined-conference +@item undefined-conference Conference @rarg{conference} does not exist, or is secret. @item conference-zero @rarg{conference} is zero. @@ -3234,8 +3228,8 @@ Conference @rarg{conference} does not exist, or is secret. -> ( @lt{Conf-No} ); @end example -This call is used to create new conferences. @rarg{name} is the name of -the new conference and @rarg{type} is its type. If successful, the call +This call is used to create new conferences. @rarg{name} is the name of +the new conference and @rarg{type} is its type. If successful, the call returns the conference number of the newly created conference. To use this call the session must have logged in as a user with @@ -3255,9 +3249,10 @@ privileges to create conferences (@pxref{Security}). @end example This example creates a new conference named -``@value{IAM}''@footnote{This conference is a standard Lysator conference. It's -all Padrone's fault.} which accepts all users as members and accepts -anonymous articles. The server returns 7 as the new conference number. +``@value{IAM}''@footnote{This conference is a standard Lysator +conference. It's all Padrone's fault.} which accepts all users as +members and accepts anonymous articles. The server returns 7 as the +new conference number. @subheading Error codes @@ -3292,12 +3287,12 @@ the @conftype{rd-prot} bit is cleared. @findex delete-conf @example - delete-conf [11] ( conf : @lt{Conf-No} ) -> ( ); + delete-conf [11] ( conf : @lt{Conf-No} ) -> ( ); @end example This call deletes the conference @rarg{conf} from the LysKOM -database. Only privileged users and the supervisors of a conference may -delete it. If the conference is a mailbox the corresponding person will +database. Only privileged users and the supervisors of a conference may +delete it. If the conference is a mailbox the corresponding person will also be deleted. @reqexample @@ -3341,7 +3336,7 @@ is corrupt.) @findex lookup-name @example - lookup-name [12] ( name : @lt{HOLLERITH} ) + lookup-name [12] ( name : @lt{HOLLERITH} ) -> ( @lt{Conf-List-Archaic} ); @end example @@ -3355,7 +3350,7 @@ lookup-name has been superseded by @reqlink{lookup-z-name}. 2 12 3H::: @t{=2 0 * *} 3 76 3Ha d 1 1 - @t{=3 3 @{ 31HAlkohol- (och annan) drogdebatt 0000 217 + @t{=3 3 @{ 31HAlkohol- (och annan) drogdebatt 0000 217 13HAnna Degerman 1001 674 27HAnarchy discussion (import) 0000 1582 @}} 4 76 3H::: 1 1 @@ -3386,7 +3381,7 @@ This call always succeeds. @end example This call retrieves the information associated with conference -@rarg{conf-no} in the LysKOM server. This call should no longer be +@rarg{conf-no} in the LysKOM server. This call should no longer be used; use @reqdlink{get-conf-stat} instead@linkhere{}. The @rarg{mask} argument determines if the name is returned or not. If @@ -3428,7 +3423,7 @@ conference in the person's membership list if the person is already a member of the conference. In protocol version 10, setting the priority to zero sets the passive -bit in the membership. The actual priority is not changed. +bit in the membership. The actual priority is not changed. @reqexample @example @@ -3441,9 +3436,9 @@ bit in the membership. The actual priority is not changed. 49 14 17 13 8 91 5 255 1 119 255 0 0 * @}} @end example -This example makes person 119 (me) a member of conference number 1. The +This example makes person 119 (me) a member of conference number 1. The priority is set to 250 and the conference is placed first in the -membership list. The first and last calls of the example show the +membership list. The first and last calls of the example show the membership list for person 119 before and after the call. @@ -3500,7 +3495,7 @@ memberships. @t{=1 1 @{ 49 14 17 13 8 91 5 255 1 5 255 0 0 * @}} @end example -This example shows how person 5 is removed from conference one. The +This example shows how person 5 is removed from conference one. The calls to get-membership demonstrate the effects on the LysKOM database. @@ -3535,17 +3530,17 @@ Not supervisor of conference @rarg{conf-no} or not supervisor of person @section set-presentation [16] (1) Recommended @findex set-presentation -@example +@example set-presentation [16] (( conf-no : @lt{Conf-No}; text-no : @lt{Text-No} )) -> ( ); @end example This call sets the presentation text of the conference or person -@rarg{conf-no} to the text @rarg{text-no}. To remove a presentation, use -a @rarg{text-no} of zero. This call protects the new presentation from +@rarg{conf-no} to the text @rarg{text-no}. To remove a presentation, use +a @rarg{text-no} of zero. This call protects the new presentation from being deleted automatically and removes such protection from the old -presentation. In lyskomd this is implemented by increasing the mark +presentation. In lyskomd this is implemented by increasing the mark count on presentation texts. @reqexample @@ -3565,8 +3560,8 @@ count on presentation texts. @end example This example shows how the presentation of person 6 is being -changed. To start with, the person had no presentation, as is shown by -the @reqdlink{get-conf-stat-old} call@linkhere{}. Later, after +changed. To start with, the person had no presentation, as is shown by +the @reqdlink{get-conf-stat-old} call@linkhere{}. Later, after @req{set-presentation} has been called, the presentation field has changed. @@ -3585,7 +3580,7 @@ Conference @rarg{conf-no} does not exist or is secret. @item permission-denied Not enough permissions to change presentation of conference -@rarg{conf-no}. +@rarg{conf-no}. @item no-such-text Text @rarg{text-no} does not exist or no read permission. @@ -3610,8 +3605,8 @@ marks. This call sets the message of the day on the conference or person @rarg{conf-no} to the article @rarg{text-no} and removes the old -message. To remove an old message without setting a new one, use a -@rarg{text-no} of zero. This call protects the new message from +message. To remove an old message without setting a new one, use a +@rarg{text-no} of zero. This call protects the new message from automatic deletion and removes such protection from the old message just as @reqlink{set-presentation}. @@ -3671,7 +3666,7 @@ marks. @end example The @req{set-supervisor} call changes the supervisor of an existing -conference. The result is that all members of the conference +conference. The result is that all members of the conference @rarg{admin} become supervisors of the conference @rarg{conf-no}. Typically, but not always, @rarg{admin} will be a mailbox. @@ -3696,7 +3691,7 @@ conference four (which is usually the ``News about LysKOM'' conference). The change in the conference structure is evident from the @reqdlink{get-conf-stat-old} calls@linkhere{} before and after the @req{set-supervisor} call. Note that the original supervisor was not -set. In order to change the supervisor of such a conference, the +set. In order to change the supervisor of such a conference, the session issuing the call must have administration privileges. @@ -3715,7 +3710,7 @@ is secret. @item permission-denied Not enough permissions or privileges to change the supervisor of -conference @rarg{conf-no}. +conference @rarg{conf-no}. @end table @@ -3734,9 +3729,9 @@ conference @rarg{conf-no}. @end example This call grants the right to send articles to the conference -@rarg{conf-no} to all members of the conference @rarg{perm-sub}. The +@rarg{conf-no} to all members of the conference @rarg{perm-sub}. The right to submit articles is per default only granted to the members of -the conference. When a person tries to submit an article but does not +the conference. When a person tries to submit an article but does not have the right to do so, the client is expected to send the article to the super-conference instead. @@ -3757,8 +3752,8 @@ the super-conference instead. @end example This example shows how all members of conference one are given -permission to send articles to conference four. From the beginning, -only members of conference four were permitted to submit articles. The +permission to send articles to conference four. From the beginning, +only members of conference four were permitted to submit articles. The change is evident from the @reqdlink{get-conf-stat-old} calls@linkhere{} before and after the @req{set-permitted-submitters} call. @@ -3779,7 +3774,7 @@ or is secret. @item permission-denied Not enough permissions to change the permitted submitters of conference -@rarg{conf-no}. +@rarg{conf-no}. @end table @@ -3796,7 +3791,7 @@ Not enough permissions to change the permitted submitters of conference @end example Makes the conference @rarg{super-conf} the super-conference of the -conference @rarg{conf-no}. When an article is submitted to a conference +conference @rarg{conf-no}. When an article is submitted to a conference that does not accept it, it is sent to the super-conference instead. @reqexample @@ -3816,7 +3811,7 @@ that does not accept it, it is sent to the super-conference instead. @end example This example demonstrates how the super-conference of conference 1 is -set to conference 8. The calls to @reqlink{get-conf-stat-old} demonstrate the +set to conference 8. The calls to @reqlink{get-conf-stat-old} demonstrate the change in the conference structure. @@ -3848,7 +3843,7 @@ Not enough permissions to change super-conference of conference @end example Sets the conference type of conference @rarg{conf-no} to @rarg{type}. -Before protocol version 8, @rarg{type} could only be four bits. Starting +Before protocol version 8, @rarg{type} could only be four bits. Starting with protocol version 8, either a four-bit @type{Conf-Type} or an eight-bit @type{Extended-Conf-Type} is allowed. @@ -3863,7 +3858,7 @@ eight-bit @type{Extended-Conf-Type} is allowed. @end example This example shows a user removing the @conftype{allow-anonymous} bit -from conference four. The @reqdlink{get-uconf-stat} call@linkhere{} +from conference four. The @reqdlink{get-uconf-stat} call@linkhere{} shows all eight bits of the conference type before and after the @req{set-conf-type} call. @@ -3903,7 +3898,7 @@ membership type. @end example Sets the expiration time for articles in conference @rarg{conf-no} to -@rarg{nice} days. An article that is older than the maximum expiration +@rarg{nice} days. An article that is older than the maximum expiration time of each conference it is sent to may be deleted by the LysKOM server unless it has marks. @@ -3931,7 +3926,7 @@ Conference @rarg{conf-no} does not exist or is secret. @rarg{conf-no} is zero. @item permission-denied Not enough permissions to change the expiration time for conference -@rarg{conf-no}. +@rarg{conf-no}. @end table @@ -3946,7 +3941,7 @@ Not enough permissions to change the expiration time for conference -> ( @lt{ARRAY} @lt{Mark} ); @end example -This call returns the list of marks the current user has set. +This call returns the list of marks the current user has set. @reqexample @example @@ -3956,7 +3951,7 @@ This call returns the list of marks the current user has set. In this example, the current user has three marks, one on text 13020 with mark type 100, one on text 13042 with mark type 95 and one on text -12213 with mark type 95. The maximum number of marks may be arbitrarily +12213 with mark type 95. The maximum number of marks may be arbitrarily limited in the LysKOM server. @subheading Error codes @@ -4019,9 +4014,9 @@ many marks, or cause the text to have too many marks. @end example Retrieve text number @rarg{text} from the LysKOM database, starting at -position @rarg{start-char} and ending at position @rarg{end-char}. The +position @rarg{start-char} and ending at position @rarg{end-char}. The first character in the text is numbered 0 and the last can be retrieved -using @reqlink{get-text-stat}. It is also permitted to request a character +using @reqlink{get-text-stat}. It is also permitted to request a character position beyond the actual end of the text, in which case as much text as is available will be returned. @@ -4037,7 +4032,7 @@ as is available will be returned. In this example, text 100 is requested three times, first from position 0 to position 32766, then from position 5 to position 32766 and finally -from position 0 to position 4. The first reply contains the entire text, +from position 0 to position 4. The first reply contains the entire text, the following two contain only the requested portion. @@ -4068,7 +4063,7 @@ Attempt to retrieve text number 0. -> ( @lt{Text-Stat-Old} ); @end example -Get information about text number @rarg{text-no}. The text-stat contains +Get information about text number @rarg{text-no}. The text-stat contains information about the size of the text, its recipients, comments, author and more. @@ -4084,15 +4079,15 @@ or omitted entirely. @example 1 26 100 @t{=1 7 35 16 15 6 96 1 196 1 14 1 22 1 - 7 @{ 0 7 6 85 0 15 6 1 + 7 @{ 0 7 6 85 0 15 6 1 8 13 9 12 37 16 15 6 96 1 196 1 3 311 @}} @end example In this example, text number 100 was created by person 7 at -approximately 4:35PM on July 15 1996. Its recipients are conferences 7 +approximately 4:35PM on July 15 1996. Its recipients are conferences 7 and 15, and it was sent to conference 15 by person 13 at 16:37 on the -day it was created. The text has a single comment: text 311. +day it was created. The text has a single comment: text 311. @subheading Error codes @@ -4120,7 +4115,7 @@ Attempt to retrieve text number 0. @end example Marks text @rarg{text} in conference number @rarg{conference} as read -for the current user. This call updates the membership record for the +for the current user. This call updates the membership record for the user. @reqexample @@ -4136,8 +4131,8 @@ user. @end example This example shows person 6 marking local text number 241 in conference -7 as read. In the first query-read-texts call the person has read local -text 240, but nothing higher. The mark-as-read call is reflected in the +7 as read. In the first query-read-texts call the person has read local +text 240, but nothing higher. The mark-as-read call is reflected in the second query-read-texts call, where the user is seen to have read text 241 in conference 7. @@ -4161,7 +4156,7 @@ The conference @rarg{conference} does not exist or is secret. The person logged on is not a member of conference @rarg{conference}. @item no-such-local-text One of the numbers in @rarg{text} is not a local text number in -@rarg{conference}. The error argument indicates the index of the invalid +@rarg{conference}. The error argument indicates the index of the invalid number. @item local-text-zero One of the numbers in @rarg{text} is zero. @@ -4180,15 +4175,15 @@ One of the numbers in @rarg{text} is zero. @end example Creates a new text with contents from @rarg{text} and recipients -etc. defined by @rarg{misc-info} (@pxref{The Misc-Info List}). In +etc. defined by @rarg{misc-info} (@pxref{The Misc-Info List}). In addition to the result, the server will send an asynchronous message -to all members of any of the recipients of the new text. It is not +to all members of any of the recipients of the new text. It is not defined whether this messages comes before or after the reply to -the create-text message. Clients should be prepared for either +the create-text message. Clients should be prepared for either situation. The text up to the first line feed is considered to be the subject -line. The remaining text is the message body. Although messages with +line. The remaining text is the message body. Although messages with only a subject are valid, clients should avoid letting users create such messages. @@ -4205,12 +4200,12 @@ The only Misc-Info items valid for this call are @misc{recpt}, @end example In this example, person 119 creates a text containing a subject and a -one-line body. The recipient of the text is conference five, conference -112 is a CC recipient and the text is a comment to text 33467. The -server reply indicates that the new text has been given number 33502. +one-line body. The recipient of the text is conference five, conference +112 is a CC recipient and the text is a comment to text 33467. The +server reply indicates that the new text has been given number 33502. Finally there is an asynchronous message sent to all members of -recipient conferences. Note how the message was sent before the reply to -the client. The misc-info list in this message has two additional +recipient conferences. Note how the message was sent before the reply to +the client. The misc-info list in this message has two additional fields, the local numbers of the text in each of its recipient conferences. @@ -4241,8 +4236,8 @@ conference or any superconference that will accept a text. Attempt to send an anonymous text to a conference that does not accept anonymous texts. @item illegal-misc -Invalid misc-info list. A recipient is listed more than once or there is -an unknown misc item in the misc-info list. +Invalid misc-info list. A recipient is listed more than once or there is +an unknown misc item in the misc-info list. @end table @@ -4257,7 +4252,7 @@ an unknown misc item in the misc-info list. @end example Deletes the text @rarg{text} from the LysKOM database, if the person -issuing the command may do so. +issuing the command may do so. @reqexample @example @@ -4293,7 +4288,7 @@ author. -> ( ); @end example -Adds @rarg{conf-no} as recipient to text @rarg{text-no}. If +Adds @rarg{conf-no} as recipient to text @rarg{text-no}. If @rarg{recpt-type} is 1, then a @misc{cc-recpt} (@pxref{The Misc-Info List}) is created; otherwise a @misc{recpt} is created. @@ -4302,7 +4297,7 @@ Since protocol version 8 this call can also be used to change a a recipient that already exists. Since protocol version 10 the @rarg{recpt-type} parameter is a -@type{Misc-Info}. Only infos @misc{recpt}, @misc{cc-recpt} and +@type{Misc-Info}. Only infos @misc{recpt}, @misc{cc-recpt} and @misc{bcc-recpt} are accepted. In protocol version 9 and earlier this argument was a @type{BOOL}, that indicated if the recipient should be a @misc{cc-recpt} (when true) or @misc{recpt} (when false). @@ -4324,7 +4319,7 @@ a @misc{cc-recpt} (when true) or @misc{recpt} (when false). @end example This example show how conference 5 is added first as a recipient of text -1, then changed to a carbon-copy recipient. The misc-info list reflects +1, then changed to a carbon-copy recipient. The misc-info list reflects these changes. @@ -4360,7 +4355,7 @@ the text or supervisor of the recipient. @item access-denied Attempt to add a conference as recipient that the person logged on does -not have permission to add texts to. The client may have to chase the +not have permission to add texts to. The client may have to chase the super conf chain. @end table @@ -4379,7 +4374,7 @@ super conf chain. @end example Removes @rarg{conf-no} from the list of recipients of text -@rarg{text-no}. Recipients may be removed by the author of the text or +@rarg{text-no}. Recipients may be removed by the author of the text or by the supervisor of the recipients of the text or by the supervisor of the author. @@ -4394,10 +4389,10 @@ the author. @t{=1 2 22 12 17 6 97 4 197 1 5 4 256 1 0 *} 1 31 1 5 @t{%1 30 0} -@end example +@end example In this example, conference 5 is removed from the recipient list of text -number 5. When the call is repeated, the server simply returns an error +number 5. When the call is repeated, the server simply returns an error since conference 5 is not a recipient of the text. @subheading Error codes @@ -4410,7 +4405,7 @@ Login required before issuing this call. The text @rarg{text-no} does not exist or is secret. @item not-recipient -The conference @rarg{conf-no} is not a recipient of text @rarg{text-no}. +The conference @rarg{conf-no} is not a recipient of text @rarg{text-no}. @item undefined-conference The conference @rarg{conf-no} does not exist or is secret. @@ -4420,7 +4415,7 @@ The conference @rarg{conf-no} does not exist or is secret. @item permission-denied Not supervisor of text author or conference, and not sender of text to -@rarg{conf-no} and not enough privileges set and enabled. +@rarg{conf-no} and not enough privileges set and enabled. @end table @@ -4437,8 +4432,8 @@ Not supervisor of text author or conference, and not sender of text to Add a comment link between the text @rarg{comment-to} and the text @rarg{text-no} (@rarg{text-no} becomes a comment to the text -@rarg{comment-to}). This call is used to add comment links after a text -has been created. The normal procedure for creating comments is to add a +@rarg{comment-to}). This call is used to add comment links after a text +has been created. The normal procedure for creating comments is to add a @misc{comm-to} element to the text's misc-info list when the text is created (@pxref{The Misc-Info List}). @@ -4458,7 +4453,7 @@ created (@pxref{The Misc-Info List}). @end example In this example, text number two is added as a comment to text number -one. The change is reflected in the Misc-Info List of the texts. +one. The change is reflected in the Misc-Info List of the texts. @subheading Error codes @@ -4467,7 +4462,7 @@ one. The change is reflected in the Misc-Info List of the texts. @item login-first Login required before issuing this call. @item index-out-of-range -The texts @rarg{text-no} and @rarg{comment-to} are identical. The +The texts @rarg{text-no} and @rarg{comment-to} are identical. The @field{error-status} is @rarg{text-no}. @item no-such-text The text @rarg{text-no} of @rarg{comment-to} are undefined. @@ -4507,7 +4502,7 @@ of comments. @end example In this example text 2 is a comment to text 1, as shown by the misc-info -lists of the two texts. The @req{sub-comment} is called. The misc-info +lists of the two texts. The @req{sub-comment} is called. The misc-info lists are changed to reflect the change. @@ -4544,33 +4539,33 @@ anyway. This call has been superceded by @reqlink{local-to-global}. This call retrieves an array mapping local text numbers to global -numbers. It is most often used to get a list of unread texts in a -conference. Clients will usually use the @reqlink{query-read-texts} or -@reqlink{get-membership} calls to find the last local number a user has +numbers. It is most often used to get a list of unread texts in a +conference. Clients will usually use the @reqlink{query-read-texts} or +@reqlink{get-membership} calls to find the last local number a user has read in a particular conference, then use the @req{get-map} call to retrieve the global numbers of all unread texts in the conference. The @rarg{conf-no} parameter specifies which conference to get the map -of. @rarg{first-local-no} is the local number of the first text returned -by the call. @rarg{no-of-texts} is the maximum number of text the client +of. @rarg{first-local-no} is the local number of the first text returned +by the call. @rarg{no-of-texts} is the maximum number of text the client wants. -The result is a list of global text numbers. The first element of the +The result is a list of global text numbers. The first element of the list is the global number of local number @rarg{first-local-no}, specified by the call; the second element is the global number of local -number @rarg{first-local-no} plus one; and so forth. The list returned +number @rarg{first-local-no} plus one; and so forth. The list returned by the server is at most @rarg{no-of-texts} long, but may be shorter if -the call specifies more texts that there are in the conference. +the call specifies more texts that there are in the conference. If @rarg{first-local-no} is higher than the highest local text number, the server will return an error. If @rarg{first-local-no} is lower than the lowest number that still exists, the server will set @rarg{first-local-no} in the returned -@type{Text-List} to the first text that still exists. The size of the +@type{Text-List} to the first text that still exists. The size of the returned array will be decreased by the same amount as -@rarg{first-local-no} is increased. This may result in an empty array -being returned. (This paragraph applies even when @rarg{first-local-no} +@rarg{first-local-no} is increased. This may result in an empty array +being returned. (This paragraph applies even when @rarg{first-local-no} is 0.) If no texts at all exists in @rarg{conf-no} the resulting array will be @@ -4591,11 +4586,11 @@ to be created will receive. @t{=5 4 0 *} @end example -This example shows five @req{get-map} calls. The first retrieves the +This example shows five @req{get-map} calls. The first retrieves the mappings of local numbers 10 to 15; the second call returns local -numbers 16 to 18. As this example shows the maps are not necessarily +numbers 16 to 18. As this example shows the maps are not necessarily sorted in ascending order, since texts may be added after their -creation, and the maps may contain zeroes anywhere. These represent +creation, and the maps may contain zeroes anywhere. These represent texts that have been removed for some reason. Since the first example returned two leading zeroes we can be certain @@ -4648,8 +4643,8 @@ This call simply returns the local time according to the server. @t{=1 23 47 19 17 6 97 4 197 1} @end example -This example demonstrates the call. According to the server the time is -19:47:23, Thursday July 17, 1997. The result also shows that it is the +This example demonstrates the call. According to the server the time is +19:47:23, Thursday July 17, 1997. The result also shows that it is the 197th day of the year, and that daylight savings time is in effect. @@ -4670,7 +4665,7 @@ This call always succeeds @end example This call returns the @type{Info-Old} structure for the server -(@pxref{Info-Old}). Clients should call this in order to find +(@pxref{Info-Old}). Clients should call this in order to find out which conferences are used for presentations and such. This call has been superceded by @reqlink{get-info}. @@ -4709,9 +4704,9 @@ This call always succeeds. Add a footnote link between the text @rarg{footnote-to} and the text @rarg{text-no} (@rarg{text-no} becomes a footnote to the text -@rarg{footnote-to}). This call is used to add footnote links after a text -has been created. Only the author of both texts is allowed to add -the footnote link. +@rarg{footnote-to}). This call is used to add footnote links after a text +has been created. Only the author of both texts is allowed to add +the footnote link. @reqexample @example @@ -4729,7 +4724,7 @@ the footnote link. @end example In this example, text number two is added as a footnote to text number -one. The change is reflected in the Misc-Info List of the texts. +one. The change is reflected in the Misc-Info List of the texts. @subheading Error codes @@ -4762,7 +4757,7 @@ Text @rarg{text-no} is already a footnote to @rarg{footnote-to}. @end example This call removes the text @rarg{text-no} from @rarg{footnote-to}'s list -of footnotes. Only the author of a footnote may remove it. +of footnotes. Only the author of a footnote may remove it. @reqexample @example @@ -4780,7 +4775,7 @@ of footnotes. Only the author of a footnote may remove it. @end example In this example text 2 is a footnote to text 1, as shown by the -misc-info lists of the two texts. The @req{sub-footnote} is called. +misc-info lists of the two texts. The @req{sub-footnote} is called. The misc-info lists are changed to reflect the change. @subheading Error codes @@ -4797,7 +4792,7 @@ The text @rarg{text-no} is not a footnote to @rarg{footnote-to}. Not supervisor of the author of @rarg{text-no} and not enough privileges set and enabled to complete call anyway. @end table - + @node who-is-on-old @@ -4809,8 +4804,8 @@ set and enabled to complete call anyway. -> ( @lt{ARRAY} @lt{Who-Info-Old} ); @end example -This call is obsolete. Use @reqlink{get-static-session-info} and -@reqlink{who-is-on-dynamic} instead. If the server does not support these +This call is obsolete. Use @reqlink{get-static-session-info} and +@reqlink{who-is-on-dynamic} instead. If the server does not support these calls, use @reqlink{who-is-on} instead. The returned list contains all sessions where a person is logged in and @@ -4836,9 +4831,9 @@ This call always succeeds. Only read the last @rarg{no-of-unread} in the conference @rarg{conf-no}. This call modifies the @field{last-text-read} of current person's -membership for the conference. This call is sometimes used to +membership for the conference. This call is sometimes used to implement the ``only read last N texts'' command found in many -clients. Due to possible race conditions@footnote{Another client might +clients. Due to possible race conditions@footnote{Another client might create a new text immediately before the server processes this @req{set-unread} call, so you might end up setting @field{last-text-read} to something unexpected.}, this call is usually @@ -4884,8 +4879,8 @@ Not a member of conference @rarg{conf-no}. -> ( ); @end example -This call sets the login message of LysKOM. It can only be executed by a -privileged person, with the proper privileges enabled. A somewhat less +This call sets the login message of LysKOM. It can only be executed by a +privileged person, with the proper privileges enabled. A somewhat less convenient way of doing this is to use the @reqdlink{set-info} call@linkhere{}. @@ -4900,7 +4895,7 @@ call@linkhere{}. @end example This example shows how the login message of LysKOM is set using the -set-motd-of-lyskom call. The results of the @req{get-info} calls +set-motd-of-lyskom call. The results of the @req{get-info} calls demonstrate the effect. @subheading Error codes @@ -4927,8 +4922,8 @@ The text @rarg{text-no} already has the maximum number of marks. @end example Sets the security level for the current session to @rarg{level}. -@xref{Security}, for details about security levels. The only levels -that make any sense right now are 0 and 255. This call may be issued +@xref{Security}, for details about security levels. The only levels +that make any sense right now are 0 and 255. This call may be issued by any person, but without the right privilege bits set, it has no effect. @@ -4963,9 +4958,9 @@ Login required before issuing this call. @end example This call instructs the LysKOM server to make sure the permanent copy of -its database is current. Processing of requests is normally blocked +its database is current. Processing of requests is normally blocked until this call has completed, but the exact details depend on the -server implementation. This call is privileged in most implementations. +server implementation. This call is privileged in most implementations. @reqexample @example @@ -5002,7 +4997,7 @@ Administrator bit not set or privileges not enabled. @end example This call instructs the server to save all data and shut down. -@rarg{exit-val} is currently not used. This call is privileged. +@rarg{exit-val} is currently not used. This call is privileged. @reqexample @example @@ -5013,7 +5008,7 @@ This call instructs the server to save all data and shut down. @t{:2 13 5 3} @end example -This example shows the shutdown of a server. The asynchronous message +This example shows the shutdown of a server. The asynchronous message sent after the call returns is the result of a session being forced to log out. @@ -5036,7 +5031,7 @@ Administrator bit not set or privileges not enabled. -> ( ); @end example -This call can been replaced by @reqlink{send-message}. It is a privileged +This call can been replaced by @reqlink{send-message}. It is a privileged call. @subheading Error codes @@ -5064,10 +5059,10 @@ Messages have been disabled. @end example This call retrieves the membership record for a list of conferences for -a single person. @rarg{person} is the person whose memberships are to be -retrieved. @rarg{first} is the first position in the membership list to -retrieve, numbered from 0 and up. @rarg{no-of-confs} is the number of -membership records to retrieve. If @rarg{want-read-texts} is @samp{0} +a single person. @rarg{person} is the person whose memberships are to be +retrieved. @rarg{first} is the first position in the membership list to +retrieve, numbered from 0 and up. @rarg{no-of-confs} is the number of +membership records to retrieve. If @rarg{want-read-texts} is @samp{0} the server will not send the contents of the @field{read-texts} array of the memberships. (The size will be transmitted, but a single asterisk (@samp{*}) will be sent instead of the array itself.) @@ -5092,10 +5087,10 @@ zero.) @t{=1 1 @{ 20 14 22 17 6 97 4 197 1 6 100 2 0 * @}} @end example -In this example we retrieve the memberships of person 5. The first -call asks for three memberships, starting with number 0. Since this +In this example we retrieve the memberships of person 5. The first +call asks for three memberships, starting with number 0. Since this person is only a member of two conferences, the list returned only -contains two memberships. (An extra newline has been inserted in the +contains two memberships. (An extra newline has been inserted in the result of the first call to make the result more readable.) The next two calls retrieve a single membership each, the first by asking for only one, and the second by asking for four memberships, starting with @@ -5132,12 +5127,12 @@ This call is obsolete; instead you should use @reqlink{map-created-texts}. This call returns a list of the texts written by a person. @rarg{person} is the person whose created texts are to be -retrieved. @rarg{first} is the first text to -retrieve. @rarg{no-of-texts} is the number of texts to retrieve. +retrieved. @rarg{first} is the first text to +retrieve. @rarg{no-of-texts} is the number of texts to retrieve. This call is essentially the same as @reqlink{get-map}, but instead of returning the texts sent to a single conference, it returns the texts -written by a single person to any conference. The number of texts +written by a single person to any conference. The number of texts written by any one person is contained in the Person record for that person. @@ -5162,10 +5157,10 @@ Besides, they are both obsolete calls.}) @t{=3 12 8 @{ 309 312 324 327 329 339 0 387 @}} @end example -In this example we have retrieved all texts written by person five. The +In this example we have retrieved all texts written by person five. The first call asked for 100 texts, but only 8 were returned, which implies -that person number 5 only created a total of 8 texts. We can also see -that person 5 wrote all the first 8 texts in the conference system. The +that person number 5 only created a total of 8 texts. We can also see +that person 5 wrote all the first 8 texts in the conference system. The second call shows how a part of the map can be retrieved. The third call asks for eight texts written by person 10, starting with @@ -5203,7 +5198,7 @@ text. This call returns a list of members of the conference @rarg{conf}. @rarg{first} is the first index in the membership to return, numbered -from zero and up. @rarg{no-of-members} is the maximum number of members +from zero and up. @rarg{no-of-members} is the maximum number of members to return. @reqexample @@ -5217,8 +5212,8 @@ to return. @end example In this example the client first requests the first 100 members in -conference 1. The second request is for the first 100 members of -conference 6. The last request is for members 2 and 3 in conference 6. +conference 1. The second request is for the first 100 members of +conference 6. The last request is for members 2 and 3 in conference 6. As can be seen from the examples, the returned list is truncated if there are fewer members than requested. @@ -5242,9 +5237,9 @@ The conference @rarg{conf} does not exist or is secret. -> ( @lt{Person} ); @end example -This call returns the person @rarg{pers-no}. This call does not return +This call returns the person @rarg{pers-no}. This call does not return all the information a client usually needs since the name is not -included in the Person data structure. Use @reqlink{get-conf-stat} on the +included in the Person data structure. Use @reqlink{get-conf-stat} on the same number to get additional information about the person. @reqexample @@ -5258,7 +5253,7 @@ same number to get additional information about the person. @end example This simple example shows how person number 8 is retrieved from the -server. The second call shows the @req{get-conf-stat-old} call on the same +server. The second call shows the @req{get-conf-stat-old} call on the same ID number. @subheading Error codes @@ -5284,8 +5279,8 @@ This call retrieves the conference data structure for conference number @rarg{conf-no}. Important note: This call does not return the extra flag bits that were -introduced in protocol version 8. To get this information, use the -@req{get-uconf-stat} call instead. However, clients should be able to +introduced in protocol version 8. To get this information, use the +@req{get-uconf-stat} call instead. However, clients should be able to handle @type{Conference-Old} structures with an arbitrary number of flag bits since we may decide to change the behavior of this call in the future. @@ -5301,7 +5296,7 @@ future. @end example This simple example retrieves conferences 1 and 8 from the server. -Conference 1 is a regular conference, and conference 8 is a mailbox. +Conference 1 is a regular conference, and conference 8 is a mailbox. @subheading Error codes @@ -5321,13 +5316,13 @@ The conference @rarg{conf-no} does not exist or is secret. -> ( @lt{ARRAY} @lt{Who-Info} ); @end example -This call is obsolete. Please use @reqlink{who-is-on-dynamic} and +This call is obsolete. Please use @reqlink{who-is-on-dynamic} and @reqdlink{get-static-session-info} calls instead@linkhere{}. Nonetheless, servers should support this call since many clients still use it. This call should simply return a list of visible sessions (sessions -where a person is logged in and the invisible flag is unset). The data +where a person is logged in and the invisible flag is unset). The data structure is described elsewhere (@pxref{Who-Info}). @subheading Error codes @@ -5345,8 +5340,8 @@ This call always succeeds. @end example This call returns a list of conferences in which the person -@rarg{pers-no} may have unread texts. This call will return a result for -any valid @rarg{pers-no}. To retrieve information about secret persons, +@rarg{pers-no} may have unread texts. This call will return a result for +any valid @rarg{pers-no}. To retrieve information about secret persons, or to get information about unread texts in secret conference, the session must log on as a person with access to that information. @@ -5359,7 +5354,7 @@ they appear on the persons list of memberships. @reqexample @example - 1 52 7 + 1 52 7 @t{=1 2 @{ 1 6 @}} 1 52 1 @t{%1 10 0} @@ -5368,8 +5363,8 @@ they appear on the persons list of memberships. @end example This example shows how a session first retrieves the list of conferences -in which person 7 has unread texts. The next request is for the unread -conferences of person 1, but that happens to be a conference. The last +in which person 7 has unread texts. The next request is for the unread +conferences of person 1, but that happens to be a conference. The last request is for the unread conferences of person 1000, but that person didn't exist in the test database. @@ -5427,7 +5422,7 @@ Conference @rarg{recipient} does not exist or is secret. @item feature-disabled The message feature has been disabled in the server. @item message-not-sent -The message was not sent for some other reason. Perhaps the recipient is +The message was not sent for some other reason. Perhaps the recipient is not accepting messages or there are no viable recipients for a group message. @end table @@ -5442,8 +5437,8 @@ message. -> ( @lt{Session-Info} ); @end example -This call is obsolete. It has been replaced by -@reqlink{get-session-info-ident}, which in turn is also obsolete. See +This call is obsolete. It has been replaced by +@reqlink{get-session-info-ident}, which in turn is also obsolete. See @req{get-session-info-ident} for more information. @@ -5468,7 +5463,7 @@ The session @rarg{session-no} does not exist. @end example This call disconnects the session @rarg{session-no} from the LysKOM -server. A session can always disconnect itself, even without logging in. +server. A session can always disconnect itself, even without logging in. If the session is logged in as user @i{foo} it can also disconnect any session logged in as a person for which @i{foo} is the supervisor. @@ -5490,8 +5485,8 @@ In this example the client asks for its own session number, then disconnects itself (disconnection session 0 would have had the same effect.) The asynchronous message sent just before the session is disconnected is the logout message for the user that was logged on in -the session. The ``Connection closed by foreign host.'' is not part of -the server output. This message was generated by telnet. +the session. The ``Connection closed by foreign host.'' is not part of +the server output. This message was generated by telnet. @subheading Error codes @@ -5518,7 +5513,7 @@ The session @rarg{session-no} does not exist. @end example This call simply returns the session number of the session issuing the -call. +call. @reqexample @example @@ -5546,7 +5541,7 @@ This call always succeeds. @end example This call sets the user-area field for the person @rarg{pers-no} in the -database to the text @rarg{user-area}. The user area is used to store +database to the text @rarg{user-area}. The user area is used to store client data for a particular person. @xref{The User Area}, for more details. @@ -5562,7 +5557,7 @@ details. @t{ 6 58 21 19 6 97 6 199 1 11 458 7 71 2592 7 13 0 0 3 1 0 4} @end example -In this example the user area of person 7 is set to text number 11. The +In this example the user area of person 7 is set to text number 11. The original user area was text numbers zero, which means that the person had no user area. @@ -5588,7 +5583,7 @@ Not enough access to person @rarg{pers-no} to complete the call. @end example This call returns the number of the last text created before -@rarg{before}. There is no guarantee that the text is readable by the +@rarg{before}. There is no guarantee that the text is readable by the person making the request, or that the text even exists. This call assumes that all texts are written in chronological order, @@ -5633,7 +5628,7 @@ This call never fails. @end example Similar to @reqlink{create-text-old}, but the text is created with the -@field{author} field set to zero. Not even the server has a record of +@field{author} field set to zero. Not even the server has a record of who created the text. The original intended use for this call was for importing texts from @@ -5656,12 +5651,12 @@ in protocol version 10), @misc{comm-to} and @misc{footn-to}. @end example In this example, person 119 creates a text containing a subject and a -one-line body. The recipient of the text is conference five, conference -112 is a CC recipient and the text is a comment to text 33467. The -server reply indicates that the new text has been given number 33502. +one-line body. The recipient of the text is conference five, conference +112 is a CC recipient and the text is a comment to text 33467. The +server reply indicates that the new text has been given number 33502. Finally there is an asynchronous message sent to all members of -recipient conferences. Note how the message was sent before the reply to -the client. The misc-info list in this message has two additional +recipient conferences. Note how the message was sent before the reply to +the client. The misc-info list in this message has two additional fields, the local numbers of the text in each of its recipient conferences. @@ -5691,8 +5686,8 @@ conference or any superconference that will accept a text. Attempt to send an anonymous text to a conference that does not accept anonymous texts. @item illegal-misc -Invalid misc-info list. A recipient is listed more than once or there is -an unknown misc item in the misc-info list. +Invalid misc-info list. A recipient is listed more than once or there is +an unknown misc item in the misc-info list. @end table @@ -5708,7 +5703,7 @@ an unknown misc item in the misc-info list. @end example This call returns the next readable text in the database created after -text @rarg{start}. @rarg{start} does not have to be a valid or readable +text @rarg{start}. @rarg{start} does not have to be a valid or readable text number, as shown in the examples. @reqexample @@ -5721,7 +5716,7 @@ text number, as shown in the examples. This example shows how to retrieve the first readable text in the LysKOM database by calling @req{find-next-text-no} with @rarg{start} set to zero. -In the example, the first text is number 2. The second example gets the +In the example, the first text is number 2. The second example gets the text following number 2, which happens to be text number 4. @subheading Error codes @@ -5742,7 +5737,7 @@ There is no text following text @rarg{start}. @end example This call returns the first readable text in the database created most -recently before @rarg{start}. @rarg{start} does not have to be a valid +recently before @rarg{start}. @rarg{start} does not have to be a valid or readable text number, as shown in the examples. @reqexample @@ -5778,7 +5773,7 @@ There is no text preceding text @rarg{start}. -> ( ); @end example -This call is used to log in. The session is logged in as person number +This call is used to log in. The session is logged in as person number @rarg{person} if @rarg{passwd} is the correct password for that person. If @rarg{invisible} is true, the session is invisible: it will not be returned by @reqlink{who-is-on} and @reqlink{who-is-on-ident}, and the @@ -5786,7 +5781,7 @@ dynamic session info (@pxref{Dynamic-Session-Info}) will have the invisible flag set. Invisible sessions are primarily used by software agents that do not act -on the behalf of real users. +on the behalf of real users. @reqexample @example @@ -5801,10 +5796,10 @@ on the behalf of real users. @end example This example first shows a session log in as person seven with the -invisible flag set. Because of this the asynchronous login message is -not sent. The second call logs in as person seven again. This time a +invisible flag set. Because of this the asynchronous login message is +not sent. The second call logs in as person seven again. This time a login message is sent, but not a logout message since the login was -invisible. The third example shows a third login as person 7, but this +invisible. The third example shows a third login as person 7, but this time both the logout and login messages are sent. @subheading Error codes @@ -5852,7 +5847,7 @@ This call always succeeds. -> ( @lt{Session-Info-Ident} ); @end example -This call is obsolete. Use @reqlink{who-is-on-dynamic} and +This call is obsolete. Use @reqlink{who-is-on-dynamic} and @reqlink{get-static-session-info} instead. @subheading Error codes @@ -5874,16 +5869,16 @@ The session @rarg{session-no} does not exist. -> ( @lt{ARRAY} @lt{Pers-No} ); @end example -This call is obsolete. It has been replaced by @reqlink{re-z-lookup}. +This call is obsolete. It has been replaced by @reqlink{re-z-lookup}. It returns a list of persons matching the regular expression -@rarg{regexp}. The regexp syntax used is that of the @command{ed}(1) +@rarg{regexp}. The regexp syntax used is that of the @command{ed}(1) Unix utility. @subheading Error codes @table @errorcode @item regexp-error -Error compiling the regexp @rarg{regexp}. Perhaps the pattern is +Error compiling the regexp @rarg{regexp}. Perhaps the pattern is not a correct regexp. @end table @@ -5897,16 +5892,16 @@ not a correct regexp. -> ( @lt{ARRAY} @lt{Conf-No} ); @end example -This call is obsolete. It has been replaced by @reqlink{re-z-lookup}. It +This call is obsolete. It has been replaced by @reqlink{re-z-lookup}. It returns a list of conferences matching the regular expression -@rarg{regexp}. The regexp syntax used is that of the @command{ed}(1) Unix -utility. +@rarg{regexp}. The regexp syntax used is that of the @command{ed}(1) Unix +utility. @subheading Error codes @table @errorcode @item regexp-error -Error compiling the regexp @rarg{regexp}. Perhaps the pattern is +Error compiling the regexp @rarg{regexp}. Perhaps the pattern is not a correct regexp. @end table @@ -5922,10 +5917,10 @@ not a correct regexp. -> ( @lt{ARRAY} @lt{Pers-No} ); @end example -This call is obsolete. It has been replaced by @reqlink{lookup-z-name}. +This call is obsolete. It has been replaced by @reqlink{lookup-z-name}. This call returns a list of persons with names matching the -contracted name in @rarg{name}. @xref{Name Expansion}, for a +contracted name in @rarg{name}. @xref{Name Expansion}, for a description of the matching process. @subheading Error codes @@ -5943,10 +5938,10 @@ This call always succeeds. -> ( @lt{ARRAY} @lt{Conf-No} ); @end example -This call is obsolete. It has been replaced by @reqlink{lookup-z-name}. +This call is obsolete. It has been replaced by @reqlink{lookup-z-name}. This call returns a list of conferences with names matching the -contracted name in @rarg{name}. @xref{Name Expansion}, for a +contracted name in @rarg{name}. @xref{Name Expansion}, for a description of the matching process. @subheading Error codes @@ -5966,11 +5961,11 @@ This call always succeeds. @end example This call is used to tell the server which client and which version of -that client is being used. The name of the client is passed in -@rarg{client-name} and the version in @rarg{client-version}. The +that client is being used. The name of the client is passed in +@rarg{client-name} and the version in @rarg{client-version}. The information sent in this call is made available to other sessions through the @reqlink{get-client-name} and @reqdlink{get-client-version} -calls@linkhere{}. This call should be used exactly once per session. +calls@linkhere{}. This call should be used exactly once per session. The following names are currently registered: @@ -5998,10 +5993,10 @@ The following names are currently registered: @end example In this example the @reqdlink{who-am-i} call is used to find the ID of -the current session@linkhere{}. Next, @req{set-client-version} is used +the current session@linkhere{}. Next, @req{set-client-version} is used to set the name of the client to ``elisp-client'' and the version to -``0.45''. The third call is to @reqdlink{get-client-name}, which -returns the string just sent to the server@linkhere{}. Finally +``0.45''. The third call is to @reqdlink{get-client-name}, which +returns the string just sent to the server@linkhere{}. Finally @reqlink{get-client-version} is used to retrieve the client version of session number 7, which is, as expected, the string ``0.45''. @@ -6027,8 +6022,8 @@ is undefined. @end example This call returns the name of the client that owns session number -@rarg{session}. This client name string returned is the one set by the -client using @reqlink{set-client-version}. If @req{set-client-version} +@rarg{session}. This client name string returned is the one set by the +client using @reqlink{set-client-version}. If @req{set-client-version} has not been issued in session number @rarg{session}, the empty string is returned. @@ -6054,8 +6049,8 @@ The session @rarg{session} does not exist. @end example This call returns the version of the client that owns session number -@rarg{session}. This client version string returned is the one set by -the client using @reqlink{set-client-version}. If +@rarg{session}. This client version string returned is the one set by +the client using @reqlink{set-client-version}. If @req{set-client-version} has not been issued in session number @rarg{session}, the empty string is returned. @@ -6083,11 +6078,11 @@ The session @rarg{session} does not exist. @end example This call associates the mark @rarg{mark-type} with the text -@rarg{text}. The list of marks set by a person can be retrieved using +@rarg{text}. The list of marks set by a person can be retrieved using the @reqdlink{get-marks} call@linkhere{}. Currently, servers do not associate any particular meaning to the -different types of marks, but that may change in the future. Currently, +different types of marks, but that may change in the future. Currently, servers should not delete texts that have marks, except by user request. @reqexample @@ -6101,7 +6096,7 @@ servers should not delete texts that have marks, except by user request. @end example This example shows how a person with no marks set sets mark 230 on text -number 110. The calls to @reqlink{get-marks} show the effect of the call. +number 110. The calls to @reqlink{get-marks} show the effect of the call. @subheading Error codes @@ -6131,7 +6126,7 @@ Already the maximum number of marks on text @rarg{text}. @end example This call removes any marks the logged-in person has set on the text -@rarg{text-no}. +@rarg{text-no}. @reqexample @example @@ -6170,15 +6165,15 @@ The text @rarg{text-no} was not marked. @end example This call returns a list of those conferences and/or persons matching -the regular expression @rarg{regexp}. If @rarg{want-confs} is true, then -the result will include non-mailbox conferences. If +the regular expression @rarg{regexp}. If @rarg{want-confs} is true, then +the result will include non-mailbox conferences. If @rarg{want-persons} is true, then the result will include mailbox -conferences. +conferences. -See also @ref{lookup-z-name}, for an alternative way to look up names. +See also @ref{lookup-z-name}, for an alternative way to look up names. Refer to @ref{Name Expansion}, for more details on how name lookup -works. +works. @reqexample @example @@ -6193,19 +6188,19 @@ works. @t{ 21HTrains (-) Discussion 0000 11 @}} @end example -This example shows three calls to @req{re-z-lookup}. The first call +This example shows three calls to @req{re-z-lookup}. The first call returns all conferences and persons in the entire database, in this case -two conferences and two persons. The second example uses the same +two conferences and two persons. The second example uses the same regular expression, but in this case, the call specifies that the result is only to contain conferences, so the two persons are not -returned. The third example simply returns all names matching the +returned. The third example simply returns all names matching the pattern ``T.*[cC]''. @subheading Error codes @table @errorcode @item regexp-error -Error compiling the regexp @rarg{regexp}. Perhaps the pattern is +Error compiling the regexp @rarg{regexp}. Perhaps the pattern is not a correct regexp. @end table @@ -6220,10 +6215,10 @@ not a correct regexp. -> ( @lt{Version-Info} ); @end example -This call returns information about the server version. The data -returned by this call are primarily useful for presenting to the user. A +This call returns information about the server version. The data +returned by this call are primarily useful for presenting to the user. A client should not use this call to determine what the server's -capabilities are. +capabilities are. @reqexample @example @@ -6252,9 +6247,9 @@ This call always succeeds. @end example This call looks up the name @rarg{name} in the server, and returns a -list of all matching conferences and/or persons. If @rarg{want-confs} +list of all matching conferences and/or persons. If @rarg{want-confs} is true, then the result will include conferences that are not -mailboxes. If @rarg{want-pers} is true, then the result will include +mailboxes. If @rarg{want-pers} is true, then the result will include conferences that are mailboxes. See also @ref{re-z-lookup}, for an alternative way to look up names. @@ -6274,10 +6269,10 @@ Refer to @ref{Name Expansion}, for details on the matching process. @t{ 21HTrains (-) Discussion 0000 11 @}} @end example -This example shows three calls to @req{lookup-z-name}. The first call -retrieves all conferences and persons in the server. The second request +This example shows three calls to @req{lookup-z-name}. The first call +retrieves all conferences and persons in the server. The second request looks up the same name as the first, but this time the result is -restricted to conferences. The final request requests all conferences +restricted to conferences. The final request requests all conferences and persons matching the pattern ``T C''. @subheading Error codes @@ -6297,7 +6292,7 @@ This call always succeeds. This call tells the server that the last local text number the person issuing the call has read in conference @rarg{conference} is -@rarg{last-read}. This call is typically used when a user wants to have +@rarg{last-read}. This call is typically used when a user wants to have a specific number of unread texts in a particular conference. @reqexample @@ -6311,7 +6306,7 @@ a specific number of unread texts in a particular conference. @end example This example shows how person 7 originally had read everything up to and -including local text number 6 in conference 6. After the call to +including local text number 6 in conference 6. After the call to @req{set-last-read}, the @reqlink{query-read-texts} call reports that person 7 has read everything up to and including local text number 3. @@ -6340,7 +6335,7 @@ Not a member of conference @rarg{conference}. This call returns some information about conference @rarg{conference}. The information it returns is sufficient for most uses of conference information, and this call should be used instead of -@reqdlink{get-conf-stat} wherever possible@linkhere{}. It uses less +@reqdlink{get-conf-stat} wherever possible@linkhere{}. It uses less bandwidth and the lyskomd server always keeps all @type{UConference} objects in memory, so this call is significantly faster than @req{get-conf-stat}. @@ -6363,9 +6358,9 @@ conference. @end example This example shows the difference between @reqlink{get-conf-stat-old} and -@req{get-uconf-stat}. In the first two examples conference 6 is +@req{get-uconf-stat}. In the first two examples conference 6 is retrieved, and in the second two, conference 7, which happens to be a -person, is retrieved. Note the difference in length of the flag field. +person, is retrieved. Note the difference in length of the flag field. @subheading Error codes @@ -6383,14 +6378,14 @@ The conference @rarg{conference} does not exist or is secret. @findex set-info @example - set-info [79] ( info : @lt{Info-Old} ) + set-info [79] ( info : @lt{Info-Old} ) -> ( ); @end example This call sets the server information retrieved by @reqlink{get-info-old}. The version number in the info structure is ignored (but must be present); all other fields are stored permanently -in the LysKOM database. This is a privileged call. +in the LysKOM database. This is a privileged call. @reqexample @example @@ -6400,7 +6395,7 @@ in the LysKOM database. This is a privileged call. This example sets the conference presentation conference to one, the user presentation conference to two, the motd conference to three and -the news conference to four. It also sets the login message to text +the news conference to four. It also sets the login message to text 1080. It also attempts to set the version number to 1.9.1, but that number is silently ignored by the server. @@ -6435,19 +6430,19 @@ day, and the current implementation of the server does accept MOTD to be @findex accept-async @example - accept-async [80] ( request-list : @lt{ARRAY} @lt{INT32} ) + accept-async [80] ( request-list : @lt{ARRAY} @lt{INT32} ) -> ( ); @end example This call advises the server that the client wants to receive the -asynchronous messages listed in @rarg{request-list}. The server must +asynchronous messages listed in @rarg{request-list}. The server must send these messages to the client when applicable, but may also send -other types of messages if it so desires. The list of currently +other types of messages if it so desires. The list of currently requested asynchronous messages may be retrieved using the @reqdlink{query-async} call@linkhere{}. Don't forget that message type 12 is personal, group and global -text messages. Most users will not want these turned off. +text messages. Most users will not want these turned off. @reqexample @example @@ -6463,14 +6458,14 @@ when someone logs in (message 9). If the client requests a message that the server does not send, the server will reply with an error message saying which message number it -does not support. The call will succeed anyway. This mechanism is useful +does not support. The call will succeed anyway. This mechanism is useful for clients that want new versions of some messages, but need to be compatible with older servers. @table @errorcode @item unknown-async At least one of the numbers in @rarg{request-list} is not the number -of an async message the server knows about. The @field{error-status} +of an async message the server knows about. The @field{error-status} indicates the first offending number. Please note that a bug in lyskomd 1.9.0 prevented the server from @@ -6491,15 +6486,15 @@ overrun. @findex query-async @example - query-async [81] ( ) + query-async [81] ( ) -> ( @lt{ARRAY} @lt{INT32} ); @end example This call queries the server for which asynchronous messages the client -is receiving. Note that the client may not be able to turn off all +is receiving. Note that the client may not be able to turn off all messages returned in this list since the server may consider some -messages to be mandatory. Also note that the client may still receive -messages that are not listed in the result of this call. Even though +messages to be mandatory. Also note that the client may still receive +messages that are not listed in the result of this call. Even though those messages are turned off, the server may decide to send them under certain circumstances. @@ -6511,7 +6506,7 @@ certain circumstances. In this example the client is receiving seven types of asynchronous messages: messages about new articles, changed names, database synching, -new logins, rejected connections, personal messages and logouts. This +new logins, rejected connections, personal messages and logouts. This particular set was the default for new connections to lyskomd 1.9 servers. @xref{Asynchronous Messages}, for the currently recommended list of asynchronous messages that servers should preselect. @@ -6530,7 +6525,7 @@ This call always succeeds. -> ( ); @end example -This call simply notifies the server that the user is active. The +This call simply notifies the server that the user is active. The server uses the time of the last user-active call to calculate how long a user has been idle. @@ -6615,8 +6610,8 @@ The session @rarg{session-no} does not exist. @end example This call returns the collate table being used by the server to match -names. If index A and index B in the string are the same character, -characters A and B are considered equivalent. An empty collate table +names. If index A and index B in the string are the same character, +characters A and B are considered equivalent. An empty collate table indicates that the server considers all characters different. Currently, the lyskomd server only deals with 8-bit characters. Clients @@ -6643,15 +6638,15 @@ This call always succeeds. @end example Creates a new text with contents from @rarg{text} and recipients -etc. defined by @rarg{misc-info} (@pxref{The Misc-Info List}). In +etc. defined by @rarg{misc-info} (@pxref{The Misc-Info List}). In addition to the result, the server will send an asynchronous message -to all members of any of the recipients of the new text. It is not +to all members of any of the recipients of the new text. It is not defined whether this messages comes before or after the reply to -the create-text message. Clients should be prepared for either +the create-text message. Clients should be prepared for either situation. The text up to the first line feed is considered to be the subject -line. The remaining text is the message body. Although messages with +line. The remaining text is the message body. Although messages with only a subject are valid, clients should avoid letting users create such messages. @@ -6683,16 +6678,16 @@ set. Attempt to comment a text with the maximum number of comments already set. @item index-out-of-range -Attempt to create a text failed because we reached the maximum number of +Attempt to create a text failed because we reached the maximum number of texts permitted. @item access-denied Attempt to send a text to a conference failed because no access to the conference or any superconference that will accept a text. @item illegal-misc -Invalid misc-info list. A recipient is listed more than once or there is -an unknown misc item in the misc-info list. +Invalid misc-info list. A recipient is listed more than once or there is +an unknown misc item in the misc-info list. @item illegal-aux-item -One of the aux-items in @rarg{aux-items} is illegal. The tag might be +One of the aux-items in @rarg{aux-items} is illegal. The tag might be out of range, the item not applicable to texts or whatever @item aux-item-permission One of the items looks valid but could not be created anyway. @@ -6714,7 +6709,7 @@ Too many misc-items or aux-items were specified. Similar to @reqlink{create-text}, but the text is created the author -field set to zero. Not even the server has a record of who created the +field set to zero. Not even the server has a record of who created the text. The original intended use for this call was for importing texts from @@ -6755,10 +6750,10 @@ conference or any superconference that will accept a text. Attempt to send an anonymous text to a conference that does not accept anonymous texts. @item illegal-misc -Invalid misc-info list. A recipient is listed more than once or there is -an unknown misc item in the misc-info list. +Invalid misc-info list. A recipient is listed more than once or there is +an unknown misc item in the misc-info list. @item illegal-aux-item -One of the aux-items in @rarg{aux-items} is illegal. The tag might be +One of the aux-items in @rarg{aux-items} is illegal. The tag might be out of range, the item not applicable to texts or whatever @item aux-item-permission One of the items looks valid but could not be created anyway. @@ -6778,9 +6773,9 @@ One of the items looks valid but could not be created anyway. -> ( @lt{Conf-No} ); @end example -This call is used to create new conferences. @rarg{name} is the name of -the new conference and @rarg{type} is its type. If successful, the call -returns the conference number of the newly created conference. The list +This call is used to create new conferences. @rarg{name} is the name of +the new conference and @rarg{type} is its type. If successful, the call +returns the conference number of the newly created conference. The list @rarg{aux-items} contains the aux items to attach to the conference. To use this call the session must have logged in as a user with @@ -6795,7 +6790,7 @@ Login required before issuing this call. @item permission-denied The server does not allow anyone to create a conference and user does -not have the @req{create-conf} bit set. May also be an attempt to +not have the @req{create-conf} bit set. May also be an attempt to create a conference with the @conftype{letterbox} bit set. @item conference-exists @@ -6812,7 +6807,7 @@ The conference type has the @conftype{secret} bit set, but the @conftype{rd-prot} bit is cleared. @item illegal-aux-item -One of the aux-items in @rarg{aux-items} is illegal. The tag might be +One of the aux-items in @rarg{aux-items} is illegal. The tag might be out of range, the item not applicable to conferences or whatever @item aux-item-permission @@ -6837,10 +6832,10 @@ One of the items looks valid but could not be created anyway. This call requests that the server create a new person with the name and -password given as arguments. To create a person the session must be -logged in as a person with sufficient privileges. The list +password given as arguments. To create a person the session must be +logged in as a person with sufficient privileges. The list @rarg{aux-items} contains the aux items that are to be attached to the -new person's mailbox conference. The person flags are set to +new person's mailbox conference. The person flags are set to @rarg{flags}. The new person will be a member of exactly one conference: the @@ -6869,7 +6864,7 @@ There is already a person named @rarg{name}. The string @rarg{passwd} is not a valid password. @item illegal-aux-item -One of the aux-items in @rarg{aux-items} is illegal. The tag might be +One of the aux-items in @rarg{aux-items} is illegal. The tag might be out of range, the item not applicable to conferences or mailboxes or whatever. @@ -6890,7 +6885,7 @@ One of the items looks valid but could not be created anyway. @end example -Get information about text number @rarg{text-no}. The text-stat contains +Get information about text number @rarg{text-no}. The text-stat contains information about the size of the text, its recipients, comments, author and more. @@ -6977,7 +6972,7 @@ One of the items in @rarg{add} is illegal for some reason. This call deleted the aux-items listed in @rarg{delete} from the conference @rarg{conf} and then adds the ones listed in @rarg{add} -to the text. Either list may be empty, and the call is guaranteed to +to the text. Either list may be empty, and the call is guaranteed to either completely fail or completely succeed. @subheading Error codes @@ -7006,7 +7001,7 @@ One of the items in @rarg{add} is illegal for some reason. @end example This call returns the @type{Info} structure for the server -(@pxref{Info}). Clients should call this in order to find +(@pxref{Info}). Clients should call this in order to find out which conferences are used for presentations and such. It can be issued without logging in. @@ -7032,7 +7027,7 @@ can be retrieved using @reqlink{get-info}.) It only succeeds when issued by a person with the admin bit set and privileges enabled. The items in @rarg{items-to-delete} are removed, and the items in -@rarg{items-to-add} are added. This call is atomic; either all +@rarg{items-to-add} are added. This call is atomic; either all deletions or additions succedd, or none of them is made. @subheading Error codes @@ -7059,8 +7054,8 @@ Attempt to delete an undeletable item or create an uncreateable item. @end example Returns the list of aux-items that have specific definitions in the -server. These items are the only items within the restricted tag ranges -that can be created. The meanings of the various item types are defined +server. These items are the only items within the restricted tag ranges +that can be created. The meanings of the various item types are defined in this document. @subheading Error codes @@ -7080,7 +7075,7 @@ This call always succeeds. @end example This call sets the @rarg{expire} field of the conference @rarg{conf-no} -to @rarg{expire}. This call can only be issued by the conference's +to @rarg{expire}. This call can only be issued by the conference's supervisor or a privileged user. @subheading Error codes @@ -7107,8 +7102,8 @@ complete the call anyway. This call is used to find the number of unread texts in a conference. The data it returns is actually a membership structure which specifies -which texts have been read. It is up to the client to transform the data -to a more usable form. @rarg{person} is the person being queried +which texts have been read. It is up to the client to transform the data +to a more usable form. @rarg{person} is the person being queried and @rarg{conference} is the conference in question. Calling @req{query-read-texts} does not require the session to be logged in. @@ -7120,23 +7115,23 @@ Calling @req{query-read-texts} does not require the session to be logged in. @t{ 3 @{ 135 136 137 @} 5 01000000} @end example -This example finds the read texts for user 6 in conference 1. The +This example finds the read texts for user 6 in conference 1. The returned data indicates that the user last read conference 1 (the tenth number) on Monday July 12th, 1993 at 11:05:32 (the first nine numbers), that the person has assigned priority 20 to the conference (the eleventh number) and that all articles up to and including local number 133 plus -articles 135, 136 and 137 have been read. The membership was added by +articles 135, 136 and 137 have been read. The membership was added by person 5, and it is passive. -@c FIXME: Is the example correct? Shouldn't there be a time -@c after "5" and before "01000000"? / kent 990711 +@c FIXME: Is the example correct? Shouldn't there be a time +@c after "5" and before "01000000"? / kent 990711 @subheading Error codes @table @errorcode @item undefined-person @rarg{person} does not exist, or no access to person. -@item undefined-conference +@item undefined-conference Conference @rarg{conference} does not exist, or is secret. @item conference-zero @rarg{conference} is zero. @@ -7159,20 +7154,20 @@ privileges to find out if @rarg{person} is a member. @end example This call retrieves the membership record for a list of conferences -for a single person. @rarg{person} is the person whose memberships are -to be retrieved. @rarg{first} is the first position in the membership -list to retrieve, numbered from 0 and up. @rarg{no-of-confs} is the -number of membership records to retrieve. If @rarg{want-read-texts} is +for a single person. @rarg{person} is the person whose memberships are +to be retrieved. @rarg{first} is the first position in the membership +list to retrieve, numbered from 0 and up. @rarg{no-of-confs} is the +number of membership records to retrieve. If @rarg{want-read-texts} is @samp{0}, the server will not send the contents of the -@field{read-texts} array of the memberships. (The size will be +@field{read-texts} array of the memberships. (The size will be transmitted, but a single asterisk (@samp{*}) will be sent instead of the array itself.) The server will return a membership list that is shorter than @rarg{no-of-confs} if @rarg{no-of-confs} + @rarg{first} is larger than -the number of conferences the person is a member of. Elements of the +the number of conferences the person is a member of. Elements of the member list that the person requesting the list does not have sufficient -privileges to see may be cleared. Cleared elements simply have all +privileges to see may be cleared. Cleared elements simply have all fields set to zero. @reqexample @@ -7189,10 +7184,10 @@ fields set to zero. @t{ 49 14 17 13 8 91 5 255 1 00000000 @}} @end example -In this example we retrieve the memberships of person 5. The first call -asks for three memberships, starting with number 0. Since this person is +In this example we retrieve the memberships of person 5. The first call +asks for three memberships, starting with number 0. Since this person is only a member of two conferences, the list returned only contains two -memberships. The next two calls retrieve a single membership each. The +memberships. The next two calls retrieve a single membership each. The first by asking for only one, and the second by asking for four memberships, starting with number 1. @@ -7228,13 +7223,13 @@ Make the person @rarg{pers-no} a member of conference @rarg{conf-no}. The membership priority is set to @rarg{priority} and its position in the membership list is set to @rarg{where}. -The membership flags are set to @rarg{type}. If the current user is +The membership flags are set to @rarg{type}. If the current user is adding a user he isn't supervisor of, the @field{invitation} bit of @rarg{type} is automatically set by the server. This call can be used to change the priority, position and flags of a conference in the person's membership list if the person is already a -member of the conference. The person doing this must either be a +member of the conference. The person doing this must either be a supervisor of the affected person, or have sufficient privileges enabled. @@ -7246,15 +7241,15 @@ enabled. @t{=1} 1 100 119 119 251 1 00000000 @t{=1} - 1 99 119 0 10 0 + 1 99 119 0 10 0 @t{=1 2 @{ 52 30 14 11 5 96 2 162 1 1 250 0 0 * 119 00000000 49 14 17 13 8 91 5 251 1 119 255 0 0 * 10000000 @}} @end example This example makes person 119 (me) a member of conference number 1 and changes the priority and some flags of the preexisting membership in -conference 119. The priority is set to 250 and the conference is placed -first in the membership list. The first and last calls of the example +conference 119. The priority is set to 250 and the conference is placed +first in the membership list. The first and last calls of the example show the membership list for person 119 before and after the calls. @@ -7302,12 +7297,12 @@ privileges to change the priorities of person @rarg{pers-no}. This call returns a list of members of the conference @rarg{conf}. @rarg{first} is the first index in the membership to return, numbered -from zero and up. @rarg{no-of-members} is the maximum number of members +from zero and up. @rarg{no-of-members} is the maximum number of members to return. Some of the elements of the result may be cleared if the person requesting the information does not have sufficient privileges to see -the contents. Cleared elements simply have all fields set to zero. +the contents. Cleared elements simply have all fields set to zero. @reqexample @example @@ -7322,8 +7317,8 @@ the contents. Cleared elements simply have all fields set to zero. @end example In this example the client first requests the first 100 members in -conference 1. The second request is for the first 100 members of -conference 6. The last request is for members 2 and 3 in conference 6. +conference 1. The second request is for the first 100 members of +conference 6. The last request is for members 2 and 3 in conference 6. @subheading Error codes @@ -7346,12 +7341,12 @@ The conference @rarg{conf} does not exist or is secret. -> ( ); @end example -This call modifies the type of a membership. The person @rarg{pers} -membership in conference @rarg{conf} is affected. The server may impose -arbitrary restrictions on how the membership type may be changed. -Typically it will only be possible to clear the @field{invitation} bit. +This call modifies the type of a membership. The person @rarg{pers} +membership in conference @rarg{conf} is affected. The server may impose +arbitrary restrictions on how the membership type may be changed. +Typically it will only be possible to clear the @field{invitation} bit. It is possible that the server will not permit the @field{secret} bit to -be set. Attempting to set a membership type that does not agree with +be set. Attempting to set a membership type that does not agree with the server's restrictions will result in an error. @@ -7392,7 +7387,7 @@ restrictions set on the server or on the conference @rarg{conf} -> ( @lt{Text-Mapping} ); @end example -This call retrieves information that makes it possible to convert +This call retrieves information that makes it possible to convert @rarg{no-of-existing-texts} existing local text numbers starting at @rarg{first-local-no} to global text numbers, provided that there are that many local texts. @@ -7412,7 +7407,7 @@ how many deleted texts there are after @rarg{first-local-no}. @t{=1 1 7 1 1 1 6 @{ 1003 1005 1009 1029 0 1034 @}} 2 103 93 1 6 @t{=2 1 63 1 0 6 @{ - 1 1003 + 1 1003 2 1005 3 1009 4 1029 @@ -7543,7 +7538,7 @@ information about the texts in the conference. @end example Sets the @rarg{keep-commented} field of the conference @rarg{conf-no} to -@rarg{keep-commented}. This call can only be issued by a conference's +@rarg{keep-commented}. This call can only be issued by a conference's supervisor or a privileged user. @subheading Error codes @@ -7569,7 +7564,7 @@ complete the call anyway. -> ( ); @end example -Set the flags field of person @rarg{pers-no} to @rarg{flags}. This call +Set the flags field of person @rarg{pers-no} to @rarg{flags}. This call can only be issued by the person supervisor or a privileged user. @subheading Error codes @@ -7629,10 +7624,10 @@ reject them if a client uses it as an argument to @end ifnottex Clients can select which messages to receive by issuing an -@reqdlink{accept-async} call@linkhere{}. They can find out which +@reqdlink{accept-async} call@linkhere{}. They can find out which messages are being sent by issuing the @reqdlink{query-async} -call@linkhere{}. Note that the server can send other messages as -well. For example, a broadcast message from a person with admin bits +call@linkhere{}. Note that the server can send other messages as +well. For example, a broadcast message from a person with admin bits set may get through even if the client has not requested broadcast messages. @@ -7642,12 +7637,12 @@ messages they want. Servers are encouraged to preselect the @async{async-new-text-old}, @async{async-new-name}, @async{async-sync-db}, @async{async-leave-conf}, @async{async-login}, @async{async-rejected-connection}, @async{async-send-message} and -@async{async-logout} messages. These correspond to the useful messages +@async{async-logout} messages. These correspond to the useful messages that were sent prior to the introduction of @reqlink{accept-async}. An asynchronous message is sent as a colon immediately followed by the number of message parameters, the message number and the message -parameters. For example, message number 5 could be sent as +parameters. For example, message number 5 could be sent as @example :3 5 119 11HDavid Byers 13HDavid C Byers @@ -7665,8 +7660,8 @@ calls. text-stat : @lt{Text-Stat-Old} )); @end example -This message is sent when a text is created. The text number of the text -is sent in @aarg{text-no} and the text stat in @aarg{text-stat}. This +This message is sent when a text is created. The text number of the text +is sent in @aarg{text-no} and the text stat in @aarg{text-stat}. This message is sent to all logged-in members of any recipient of the text. In protocol version 10 this call has been superceded by @ref{async-new-text}. @@ -7682,7 +7677,7 @@ In protocol version 10 this call has been superceded by @ref{async-new-text}. async-i-am-off [1] ( person : @lt{Pers-No} ); @end example -This message was sent when @aarg{person} logged off. It has been +This message was sent when @aarg{person} logged off. It has been replaced by @asynclink{async-logout}, since this asynchronous message could not differentiate between sessions if the same person was logged in more than once. @@ -7702,7 +7697,7 @@ in more than once. This message was sent when @aarg{person} changed his @code{what-i-am-doing} string to @aarg{what-am-i-doing} or his working -conference to @aarg{conference}. +conference to @aarg{conference}. It has been replaced by call number 6, @asynclink{async-i-am-on}, since this asynchronous message could not differentiate between sessions if @@ -7720,7 +7715,7 @@ the same person was logged in more than once. new-name : @lt{HOLLERITH} )); @end example -This message is sent when a person or conference changes names. The +This message is sent when a person or conference changes names. The conference whose name is being changed is sent in @aarg{conf-no}, the old name in @aarg{old-name} and the new name in @aarg{new-name}. @@ -7737,7 +7732,7 @@ old name in @aarg{old-name} and the new name in @aarg{new-name}. This message is sent when a session's working conference, @code{what-i-am-doing} string (@pxref{change-what-i-am-doing}) or -username changes. The new information is sent in @aarg{info}. +username changes. The new information is sent in @aarg{info}. @c FIXME: can the username change? @@ -7751,8 +7746,8 @@ username changes. The new information is sent in @aarg{info}. @end example This message is sent once just before the server blocks to save its -database and once just after it blocks. There is no good way to tell the -difference between the two cases. +database and once just after it blocks. There is no good way to tell the +difference between the two cases. @@ -7765,7 +7760,7 @@ difference between the two cases. @end example This message is sent to a user when the user's membership in the working -conference is removed for any reason. The conference the user is being +conference is removed for any reason. The conference the user is being removed from is sent in @aarg{conf-no}. Earlier versions of the LysKOM Protocol A specifications stated that @@ -7796,7 +7791,7 @@ to a passive membership. session-no : @lt{Session-No} )); @end example -This message is sent when someone logs in. The identity of the person +This message is sent when someone logs in. The identity of the person logging in is sent in @aarg{pers-no}, and the session number in @aarg{session-no}. @@ -7814,7 +7809,7 @@ logging in is sent in @aarg{pers-no}, and the session number in @end example This message has been superceded by @asyncdlink{async-send-message} which -is more flexible@linkhere{}. It used to be sent when the administrator +is more flexible@linkhere{}. It used to be sent when the administrator (@aarg{sender}) broadcasted a string (@aarg{message}) to all LysKOM users, but is no longer used. @@ -7830,8 +7825,8 @@ users, but is no longer used. @end example This message is sent when someone fails to log in because the maximum -number of allowed connections has been reached. Some clients may take -this as a signal to log out. Administrators should take it as a signal +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. @@ -7847,10 +7842,10 @@ to allow more connections. @end example This message is sent when someone (the @aarg{sender}) sends a message -string (the @aarg{message}). The recipient of the message is sent in -@aarg{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 +string (the @aarg{message}). The recipient of the message is sent in +@aarg{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. @@ -7865,9 +7860,9 @@ conference. session-no : @lt{Session-No} )); @end example -This message is sent when someone logs out. @aarg{pers-no} is the person +This message is sent when someone logs out. @aarg{pers-no} is the person logging out and @aarg{session-no} is the session in which the person is -logging out. This message might also be sent when a session disconnects, +logging out. This message might also be sent when a session disconnects, even if there is nobody logged on in the session. @@ -7882,7 +7877,7 @@ even if there is nobody logged on in the session. @end example This message is sent when a text is deleted and the currently logged-in -person is a member of one of the recipients. The text number being +person is a member of one of the recipients. The text number being deleted is sent in @aarg{text-no} and the text stat in @aarg{text-stat}. @@ -7896,8 +7891,8 @@ deleted is sent in @aarg{text-no} and the text stat in @aarg{text-stat}. text-stat : @lt{Text-Stat} )); @end example -This message indicates that a new text has been created. The text has -number @aarg{text-no}, and the text stat is @aarg{text-stat}. The +This message indicates that a new text has been created. The text has +number @aarg{text-no}, and the text stat is @aarg{text-stat}. The message is sent to all logged-in members of any recipient of the text. @@ -7912,8 +7907,8 @@ message is sent to all logged-in members of any recipient of the text. @end example This message indicates that a new recipient has been added to text -@aarg{text-no}. The recipient added is @aarg{conf-no} and the type of -recipient is indicated by @aarg{type}. This message is sent to all +@aarg{text-no}. The recipient added is @aarg{conf-no} and the type of +recipient is indicated by @aarg{type}. This message is sent to all recipients of the text that are permitted to know about the new recipient. @@ -7930,8 +7925,8 @@ recipient. @end example This message indicates that a recipient has been removed from text -@aarg{text-no}. The recipient removed is @aarg{conf-no} and the type of -recipient is indicated by @aarg{type}. This message is sent to everybody +@aarg{text-no}. The recipient removed is @aarg{conf-no} and the type of +recipient is indicated by @aarg{type}. This message is sent to everybody that were recipients of the text and that were permitted to know about the recipient. @@ -7946,7 +7941,7 @@ the recipient. @end example This message indicates that the membership for @aarg{pers-no} in -conference @aarg{conf-no} has been added. This message is currently sent +conference @aarg{conf-no} has been added. This message is currently sent only to @aarg{pers-no}, but that may change in the future. See also @ref{async-leave-conf}. @@ -7957,7 +7952,7 @@ See also @ref{async-leave-conf}. @chapter 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, +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. @@ -7973,14 +7968,14 @@ including the syntax of the error response. @table @code @item no-error (0) -No error has occurred. @field{error-status} is undefined. This should +No error has occurred. @field{error-status} is undefined. This should never happen, but it might. @item not-implemented (2) -The call has not been implemented yet. @field{error-status} is undefined. +The call has not been implemented yet. @field{error-status} is undefined. @item obsolete-call (3) -The call is obsolete and no longer implemented. @field{error-status} is +The call is obsolete and no longer implemented. @field{error-status} is undefined. @item invalid-password (4) @@ -7992,15 +7987,15 @@ A string was too long (see descriptions of each call.) @field{error-status} indicates the maximum string length. @item login-first (6) -Login is required before issuing the call. @field{error-status} is -undefined. +Login is required before issuing the call. @field{error-status} is +undefined. @item login-disallowed (7) -The system is in single-user mode. You need to be privileged to log in -despite this. @field{error-status} is undefined. +The system is in single-user mode. You need to be privileged to log in +despite this. @field{error-status} is undefined. @item conference-zero (8) -Attempt to use conference number 0. @field{error-status} is undefined. +Attempt to use conference number 0. @field{error-status} is undefined. @item undefined-conference (9) Attempt to access a non-existent or secret conference. @@ -8011,69 +8006,69 @@ Attempt to access a non-existent or secret person. @field{error-status} contains the person number in question. @item access-denied (11) -No read/write access to something. This might be returned in response to +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. @field{error-status} +conference without enough permission to do so. @field{error-status} indicates the object to which we didn't have enough permissions to. @item permission-denied (12) -Not enough permissions to do something. The exact meaning of this -response depends on the call. @field{error-status} indicated the object +Not enough permissions to do something. The exact meaning of this +response depends on the call. @field{error-status} indicated the object for which permission was lacking, or zero. @item not-member (13) The call requires the caller to be a member of some conference that the -caller is not a member of. @field{error-status} indicates the conference +caller is not a member of. @field{error-status} indicates the conference in question. @item no-such-text (14) Attempt to access a text that either does not exist or is secret in some -way. @field{error-status} indicates the text number in question. +way. @field{error-status} indicates the text number in question. @item text-zero (15) -Attempt to use text number 0. @field{error-status} is undefined. +Attempt to use text number 0. @field{error-status} is undefined. @item no-such-local-text (16) Attempt to access a text using a local text number that does not -represent an existing text. @field{error-status} indicates the offending +represent an existing text. @field{error-status} indicates the offending number. @item local-text-zero (17) -Attempt to use local text number zero. @field{error-status} is undefined. +Attempt to use local text number zero. @field{error-status} is undefined. @item bad-name (18) Attempt to use a name that's too long, too short or contains invalid -characters. @field{error-status} is undefined. +characters. @field{error-status} is undefined. @item index-out-of-range (19) -Attempt to use a number that's out of range. The range and meaning of -the numbers depends on the call issued. @field{error-status} is +Attempt to use a number that's out of range. The range and meaning of +the numbers depends on the call issued. @field{error-status} is undefined unless stated otherwise in the call documentation. @item conference-exists (20) Attempt to create a conference or person with a name that's already -occupied. @field{error-status} is undefined. +occupied. @field{error-status} is undefined. @item person-exists (21) Attempt to create a person with a name that's already occupied. -@field{error-status} is undefined. This error code is probably not used, +@field{error-status} is undefined. This error code is probably not used, but you never know for sure. @item secret-public (22) Attempt to give a conference a type with @conftype{secret} bit set and the -@conftype{rd-prot} bit unset. This is an error since such a conference type -is inconsistent. @field{error-status} is undefined. +@conftype{rd-prot} bit unset. This is an error since such a conference type +is inconsistent. @field{error-status} is undefined. @item letterbox (23) Attempt to change the @conftype{letterbox} flag of a conference. @field{error-status} indicates the conference number. @item ldb-error (24) -Database is corrupted. @field{error-status} is an internal code. +Database is corrupted. @field{error-status} is an internal code. @item illegal-misc (25) -Attempt to create an illegal misc item. @field{error-status} contains the +Attempt to create an illegal misc item. @field{error-status} contains the index of the illegal item. @item illegal-info-type (26) @@ -8086,11 +8081,11 @@ Attempt to add a recipient that is already a recipient of the same type. @field{error-status} contains the recipient that already is. @item already-comment (28) -Attempt to add a comment to a text twice over. @field{error-status} +Attempt to add a comment to a text twice over. @field{error-status} contains the text number of the text that already is a comment. @item already-footnote (29) -Attempt to add a footnote to a text twice over. @field{error-status} +Attempt to add a footnote to a text twice over. @field{error-status} contains the text number of the text that already is a footnote. @@ -8100,35 +8095,35 @@ Attempt to remove a recipient that isn't really a recipient. @item not-comment (31) Attempt to remove a comment link that does not exist. -@field{error-status} contains the text number that isn't a comment. +@field{error-status} contains the text number that isn't a comment. @item not-footnote (32) Attempt to remove a footnote link that does not exist. -@field{error-status} contains the text number that isn't a footnote. +@field{error-status} contains the text number that isn't a footnote. @item recipient-limit (33) Attempt to add a recipient to a text that already has the maximum number -of recipients. @field{error-status} is the text that has the maximum +of recipients. @field{error-status} is the text that has the maximum number of recipients. @item comment-limit (34) Attempt to add a comment to a text that already has the maximum number -of comments. @field{error-status} is the text with the maximum number of -comments. +of comments. @field{error-status} is the text with the maximum number of +comments. @item footnote-limit (35) Attempt to add a footnote to a text that already has the maximum number -of footnote. @field{error-status} is the text with the maximum number of -footnotes. +of footnote. @field{error-status} is the text with the maximum number of +footnotes. @item mark-limit (36) Attempt to add a mark to a text that already has the maximum number -of marks. @field{error-status} is the text with the maximum number of -marks. +of marks. @field{error-status} is the text with the maximum number of +marks. @item not-author (37) Attempt to manipulate a text in a way that required the user to be the -author of the text, when not in fact the author. @field{error-status} +author of the text, when not in fact the author. @field{error-status} contains the text number in question. @item no-connect (38) @@ -8144,45 +8139,45 @@ Currently unused. Currently unused. @item undefined-session (42) -Attempt to access a session that does not exist. @field{error-status} +Attempt to access a session that does not exist. @field{error-status} contains the offending session number. @item regexp-error (43) -Error using a regexp. The regexp may be invalid or the server unable to -compile it for other reasons. @field{error-status} is undefined. +Error using a regexp. The regexp may be invalid or the server unable to +compile it for other reasons. @field{error-status} is undefined. @item not-marked (44) Attempt to manipulate a text in a way that requires the text to be -marked, when in fact it is not marked. @field{error-status} indicates the +marked, when in fact it is not marked. @field{error-status} indicates the text in question. @item temporary-failure (45) -Temporary failure. Try again later. @field{error-status} is undefined. +Temporary failure. Try again later. @field{error-status} is undefined. @item long-array (46) -An array sent to the server was too long. @field{error-status} is +An array sent to the server was too long. @field{error-status} is undefined. @item anonymous-rejected (47) Attempt to send an anonymous text to a conference that does not accept -anonymous texts. @field{error-status} is undefined. +anonymous texts. @field{error-status} is undefined. @item illegal-aux-item (48) -Attempt to create an invalid aux-item. Probably the tag or data are -invalid. @field{error-status} contains the index in the aux-item list +Attempt to create an invalid aux-item. Probably the tag or data are +invalid. @field{error-status} contains the index in the aux-item list where the invalid item appears. @item aux-item-permission (49) -Attempt to manipulate an aux-item without enough permissions. This +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. @field{error-status} contains the index at +without permissions to do so. @field{error-status} contains the index at which the item appears in the aux-item list sent to the server. @item unknown-async (50) Sent in response to a request for an asynchronous message the server -does not send. The call succeeds, but this is sent as a warning to the -client. @field{error-status} contains the message type the server did not +does not send. The call succeeds, but this is sent as a warning to the +client. @field{error-status} contains the message type the server did not understand. @item internal-error (51) @@ -8191,17 +8186,17 @@ The server has encountered a possibly recoverable internal error. @item feature-disabled (52) Attempt to use a feature that has been explicitly disabled in the -server. @field{error-status} is undefined. +server. @field{error-status} is undefined. @item message-not-sent (53) -Attempt to send an asynchronous message failed for some reason. Perhaps +Attempt to send an asynchronous message failed for some reason. Perhaps the recipient is not accepting messages at the moment or there are no viable recipients for a group message. @field{error-status} is undefined. @item invalid-membership-type (54) A requested membership type was not compatible with restrictions set on -the server or on a specific conference. @field{error-status} is +the server or on a specific conference. @field{error-status} is undefined unless specifically mentioned in the documentation for a specific call. @@ -8214,75 +8209,75 @@ specific call. @chapter Aux-Item Types Some of the aux-items below (mostly the ones that begin with "mx-") are -used by mail importers. For information about supplementary aux-items +used by mail importers. For information about supplementary aux-items introduced by @command{komimportmail}, see @ref{komimportmail Aux-Item Types}. @table @samp @item content-type [1] (text) -Specifies the content type of a text. Data is a valid MIME type or one +Specifies the content type of a text. Data is a valid MIME type or one of the special LysKOM types (@pxref{LysKOM Content Types}). -This item may only be set by the author of a text. The inherit, secret -and hide-owner bits are cleared. Only one content-type item can be +This item may only be set by the author of a text. The inherit, secret +and hide-owner bits are cleared. Only one content-type item can be created per creator. @item fast-reply [2] (text) -Data is a string that constitutes a brief comment to the text. This -comment should be displayed immediately after the text body. +Data is a string that constitutes a brief comment to the text. This +comment should be displayed immediately after the text body. An item of this type will never be inherited, can always be deleted, is never anonymous and is never secret. @item cross-reference [3] (text, conference, 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 +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 simly that, a text that describes the cross-reference. For +of T, C or P. T specifies that the cross-reference points to a text; C +that it points to a conference; and P that it points to a person. The +number is the id of the target of the cross reference. The descriptive +text is simly that, a text that describes the cross-reference. For example, "T15 Check this out!" is a cross reference to text 15 with a description that reads "Check this out!", and "T17" is a cross reference without a description. The inherit bit is automatically cleared and the item can always be -deleted. +deleted. @item no-comments [4] (text) When this item is set, the author requests that nobody comments the -text. This is advisory only; it is still possible to write comments, but +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. +wishes. Data should be empty. -This item may only be set by the author. The secret, hide-creator and +This item may only be set by the author. The secret, hide-creator and inherit bits are automatically cleared. @item personal-comment [5] (text) -When this item is set, the author requests only personal comments. This +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. +comment. Data should be empty. -This item may only be set by the author. The secret, hide-creator and +This item may only be set by the author. The secret, hide-creator and inherit bits are automatically cleared. @item request-confirmation [6] (text) The author requests that everyone who reads the text confirms having -done so by creating read-confirmation items on the text. Clients should +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. +displayed. Data should be empty. The hide-creator, secret and inherit bits are automatically cleared. @item read-confirm [7] (text) This item can be taken as confirmation that the item creator has read -the text to which the item is attached. Clients should never ever create +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. @@ -8293,37 +8288,37 @@ Once created an item of this type cannot be deleted. @item 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 +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 +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. +and ADDRESS is either an e-mail address or a LysKOM conference. Hopefully we'll be able to replace this with a forwarding mechanism later. This item can only be set by the conference supervisor or in the case of -a mailbox, the person attached to the mailbox. The hide-creator and -secret bits are cleared automatically. Only one redirect can be +a mailbox, the person attached to the mailbox. The hide-creator and +secret bits are cleared automatically. Only one redirect can be specified. @item x-face [9] (conference, letterbox, server) -Data is the face of the person in compface format. Cool, innit? +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. +a mailbox, the person attached to the mailbox. The hide-creator and +secret bits are cleared automatically. @item 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 +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. @@ -8331,7 +8326,7 @@ The inherit flag is automatically cleared. @item pgp-signature [11] (text) -Data is a PGP signature of the text. The signature should be the +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. @@ -8340,40 +8335,40 @@ Signatures cannot be deleted once they have been created. @item pgp-public-key [12] (letterbox) -Data is the public key of the person. It is desirable that the public +Data is the public key of the person. It is desirable that the public key contains a userid of the format "LysKOM +", where @var{n} is the number of the person in the LysKOM server specified -in @var{server}. This rule is currently not enforced. +in @var{server}. This rule is currently not enforced. -This item can only be set by the person himself. The hide-creator, +This item can only be set by the person himself. The hide-creator, secret and inherit bits are automatically cleared. @item e-mail-address [13] (conference, letterbox, server) -Data is an RFC 822-style email address. When set on a mailbox, it -should be the email address of the person. If the person has multiple +Data is an RFC 822-style email address. When set on a mailbox, it +should be the email address of the person. If the person has multiple email addresses he may set serveral e-mail-address aux-items. The meaning of this aux-item when set on a conference that isn't a -mailbox is vague. For a conference that is used as to import a mailing -list this should be the email address of the list. For other conferences +mailbox is vague. For a conference that is used as to import a mailing +list this should be the email address of the list. For other conferences we haven't really defined a sensible use. When this aux-item is set on the server it shold contain the email address of the administrator (or administrators.) This aux-item can only be set by the supervisor of a conference or the -server administrator. The creator cannot be hidden. +server administrator. The creator cannot be hidden. @item faq-text [14] (conference, server) Data is a decimal text number, which is a FAQ for the conference (or -server). Creating an item of this type automatically causes creation of +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 +This item can only be set by the supervisor or server administrator. The hide-creator, secret, and inherit bits are automatically cleared. @@ -8406,11 +8401,11 @@ header containing @code{"Joe Q. Public" }. Data is the proper e-mail address (called @code{addr-spec} in the mail standards) extracted from the @code{From} header of an imported -e-mail. +e-mail. Clients should display this address together with the @aux{mx-author}, -preferably inside angles. If @aux{mx-author} is not present, this address -should be shown anyway. It can also be used by clients to construct an +preferably inside angles. If @aux{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: @code{john.q.public@@example.com} which may come from a @@ -8421,14 +8416,14 @@ something like @code{"Joe Q. Public" }. Data is the proper e-mail address (called @code{addr-spec} in the mail standards) extracted from the @code{Reply-To} header of an imported -e-mail. Clients should use this for constructing replies to imported +e-mail. Clients should use this for constructing replies to imported messages. @item mx-to [19] (text) Data is a single e-mail address from an email @code{To} header. Multiple @aux{mx-to} items may be present when multiple recipients are -specified in the header. Clients should display these items along +specified in the header. Clients should display these items along with the normal LysKOM recipient headers. Sample contents: Both @code{john.q.public@@example.com} and @@ -8442,37 +8437,37 @@ the @code{To} header. @item mx-date [21] (text) Data is the date and time from the @code{Date} header of an imported -email. Its format is "YYYY-MM-DD hh:mm:ss TZ". YYYY is the year the +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 +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 +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 mesage was imported would then be +time. The date and time when the mesage was imported would then be displayed elsewhere or not at all. @item mx-message-id [22] (text) Data is the @code{Message-ID} header of an imported e-mail, with -whitespace and comments removed. The Message-ID should contain the +whitespace and comments removed. The Message-ID should contain the surrounding angles. @item 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 +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 @code{In-Reply-To} header of the imported e-mail, but it could also have been picked from the end of the @code{References} header line. -If the text really comments more than one other text directly, +If the text really comments more than one other text directly, it is allowed to attach more than one @aux{mx-in-reply-to} items to it. @@ -8480,7 +8475,7 @@ it. Data is a string that contains all of the headers of an imported email, including @code{Subject}, and including those that are redundantly -stored in other aux-items. The headers are concatenated with "\n". In +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. @@ -8488,33 +8483,33 @@ Clients are encouraged to provide a command to display this information. @item mx-allow-filter [25] (conference, letterbox) -This aux-item has been declared obsolete. It was intended to supply +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. @item mx-reject-forward [26] (conference, letterbox) -This aux-item has been declared obsolete. It was intended +This aux-item has been declared obsolete. It was intended to supplement mx-allow-filter by telling where rejected mails should be sent. @item notify-comments [27] (letterbox) -Data is a decimal text number that the user is interested in. Clients +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 +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 +This item can only be set by the owner of the letterbox. No flags are forced or cleared. @item 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 +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. @item recommended-conf [29] (server) @@ -8599,18 +8594,18 @@ or KOM conventions. This type of expansion, used by the @reqdlink{re-z-lookup} call and its predecessors@linkhere{} simply matches @command{ed}(1) style regular expressions to names in the database to find the list of -matching names. The matching is case sensitive. +matching names. The matching is case sensitive. @section KOM Conventions -This type of matching is a little more complicated. Patterns consist of -words and parenthesized expressions, and contain implicit wildcards. The +This type of matching is a little more complicated. Patterns consist of +words and parenthesized expressions, and contain implicit wildcards. The @command{lyskomd} program implements an approximation of theses -conventions. Since @command{lyskomd} is the trendsetter, these semantics +conventions. Since @command{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 +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. @@ -8633,8 +8628,8 @@ equivalent according to swascii rules. @node LysKOM Content Types @chapter LysKOM Content Types -LysKOM defines a few special content types for texts. They are all -described in this chapter. In addition to these, clients must support +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. @@ -8647,7 +8642,7 @@ text/html. @node Reformattable Text (x-kom/basic) @section Reformattable Text -This type of content corresponds to the mime type x-kom/basic. It is raw +This type of content corresponds to the mime type x-kom/basic. It is raw text that can be reformatted by the client without ill effects, but that can be legibly displayed on a text terminal without formatting. @@ -8681,27 +8676,27 @@ This content type indicates that the article contains a user area. @chapter The User Area The user area is a regular text that is used to store client-specific -information in the server. Most clients use this to store settings a -user has made that are specific to a particular server. There are also +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 +The user-area is divided into several sub-blocks. The common block is shared by all clients, and its formats and contents dictated by this -protocol specification. Clients may also create one or more blocks. +protocol specification. Clients may also create one or more blocks. -The entire user-area is coded as a @type{HOLLERITH}. This string in turn -contains a list of pairs of @type{HOLLERITH} strings. Each pair consists -of one string containing the block name and one containing the data. This +The entire user-area is coded as a @type{HOLLERITH}. This string in turn +contains a list of pairs of @type{HOLLERITH} strings. Each pair consists +of one string containing the block name and one containing the data. This format ensures that clients can copy or read past other clients' blocks without knowing their structure. The following block names have been defined: @table @code @item common -The common block shared by all clients. The format of the common block is +The common block shared by all clients. The format of the common block is described below. @item elisp -The block created by the Emacs list client. The format is completely +The block created by the Emacs list client. The format is completely undocumented, but you'll need a lisp reader to parse it. @item WWW-kom The block created by the web gateway WWW-kom. It has the same syntax as @@ -8716,20 +8711,20 @@ what you name your client's block. @section The Common Block -This defines the theoretical structure of the common block. The real +This defines the theoretical structure of the common block. The real world probably does not agree entirely with this, and it is likely to -change just as soon as I have time to define something better. In the +change just as soon as I have time to define something better. In the mean while you're probably better off ignoring the common block and -storing all your settings in a client block. The Emacs lisp client uses +storing all your settings in a client block. The Emacs lisp client uses the common block, but I have a feeling that it might store data that -other clients can't read. - -The common block contains a list of variable settings. Each variable -setting consists of a name, some whitespace, and a value. Settings are -separated by a line feed character. As of protocol version 10, values -can be integers, strings, booleans or lists. The encoding is such that a -value is encoded as a single protocol A token. That means that strings -and lists are both encoded as HOLLERITHs. The reason for this is to +other clients can't read. + +The common block contains a list of variable settings. Each variable +setting consists of a name, some whitespace, and a value. Settings are +separated by a line feed character. As of protocol version 10, values +can be integers, strings, booleans or lists. The encoding is such that a +value is encoded as a single protocol A token. That means that strings +and lists are both encoded as HOLLERITHs. The reason for this is to simplify for clients that need to ignore the value, and so it is possible to add new value types without confusing old clients (new types will be encoded as HOLLERITHs.) @@ -8756,35 +8751,35 @@ elems : elems value Currently the following variables are used, but more may be added, and as of protocol version 10, clients should be able to cope with variables they know nothing of in the common block, as long as they are of one of -the types above. Pre-protocol version 10 clients can't deal with +the types above. Pre-protocol version 10 clients can't deal with HOLLERITHs in the common block. As of protocol 10 the following variables are stored in the common -block: +block: @table @code @item created-texts-are-read True if the user wants texts s/he creates to be marked as read -automatically. Boolean. +automatically. Boolean. @item dashed-lines True if the user wants dashed lines around the text body when it's -displayed. Boolean. +displayed. Boolean. @item presence-messages True if the user wants messages about people logging in and logging out -of LysKOM. Boolean. +of LysKOM. Boolean. @item print-number-of-unread-on-entrance True if the user wants to see the number of unread texts when entering a -conference. Boolean. +conference. Boolean. @item read-depth-first -True if the user wants to read text in depth-first order. Boolean. +True if the user wants to read text in depth-first order. Boolean. @item reading-puts-comments-in-pointers-last True if the user wants the client to display comment links after the -text body. Boolean. +text body. Boolean. @item confirm-multiple-recipients True if the user wants the client to ask for confirmation before sending @@ -8803,7 +8798,7 @@ The default mark to set on marked texts. @appendix 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. +it contains some information that may be useful for client writers. @menu * Common Commands:: Common commands and how they're implemented. @@ -8813,7 +8808,7 @@ it contains some information that may be useful for client writers. @node Common Commands @section Common Commands -Most clients will implement certain commands. This main purpose of this +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. @@ -8827,16 +8822,16 @@ to answer some questions that seem to come up over and over again. @subsection What do I have unread Each person has a membership list containing the conferences the person -is a member of. Each element is an object of type Membership. Among +is a member of. Each element is an object of type Membership. Among other things it contains the number of the conference, the priority of the membership, when the person most recently marked a text as read in the conference, and which texts the person has read. The list of read texts consists of two parts: a local text number called @field{last-text-read} and a list of local text numbers called -@field{read-texts}. The person has marked all texts up to and including +@field{read-texts}. The person has marked all texts up to and including @field{last-text-read} as read, and also the texts listed in -@field{read-texts}. All other texts in the conference are unread. Clients +@field{read-texts}. All other texts in the conference are unread. Clients can use either the @req{query-read-texts} or @req{get-membership} calls to get membership data. @@ -8844,39 +8839,39 @@ The standard procedure for finding out which texts are unread is the following: @enumerate -@item Call @req{get-unread-confs} for the person. +@item Call @req{get-unread-confs} for the person. This returns a list of conferences in which the person may have unread -texts. This call may return conferences that do not contain any unread -texts, but it will never forget to return a conference that does contain +texts. This call may return conferences that do not contain any unread +texts, but it will never forget to return a conference that does contain an unread text. -@item Call @req{query-read-texts} for each conference returned in -the previous step. This will return the membership data for all the +@item Call @req{query-read-texts} for each conference returned in +the previous step. This will return the membership data for all the conferences that may contain unread texts. @item Call @req{get-uconf-stat} for each conference returned in -the first step. The conference status will be needed shortly. Repeat the +the first step. The conference status will be needed shortly. Repeat the following steps for each conference. @item Compare the highest existing local number in the conference (from the conference status) with the @field{last-text-read} field for the -corresponding membership. If the highest existing local text is higher +corresponding membership. If the highest existing local text is higher than @field{last-text-read}, the conference may contain unread texts. @item Get part of the local to global map from the conference starting at @field{last-text-read} and ending at the highest existing local -number. Every local number in the map that is not read according to the +number. Every local number in the map that is not read according to the membership data and that has a mapping to a global number is an unread -text. You might say that you remove the read texts from the map to get +text. You might say that you remove the read texts from the map to get the unread texts. @end enumerate -Take care not to call get-map or get-membership too much since they tend -to be expensive operations. Use @req{get-unread-confs} and -@req{query-read-texts} to minimize the work. Another point to remember +Take care not to call get-map or get-membership too much since they tend +to be expensive operations. Use @req{get-unread-confs} and +@req{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. +about new texts. Clients need to listen to these messages. @@ -8891,7 +8886,7 @@ about new texts. Clients need to listen to these messages. @section Client Conventions There are certain conventions that most clients follow, and that users -expect. These are not part of the protocol and are subject to change. In +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. @@ -8906,7 +8901,7 @@ will go away when the protocol is updated to correct these deficiencies. @subsection Text formatting Traditionally the only clients for LysKOM were text-based and only -displayed texts exactly as they were stored in the server. Although +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. @@ -8933,12 +8928,12 @@ The same conventions apply to messages sent with the @node Content type specification @subsection Content type specification -This convention is understood by all popular clients. If the first line +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 +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 +Starting with protocol version 10, this ugly workaround is obsolete. Use aux-items to specify content type instead. @@ -8947,7 +8942,7 @@ aux-items to specify content type instead. @subsection Remote control This convention is only implemented by the Emacs-Lisp client, but since -I work on that client, I'm free to write about it. This is a subprotocol +I work on that client, I'm free to write about it. This is a subprotocol between clients, transferred by messages sent using @reqlink{send-message}. @@ -8956,13 +8951,13 @@ between clients, transferred by messages sent using @appendix 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 +first LysKOM server became operational. Protocol version 10 introduces a lot of aux-items, a large part of which are intented for use by mail -importers to enhance the functionality. As of this moment, there is one +importers to enhance the functionality. As of this moment, there is one mail importer (@command{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 +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. @@ -8970,44 +8965,44 @@ her experiences. 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 +threading. During this, it creates one or more texts and a lot of aux-items. @subsection Recipients Although a mail message contains @code{To} and @code{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, +not the header recipients, that should be used. To understand this, consider a mail where the @code{To} header contains a personal mail -address. The mail is received using a tool like @command{procmail} and -forwarded to the LysKOM importer. The envelope address will be correct, +address. The mail is received using a tool like @command{procmail} and +forwarded to the LysKOM importer. The envelope address will be correct, but the @code{To} header will still contain the personal address. The @command{komimportmail} importer uses addresses like ``@var{number}@@@var{server}'', where @var{number} is the number of the recipient and @var{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, +importer. For backwards compatibility with earlier importers, it is +allowed to prepend a ``p'' before the number. Instead of the number, @command{komimportmail} can accept a name, as long as the name can be -resolved to exactly one conference or letterbox. Before looking up the +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, +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 @code{john.q.public@@example.com} and -@code{sven.svensson@@exempel.se}. Two different mail servers handle the +@code{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 +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 @code{Message-ID} to LysKOM text number for imported messages. If a -message is seen more than once, the message is not imported. Instead, +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 @code{Message-ID} of an interesting imported mail can add -himself or some open conference as a recipient. Perhaps the importer +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 @@ -9016,17 +9011,17 @@ that do not allow messages, even though the server might not complain. 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 @command{komimportmail} importer +conferences. A potential problem is that this leaks secret information +from the server. For the time being, the @command{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. @subsection Threading -The importer should do its best to thread messages. When the importer +The importer should do its best to thread messages. When the importer sees a new message it needs to look at the @code{In-Reply-To} header to -see what the message is a reply to. If the @code{In-Reply-To} header +see what the message is a reply to. If the @code{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 @code{References} header may be used instead. @@ -9036,14 +9031,14 @@ 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 +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 +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 @@ -9053,16 +9048,16 @@ become comments to the message when it is imported. @subsection MIME issues An importer should try to handle e-mail messages containing MIME -appendices as smart as possible. As the current LysKOM model lacks +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 +structure to a corresponding LysKOM comment tree. However, this would require creating empty interior nodes to attach some comments to. Therefore, the @command{komimportmail} importer currently uses a rather -naive algorithm: All leaf parts are found. The first one gets to be the +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. @@ -9087,7 +9082,7 @@ 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. -@item +@item The information contained in the @type{Misc-Info} array should be integrated into the @type{Text-Stat}. There should be one array of recipients, one of texts that comments this text, and so on. This @@ -9278,14 +9273,14 @@ use 80=accept-async to listen to 15=async-new-text instead. @item Notes @itemize @bullet @item Since protocol version 9 setting a priority of zero for a -conference was supposed to indicate passive membership in a conference. -It was largely up to the client to implement this. True passive +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 +Membership-type extension to the Membership type. In order to maintain compatibility with clients that interpret priority 0 as passive membership, the old calls @reqlink{add-member-old} and -@reqlink{get-membership-old} perform magic, translating between priorities -and membership types. The magic is documented with each call. +@reqlink{get-membership-old} perform magic, translating between priorities +and membership types. The magic is documented with each call. @end itemize @end table @@ -9475,8 +9470,8 @@ Some typos and other minor errors were fixed. Distributed with lyskomd 2.0.2. @item 10.1: 1999-07-12 -Call @req{sub-comment} was incorrectly marked obsolete. This has been -corrected. Regexps are case sensitive. The Info-Type enumeration was +Call @req{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 @req{add-recipient}, @async{async-new-recipient} and @async{async-sub-recipient}.) Distributed @@ -9496,13 +9491,13 @@ Protocol version 9. Distributed with lyskomd 1.9.0. Protocol version 8. Distributed with lyskomd 1.8.0. @item 7.1: 1995-01-08. -Protocol and document revision history were added by Per Cederqvist. Outline -mode was used to make the document more manageable. This version was +Protocol and document revision history were added by Per Cederqvist. Outline +mode was used to make the document more manageable. This version was distributed with lyskomd 1.7.1. @item 7.0: 1994-12-31. -The first specification with a version number. All calls that had been added -since 1991-06-25 were documented. Pell and Per Cederqvist did the deed. This +The first specification with a version number. All calls that had been added +since 1991-06-25 were documented. Pell and Per Cederqvist did the deed. This version was distributed with lyskomd 1.7.0. @item 1993-05-19. @@ -9524,3 +9519,8 @@ Lars Aronsson documented the protocol that was in use at the time. @printindex fn @bye + +Local Variables: +sentence-end: "[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*" +sentence-end-double-space: t +End: