Commit ad839790 authored by David Byers's avatar David Byers
Browse files

(Aux-Item Types): Document letterbox, text

	and other type parameters of aux-item definitions (bug 9).
(Person Status Types, Who Information, Session Information):
	Improved documentation of the username field (bug 196).
(add-member): Fixed documentation of error codes (bug 199).
(async-i-am-on): Fixed error in the message description (bug 200).
(Importing and Exporting E-Mail): Improved documentation on what
	aux-items affect importers (bug 201)
parent 5b97bce4
...@@ -2272,8 +2272,14 @@ The fields of @type{Person} are ...@@ -2272,8 +2272,14 @@ The fields of @type{Person} are
@table @field @table @field
@item username @item username
The name of the user. The identity of the user from which the person most recently
@c FIXME (bug 196): this is wrong/needs explanation/should be renamed. connected, currently
@samp{@t{remote-user}(@t{ident-user})@@@t{remote-host}}. @t{remote-user}
is the string sent during the initial handshake (@pxref{Connecting to
the Server}; @t{ident-user} is the user identy derived from the IDENT
protocol; @t{remote-host} is the name or address of the connecting
host. Note that ident-user may be missing (including the surrounding
parentheses) or set to an arbitrary string.
@item privileges @item privileges
The privileges of the person. The privileges of the person.
@item flags @item flags
...@@ -2721,9 +2727,14 @@ The person's session number. ...@@ -2721,9 +2727,14 @@ The person's session number.
@item what-am-i-doing @item what-am-i-doing
A client-supplied string saying what the person is doing. A client-supplied string saying what the person is doing.
@item username @item username
The name of the ``real'' user constructed from @field{hostname} and The identity of the user from which the session is connected,
@field{ident-user} (see below) and information from the client. currently
@c FIXME (bug 196): define the format @samp{@t{remote-user}(@t{ident-user})@@@t{remote-host}}. @t{remote-user}
is the string sent during the initial handshake (@pxref{Connecting to
the Server}; @t{ident-user} is the user identy derived from the IDENT
protocol; @t{remote-host} is the name or address of the connecting
host. Note that ident-user may be missing (including the surrounding
parentheses) or set to an arbitrary string.
@end table @end table
...@@ -2739,9 +2750,7 @@ The person's session number. ...@@ -2739,9 +2750,7 @@ The person's session number.
@item what-am-i-doing @item what-am-i-doing
A client-supplied string saying what the person is doing. A client-supplied string saying what the person is doing.
@item username @item username
The name of the ``real'' user constructed from @field{hostname} and See the @field{username} field in @type{Who-Info} above.
@field{ident-user}.
@c FIXME (bug 196): define the format
@item hostname @item hostname
The host the connection originated at. The host the connection originated at.
@item ident-user @item ident-user
...@@ -2842,7 +2851,7 @@ The number of this session. ...@@ -2842,7 +2851,7 @@ The number of this session.
@item what-am-i-doing @item what-am-i-doing
A client-supplied string saying what the person is currently doing. A client-supplied string saying what the person is currently doing.
@item username @item username
The name of the ``real'' user (see @type{Who-Info} above.) See the @field{username} field in @type{Who-Info} above.
@item idle-time @item idle-time
The number of seconds since @reqdlink{user-active} was used by this The number of seconds since @reqdlink{user-active} was used by this
session@linkhere{}, or since the session was created if session@linkhere{}, or since the session was created if
...@@ -2864,7 +2873,7 @@ The number of this session. ...@@ -2864,7 +2873,7 @@ The number of this session.
@item what-am-i-doing @item what-am-i-doing
A client-supplied string saying what the person is currently doing. A client-supplied string saying what the person is currently doing.
@item username @item username
The name of the ``real'' user (see @type{Who-Info-Ident} above.) See the @field{username} field in @type{Who-Info} above.
@item hostname @item hostname
The host the connection originated at. The host the connection originated at.
@item ident-user @item ident-user
...@@ -2885,7 +2894,7 @@ The fields of @type{Static-Session-Info} are ...@@ -2885,7 +2894,7 @@ The fields of @type{Static-Session-Info} are
@table @field @table @field
@item username @item username
The name of the ``real'' user (see @type{Who-Info-Ident} above.) See the @field{username} field in @type{Who-Info} above.
@item hostname @item hostname
The host the connection originated at. The host the connection originated at.
@item ident-user @item ident-user
...@@ -7477,7 +7486,8 @@ Login required before issuing this call. ...@@ -7477,7 +7486,8 @@ Login required before issuing this call.
The text @rarg{text} does not exist or is secret. The text @rarg{text} does not exist or is secret.
@item aux-item-permission @item aux-item-permission
No permission to delete one or more of the items in @rarg{delete}, or No permission to delete one or more of the items in @rarg{delete}, or
not enough permissions to add one or more of the items in @rarg{add}. @rarg{delete} indicates a non-existent aux-item, or not enough
permissions to add one or more of the items in @rarg{add}.
@item illegal-aux-item @item illegal-aux-item
One of the items in @rarg{add} is illegal for some reason. One of the items in @rarg{add} is illegal for some reason.
@end table @end table
...@@ -7512,7 +7522,8 @@ Login required before issuing this call. ...@@ -7512,7 +7522,8 @@ Login required before issuing this call.
The conference @rarg{conf} does not exist or is secret. The conference @rarg{conf} does not exist or is secret.
@item aux-item-permission @item aux-item-permission
No permission to delete one or more of the items in @rarg{delete}, or No permission to delete one or more of the items in @rarg{delete}, or
not enough permissions to add one or more of the items in @rarg{add}. @rarg{delete} indicates a non-existent aux-item, or not enough
permissions to add one or more of the items in @rarg{add}.
@item illegal-aux-item @item illegal-aux-item
One of the items in @rarg{add} is illegal for some reason. One of the items in @rarg{add} is illegal for some reason.
@end table @end table
...@@ -7568,7 +7579,9 @@ Admin bit not set or privileges not enabled. ...@@ -7568,7 +7579,9 @@ Admin bit not set or privileges not enabled.
@item illegal-aux-item @item illegal-aux-item
Attempt to create an invalid aux item. Attempt to create an invalid aux item.
@item aux-item-permission @item aux-item-permission
Attempt to delete an undeletable item or create an uncreateable item. No permission to delete one or more of the items in @rarg{delete}, or
@rarg{delete} indicates a non-existent aux-item, or not enough
permissions to add one or more of the items in @rarg{add}.
@end table @end table
...@@ -7813,10 +7826,7 @@ Conference @rarg{conf-no} does not exist or is secret. ...@@ -7813,10 +7826,7 @@ Conference @rarg{conf-no} does not exist or is secret.
Person @rarg{pers-no} does not exist Person @rarg{pers-no} does not exist
@item access-denied @item access-denied
@c FIXME (bug 199): the "or to change" part is bogus, right? Aren't those Not enough permissions or privileges to add members to @rarg{conf-no}.
@c circumstances covered by permission-denied?
Not enough permissions or privileges to add members to @rarg{conf-no}
or to change privileges, position or type of a preexisting membership.
@item permission-denied @item permission-denied
Person @rarg{pers-no} is already a member of conference @rarg{conf-no}, Person @rarg{pers-no} is already a member of conference @rarg{conf-no},
...@@ -9049,10 +9059,9 @@ old name in @aarg{old-name} and the new name in @aarg{new-name}. ...@@ -9049,10 +9059,9 @@ old name in @aarg{old-name} and the new name in @aarg{new-name}.
async-i-am-on [6] ( info : @lt{Who-Info} ); async-i-am-on [6] ( info : @lt{Who-Info} );
@end example @end example
This message is sent when a session's working conference, This message is sent when a session's working conference or
@code{what-i-am-doing} string (@pxref{change-what-i-am-doing}) or @code{what-i-am-doing} string (@pxref{change-what-i-am-doing})
username changes. The new information is sent in @aarg{info}. changes. The new information is sent in @aarg{info}.
@c FIXME (bug 200): can the username change?
...@@ -9635,6 +9644,37 @@ An argument of type @type{BOOL} was given a value that is neither ...@@ -9635,6 +9644,37 @@ An argument of type @type{BOOL} was given a value that is neither
@node Aux-Item Types @node Aux-Item Types
@chapter Aux-Item Types @chapter Aux-Item Types
The following list includes all predefined aux-items. Client writers
can expect that the definitions of these items will not change unless
explicitly stated.
Each listing is of the form @samp{name [tag] (types)},
where @field{name} is the name of the aux-item, @field{tag} is
the aux-item tag and @field{types} is a comma-separated list of object
types the aux-item may be attached to. The possible types are:
@table @code
@item text
Indicates that the aux-item may be attached to texts.
@item create text
Indicates that the aux-item may be attached to texts, but only when
the text is being created; once the text exists, the item may not be
added.
@item conference
Indicates that the aux-item may be attached to conferences that do not
have the @conftype{letterbox} flag set.
@item letterbox
Indicates that the aux-item may be attached to conferences that have
the @conftype{letterbox} flag set.
@item server
Indicates that the aux-item may be attached to the server itself.
@end table
Some of the aux-items below (mostly the ones that begin with "mx-") are Some of the aux-items below (mostly the ones that begin with "mx-") are
used by mail importers. used by mail importers.
...@@ -9810,7 +9850,7 @@ The data should be the client name, a space, and the client version used ...@@ -9810,7 +9850,7 @@ The data should be the client name, a space, and the client version used
in the @reqlink{set-client-version} call. The server may enforce this in the @reqlink{set-client-version} call. The server may enforce this
restriction. restriction.
@item mx-author [16] (text) @item mx-author [16] (create text)
Data is a string containing the name of the author of an imported Data is a string containing the name of the author of an imported
e-mail, extracted from the @code{From} header. This aux-item may be e-mail, extracted from the @code{From} header. This aux-item may be
...@@ -10961,9 +11001,12 @@ who knows the @code{Message-ID} of an interesting imported mail can add ...@@ -10961,9 +11001,12 @@ 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. should check for matching contents before adding recipients.
The importer needs to be careful not to deliver messages to conferences The importer needs to be careful not to deliver messages to
that do not allow messages, even though the server might not complain. conferences that do not allow messages, even though the server might
@c FIXME (bug 201): Please elaborate on that... not complain. Limitations on what messages a conference accepts are
defined by aux-items. See @ref{The Aux-Item List} and @ref{Aux-Item
Types}, in particular @aux{redirect}, @aux{allowed-content-type} and
@aux{mx-refuse-import} for more information.
For mail delivery to work for any conference, the importer has to use a 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 privileged person, or it will be unable to deliver mail to secret
......
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