Commit 873f2ef9 authored by David Byers's avatar David Byers

More hacking notes. Content tables. mail import/export

parent 0264aa6e
......@@ -2,7 +2,7 @@
@c
@c FIXME: Explain how the garb works with nice and keep-commented
@c
@c $Id: Protocol-A.texi,v 1.49 1999/01/13 12:00:13 byers Exp $
@c $Id: Protocol-A.texi,v 1.50 1999/01/14 11:47:32 byers Exp $
@c %**start of header
@setfilename protocol-a.info
@settitle LysKOM Protocol A
......@@ -620,7 +620,7 @@ A BCC recipient group is only visible to members and supervisors of the
recipient. This is enforced by the server.
This type of group was introduced in protocol version 10. When
old-style calls such as @code{@xref{get-text-stat-old}} are used this
old-style calls such as @xref{get-text-stat-old} are used this
will be converted to a CC recipient group by the server for the benefit
of clients that don't understand this group.
......@@ -928,77 +928,82 @@ The data should be the client name, a space, and the client version used
in the @code{set-client-version} call. The server may enforce this
restriction.
@item x-author [16] (text)
@item mx-author [16] (text)
For imported texts using email gateway. Data is a string with
the (readable) name of the author.
Data is a string containing the name of the author of an imported
e-mail. Clients should display this instead of the actual author of the
text, which will be an importer ID.
Kom clients should show this field instead of the id of the importing kom-id.
@item x-from [17] (text)
@item mx-from [17] (text)
Data is a plain email addres, the From: field from an imported email.
Used by the kom client to construct an email reply to an imported text.
Data is the e-mail address extracted from the @code{From} header of an
imported e-mail. This field can be used by clients to construct an
address for personal (e-mail) replies to an imported message.
@item x-reply-to [18] (text)
Data is a plain email addres, comes from the Reply-To: field in the
imported email.
@item mx-reply-to [18] (text)
@item x-to [19] (text)
Data is the e-mail address extracted from the @code{Reply-To} header of
an imported e-mail. Clients should use this for constructing replies to
imported messages.
Data is one email address can be in variable format. Multiple x-to
can be present. The format is the same as is allowed in To: fields in
emails. If the text is imported these are the other receivers as seen in
the email. If the text originates from a kom-person (and thus not an
importer) this field is used in constructing an email, if an exporter
is present.
@item x-cc [20] (text)
@item mx-to [19] (text)
Data in the same format as for "x-to", usage the same but will
be a carbon copy instead when exported.
Data is a single e-mail address, and must be valid as the contents of an
e-mail @code{To} header. Multiple @code{mx-o} items may be present. For
imported messages, these items contain the @code{To} header of the
messages.
@item x-date [21] (text)
On messages created by a LysKOM person, the @code{mx-to} items are used
by the exporter to determine that the message is to be exported and
where to send it.
Data is the send-date of an imported email. Can be in free format, even
if a readable format, such as "YYYY-MM-DD hh:mm:ss", is preferred. Kom
client should display this date as originating date, date of the
imported text entity in kom may be different (and can be shown as
received). In case of the text being exported from kom, this date is set
by the exporter.
@item mx-cc [20] (text)
@item x-message-id [22] (text)
Same as @code{mx-to}, but applies to the @code{CC} header rather than
the @code{To} header.
Data is a string which is the message id from the imported email.
Message id does not contain the enclosing < >. Preferably the importer
should only add receivers when importing the same email more times with
the same msg-id. When a text is exported, the x-message-id is
constructed as an email address which contains the kom text number and
server in an unique way. (x-message-id is generally generated by the
exporter as follows. A kom text that is exported is copied to the
importer, the importer sets the fields in the originating kom text which
it normally would set when importing.) Preliminary, the format is
"Text-<textno>@@<lyskomserver>". Lyskom server takes the same format as
vaguely defined in aux-info pgp-public-key [12].
@item x-in-reply-to [23] (text)
@item mx-date [21] (text)
Data is a string which stores one "In-Reply-To:" msg id from the
email. If several msg ids are present all of them have one x-in-reply-to
each. The stored msg id has the same format as x-message-id. For each such
text a kom (comment) link should be created by the importer if these
referenced emails previously has been imported. Exporters must set this
for kom texts that are exported as emails, if the text is a
comment. Multiple x-in-reply-to can exist.
Data is the send data of an imported e-mail. Its format is "YYYY-MM-DD
hh:mm:ss TZ". YYYY is the year the message was sent, MM is the month, DD
is the day, hh is the hour, mm is the minute and ss is the second. This
date and time are given in the timezone where the message was sent. TZ
is the timezone the date is valid for. It must be of the form "+hhmm" or
"-hhmm", where hh is the number of hours offset from UTC and mm is the
number of minutes offset. Symbolic timezones are not permitted. The
timezone specification is recommended but optional, since it is not
always available.
@item x-misc [24] (text)
Clients should display this date as the date a text was written since
the imported text will have been created at a later date.
Data is a string that contains all of the headers (incl subject:),
including whose that are redundantly stored in other aux-items. It is
set by the importer. The fields are concatenated with "\n".
@item x-allow-filter [25] (conf)
@item mx-message-id [22] (text)
Data is the @code{Message-ID} header of an imported e-mail. This is used
by e-mail importers.
@item mx-in-reply-to [23] (text)
Data is a string containing one item from the @code{In-Reply-To} header
of an imported e-mail. If the @code{In-Reply-To} header contains several
items, there will be several @code{mx-in-reply-to} items.
@item mx-misc [24] (text)
Data is a string that contains all of the headers, including
@code{Subject}, and including whose that are redundantly stored in other
aux-items. It is set by the importer. The fields are concatenated with
"\n". In other words, this item contains all headers of an imported
e-mail as they appear in the message.
@item mx-allow-filter [25] (conference)
Data is a regexp string which allows a sender (a field in the
email-header) to import the message. If none is present, the text is
......@@ -1018,11 +1023,11 @@ However, if the string starts with a "!" the email will be rejected if
the there is a match (negative filter), even if one of the filter allowed it. Example:
"!From:*aol*", "!Subject:*money*".
@item x-reject-forward [26] (conf)
@item mx-reject-forward [26] (conference)
Data is a string with either an email name on the same format as
aux-info rediret [8]. The mail is forwarded to this address if it was
rejected by "x-import-filter".
rejected by "mx-import-filter".
@item notify-comments [27] (letterbox)
......@@ -1212,8 +1217,8 @@ in @code{read-texts} from the result
The process is complicated because of the translation between local and
global text numbers. If the server does not implement the
@code{@pxref{local-to-global}} call, it is possible to use the less
efficient but perfectly serviceable @code{@pxref{get-map}} call instead.
@pxref{local-to-global} call, it is possible to use the less
efficient but perfectly serviceable @pxref{get-map} call instead.
@node Client-Server Dialog, ,Membership and Reading , Introduction
......@@ -1247,7 +1252,8 @@ protocol-dependent. Protocol A servers will reply with the string
After connecting, calls to the server can be made. Most calls require
the user to log in, but some calls can be made without a log-in. Calls
to the server are made by sending a reference number followed by the
call as specified.
call as specified. The call @i{must} be terminated with a newline
character, but extra newlines @i{within} the call are permitted.
@example
server-call ::=
......@@ -7334,7 +7340,7 @@ person with admin bits set may get through even if the client has not
requests broadcast messages.
When a connection is opened some messages are selected by default.
Clients should use the @code{@ref{accept-async}} call to select which
Clients should use the @ref{accept-async} call to select which
messages they want. Servers are encouraged to preselect the
@code{new-text-old}, @code{new-name}, @code{sync-db}, @code{leave-conf},
@code{login}, @code{rejected-connection}, @code{send-message} and
......@@ -7355,7 +7361,7 @@ calls.
The messages with status "O" are included here for historical purposes
only. Servers are not required to handle them, and are encouraged to
reject them if a client uses it as an argument to
@code{@ref{accept-async}}.
@ref{accept-async}.
@menu
Message Name Status Description Number
......@@ -7486,8 +7492,8 @@ for the removal is.
Possible reasons include:
@itemize @bullet
@item The session issued a @code{@ref{sub-member}} call.
@item Some other session issued a @code{@ref{sub-member}} call.
@item The session issued a @ref{sub-member} call.
@item Some other session issued a @ref{sub-member} call.
@item The conference was deleted.
@item The person was deleted.
@end itemize
......@@ -8175,7 +8181,7 @@ aux-items to specify content type instead.
@node Remote control, Type Index, Content type specification, Client Conventions
@node Remote control, Importing and Exporting E-Mail, Content type specification, Client Conventions
This convention is only implemented by the Emacs-Lisp client, but since
I work on that client, I'm free to write about it. This is a subprotocol
......@@ -8183,6 +8189,178 @@ between clients, transferred by messages sent using
@pxref{send-message}.
@node Importing and Exporting E-Mail, TypeIndes, Writing Clients, Top
@chapter Importing and Exporting E-Mail
E-mail importing and exporting is not implemented. This chapter contains
suggestions for how to do it. The first person to implement a forwarder
should rewrite this section based on his or her experiences.
There are some holes in this description. For example, it was suggested
at some point that it might be possible to use inheritance for automatic
export of messages from conferences, so that people could more or less
participate in mailing lists but only use the LysKOM interface.
Importing and exporting will be implemented through a special client and
user. The client can log on periodically and check if any new texts have
been created. It should store the last text number it examined, and use
the get-next-text call to find any new texts.
@section Exporting E-Mail
For each text the exporter examines, it has to check if the text needs
to be exported. A text will have to be exported if it has an
@code{mx-to} aux-item, if the text was not imported or if the item was
added after the text was imported.
The exportes is responsible for setting the @code{Date},
@code{Message-ID}, @code{From}, @code{Reply-To}, @code{To}, @code{CC}
and @code{In-Reply-To} fields in the exported message.
@table @code
@item Date
The date should be set to the date the text was created, not the date
the text was exported.
@item Message-ID
The message ID is to have the format ``T@i{textno}@@@i{server}'', where
@i{textno} is the text number in the server and @i{server} is the name
of the LysKOM server. This allows the importer to figure out how to
thread e-mail replies to exported messages.
@item From
If the message originates with the LysKOM server, the exporter
constructs a valid @code{From} address, that when replied to will cause
the importer to give the message the correct recipients.
If the message originates outside of the LysKOM server (it is imported),
the exporter uses the @code{mx-from} item to get the @code{From} header.
@item Reply-To
If the message originates with the LysKOM server and the author of the
text has a @code{redirect} aux-item set, the exporter should use it to
construct a @code{Reply-To} header.
If the message is imported to LysKOM, the exporter should use the
@code{mx-reply-to} item, if there is one, to construct this header.
@item To
@item CC
The @code{mx-to} and @code{mx-cc} aux-items contain the values for these
headers.
@item In-Reply-To
If the message is a comment to an impored message, the exporter is to
use the @code{mx-message-id} aux-item of the commented texts for the
@code{In-Reply-To} header. If the commented text is not imported, the
exporter is to construct a message ID for the commented text using the
same method as for the @code{Message-ID} header.
@end table
For the mail exporter to work, it will need special privileges.
@section Importing
The main job of the mail importer is to figure out where to deliver mail
and how to deal with threading. The importer can find the recipients in
the @code{To} and @code{CC} headers of the message. The current (very
simple) importer uses addresses like ``p@i{person}@@@i{server}´´, wherre
@i{person} is the number of the recipient and @i{server} is the LysKOM
server.
The importer should add recipients in the @code{CC} header as
carbon-copy-recipients, and recipients in the @code{To} header as
regular recipients. The importer needs to be careful to not deliver
messages to conferences that do not allow messages, even though the
server might not complain.
For mail delivery to work, the importer has to run as a privileged user,
or it would be unable to deliver mail to secret conferences. A potential
problem is that this leaks secret information from the server, so it
should probably be possible to configure on a per-conference basis
whether it accepts imported e-mail. This is currently not possible, but
can easily be implemented, should the implementor of the first good
importer want it.
@subsection Threading
The importer should do its best to thread messages. When the importer
sees a new message it needs to look at the @code{In-Reply-To} header to
see what the message is a reply to. If a previously imported message or
a LysKOM text is in the @code{In-Reply-To} header, the new text should
be made a comment to the replied-to text.
This means that the importer will probably have to maintain its own
database of imported texts that maps the message ID to the text number
in the LysKOM database. There is no other way to find the text number
for a particular imported text.
@section An Algorithm, Sort Of
Here's an outline for algorithms for import and export of messages.
They're hardly complete, and may not even quite work, but they should
give the general idea of how things can work.
@example
function import-message (message)
{
recipient_list = To header of message
cc_list = CC header of message
delete recipients from recipient_list that do not want imported mail
delete recipients from cc_list that do not want imported mail
for each element el in In-Reply-To header of message
if el is a LysKOM message ID
text_no = text number of el
if el is in the imported database
text_no = text number from database
if text_no is set
add text_no to comm_to
result = create_text with
recipients = recipient_list
cc-recipients = cc_list
comment-to = comm_to
aux-items extracted from header
if result is a failure, construct and send a bounce
put Message-ID and result into the imported database
}
function exporter ()
{
text_no = last_examined_text_no
while text_no = get-next-text
if (text text_no is not imported or
text text_no has an mx-to item created after the text)
message = get-text text_no
message-ID = text_no@@server
date = creation-date of message
to = mx-to item of text text_no
cc = mx-cc item of text text_no
add e-mail of LysKOM cc-recipients to text text_no to cc
if there is an mx-from item of text text_no
from = mx-from item of text text_no
else
mx-from = e-mail of author in LysKOM
send the message
}
@end example
@node Type Index, Request Index, Remote control, Top
@chapter Type Index
......@@ -8193,4 +8371,5 @@ between clients, transferred by messages sent using
@printindex fn
@contents
@bye
\input texinfo
@c $Id: hacking.texi,v 1.2 1999/01/13 12:00:17 byers Exp $
@c $Id: hacking.texi,v 1.3 1999/01/14 11:47:35 byers Exp $
@c %**start of header
@setfilename hacking.info
@settitle "Hacking lyskomd"
@settitle Hacking lyskomd
@setchapternewpage odd
@c %**end of header
......@@ -23,9 +23,9 @@ are preserved on all copies.
@titlepage
@sp 10
@title "Hacking lyskomd"
@title Hacking lyskomd
@sp 2
@subtitle "How to extend, modify and generally mess up lyskomd"
@subtitle How to extend, modify and generally mess up lyskomd
@sp 2
@author by the lyskomd developers
......@@ -60,6 +60,7 @@ another language under the same conditions as for modified versions.
* Adding Aux-Item Types::
* Modifying an Existing Stored Type::
* Notes::
* Traversing Connections::
@end menu
@end ifinfo
......@@ -202,7 +203,7 @@ void async_@i{something}(struct connection *cptr,
@node Adding Configuration Parameters to the Server, Adding a New Protocol Request, Adding Asynchronous Message, Top
@comment node-name, next, previous, up
@chapter
@chapter Adding Configuration Parameters to the Server
Make sure that you really understand what you want to configure. Think
it over again. Find a good, descriptive name for it.
......@@ -235,7 +236,9 @@ idea.
@item Declare the function in @code{include/services.h}
@item Declare the function @i{last} in @code{server/fncdef.txt}
@item Declare the function @i{last} in @code{server/fncdef.txt}. It
should be given a call number one higher than the currently existing
highest contiguous call number.
@item If the function takes a pn input parameter of a new type, changes
need to be made in several places. @xref{Adding New Input Types}.
......@@ -249,9 +252,6 @@ need to be made in several plaves. @xref{Adding New Result Types}.
@item Write the function in a suitable place in the server directory.
@item Add the function to @code{prot_a_is_legal_fnc} in
@code{server/prot-a.c}
@item Write tests for the new function in
@code{server/testsuite/lyskomd.0}. Write one file for testing the
functionality. Write tests in @code{01.exp} (behavior when the client is
......@@ -260,6 +260,9 @@ not logged on) and @code{03.exp} (normal behavior.)
@item Run the testsuite to make sure nothing old has been broken.
@end enumerate
It is no longer necessary to update prot_a_is_legal_fnc since it is
generated automatically.
@menu
* Adding New Input Types:: Procedure for adding input types.
......@@ -561,15 +564,16 @@ example, if version 0 and version 1 are the same, only write an
case 1.
@node Notes, , Modifying an Existing Stored Type, Top
@node Notes, Traversing Connections, Modifying an Existing Stored Type, Top
@comment node-name, next, previous, up
@chapter Notes
@menu
* Membership Notes::
* Notes for fncdef.txt::
@end menu
@node Membership Notes, , Notes, Notes
@node Membership Notes, Notes for fncdef.txt, Notes, Notes
@comment node-name, next, previous, up
@section Membership Notes
......@@ -577,6 +581,99 @@ The @code{position} field in the membership is @i{not} stored. It has to
be set every time a membership is requested for transmission to the
client.
@node Notes for fncdef.txt, , Membership Notes, Notes
@comment node-name, next, previous, up
@section Notes for fncdef.txt
The fncdef.txt file is used to define the RPC functions. Each line
consists of the call number, the return type of the call, the parameters
and the output types of the call.
Some examples:
@example
10 number create_conf_old c_string (param.conf_name_len) conf_type
12 success lookup_name c_string (param.conf_name_len) : conf_list
@end example
The first line defines a call named @code{create_conf_old} that takes
two arguments, a string that can only be as long as
@code{param.conf_name_len} and a @code{conf_type}. It returns a number
to the client. If the service call returns -1, the server will return an
error. The @code{create_conf_old} call has RPC number 10.
The second line defines a call named @code{lookup_name} that takes a
string argument that can be no longer than @code{param.conf_name_len},
and returns a @code{conf_list}. The service call returns a
@code{Success}. If it does not return @code{OK}, the server will return
an error. The @code{lookup_name} call has RPC number 12.
@subsection Scripts That Use fncdef.txt
The following scripts operate on @code{fncdef.txt}. If you make
modifications to the format of @code{fncdef.txt}, you have to update
these scripts.
@table @code
@item call-switch.awk
Generates @code{call-switch.incl}, which is included by
@code{connections.c}
@item com-h.awk
Generates @code{com.h}, which is included by several files.
@item fnc-def-init.awk
Generates @code{fnc-def-init.incl}, which is included by
@code{connections.c}.
@item prot-a-is-legal-fnc.awk
Generates @code{prot-a-is-legal-fnc.incl}, which is included by
@code{prot-a.c}
@item prot-a-parse-arg-c.awk
@item prot-a-parse-arg-h.awk
Generates @code{prot-a-parse-arg.c} and @code{prot-a-parse-arg.h}.
@end table
@node Traversing Connections, , Notes, Top
@comment node-name, next, previous, up
@chapter Traversing Connections
Since session 0 is interpreted as the currently active session by
get_conn_by_number it is important to be careful when traversing
sessions. Code like this does not work since it will do one iteration
through the loop with @code{sess} set to zero. This formerly caused
@code{get_conn_by_number} to return @code{NULL}, but now causes it to
return the session pointer for the current session.
@example
for (sess = 0; (sess = traverse_connections(sess)) != 0; )
{
cptr = get_conn_by_number(sess);
...
}
@end example
The canonical traversal code looks like this:
@example
Session_no session = 0;
while ((session = traverse_connections(session)) != 0)
{
cptr = get_conn_by_number(session);
...
}
@end example
This code has @code{session} set to a session number before ever
entering the loop.
@contents
@bye
\input texinfo
@c $Id: lyskomd.texi,v 1.2 1999/01/07 15:10:39 byers Exp $
@c $Id: lyskomd.texi,v 1.3 1999/01/14 11:47:36 byers Exp $
@c %**start of header
@setfilename lyskomd.info
@settitle "lyskomd Reference Manual"
@settitle lyskomd Reference Manual
@setchapternewpage odd
@c %**end of header
......@@ -23,9 +23,9 @@ are preserved on all copies.
@titlepage
@sp 10
@title "lyskomd Reference Manual"
@title lyskomd Reference Manual
@sp 2
@subtitle "Server version 2.0"
@subtitle Server version 2.0
@sp 2
@author by the lyskomd developers
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment