Commit 5647cba9 authored by Per Cederqvist's avatar Per Cederqvist

(Protocol Version History): Moved to a separate appendix.

parent 6c0a304d
......@@ -8,7 +8,7 @@
@c FIXME: Check for too much text before @menu.
@c FIXME: error-reply defined twice (conflicting).
@c
@c $Id: Protocol-A.texi,v 1.127 2001/05/01 16:16:36 ceder Exp $
@c $Id: Protocol-A.texi,v 1.128 2001/05/01 16:21:27 ceder Exp $
@c %**start of header
@setfilename protocol-a.info
@settitle LysKOM Protocol A
......@@ -411,302 +411,6 @@ The LysKOM developers can be reached by email to
* Notation::
@end menu
@node Protocol Version History
@section Protocol Version History
@subsection Protocol version 10 (first implemented in lyskomd 2.0.0)
@table @asis
@item Error codes
The error codes are now documented. Several error codes were changed to
more sane values while documenting the new behaviour.
@item New Server Calls
These new calls have status Recommended.
@itemize @bullet
@item 85=get-collate-table
@item 86=create-text
@item 87=create-anonymous-text
@item 88=create-conf
@item 89=create-person
@item 90=get-text-stat
@item 91=get-conf-stat
@item 92=modify-text-info
@item 93=modify-conf-info
@item 94=get-info
@item 95=modify-system-info
@item 96=query-predefined-aux-items
@item 98=query-read-texts
@item 99=get-membership
@item 100=add-member
@item 101=get-members
@item 102=set-membership-type
@item 103=local-to-global
@item 104=map-created-texts
@item 106=set-pers-flags
@end itemize
These new calls have status Experimental.
@itemize @bullet
@item 97=set-expire
@item 105=set-keep-commented
@end itemize
@item Name changes
@multitable {59=create-anonymous-text} {59=create-anonymous-text-old}
@item Old name @tab New name
@item 5=create-person @tab 5=create-person-old
@item 9=query-read-texts @tab 9=query-read-texts-old
@item 10=create-conf @tab 10=create-conf-old
@item 13=get-conf-stat-old @tab 13=get-conf-stat-older
@item 14=add-member @tab 14=add-member-old
@item 26=get-text-stat @tab 26=get-text-stat-old
@item 28=create-text @tab 28=create-text-old
@item 36=get-info @tab 36=get-info-old
@item 46=get-membership @tab 46=get-membership-old
@item 48=get-members @tab 48=get-members-old
@item 50=get-conf-stat @tab 50=get-conf-stat-old
@item 59=create-anonymous-text @tab 59=create-anonymous-text-old
@end multitable
@item Status change
The following calls have change status from Experimental to Recommended.
@itemize @bullet
@item 58=get-last-text
@item 77=set-last-read
@item 78=get-uconf-stat
@end itemize
The following calls have changed status from Recommended or
Experimental to Obsolete.
@itemize @bullet
@item 5=create-person-old
@item 9=query-read-texts-old
@item 10=create-conf-old
@item 14=add-member-old
@item 26=get-text-stat-old
@item 28=create-text-old
@item 36=get-info-old
@item 46=get-membership-old
@item 47=get-created-texts
@item 48=get-members-old
@item 50=get-conf-stat-old
@item 59=create-anonymous-text-old
@end itemize
@item New and Modified Structures
@itemize @bullet
@item Aux-Item
@item Aux-Item-Input
@item Conference
@item Info
@item Member
@item Membership
@item Membership-Type
@item Misc-Info
@item Text-Stat
@end itemize
@item Renamed Asynchronous Messages
A @samp{async-} prefix has been added to the name of all asynchronous
messages. In addition, 0=new-text has been renamed to
0=async-new-text-old, and it is now considered obsolete. Clients should
use 80=accept-async to listen to 15=async-new-text instead.
@item New Asynchronous Messages
@itemize @bullet
@item 14=async-deleted-text
@item 15=async-new-text
@item 16=async-new-recipient
@item 17=async-sub-recipient
@item 18=async-new-membership
@end itemize
@item Notes
@itemize @bullet
@item Since protocol version 9 setting a priority of zero for a
conference was supposed to indicate passive membership in a conference.
It was largely up to the client to implement this. True passive
memberships have been introduced in this protocol version through the
Membership-type extension to the Membership type. In order to maintain
compatibility with clients that interpret priority 0 as passive
membership, the old calls @reqlink{add-member-old} and
@reqlink{get-membership-old} perform magic, translating between priorities
and membership types. The magic is documented with each call.
@end itemize
@end table
@subsection Protocol version 9 (first implemented in lyskomd 1.9.0)
@table @asis
@item New functionality
@itemize @bullet
@item The server shall now reply with error @errorcode{not-implemented} when
a client attempts to use an unimplemented call. This feature requires
that the client uses newline as call terminator.
@end itemize
@item Added Commands
@itemize @bullet
@item 79=set-info: Can change server information.
@item 80=accept-async: Can select asynchronous messages to receive.
@item 81=query-async: Can query which messages are being send.
@item 82=user-active
@item 83=who-is-on-dynamic
@item 84=get-static-session-info
@end itemize
@item Changed names
@itemize @bullet
@item @req{change-conference} was previously called @code{pepsi}. The
name was changed, but not the functionality.
@end itemize
@item Status change
@itemize @bullet
@item 63=@req{who-is-on-ident} is now considered obsolete.
@item 64=@req{get-session-info-ident} is now considered obsolete.
@end itemize
@end table
@subsection Protocol version 8 (first implemented in lyskomd 1.8.0)
@table @asis
@item Added Functionality
@itemize @bullet
@item
30=add-recipient: Can change @misc{recpt} to @misc{cc-recpt} and vice versa.
@item
21=set-conf-type: Accepts @type{Conf-Type} and @type{Extended-Conf-Type}.
@item
10=create-conf: Accepts @type{Conf-Type} and @type{Extended-Conf-Type}.
@end itemize
@item New Commands
@itemize @bullet
@item
77=set-last-read
@item
78=get-uconf-stat
@end itemize
@end table
@subsection Protocol version 7 (first implemented in lyskomd 1.7.0)
@table @asis
@item Added Functionality
@itemize @bullet
@item
53=send-message: Recipient can be a conference or a person.
@end itemize
@item New Commands
@itemize @bullet
@item
74=re-z-lookup
@item
75=get-version-info
@item
76=lookup-z-name
@end itemize
@item Other
@itemize @bullet
@item
The asynchronous message 1=i-am-off has been removed
@end itemize
@end table
@subsection Protocol Version 6 (first implemented in lyskomd 1.4.0)
@table @asis
@item New Calls
@itemize @bullet
@item
67=lookup-person
@item
68=lookup-conf
@item
69=set-client-version
@item
70=get-client-name
@item
71=get-client-version
@item
72=mark-text
@item
73=unmark-text
@end itemize
@end table
@subsection Protocol Version 5 (first implemented in lyskomd 1.3.0)
@table @asis
@item New Calls
@itemize @bullet
@item
65=re-lookup-person
@item
66=re-lookup-conf
@end itemize
@end table
@subsection Protocol Version 4 (first implemented in lyskomd 1.1.1)
@table @asis
@item New Calls
@itemize @bullet
@item
62=login
@item
63=who-is-on-ident
@item
64=get-session-info-ident
@end itemize
@end table
@subsection Protocol Version 3 (first implemented in lyskomd 1.1.0)
@table @asis
@item New Calls
@itemize @bullet
@item
61=find-previous-text-no
@item
60=find-next-text-no
@item
59=create-anonymous-text
@item
58=get-last-text
@end itemize
@end table
@subsection Protocol Version 2 (first implemented in lyskomd 0.30.0)
@table @asis
@item New Calls
@itemize @bullet
@item
57=set-user-area
@end itemize
@end table
@subsection Protocol Version 1 (first implemented in lyskomd 0.29.2)
@table @asis
@item New Calls
All calls from 0--56.
@end table
@node Notation
@section Notation
......@@ -9152,123 +8856,420 @@ between clients, transferred by messages sent using
@reqlink{send-message}.
@node Importing and Exporting E-Mail
@chapter Importing and Exporting E-Mail
@node Importing and Exporting E-Mail
@chapter Importing and Exporting E-Mail
E-mail import has been implemented using various programs since the
first LysKOM server became operational. Protocol version 10 introduces a
lot of aux-items, a large part of which are intented for use by mail
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
and implement an exporter gets to rewrite this chapter based on his or
her experiences.
@section Importing e-mail
The main job of the mail importer is to figure out where to deliver
mail, how to handle MIME coding and/or structure and how to deal with
threading. During this, it creates one or more texts and a lot of
aux-items.
@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,
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,
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,
@command{komimportmail} can accept a name, as long as the name can be
resolved to exactly one conference or letterbox. Before looking up the
name, any underscore or period is translated into a space.
Care should be taken when a mail is received more than once. This can
happen if a mail is addressed to more than one address. For example,
assume that a mail is sent to @code{john.q.public@@example.com} and
@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
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,
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
should check for matching contents before adding recipients.
The importer needs to be careful not to deliver messages to conferences
that do not allow messages, even though the server might not complain.
@c FIXME: Please elaborate on that...
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
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
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
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.
If the Message-ID of a previously imported e-mail is found, the new text
should be made a comment of the replied-to text.
This means that the importer will probably have to maintain its own
database of imported texts that maps the message ID to the text number
in the LysKOM database. There is no other way to find the text number
for a particular imported text. Fortunately, this is exactly the same
database we need to solve the multiple reception problem described
above.
It has been noted that messages on some mailing lists arrive in peculiar
order, with replies before the original messages. Perhaps this is due to
moderation. A smart importer should be prepared to handle this, by
adding a comment link when the original message eventually arrives.
One possible solution is to add a new kind of entry to the Message-ID
database, mapping a Message-ID to a list of text numbers that should
become comments to the message when it is imported.
@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
hierarchical structuring inside articles, appendices should probably be
imported as comments or footnotes to the main message.
One would think that it is easy to convert the hierarchical MIME
structure to a corresponding LysKOM comment tree. However, this would
require creating empty interior nodes to attach some comments to.
Therefore, the @command{komimportmail} importer currently uses a rather
naive algorithm: All leaf parts are found. The first one gets to be the
main text, and the rest are included as comments to it.
Appendices encoded with Base64 or Quoted-Printable should be decoded.
When creating aux-items like @aux{mx-author}, text coded using the
method in RFC 2047 should be decoded.
@node Protocol Version History
@section Protocol Version History
@subsection Protocol version 10 (first implemented in lyskomd 2.0.0)
@table @asis
@item Error codes
The error codes are now documented. Several error codes were changed to
more sane values while documenting the new behaviour.
@item New Server Calls
These new calls have status Recommended.
@itemize @bullet
@item 85=get-collate-table
@item 86=create-text
@item 87=create-anonymous-text
@item 88=create-conf
@item 89=create-person
@item 90=get-text-stat
@item 91=get-conf-stat
@item 92=modify-text-info
@item 93=modify-conf-info
@item 94=get-info
@item 95=modify-system-info
@item 96=query-predefined-aux-items
@item 98=query-read-texts
@item 99=get-membership
@item 100=add-member
@item 101=get-members
@item 102=set-membership-type
@item 103=local-to-global
@item 104=map-created-texts
@item 106=set-pers-flags
@end itemize
These new calls have status Experimental.
@itemize @bullet
@item 97=set-expire
@item 105=set-keep-commented
@end itemize
@item Name changes
@multitable {59=create-anonymous-text} {59=create-anonymous-text-old}
@item Old name @tab New name
@item 5=create-person @tab 5=create-person-old
@item 9=query-read-texts @tab 9=query-read-texts-old
@item 10=create-conf @tab 10=create-conf-old
@item 13=get-conf-stat-old @tab 13=get-conf-stat-older
@item 14=add-member @tab 14=add-member-old
@item 26=get-text-stat @tab 26=get-text-stat-old
@item 28=create-text @tab 28=create-text-old
@item 36=get-info @tab 36=get-info-old
@item 46=get-membership @tab 46=get-membership-old
@item 48=get-members @tab 48=get-members-old
@item 50=get-conf-stat @tab 50=get-conf-stat-old
@item 59=create-anonymous-text @tab 59=create-anonymous-text-old
@end multitable
@item Status change
The following calls have change status from Experimental to Recommended.
@itemize @bullet
@item 58=get-last-text
@item 77=set-last-read
@item 78=get-uconf-stat
@end itemize
The following calls have changed status from Recommended or
Experimental to Obsolete.
@itemize @bullet
@item 5=create-person-old
@item 9=query-read-texts-old
@item 10=create-conf-old
@item 14=add-member-old
@item 26=get-text-stat-old
@item 28=create-text-old
@item 36=get-info-old
@item 46=get-membership-old
@item 47=get-created-texts
@item 48=get-members-old
@item 50=get-conf-stat-old
@item 59=create-anonymous-text-old
@end itemize
@item New and Modified Structures
@itemize @bullet
@item Aux-Item
@item Aux-Item-Input
@item Conference
@item Info
@item Member
@item Membership
@item Membership-Type
@item Misc-Info
@item Text-Stat
@end itemize
@item Renamed Asynchronous Messages
A @samp{async-} prefix has been added to the name of all asynchronous
messages. In addition, 0=new-text has been renamed to
0=async-new-text-old, and it is now considered obsolete. Clients should
use 80=accept-async to listen to 15=async-new-text instead.
@item New Asynchronous Messages
@itemize @bullet
@item 14=async-deleted-text
@item 15=async-new-text
@item 16=async-new-recipient
@item 17=async-sub-recipient
@item 18=async-new-membership
@end itemize
@item Notes
@itemize @bullet
@item Since protocol version 9 setting a priority of zero for a
conference was supposed to indicate passive membership in a conference.
It was largely up to the client to implement this. True passive
memberships have been introduced in this protocol version through the
Membership-type extension to the Membership type. In order to maintain
compatibility with clients that interpret priority 0 as passive
membership, the old calls @reqlink{add-member-old} and
@reqlink{get-membership-old} perform magic, translating between priorities
and membership types. The magic is documented with each call.
@end itemize
@end table
E-mail import has been implemented using various programs since the
first LysKOM server became operational. Protocol version 10 introduces a
lot of aux-items, a large part of which are intented for use by mail
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
and implement an exporter gets to rewrite this chapter based on his or
her experiences.
@subsection Protocol version 9 (first implemented in lyskomd 1.9.0)
@section Importing e-mail
@table @asis
@item New functionality
@itemize @bullet
@item The server shall now reply with error @errorcode{not-implemented} when
a client attempts to use an unimplemented call. This feature requires
that the client uses newline as call terminator.
@end itemize
@item Added Commands
@itemize @bullet
@item 79=set-info: Can change server information.
@item 80=accept-async: Can select asynchronous messages to receive.
@item 81=query-async: Can query which messages are being send.
@item 82=user-active
@item 83=who-is-on-dynamic
@item 84=get-static-session-info
@end itemize
@item Changed names
@itemize @bullet
@item @req{change-conference} was previously called @code{pepsi}. The
name was changed, but not the functionality.
@end itemize
@item Status change
@itemize @bullet
@item 63=@req{who-is-on-ident} is now considered obsolete.
@item 64=@req{get-session-info-ident} is now considered obsolete.
@end itemize
@end table
The main job of the mail importer is to figure out where to deliver
mail, how to handle MIME coding and/or structure and how to deal with
threading. During this, it creates one or more texts and a lot of
aux-items.
@subsection Protocol version 8 (first implemented in lyskomd 1.8.0)
@subsection Recipients
@table @asis
@item Added Functionality
@itemize @bullet
@item
30=add-recipient: Can change @misc{recpt} to @misc{cc-recpt} and vice versa.
@item
21=set-conf-type: Accepts @type{Conf-Type} and @type{Extended-Conf-Type}.
@item
10=create-conf: Accepts @type{Conf-Type} and @type{Extended-Conf-Type}.
@end itemize
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,
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,
but the @code{To} header will still contain the personal address.
@item New Commands
@itemize @bullet
@item
77=set-last-read
@item
78=get-uconf-stat
@end itemize
@end table
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,
@command{komimportmail} can accept a name, as long as the name can be
resolved to exactly one conference or letterbox. Before looking up the
name, any underscore or period is translated into a space.
@subsection Protocol version 7 (first implemented in lyskomd 1.7.0)
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
two recipients, but both eventually decide to forward the mail to the
LysKOM importer (but for different conferences). The LysKOM importer
will receive the mail twice, with different envelope recipients.
@table @asis
@item Added Functionality
@itemize @bullet
@item
53=send-message: Recipient can be a conference or a person.
@end itemize
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,
recipients are added to the existing text.
@item New Commands
@itemize @bullet
@item
74=re-z-lookup
@item
75=get-version-info
@item
76=lookup-z-name
@end itemize