SESSION LAYER PROTOCOL FOR CITADEL/UX
- (c) 1995-1999 by Art Cancro et. al. All Rights Reserved
+ (c) 1995-2001 by Art Cancro et. al. All Rights Reserved
INTRODUCTION
developments ahead of time, please at least send in an e-mail documenting
what you did, so that your new commands can be added to this document.
- The coordinator of the Citadel/UX project is Art Cancro <ajc@uncnsrd.mt-kisco.ny.us>.
+ The coordinator of the Citadel/UX project is Art Cancro
+<ajc@uncensored.citadel.org>.
CONNECTING TO A SERVER
should begin sending a listing of some sort. The client *must* send something,
even if it is an empty listing. Again, the listing ends with "000" on a line
by itself.
-
+ BINARY_FOLLOWS and SEND_BINARY mean that the client must immediately send
+or receive a block of binary data. The first parameter will always be the
+number of bytes.
+ ASYNC_MESSAGE_FOLLOWS means that an asynchronous, or unsolicited, message
+follows. The next line will be one of the above codes, and if a data transfer
+is involved it must be handled immediately. Note that the client will not
+receive this type of response unless it indicates to the server that it is
+capable of handling them; see the writeup of the ASYN command later in this
+document.
PARAMETERIZATION
----------------
Other bits may be defined in the future. The listing terminates, as with
all listings, with "000" on a line by itself.
- Version 4.01 and above only:
-
Starting with version 4.01 and above, floors are supported. The first
argument to LKRN should be the number of the floor to list rooms from. Only
rooms from this floor will be listed. If no arguments are passed to LKRN, or
The third field displayed on each line is the number of the floor the room
is on. The LFLR command should be used to associate floor numbers with
floor names.
+
+ The fourth field displayed on each line is a "room listing order." Unless
+there is a compelling reason not to, clients should sort any received room
+listings by this value.
This command retrieves the screen dimensions and user options for the
currently logged in account. ERROR will be returned if no user is logged
-in, of course. Otherwise, OK will be returned, followed by three parameters.
+in, of course. Otherwise, OK will be returned, followed by four parameters.
The first parameter is the user's screen width, the second parameter is the
user's screen height, and the third parameter is a bag of bits with the
following meanings:
There are other bits, too, but they can't be changed by the user (see below).
+ The fourth parameter, if present, is the moderation level this user is
+filtering at.
+
SETU (SET User configuration)
This command does the opposite of SETU: it takes the screen dimensions and
user options (which were probably obtained with a GETU command, and perhaps
modified by the user) and writes them to the user account. This command
-should be passed three parameters: the screen width, the screen height, and
-the option bits (see above).
+should be passed four parameters: the screen width, the screen height,
+the option bits (see above), and the desired moderation level to filter at.
Note that there exist bits here which are not listed in this document. Some
are flags that can only be set by Aides or the system administrator. SETU
This command obtains a listing of all the messages in the current room
which the client may request. This command may be passed a single parameter:
either "all", "old", or "new" to request all messages, only old messages, or
-new messages. Or it may be passed two parameters: "last" plus a number, in which
-case that many message pointers will be returned, or "first" plus a number, for
-the corresponding effect. If no parameters are specified, "all" is assumed.
+new messages. Or it may be passed two parameters: "last" plus a number, in
+which case that many message pointers will be returned, or "first" plus a
+number, for the corresponding effect. If no parameters are specified, "all"
+is assumed.
- In Citadel/UX 5.00 and above, the client may also specify "gt" plus a number, to
-list all messages in the current room with a message number greater than the one
-specified.
+ In Citadel/UX 5.00 and above, the client may also specify "gt" plus a number,
+to list all messages in the current room with a message number greater than
+the one specified.
+
+ The third argument, valid only in Citadel/UX 5.60 and above, may be either
+0 or 1. If it is 1, this command behaves differently: before a listing is
+returned, the client must transmit a list of fields to search for. The field
+headers are listed below in the writeup for the "MSG0" command.
- This command can return two possible results. An ERROR code may be returned
+ This command can return three possible results. An ERROR code may be returned
if no user is currently logged in or if something else went wrong. Otherwise,
LISTING_FOLLOWS will be returned, and the listing will consist of zero or
more message numbers, one per line. The listing ends, as always, with the
string "000" alone on a line by itself. The listed message numbers can be used
-to request messages from the system.
+to request messages from the system. If "search mode" is being used, the
+server will return START_CHAT_MODE, and the client is expected to transmit
+the search criteria, and then read the message list.
+
+ Since this is somewhat complex, here are some examples:
+
+ Example 1: Read all new messages
+
+ Client: MSGS NEW
+ Server: 100 Message list...
+ 523218
+ 523293
+ 523295
+ 000
+
+ Example 2: Read the last five messages
+
+ Client: MSGS LAST|5
+ Server: 100 Message list...
+ 523190
+ 523211
+ 523218
+ 523293
+ 523295
+ 000
+
+ Example 3: Read all messages written by "IGnatius T Foobar"
+
+ Client: MSGS ALL|0|1
+ Server: 800 Send template then receive message list
+ Client: from|IGnatius T Foobar
+ 000
+ Server: 518604
+ 519366
+ 519801
+ 520201
+ 520268
+ 520805
+ 520852
+ 521579
+ 521720
+ 522571
+ 000
+
+ Note that in "search mode" the client may specify any number of search
+criteria. These criteria are applied with an AND logic.
+
MSG0 (read MeSsaGe, mode 0)
This is a command used to read the text of a message. "Mode 0" implies that
LISTING_FOLLOWS code will be returned, followed by the contents of the message.
The following fields may be sent:
- type= Formatting type. Currently, there are two defined types. Type 0 is
-"traditional" Citadel formatting. This means that newlines should be treated
-as spaces UNLESS the first character on the next line is a space. In other
-words, only indented lines should generate a newline on the user's screen when
-the message is being displayed. This allows a message to be formatted to the
-reader's screen width. It also allows the use of proportional fonts.
-Type 1 is a simple fixed-format message. The message should be displayed to
+ type= Formatting type. The currently defined types are:
+ 0 = "traditional" Citadel formatting. This means that newlines should be
+treated as spaces UNLESS the first character on the next line is a space. In
+other words, only indented lines should generate a newline on the user's screen
+when the message is being displayed. This allows a message to be formatted to
+the reader's screen width. It also allows the use of proportional fonts.
+ 1 = a simple fixed-format message. The message should be displayed to
the user's screen as is, preferably in a fixed-width font that will fit 80
columns on a screen.
+ 4 = MIME format message. The message text is expected to contain a header
+with the "Content-type:" directive (and possibly others).
msgn= The message ID of this message on the system it originated on.
path= An e-mailable path back to the user who wrote the message.
room= The name of the room the message originated in.
node= The short node name of the system this message originated on.
hnod= The long node name of the system this message originated on.
+ zaps= The id/node of a message which this one zaps (supersedes).
text Note that there is no "=" after the word "text". This string
signifies that the message text begins on the next line.
Line 12 - Paging level. 0 if the system only supports inline paging,
1 if the system supports "extended" paging (check-only and
multiline modes). See the SEXP command for further information.
+ Line 13 - The "nonce" for this session, for support of APOP-style
+ authentication. If this field is present, clients may authenticate
+ in this manner.
*** NOTE! *** The "server type" code is intended to promote global
compatibility in a scenario in which developers have added proprietary
your own.
-> Clients other than your own should still be able to utilize your server,
even if your proprietary extensions aren't supported.
- -> Please contact Art Cancro <ajc@uncnsrd.mt-kisco.ny.us> and obtain a unique
+ -> Please contact Art Cancro <ajc@uncensored.citadel.org> and obtain a unique
server type code, which can be assigned to your server program.
-> If you document what you did in detail, perhaps it can be added to a
future release of the Citadel/UX program, so everyone can enjoy it. Better
The server message contained on the same line with LISTING_FOLLOWS will
contain the name of the system and the name of the directory, such as:
- uncnsrd.mt-kisco.ny.us|/usr/bbs/files/my_room_directory
+ uncensored.citadel.org|/usr/bbs/files/my_room_directory
SLRP (Set Last-message-Read Pointer)
- This command is used to mark messages as having been read. Its sole parameter
+ This command marks all messages in the current room as read (seen) up to and
+including the specified number. Its sole parameter
is the number of the last message that has been read. This allows the pointer
to be set at any arbitrary point in the room. Optionally, the parameter
"highest" may be used instead of a message number, to set the pointer to the
2. The name of the room's directory (if it's a directory room)
3. Various flags (bits) associated with the room (see LKRN cmd above)
4. The floor number on which the room resides
+ 5. The room listing order
SETR (SET Room attributes)
3. Various flags (bits) associated with the room (see LKRN cmd above)
4. "Bump" flag (see below)
5. The floor number on which the room should reside
+ 6. The room listing order
*Important: You should always use GETR to retrieve the current attributes of
the room, then change what you want to change, and then use SETR to write it
Delete a message from the current room. The one argument that should be
passed to this command is the message number of the message to be deleted.
The return value will be OK if the message was deleted, or an ERROR code.
+If the delete is successful, the message's reference count is decremented, and
+if the reference count reaches zero, the message is removed from the message
+base.
- MOVE (MOVE a message to a different room)
+ MOVE (MOVE or copy a message to a different room)
Move a message to a different room. The two arguments that should be passed
to this command are the message number of the message to be deleted, and the
usually means that either the user does not have permission to perform this
operation, or that the target room does not exist.
+ In Citadel/UX 5.55 and above, a third argument may be specified: 0 or 1 to
+designate whether the message should be moved (0) or copied (1) to the target
+room. In the case of a "copy" operation, the message's reference count is
+incremented, and a pointer to the message will exist in both the source *and*
+target rooms. In the case of a "move" operation, the message pointer is
+deleted from the source room and the reference count remains the same.
+
KILL (KILL current room)
Line 8: Telephone number
Line 9: Access level
Line 10: Internet e-mail address
+ Line 11: Country
Users without Aide privileges may retrieve their own registration using
this command. This can be accomplished either by passing the user's own
Line 5: ZIP Code
Line 6: Telephone number
Line 7: e-mail address
+ Line 8: Country
CHEK (CHEcK various things)
this client (Note: NOOP's don't count)
6 - The last command received from a client. (NOOP's don't count)
7 - Session flags. These are: + (spoofed address), - (STEALTH mode), *
- (posting) and . (idle). (Citserver 5.02 and above)
+ (posting) and . (idle).
+ 8 - Actual user name, if user name is masqueraded and viewer is an Aide.
+ 9 - Actual room name, if room name is masqueraded and viewer is an Aide.
+ 10 - Actual host name, if host name is masqueraded and viewer is an Aide.
The listing is terminated, as always, with the string "000" on a line by
itself.
OK (file is open)
If the file is successfully opened, OK will be returned, along with the
-size (in bytes) of the file, and (in version 5.00 and above) the time of last
-modification.
+size (in bytes) of the file, the time of last modification (if applicable),
+the filename (if known), and the MIME type of the file (if known).
CLOS (CLOSe the download file)
This is one of two commands which implement "express messages" (also known
as "paging"). An express message is a near-real-time message sent from one
logged in user to another. When an express message is sent, it will be
-displayed the next time the target user executes a PEXP command.
+displayed the next time the target user executes a PEXP or GEXP command.
The SEXP command accepts two arguments: the name of the user to send the
message to, and the text of the message. If the message is successfully
never be received.
- PEXP (Print EXPress messages)
+ PEXP (Print EXPress messages) ***DEPRECATED***
- This command, called without any arguments, simply dumps out the contents
+ This command is deprecated; it will eventually disappear from the protocol and
+its use is not recommended. Please use the GEXP command instead.
+
+ Called without any arguments, PEXP simply dumps out the contents
of any waiting express messages. It returns ERROR if there is a problem,
otherwise it returns LISTING_FOLLOWS followed by all messages.
Receive from the server a named user's bio. This command should be passed
a single argument - the name of the user whose bio is requested. RBIO returns
-LISTING_FOLLOWS plus the bio file if the user exists and has a bio on file,
-ERROR+NO_SUCH_USER if the named user does not exist, or ERROR+FILE_NOT_FOUND
-if the user exists but has no bio on file.
+LISTING_FOLLOWS plus the bio file if the user exists and has a bio on file.
+The return has the following parameters: the user name, user number, access
+level, date of last call, times called, and messages posted. This command
+returns ERROR+NO_SUCH_USER if the named user does not exist.
+
+ RBIO no longer considers a user with no bio on file to be an error condition.
+It now returns a message saying the user has no bio on file as the text of the
+bio. This allows newer servers to operate with older clients.
STEL (enter STEaLth mode)
a client program is prohibited from terminating the session it is currently
running on.
+ See also: REQT
+
NSET (Network SETup commands)
0 to respectively set or clear the flag. When the "scheduled shutdown" flag is
set, the server will be shut down when there are no longer any users logged in.
Any value other than 0 or 1 will not change the flag, only report its state.
-No users will be kicked off the system, and in fact the server is still available
-for new connections. The command returns ERROR if it fails; otherwise, it
-returns OK followed by a number representing the current state of the flag.
+No users will be kicked off the system, and in fact the server is still
+available for new connections. The command returns ERROR if it fails;
+otherwise, it returns OK followed by a number representing the current state
+of the flag.
EMSG (Enter a system MeSsaGe)
-> _userpic_ (Server will attempt to write to the user's online photo)
-> Any of the "well known" filenames described in the writeup for the
OIMG command.
-
-----------------------------------------------
-The following are for citserver 5.02 and above
-----------------------------------------------
-
+
+
HCHG (Hostname CHanGe)
HCHG is a command, usable by any user, that allows a user to change their RWHO
17. Default purge time (in days) for users
18. Default purge time (in days) for rooms
19. Name of room to log express messages to (or a zero-length name for none)
-
-
-
- EXPI (EXPIre system objects)
+ 20. Access level required to create rooms
+ 21. Maximum message length which may be entered into the system
+ 22. Minimum number of worker threads
+ 23. Maximum number of worker threads
+ 24. Port number for POP3 service
+ 25. Port number for SMTP service
+ 26. Default moderation filter level for new users (-63 to +63)
+ 27. Flag (0 or 1) - allow Aides to zap (forget) rooms
+ 28. Port number for IMAP service
+
+
+ EXPI (EXPIre system objects)
Begins purge operations for objects which, according to site policy, are
"old" and should be removed. EXPI should be called with one argument, one of:
"messages" (purge old messages out of each room)
"users" (purge old users from the userlog)
+ "rooms" (remove rooms which have not been posted in for some time)
+ "visits" (purge dereferenced user/room relationship records)
EXPI returns OK (probably after a long delay while it does its work) if it
succeeds; otherwise it returns an ERROR code.
This command is probably temporary, until we can work some sort of scheduler
into the system. It is implemented in the serv_expire module.
+
+
+
+ MSG4 (read MeSsaGe, mode 4 -- enumerate MIME parts)
+
+ FIX ... do the writeup for this once it's done.
+
+
+
+ OPNA (OPeN Attachment)
+
+ Opens, as a download file, a component of a MIME-encoded message. The two
+parameters which must be passed to this command are the message number and the
+name of the desired section. If the message or section does not exist, an
+appropriate ERROR code will be returned; otherwise, if the open is successful,
+this command will succeed returning the same information as an OPEN command.
+
+
+ GEXP (Get EXPress messages)
+
+ This is a more sophisticated way of retrieving express messages than the old
+PEXP method. If there are no express messages waiting, PEXP returns ERROR;
+otherwise, it returns LISTING_FOLLOWS and the following arguments:
+
+ 0 - a boolean value telling the client whether there are any additional
+ express messages waiting following this one
+ 1 - a Unix-style timestamp
+ 2 - flags (see server.h for more info)
+ 3 - the name of the sender
+ 4 - the node this message originated on (for future support of PIP, ICQ, etc.)
+
+ The text sent to the client will be the body of the express message.
+
+ So how does the client know there are express messages waiting? It could
+execute a random GEXP every now and then. Or, it can check the byte in
+server return code messages, between the return code and the parameters. In
+much the same way as FTP uses "-" to signify a continuation, Citadel uses
+an "*" in this position to signify the presence of waiting express messages.
+
+
+ FSCK (check message base reference counts)
+
+ Verify, via the long way, that all message referenmce counts are correct. If
+the user has permission to do this then LISTING_FOLLOWS is returned, followed
+by a transcript of the run. Otherwise ERROR is returned.
+
+
+ DEXP (Disable EXPress messages)
+
+ DEXP sets or clears the "disable express messages" flag. Pass this command a
+1 or 0 to respectively set or clear the flag. When the "disable express
+messages" flag is set, no one except Aides may send the user express messages.
+Any value other than 0 or 1 will not change the flag, only report its state.
+The command returns ERROR if it fails; otherwise, it returns OK followed by a
+number representing the current state of the flag.
+
+
+ MMOD (MODerate a Message)
+
+ Set or change the moderation level of a message. The two parameters passed
+to this command should be the message number and the desired moderation level.
+Please refer to the "moderation.txt" document for a description of some
+commonly used moderation levels.
+
+ If the command succeeds, OK is returned. If the specified message does not
+exist in the current room, or if the specified moderation level is not within
+acceptable limits, ERROR+ILLEGAL_VALUE is returned. This command requires at
+least Room Aide access; if the calling user is not an Aide, or a Room Aide for
+the current room, ERROR+HIGHER_ACCESS_REQUIRED is returned.
+
+
+ REQT (REQuest client Termination)
+
+ Request that the specified client (or all clients) log off. Aide level
+access is required to run this command, otherwise ERROR+HIGHER_ACCESS_REQUIRED
+is returned.
+
+ The REQT command accepts one parameter: the session ID of the client which
+should be terminated, or 0 for all clients. When successful, the REQT command
+returns OK.
+
+ It should be noted that REQT simply transmits an express message to the
+specified client(s) with the EM_GO_AWAY flag set. Older clients do not honor
+this flag, and it is certainly possible for users to re-program their client
+software to ignore it. Therefore the effects of the REQT command should be
+considered advisory only. The recommended implementation practice is to first
+issue a REQT command, then wait a little while (from 30 seconds up to a few
+minutes) for well-behaved clients to voluntarily terminate, and then issue a
+TERM command to forcibly disconnect the client (or perhaps a DOWN command, if
+you are logging off users for the purpose of shutting down the server).
+
+
+ SEEN (set or clear the SEEN flag for a message)
+
+ Beginning with version 5.80, Citadel supports the concept of setting or
+clearing the "seen" flag for each individual message, instead of only allowing
+a "last seen" pointer. In fact, the old semantics are implemented in terms
+of the new semantics. This command requires two arguments: the number of the
+message to be set, and a 1 or 0 to set or clear the "seen" bit.
+
+ This command returns OK, unless the user is not logged in or a usage error
+occurred, in which case it returns ERROR. Please note that no checking is
+done on the supplied data; if the requested message does not exist, the SEEN
+command simply returns OK without doing anything.
+
+
+
+ ASYN (ASYNchronous message support)
+
+ Negotiate the use of asynchronous, or unsolicited, protocol messages. The
+only parameter specified should be 1 or 0 to indicate that the client can or
+cannot handle this type of messages. The server will reply OK followed by a
+1 or 0 to tell the client which mode it is now operating in.
+
+ If the command is not available on the server (i.e. it returns ERROR), or
+if the command has not been executed by the client, it should be assumed that
+this mode of operation is NOT in effect.
+
+ The client may also send any value other than 0 or 1 to simply cause the
+server to output its current state without changing it.
+
+ When asynchronous protocol mode is in effect, the client MUST handle any
+asynchronous messages as they arrive, before doing anything else.
+
+
+
+
+ ASYNCHRONOUS MESSAGES
+ ---------------------
+
+ When the client protocol is operating in asynchronous mode (please refer to
+the writeup of the ASYN command above), the following messages may arrive at
+any time:
+
+
+ 901 (express message arriving)
+
+ There is an express message intended for this client. When the client
+receives this message, it MUST act as if it just sent a GEXP command (the data
+following the 901 message WILL be a LISTING_FOLLOWS data transfer; in fact,
+the current implementation simply executes a GEXP command internally).
projects / citadel.git / blobdiff