[citadel.git] / citadel / techdoc / protocol.txt

              APPLICATION LAYER PROTOCOL FOR THE CITADEL SYSTEM
         (c) 1995-2006 by Art Cancro et. al.    All Rights Reserved


 INTRODUCTION
 ------------

 This is an attempt to document the application layer protocol used by the
Citadel system, beginning with version 4.00, which is the first version
to implement a client/server paradigm.  It is intended as a resource for
programmers who intend to develop their own Citadel clients, but it may have
other uses as well.


 IMPORTANT NOTE TO DEVELOPERS!
 -----------------------------

 Anyone who wants to add commands or other functionality to this protocol,
*please* get in touch so that these efforts can be coordinated.  New
commands added by other developers can be added to this document, so we
don't end up with new server commands from multiple developers which have
the same name but perform different functions.  If you don't coordinate new
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 project is Art Cancro
<ajc@uncensored.citadel.org>.


 CONNECTING TO A SERVER
 ----------------------

 The protocols used below the application layer are beyond the scope of this
document, but we will briefly cover the methodology employed by Citadel.

 Citadel offers its client protocol using TCP/IP.  It does so via a
multithreaded server listening on a TCP port.  Local connections may also
be made using the same protocol using Unix domain sockets.

 The port number officially assigned to Citadel by the IANA is 504/tcp.  Since
our application layer assumes a clean, reliable, sequenced connection, the use
of UDP would render the server unstable and unusable, so we stick with TCP.


 CHARACTER SETS
 --------------
 
 The native character set for the Citadel system is UTF-8.  Unless otherwise
specified, all data elements are expected to be in the UTF-8 character set.
Specifically, all non-MIME messages should be assumed to be in UTF-8.  MIME
messages may be in whatever character set is specified by the MIME header, of
course; however, some clients (such as WebCit) will automatically convert
messages from other character sets before displaying them.
 
 
 GENERAL INFORMATION ABOUT THE SERVER
 ------------------------------------

 The server is connection-oriented and stateful: each client requires its own
connection to a server process, and when a command is sent, the client must
read the response, and then transfer data or change modes if necessary.

 The application layer is very much like other Internet protocols such as SMTP
or NNTP.  A client program sends one-line commands to the server, and the
server responds with a three-digit numeric result code followed by a message
describing what happened.  This cycle continues until the end of the
session.

 Unlike protocols such as FTP, all data transfers occur in-band.  This means
that the same connection that is used for exchange of client/server
messages, will also be used to transfer data back and forth.  (FTP opens a
separate connection for data transfers.)  This keeps protocol administration
straightforward, as it can traverse firewalls without any special protocol
support on the firewall except for opening the port number.


 RESULT CODES
 ------------

 The server will respond to all commands with a 3-digit result code, which
will be the first three characters on the line.  The rest of the line may
contain a human-readable string explaining what happened.  (Some client
software will display some of these strings to the user.)

 The first digit is the most important.  The following codes are defined for
this position: ERROR, OK, MORE_DATA, LISTING_FOLLOWS, and SEND_LISTING.

 The second and third digits may provide a reason as to why a command
succeeded or failed.  See ipcdef.h for the available codes.

 ERROR means the command did not complete.
 OK means the command executed successfully.
 MORE_DATA means the command executed partially.  Usually this means that
another command needs to be executed to complete the operation.  For example,
sending the USER command to log in a user usually results in a MORE_DATA
result code, because the client needs to execute a PASS command to send the
password and complete the login.
 LISTING_FOLLOWS means that after the server response, the server will
output a listing of some sort.  The client *must* read the listing, whether
it wants to or not.  The end of the listing is signified by the string
"000" on a line by itself.
 SEND_LISTING is the opposite of LISTING_FOLLOWS.  It means that the client
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
 ----------------

 Zero or more parameters may be passed to a command.  When more than one
parameter is passed to a command, they should be separated by the "|"
symbol like this:
  SETU 80|24|260
 In this example, we're using the "SETU" command and passing three
parameters: 80, 24, and 260.

 When the server spits out data that has parameters, if more than one
parameter is returned, they will be separated by the "|" symbol like
this:
  200 80|24|260
 In this example, we just executed the "GETU" command, and it returned us
an OK result code (the '2' in the 200) and three parameters: 80, 24, and
260.


 COMMANDS
 --------

 This is a listing of all the commands that a Citadel server can execute.


 NOOP   (NO OPeration)

 This command does nothing.  It takes no arguments and always returns
OK.  It is intended primarily for testing and development, but it might also
be used as a "keep alive" command to prevent the server from timing out, if
it's running over a transport that needs this type of thing.


 ECHO   (ECHO something)

 This command also does nothing.  It simply returns OK followed by whatever
its arguments are.


 QUIT   (QUIT)

 Terminate the server connection.  This command takes no arguments.  It
returns OK and closes the connection immediately.


 LOUT   (LogOUT)

 Log out the user without closing the server connection.  It always returns
OK even if no user is logged in.


 USER   (send USER name)

 The first step in logging in a user.  This command takes one argument: the
name of the user to be logged in.  If the user exists, a MORE_DATA return
code will be sent, which means the client should execute PASS as the next
command.  If the user does not exist, ERROR + NO_SUCH_USER is returned.


 PASS   (send PASSword)

 The second step in logging in a user.  This command takes one argument: the
password for the user we are attempting to log in.  If the password doesn't
match the correct password for the user we specified for the USER command,
ERROR + PASSWORD_REQUIRED is returned.  If a USER command has not been
executed yet, ERROR + USERNAME_REQUIRED is returned.  If a user is already
logged in, ERROR + ALREADY_LOGGED_IN is returned.  If the password is
correct, OK is returned and the user is now logged in... and most of the
other server commands can now be executed.  Along with OK, the following
parameters are returned:

 0 - The user's name (in case the client wants the right upper/lower casing)
 1 - The user's current access level
 2 - Times called
 3 - Messages posted
 4 - Various flags (see citadel.h)
 5 - User number
 6 - Time of last call (UNIX timestamp)


 NEWU   (create NEW User account)

 This command creates a new user account AND LOGS IT IN.  The argument to
this command will be the name of the account.  No case conversion is done
on the name.  Note that the new account is installed with a default
configuration, and no password, so the client should immediately prompt the
user for a password and install it with the SETP command as soon as this
command completes.  This command returns OK if the account was created and
logged in, ERROR + ALREADY_EXISTS if another user already exists with this
name, ERROR + NOT_HERE if self-service account creation is disabled,
ERROR + MAX_SESSIONS_EXCEEDED if too many users are logged in, ERROR +
USERNAME_REQUIRED if a username was not provided, or ERROR + ILELGAL_VALUE
if the username provided is invalid.  If OK, it will also return the same
parameters that PASS returns.

 Please note that the NEWU command should only be used for self-service
user account creation.  For administratively creating user accounts, please
use the CREU command.


 SETP   (SET new Password)

 This command sets a new password for the currently logged in user.  The
argument to this command will be the new password.  The command always
returns OK, unless the client is not logged in, in which case it will return
ERROR + NOT_LOGGED_IN, or if the user is an auto-login user, in which case
it will return ERROR + NOT_HERE.


 CREU   (CREate new User account)

 This command creates a new user account AND DOES NOT LOG IT IN.  The first
argument to this command will be the name of the account.  No case conversion
is done on the name.  Note that the new account is installed with a default
configuration, and no password.  The second argument is optional, and will be
an initial password for the user.  This command returns OK if the account was
created, ERROR + HIGHER_ACCESS_REQUIRED if the user is not an Aide, ERROR +
USERNAME_REQUIRED if no username was specified, or ERROR + ALREADY_EXISTS if
another user already exists with this name.

 Please note that CREU is intended to be used for activities in which a
system administrator is creating user accounts.  For self-service user
account creation, use the NEWU command.


 LKRN   (List Known Rooms with New messages)

 List known rooms with new messages.  If the client is not logged in, ERROR +
NOT_LOGGED_IN is returned.  Otherwise, LISTING_FOLLOWS is returned, followed
by the room listing.  Each line in the listing contains the full name of a
room, followed by the '|' symbol, and then a number that may contain the
following bits:

#define QR_PERMANENT    1               /* Room does not purge              */
#define QR_PRIVATE      4               /* Set for any type of private room */
#define QR_PASSWORDED   8               /* Set if there's a password too    */
#define QR_GUESSNAME    16              /* Set if it's a guessname room     */
#define QR_DIRECTORY    32              /* Directory room                   */
#define QR_UPLOAD       64              /* Allowed to upload                */
#define QR_DOWNLOAD     128             /* Allowed to download              */
#define QR_VISDIR       256             /* Visible directory                */
#define QR_ANONONLY     512             /* Anonymous-Only room              */
#define QR_ANON2        1024            /* Anonymous-Option room            */
#define QR_NETWORK      2048            /* Shared network room              */
#define QR_PREFONLY     4096            /* Preferred status needed to enter */
#define QR_READONLY     8192            /* Aide status required to post     */

 Then it returns another '|' symbol, followed by a second set of bits comprised
of the following:

#define QR2_SYSTEM      1               /* System room; hide by default     */
#define QR2_SELFLIST    2               /* Self-service mailing list mgmt   */

 Other bits may be defined in the future.  The listing terminates, as with
all listings, with "000" on a line by itself.

 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
if the floor number requested is (-1), rooms on all floors will be listed.

 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.
 
 The fifth field is a special bit bucket containing fields which pertain to
room access controls:

#define UA_KNOWN                2       /* Known room */
#define UA_GOTOALLOWED          4       /* Access will be granted to this room
                                         * if the user calls it up by name */
#define UA_HASNEWMSGS           8       /* Unread messages exist in room */
#define UA_ZAPPED              16       /* Zapped from known rooms list */
  
 The sixth field is the user's current view for the room. (See VIEW command)
 The seventh field is the *default* view for the room. (See VIEW command)
 The eigth field is a unix timestamp which reflects the last time the room
  was modified (created, edited, posted in, deleted from, etc.)
 
 
 LKRO   (List Known Rooms with Old [no new] messages)

 This follows the same usage and format as LKRN.


 LZRM   (List Zapped RooMs)

 This follows the same usage and format as LKRN and LKRO.


 LKRA   (List All Known Rooms)

 Same format.  Lists all known rooms, with or without new messages.


 LRMS   (List all accessible RooMS)

 Again, same format.  This command lists all accessible rooms, known and
forgotten, with and without new messages.  It does not, however, list
inaccessible private rooms.


 LPRM   (List all Public RooMs)

 Again, same format.  This command lists all public rooms, and nothing else.
Unlike the other list rooms commands, this one can be executed without logging
in.


 GETU   (GET User configuration)

 This command retrieves the screen dimensions and user options for the
currently logged in account.  ERROR + NOT_LOGGED_IN will be returned if no
user is logged 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:

 #define US_LASTOLD     16              /* Print last old message with new  */
 #define US_EXPERT      32              /* Experienced user                 */
 #define US_UNLISTED    64              /* Unlisted userlog entry           */
 #define US_NOPROMPT    128             /* Don't prompt after each message  */
 #define US_DISAPPEAR   512             /* Use "disappearing msg prompts"   */
 #define US_PAGINATOR   2048            /* Pause after each screen of text  */

 There are other bits, too, but they can't be changed by the user (see below).


 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).  It returns ERROR + NOT_LOGGED_IN if no user is
logged in, and ERROR + ILLEGAL_VALUE if the parameters are incorrect.

 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
will ignore attempts to toggle these bits.  There also may be more user
settable bits added at a later date.  To maintain later downward compatibility,
the following procedure is suggested:

 1. Execute GETU to read the current flags
 2. Toggle the bits that we know we can toggle
 3. Execute SETU to write the flags

 If we are passed a bit whose meaning we don't know, it's best to leave it
alone, and pass it right back to the server.  That way we can use an old
client on a server that uses an unknown bit without accidentally clearing
it every time we set the user's configuration.


 GOTO   (GOTO a room)

 This command is used to goto a new room.  When the user first logs in (login
is completed after execution of the PASS command) this command is
automatically and silently executed to take the user to the first room in the
system (usually called the Lobby).

 This command can be passed one or two parameters.  The first parameter is,
of course, the name of the room.  Although it is not case sensitive, the
full name of the room must be used.  Wildcard matching or unique string
matching of room names should be the responsibility of the client.

 Note that the reserved room name "_BASEROOM_" can be passed to the server
to cause the goto command to take the user to the first room in the system,
traditionally known as the Lobby>.   As long as a user is logged in, a
GOTO command to _BASEROOM_ is guaranteed to succeed.  This is useful to
allow client software to return to the base room when it doesn't know
where else to go.

 There are also several additional reserved room names:
 "_MAIL_" goes to the user's inbox (i.e. the Mail> room).
 "_TRASH_" goes to the user's personal trashcan room (trash folder).
 "_BITBUCKET_" goes to a room that has been chosen for messages without a home.
 "_CALENDAR_" goes to the user's primary personal calendar.
 "_CONTACTS_" goes to the user's primary personal address book.
 "_NOTES_" goes to the user's primary personal notes room.
 "_TASKS_" goes to the user's primary personal task list.
 

 The second (and optional) parameter is a password, if one is required for
access to the room.  This allows for all types of rooms to be accessed via
this command: for public rooms, invitation-only rooms to which the user
has access, and preferred users only rooms to which the user has access, the
room will appear in a room listing.  For guess-name rooms, this command
will work transparently, adding the room to the user's known room list when
it completes.  For passworded rooms, access will be denied if the password
is not supplied or is incorrect, or the command will complete successfully
if the password is correct.

 The third (and also) optional parameter is a "transient" flag.  Normally,
when a user enters a private and/or zapped room, the room is added to the
user's known rooms list.  If the transient flag is set to non-zero, this is
called a "transient goto" which causes the user to enter the room without
adding the room to the known rooms list.

 The possible result codes are:

 OK    - The command completed successfully.  User is now in the room.
         (See the list of returned parameters below)

 ERROR - The command did not complete successfully.  Check the second and
third positions of the result code to find out what happened:

   NOT_LOGGED_IN     -  Of course you can't go there.  You didn't log in.
   PASSWORD_REQUIRED -  Either a password was not supplied, or the supplied
password was incorrect.
   ROOM_NOT_FOUND    -  The requested room does not exist.

 The typical procedure for entering a passworded room would be:

 1. Execute a GOTO command without supplying any password.
 2. ERROR + PASSWORD_REQUIRED will be returned.  The client now knows that
the room is passworded, and prompts the user for a password.
 3. Execute a GOTO command, supplying both the room name and the password.
 4. If OK is returned, the command is complete.  If, however,
ERROR + PASSWORD_REQUIRED is still returned, tell the user that the supplied
password was incorrect.  The user remains in the room he/she was previously
in.

 When the command succeeds, these parameters are returned:
   0. The name of the room
   1. Number of unread messages in this room
   2. Total number of messages in this room
   3. Info flag: set to nonzero if the user needs to read this room's info
      file (see RINF command below)
   4. Various flags associated with this room.  (See LKRN cmd above)
   5. The highest message number present in this room
   6. The highest message number the user has read in this room
   7. Boolean flag: 1 if this is a Mail> room, 0 otherwise.
   8. Aide flag: 1 if the user is either the Room Aide for this room, *or* is
a regular Aide (this makes access checks easy).
   9. The number of new Mail messages the user has (useful for alerting the
user to the arrival of new mail during a session)
  10. The floor number this room resides on
  11. The *current* "view" for this room (see views.txt for more info)
  12. The *default* "view" for this room
  13. Boolian flag: 1 if this is the user's Trash folder, 0 otherwise.
 
 The default view gives the client a hint as to what views the user should
be allowed to select.  For example, it would be confusing to allow messages
in a room intended for calendar items.  The server does not enforce these
restrictions, though.


 MSGS   (get pointers to MeSsaGeS in this room)

 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; "first" plus a
number, for the corresponding effect; or "gt" plus a number, to list all
messages in the current room with a message number greater than the one
specified.  If no parameters are specified, "all" is assumed.

 The third argument, 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.
 
 The optional fourth argument may also be either 0 or 1.  If it is 1, the
output of this command will include not only a list of message numbers, but
a simple header summary of each message as well.  This is somewhat resource
intensive so you shouldn't do this unless you absolutely need all the headers
immediately.  The fields which are output (in the usual delimited fashion, of
course) are: message number, timestamp, display name, node name, Internet
email address (if present), subject (if present).

 This command can return three possible results.  ERROR + NOT_LOGGED_IN will
be returned if no user is currently logged in.  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.  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
other MSG commands (MSG1, MSG2, etc.) will probably be added later on to read
messages in more robust formats.  This command should be passed two arguments.
The first is the message number of the message being requested.  The second
argument specifies whether the client wants headers and/or message body:
 0 = Headers and body
 1 = Headers only
 2 = Body only
 3 = Headers only, with MIME information suppressed (this runs faster)

 If the request is denied, ERROR + NOT_LOGGED_IN or ERROR + MESSAGE_NOT_FOUND
will be returned.  Otherwise, LISTING_FOLLOWS will be returned, followed by
the contents of the message.  The following fields may be sent:

 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.

 time=   The date and time of the message, in Unix format (the number of
seconds since midnight on January 1, 1970, GMT).

 from=   The name of the author of the message.
 rcpt=   If the message is a private e-mail, this is the recipient.
 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).

 part=   Information about a MIME part embedded in this message.
 pref=   Information about a multipart MIME prefix such as "multipart/mixed"
         or "multipart/alternative".  This will be output immediately prior
         to the various "part=" lines which make up the multipart section.
 suff=   Information about a multipart MIME suffix.  This will be output
         immediately following the various "part=" lines which make up the
         multipart section.

 text    Note that there is no "=" after the word "text".  This string
signifies that the message text begins on the next line.


 WHOK   (WHO Knows room)

 This command is available only to Aides.  ERROR + HIGHER_ACCESS_REQUIRED 
will be returned if the user is not an Aide.  Otherwise, it returns
LISTING_FOLLOWS and then lists, one user per line, every user who has
access to the current room.


 INFO   (get server INFO)

 This command will *always* return LISTING_FOLLOWS and then print out a
listing of zero or more strings.  Client software should be written to expect
anywhere from a null listing to an infinite number of lines, to allow later
backward compatibility.  The current implementation defines the following
parts of the listing:

 Line 0  - Your unique session ID on the server
 Line 1  - The node name of the Citadel server
 Line 2  - Human-readable node name of the Citadel server
 Line 3  - The fully-qualified domain name (FQDN) of the server
 Line 4  - The name of the server software, i.e. "Citadel 4.00"
 Line 5  - (The revision level of the server code) * 100
 Line 6  - The geographical location of the site (city and state if in the US)
 Line 7  - The name of the system administrator
 Line 8  - A number identifying the server type (see below)
 Line 9  - The text of the system's paginator prompt
 Line 10 - Floor Flag.  1 if the system supports floors, 0 otherwise.
 Line 11 - 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 12 - The "nonce" for this session, for support of APOP-style
           authentication.  If this field is present, clients may authenticate
           in this manner.
 Line 13 - Set to nonzero if this server supports the QNOP command.
 Line 14 - Set to nonzero if this server is capable of connecting to a
           directory service using LDAP.
 Line 15 - Set to nonzero if this server does *not* allow self-service
           creation of new user accounts.
 Line 16 - The default timezone for calendar items which do not have any
           timezone specified and are not flagged as UTC.  This will be a
           zone name from the Olsen database.

 *** NOTE! ***   The "server type" code is intended to promote global
compatibility in a scenario in which developers have added proprietary
features to their servers or clients.  We are attempting to avoid a future
situation in which users need to keep different client software around for
each Citadel they use.  *Please*, if you are a developer and plan to add
proprietary features:

 -> Your client programs should still be able to utilize servers other than
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@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 program, so everyone can enjoy it.  Better
yet, just work with the Citadel development team on the main source tree.

 If everyone follows this scheme, we can avoid a chaotic situation with lots
of confusion about which client program works with which server, etc.  Client
software can simply check the server type (and perhaps the revision level)
to determine ahead of time what commands may be utilized.

 Please refer to "developers.txt" for information on what codes belong to whom.



 RDIR   (Read room DIRectory)

 Use this command to read the directory of a directory room.  ERROR + NOT_HERE
will be returned if the room has no directory, ERROR + HIGHER_ACCESS_REQUIRED
will be returned if the room's directory is not visible and the user does not
have Aide or Room Aide privileges, ERROR + NOT_LOGGED_IN will be returned if
the user is not logged in; otherwise LISTING_FOLLOWS will be returned,
followed by the room's directory.  Each line of the directory listing will
contain three fields: a filename, the length of the file, and a description.

 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:

  uncensored.citadel.org|/usr/local/citadel/files/my_room_directory


 SLRP   (Set Last-message-Read Pointer)

 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 number of the highest
message in the room, effectively marking all messages in the room as having
been read (ala the Citadel <G>oto command).

 The command will return OK if the pointer was set, or ERROR + NOT_LOGGED_IN
if the user is not logged in.  If OK is returned, it will be followed by a
single argument containing the message number the last-read-pointer was set to.


 INVT   (INViTe a user to a room)

 This command may only be executed by Aides, or by the room aide for the
current room.  It is used primarily to add users to invitation-only rooms,
but it may also be used in other types of private rooms as well.  Its sole
parameter is the name of the user to invite.

 The command will return OK if the operation succeeded.  ERROR + NO_SUCH_USER
will be returned if the user does not exist, ERROR + HIGHER_ACCESS_REQUIRED
will be returned if the operation would have been possible if the user had
higher access, and ERROR + NOT_HERE may be returned if the room is not a
private room.


 KICK   (KICK a user out of a room)

 This is the opposite of INVT: it is used to kick a user out of a private
room.  It can also be used to kick a user out of a public room, but the
effect will only be the same as if the user <Z>apped the room - a non-stupid
user can simply un-zap the room to get back in.


 GETR   (GET Room attributes)

 This command is used for editing the various attributes associated with a
room.  A typical "edit room" command would work like this:
 1. Use the GETR command to get the current attributes
 2. Change some of them around
 3. Use SETR (see below) to save the changes
 4. Possibly also change the room aide using the GETA and SETA commands

 GETR takes no arguments.  It will only return OK if the SETR command will
also return OK.  This allows client software to tell the user that he/she
can't edit the room *before* going through the trouble of actually doing the
editing.  Possible return codes are:

 ERROR+NOT_LOGGED_IN          - No user is logged in.
 ERROR+HIGHER_ACCESS_REQUIRED - Not enough access.  Typically, only aides
and the room aide associated with the current room, can access this command.
 OK                           - Command succeeded.  Parameters are returned.

 If OK is returned, the following parameters will be returned as well:

 0. The name of the room
 1. The room's password (if it's a passworded room)
 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
 6. The default view for the room (see views.txt)
 7. A second set of flags (bits) associated with the room


 SETR   (SET Room attributes)

 This command sets various attributes associated with the current room.  It
should be passed the following arguments:

 0. The name of the room
 1. The room's password (if it's a passworded room)
 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. "Bump" flag (see below)
 5. The floor number on which the room should reside
 6. The room listing order
 7. The default view for the room (see views.txt)
 8. A second set of flags (bits) associated with the room

 *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
all back.  This is particularly important with respect to the flags: if a
particular bit is set, and you don't know what it means, LEAVE IT ALONE and
only toggle the bits you want to toggle.  This will allow for upward
compatibility.

 The _BASEROOM_, user's Mail> and Aide> rooms can only be partially edited.
Any changes which cannot be made will be silently ignored.

 If the room is a private room, you have the option of causing all users who
currently have access, to forget the room.  If you want to do this, set the
"bump" flag to 1, otherwise set it to 0.


 GETA

 This command is used to get the name of the Room Aide for the current room.
It will return ERROR + NOT_LOGGED_IN if no user is logged in, or OK if the
command succeeded.  Along with OK there will be returned one parameter: the
name of the Room Aide.  A conforming server must guarantee that the user is
always in some room.


 SETA

 The opposite of GETA, used to set the Room Aide for the current room.  One
parameter should be passed, which is the name of the user who is to be the
new Room Aide.  Under Citadel, this command may only be executed by Aides
and by the *current* Room Aide for the room.  Return codes possible are:
 ERROR + NOT_LOGGED_IN          (Not logged in.)
 ERROR + HIGHER_ACCESS_REQUIRED (Higher access required.)
 ERROR + NOT_HERE               (Room cannot be edited.)
 OK                             (Command succeeded.)


 ENT0   (ENTer message, mode 0)

 This command is used to enter messages into the system.  It accepts four
arguments:

  0  -  Post flag.  This should be set to 1 to post a message.  If it is
set to 0, the server only returns OK or ERROR (plus any flags describing
the error) without reading in a message.  Client software should, in fact,
perform this operation at the beginning of an "enter message" command
*before* starting up its editor, so the user does not end up typing a message
in vain that will not be permitted to be saved.  If it is set to 2, the
server will accept an "apparent" post name if the user is privileged enough.
This post name is arg 5.
  1  -  Recipient (To: field).  This argument is utilized only for private
mail.  It is ignored for public messages.  It contains, of course, the name
of the recipient(s) of the message.
  2  -  Anonymous flag.  This argument is ignored unless the room allows
anonymous messages.  In such rooms, this flag may be set to 1 to flag a
message as anonymous, otherwise 0 for a normal message.
  3  -  Format type.  Any valid Citadel format type may be used (this will
typically be 0; see the MSG0 command above).
  4  -  Subject.  If present, this argument will be used as the subject of
the message.
  5  -  Post name.  When postflag is 2, this is the name you are posting as.
This is an Aide only command.
  6  -  Do Confirmation.  NOTE: this changes the protocol semantics!  When
you set this to nonzero, ENT0 will reply with a confirmation message after
you submit the message text.  The reply code for the ENT0 command will be
START_CHAT_MODE instead of SEND_LISTING.
  7  -  Recipient (Cc: field).  This argument is utilized only for private
mail.  It is ignored for public messages.  It contains, of course, the name
of the recipient(s) of the message.
  8  -  Recipient (Bcc: field).  This argument is utilized only for private
mail.  It is ignored for public messages.  It contains, of course, the name
of the recipient(s) of the message.
  9  -  Exclusive message ID.  When a message is submitted with an Exclusive
message ID, any existing messages with the same ID will automatically be
deleted.  This is only applicable for Wiki rooms; other types of rooms either
ignore the supplied ID (such as message boards and mailboxes) or derive the
ID from a UUID native to the objects stored in them (such as calendars and
address books).

 Possible result codes:
  OK  -  The request is valid.  (Client did not set the "post" flag, so the
server will not read in message text.)   If the message is an e-mail with
a recipient, the text that follows the OK code will contain the exact name
to which mail is being sent.  The client can display this to the user.  The
implication here is that the name that the server returns will contain the
correct upper and lower case characters.  In addition, if the recipient is
having his/her mail forwarded, the forwarding address will be returned.
  SEND_LISTING  -  The request is valid.  The client should now transmit
the text of the message (ending with a 000 on a line by itself, as usual).
  START_CHAT_MODE  -  The request is valid.  The client should now transmit
the text of the message, ending with a 000 on a line by itself.  After
transmitting the 000 terminator, the client MUST read in the confirmation
from the server, which will also end with 000 on a line by itself.  The format
of the confirmation appears below.
  ERROR + NOT_LOGGED_IN  -  Not logged in.
  ERROR + HIGHER_ACCESS_REQUIRED  -  Higher access is required.  An
explanation follows, worded in a form that can be displayed to the user.
  ERROR + NO_SUCH_USER  -  The specified recipient does not exist.

The format of the confirmation message, if requested, is as follows:
Line 1: The new message number on the server for the message.  It will be
        positive for a real message number, or negative to denote
        that an error occurred.  If an error occurred, the message was
        not saved.
Line 2: A human-readable confirmation or error message.
Line 3: The resulting Exclusive UID of the message, if present.
(More may be added to this in the future, so do not assume that there will
only be these lines output.  Keep reading until 000 is received.)


 RINF   (read Room INFormation file)

 Each room has associated with it a text file containing a description of
the room, perhaps containing its intended purpose or other important
information.  The info file for the Lobby> (the system's base room) is
often used as a repository for system bulletins and the like.

 This command, which accepts no arguments, is simply used to read the info
file for the current room.  It will return LISTING_FOLLOWS followed by
the text of the message (always in format type 0) if the request can be
honored, or ERROR if no info file exists for the current room (which is
often the case).  Other error description codes may accompany this result.

 When should this command be used?  This is, of course, up to the discretion
of client software authors, but in Citadel it is executed in two situations:
the first time the user ever enters a room; and whenever the contents of the
file change.  The latter can be determined from the result of a GOTO command,
which will tell the client whether the file needs to be read (see GOTO above).


 DELE   (DELEte a message)

 Delete one or more messages from the current room.  The one argument that
should be passed to this command is a message number, or a list of message
numbers separated by commas, to be deleted.

 The return value will be OK if one or more messages were deleted, or an ERROR
code.  If the delete is successful, the messages' reference counts are
decremented, and if the reference count reaches zero, the messages are removed
from the message base.


 MOVE   (MOVE or copy a message to a different room)

 Move or copy a message to a different room.  This command expects to be
passed three arguments:
 0: the message number(s) of the message to be moved or copied.
 1: the name of the target room.
 2: flag: 0 to move the message, 1 to copy it without deleting from the
    source room.
 
 This command never creates or deletes copies of a message; it merely moves
around links.  When a message is moved, its reference count remains the same.
When a message is copied, its reference count is incremented.
 
 You can move/copy multiple messages with a single command by separating the
message numbers with commas; for example:  MOVE 112,113,114|Trash|0


 KILL   (KILL current room)

 This command deletes the current room.  It accepts a single argument, which
should be nonzero to actually delete the room, or zero to merely check
whether the room can be deleted.

 Once the room is deleted, the current room is undefined.  It is suggested
that client software immediately GOTO another room (usually _BASEROOM_)
after this command completes.

 Possible return codes:

 OK  -  room has been deleted (or, if checking only, request is valid).
 ERROR+NOT_LOGGED_IN  -  no user is logged in.
 ERROR+HIGHER_ACCESS_REQUIRED  -  not enough access to delete rooms.
 ERROR+NOT_HERE  -  this room can not be deleted.


 CRE8   (CRE[ate] a new room)

 This command is used to create a new room.  Like some of the other
commands, it provides a mechanism to first check to see if a room can be
created before actually executing the command.  CRE8 accepts the following
arguments:

 0  -  Create flag.  Set this to 1 to actually create the room.  If it is
set to 0, the server merely checks that there is a free slot in which to
create a new room, and that the user has enough access to create a room.  It
returns OK if the client should go ahead and prompt the user for more info,
or ERROR or ERROR+HIGHER_ACCESS_REQUIRED if the command will not succeed.
 1  -  Name for new room.
 2  -  Access type for new room:
       0  -  Public
       1  -  Private; can be entered by guessing the room's name
       2  -  Private; can be entered by knowing the name *and* password
       3  -  Private; invitation only (sometimes called "exclusive")
       4  -  Personal (mailbox for this user only)
 3  -  Password for new room (if it is a type 2 room)
 4  -  Floor number on which the room should reside (optional)
 5  -  Set to 1 to avoid automatically gaining access to the created room.
 6  -  The default "view" for the room.

 If the create flag is set to 1, the room is created (unless something
went wrong and an ERROR return is sent), and the server returns OK, but
the session is **not** automatically sent to that room.  The client still
must perform a GOTO command to go to the new room.


 FORG   (FORGet the current room)

 This command is used to forget (zap) the current room.  For those not
familiar with Citadel, this terminology refers to removing the room from
a user's own known rooms list, *not* removing the room itself.  After a
room is forgotten, it no longer shows up in the user's known room list,
but it will exist in the user's forgotten room list, and will return to the
known room list if the user goes to the room (in Citadel, this is
accomplished by explicitly typing the room's name in a <.G>oto command).

 The command takes no arguments.  If the command cannot execute for any
reason, ERROR will be returned.  ERROR+NOT_LOGGED_IN or ERROR+NOT_HERE may
be returned as they apply.

 If the command succeeds, OK will be returned.  At this point, the current
room is **undefined**, and the client software is responsible for taking
the user to another room before executing any other room commands (usually
this will be _BASEROOM_ since it is always there).


 MESG    (read system MESsaGe)

 This command is used to display system messages and/or help files.  The
single argument it accepts is the name of the file to display.  IT IS CASE
SENSITIVE.  Citadel looks for these files first in the "messages"
subdirectory and then in the "help" subdirectory.

 If the file is found, LISTING_FOLLOWS is returned, followed by a pathname
to the file being displayed.  Then the message is printed, in format type 0
(see MSG0 command for more information on this).  If the file is not found,
ERROR is returned.

 There are some "well known" names of system messages which client software
may expect most servers to carry:

 hello        -  Welcome message, to be displayed before the user logs in.
 changepw     -  To be displayed whenever the user is prompted for a new
                 password.  Warns about picking guessable passwords and such.
 register     -  Should be displayed prior to the user entering registration.
                 Warnings about not getting access if not registered, etc.
 help         -  Main system help file.
 goodbye      -  System logoff banner; display when user logs off.
 roomaccess   -  Information about how public rooms and different types of
                 private rooms function with regards to access.
 unlisted     -  Tells users not to choose to be unlisted unless they're
                 really paranoid, and warns that aides can still see
                 unlisted userlog entries.

 Citadel provides these for the Citadel Unix text client.  They are
probably not very useful for other clients:

 mainmenu     -  Main menu (when in idiot mode).
 aideopt      -  .A?
 readopt      -  .R?
 entopt       -  .E?
 dotopt       -  .?
 saveopt      -  Options to save a message, abort, etc.
 entermsg     -  Displayed just before a message is entered, when in
                 idiot mode.


 GNUR   (Get Next Unvalidated User)

 This command shows the name of a user that needs to be validated.  If there
are no unvalidated users, OK is returned.  Otherwise, MORE_DATA is returned
along with the name of the first unvalidated user the server finds.  All of
the usual ERROR codes may be returned as well (for example, if the user is
not an Aide and cannot validate users).

 A typical "Validate New Users" command would keep executing this command,
and then validating each user it returns, until it returns OK when all new
users have been validated.


 GREG   (Get REGistration for user)

 This command retrieves the registration info for a user, whose name is the
command's sole argument.  All the usual error messages can be returned.  If
the command succeeds, LISTING_FOLLOWS is returned, followed by the user's name
(retrieved from the userlog, with the right upper and lower case etc.)  The
contents of the listing contains one field per line, followed by the usual
000 on the last line.

 The following lines are defined.  Others WILL be added in the futre, so all
software should be written to read the lines it knows about and then ignore
all remaining lines:

 Line 1:  User number
 Line 2:  Password
 Line 3:  Real name
 Line 4:  Street address or PO Box
 Line 5:  City/town/village/etc.
 Line 6:  State/province/etc.
 Line 7:  ZIP Code
 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
name as the argument, or the string "_SELF_".  The command will always
succeed when used in this manner, unless no user is logged in.


 VALI   (VALIdate user)

 This command is used to validate users.  Obviously, it can only be executed
by users with Aide level access.  It should be passed two parameters: the
name of the user to validate, and the desired access level

 If the command succeeds, OK is returned.  The user's access level is changed
and the "need validation" bit is cleared.  If the command fails for any
reason, ERROR, ERROR+NO_SUCH_USER, or ERROR+HIGHER_ACCESS_REQUIRED will be
returned.


 EINF   (Enter INFo file for room)

 Transmit the info file for the current room with this command.  EINF uses
a boolean flag (1 or 0 as the first and only argument to the command) to
determine whether the client actually wishes to transmit a new info file, or
is merely checking to see if it has permission to do so.

 If the command cannot succeed, it returns ERROR.
 If the client is only checking for permission, and permission will be
granted, OK is returned.
 If the client wishes to transmit the new info file, SEND_LISTING is
returned, and the client should transmit the text of the info file, ended
by the usual 000 on a line by itself.


 LIST   (user LISTing)

 This is a simple user listing.  It always succeeds, returning
LISTING_FOLLOWS followed by zero or more user records, 000 terminated.  The
fields on each line are as follows:

 1. User name
 2. Access level
 3. User number
 4. Date/time of last login (Unix format)
 5. Times called
 6. Messages posted
 7. Password (listed only if the user requesting the list is an Aide)

 Unlisted entries will also be listed to Aides logged into the server, but
not to ordinary users.
 
 The LIST command accepts an optional single argument, which is a simple,
case-insensitive search string.  If this argument is present, only usernames
in which the search string is present will be returned.  It is a simple
substring search, not a regular expression search.  If this string is empty
or not present, all users will be returned.


 REGI   (send REGIstration)

 Clients will use this command to transmit a user's registration info.  If
no user is logged in, ERROR+NOT_LOGGED_IN is returned.  Otherwise,
SEND_LISTING is returned, and the server will expect the following information
(terminated by 000 on a line by itself):

 Line 1:  Real name
 Line 2:  Street address or PO Box
 Line 3:  City/town/village/etc.
 Line 4:  State/province/etc.
 Line 5:  ZIP Code
 Line 6:  Telephone number
 Line 7:  e-mail address
 Line 8:  Country


 CHEK   (CHEcK various things)

 When logging in, there are various things that need to be checked.   This
command will return ERROR+NOT_LOGGED_IN if no user is logged in.  Otherwise
it returns OK and the following parameters:

 0: Number of new private messages in Mail>
 1: Nonzero if the user needs to register
 2: (Relevant to Aides only) Nonzero if new users require validation
 3: The user's preferred Internet e-mail address


 DELF   (DELete a File)

 This command deletes a file from the room's directory, if there is one.  The
name of the file to delete is the only parameter to be supplied.  Wildcards
are not acceptable, and any slashes in the filename will be converted to
underscores, to prevent unauthorized access to neighboring directories.  The
possible return codes are:

 OK                            -  Command succeeded.  The file was deleted.
 ERROR+NOT_LOGGED_IN           -  Not logged in.
 ERROR+HIGHER_ACCESS_REQUIRED  -  Not an Aide or Room Aide.
 ERROR+NOT_HERE                -  There is no directory in this room.
 ERROR+FILE_NOT_FOUND          -  Requested file was not found.


 MOVF   (MOVe a File)

 This command is similar to DELF, except that it moves a file (and its
associated file description) to another room.  It should be passed two
parameters: the name of the file to move, and the name of the room to move
the file to.  All of the same return codes as DELF may be returned, and also
one additional one: ERROR+NO_SUCH_ROOM, which means that the target room
does not exist.  ERROR+NOT_HERE could also mean that the target room does
not have a directory.


 NETF   (NETwork send a File)

 This command is similar to MOVF, except that it attempts to send a file over
the network to another system.  It should be passed two parameters: the name
of the file to send, and the node name of the system to send it to.  All of
the same return codes as MOVF may be returned, except for ERROR+NO_SUCH_ROOM.
Instead, ERROR+NO_SUCH_SYSTEM may be returned if the name of the target
system is invalid.

 The name of the originating room will be sent along with the file.  Most
implementations will look for a room with the same name at the receiving end
and attempt to place the file there, otherwise it goes into a bit bucket room
for miscellaneous files.  This is, however, beyond the scope of this document;
see elsewhere for more details.


 RWHO   (Read WHO's online)

 Displays a list of all users connected to the server.  No error codes are
ever returned.  LISTING_FOLLOWS will be returned, followed by zero or more
lines containing the following three fields:

 0 - Session ID.  Citadel fills this with the pid of a server program.
 1 - User name.
 2 - The name of the room the user is currently in.  This field might not
be displayed (for example, if the user is in a private room) or it might
contain other information (such as the name of a file the user is
downloading).
 3 - (server v4.03 and above) The name of the host the client is connecting
from, or "localhost" if the client is local.
 4 - (server v4.04 and above) Description of the client software being used
 5 - The last time, locally to the server, that a command was received from
     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).
 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.
 11 - Nonzero if the session is a logged-in user, zero otherwise.

 The listing is terminated, as always, with the string "000" on a line by
itself.


 OPEN   (OPEN a file for download)

 This command is used to open a file for downloading.  Only one download
file may be open at a time.  The only argument to this command is the name
of the file to be opened.  The user should already be in the room where the
file resides.  Possible return codes are:

 ERROR+NOT_LOGGED_IN
 ERROR+NOT_HERE                (no directory in this room)
 ERROR+FILE_NOT_FOUND          (could not open the file)
 ERROR                         (misc errors)
 OK                            (file is open)

 If the file is successfully opened, OK will be returned, along with the
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 command is used to close the download file.  It returns OK if the
file was successfully closed, or ERROR if there wasn't any file open in the
first place.


 READ   (READ from the download file)

 Two arguments are passed to this command.  The first is the starting position
in the download file, and the second is the total number of bytes to be
read.  If the operation can be performed, BINARY_FOLLOWS will be returned,
along with the number of bytes to follow.  Then, immediately following the
newline, will be that many bytes of binary data.  The client *must* read
exactly that number of bytes, otherwise the client and server will get out
of sync.

 If the operation cannot be performed, any of the usual error codes will be
returned.


 UOPN   (OPeN a file for Uploading)

 This command is similar to OPEN, except that this one is used when the
client wishes to upload a file to the server.  The first argument is the name
of the file to create, and the second argument is a one-line comment
describing the contents of the file.  Only one upload file may be open at a
time.  Possible return codes are:

 ERROR+NOT_LOGGED_IN
 ERROR+NOT_HERE               (no directory in this room)
 ERROR+FILE_NOT_FOUND         (a name must be specified)
 ERROR                        (miscellaneous errors)
 ERROR+ALREADY_EXISTS         (a file with the same name already exists)
 OK

 If OK is returned, the command has succeeded and writes may be performed.


 UCLS   (CLoSe the Upload file)

 Close the file opened with UOPN.  An argument of "1" should be passed to
this command to close and save the file; otherwise, the transfer will be
considered aborted and the file will be deleted.  This command returns OK
if the operation succeeded or ERROR if it did not.


 WRIT   (WRITe to the upload file)

 If an upload file is open, this command may be used to write to it.  The
argument passed to this command is the number of bytes the client wishes to
transmit.  An ERROR code will be returned if the operation cannot be
performed.

 If the operation can be performed, SEND_BINARY will be returned, followed
by the number of bytes the server is expecting.  The client must then transmit
exactly that number of bytes.  Note that in the current implementation, the
number of bytes the server is expecting will always be the number of bytes
the client requested to transmit, but the client software should never assume
that this will always happen, in case changes are made later.


 QUSR   (Query for a USeR)

 This command is used to check to see if a particular user exists.  The only
argument to this command is the name of the user being searched for.  If
the user exists, OK is returned, along with the name of the user in the userlog
(so the client software can learn the correct upper/lower casing of the name
if necessary).  If the user does not exist, ERROR+NO_SUCH_USER is returned.
No login or current room is required to utilize this command.


 OIMG   (Open an IMaGe file)

 Open an image (graphics) file for downloading.  Once opened, the file can be
read as if it were a download file.  This implies that an image and a download
cannot be opened at the same time.  OIMG returns the same result codes as OPEN.

 All images will be in GIF (Graphics Interchange Format).  In the case of
Citadel, the server will convert the supplied filename to all lower case,
append the characters ".gif" to the filename, and look for it in the "images"
subdirectory.  As with the MESG command, there are several "well known"
images which are likely to exist on most servers:

 hello        - "Welcome" graphics to be displayed alongside MESG "hello"
 goodbye      - Logoff banner graphics to be displayed alongside MESG "goodbye"
 background   - Background image (usually tiled) for graphical clients

 The following "special" image names are defined in Citadel server version
5.00 and above:

 _userpic_    - Picture of a user (send the username as the second argument)
 _floorpic_   - A graphical floor label (send the floor number as the second
                argument).  Clients which request a floor picture will display
                the picture *instead* of the floor name.
 _roompic_    - A graphic associated with the *current* room.  Clients which
                request a room picture will display the picture in *addition*
                to the room name (i.e. it's used for a room banner, as
                opposed to the floor picture's use in a floor listing).


 NETP   (authenticate as network session with connection NET Password)

 This command is used by client software to identify itself as a transport
session for Citadel site-to-site networking.  It should be called with
two arguments: the node name of the calling system, and the "shared secret"
password for that connection.  If the authentication succeeds, NETP will
return OK, otherwise, it returns ERROR.

 
 NSYN   (Network SYNchronize room)
 
 This command can be used to synchronize the contents of a room on the
network.  It is only usable by Aides.  It accepts one argument: the name of
a network node (which must be a valid one).
 
 When NSYN is run, the *entire* contents of the current room will be spooled
to the specified node, without regard to whether any of the messages have
already undergone network processing.  It is up to the receiving node to
check for duplicates (the Citadel networker does handle this) and avoid
posting them twice.
 
 The command returns OK upon success or ERROR if the user is not an Aide.
  
 
 NUOP   (Network Upload OPen file)

 Open a network spool file for uploading.  The client must have already
identified itself as a network session using the NETP command.  If the command
returns OK, the client may begin transmitting IGnet/Open spool data using
a series of WRIT commands.  When a UCLS command is issued, the spooled data
is entered into the server if the argument to UCLS is 1 or discarded if the
argument to UCLS is 0.  If the client has not authenticated itself with a
NETP command, ERROR+HIGHER_ACCESS_REQUIRED will be returned.


 NDOP   (Network Download OPen file)

 Open a network spool file for downloading.  The client must have already
identified itself as a network session using the NETP command.  If the command
returns OK, the client may begin receiving IGnet/Open spool data using
a series of READ commands.  When a CLOS command is issued, the spooled data
is deleted from the server and may not be read again.  If the client has not
authenticated itself with a NETP command, ERROR+HIGHER_ACCESS_REQUIRED will
be returned.


 LFLR   (List all known FLooRs)

 On systems supporting floors, this command lists all known floors.  The
command accepts no parameters.  It will return ERROR+NOT_LOGGED_IN if no
user is logged in.  Otherwise it returns LISTING_FOLLOWS and a list of
the available floors, each line consisting of three fields:

 1. The floor number associated with the floor
 2. The name of the floor
 3. Reference count (number of rooms on this floor)


 CFLR   (Create a new FLooR)

 This command is used to create a new floor.  It should be passed two
arguments: the name of the new floor to be created, and a 1 or 0 depending
on whether the client is actually creating a floor or merely checking to
see if it has permission to create the floor.   The user must be logged in
and have Aide privileges to create a floor.

 If the command succeeds, it will return OK followed by the floor number
associated with the new floor.  Otherwise, it will return ERROR (plus perhaps
HIGHER_ACCESS_REQUIRED, ALREADY_EXISTS, or INVALID_FLOOR_OPERATION)
followed by a description of why the command failed.


 KFLR   (Kill a FLooR)

 This command is used to delete a floor.  It should be passed two
argument: the *number* of the floor to be deleted, and a 1 or 0 depending
on whether the client is actually deleting the floor or merely checking to
see if it has permission to delete the floor.  The user must be logged in
and have Aide privileges to delete a floor.

 Floors that contain rooms may not be deleted.  If there are rooms on a floor,
they must be either deleted or moved to different floors first.  This implies
that the Main Floor (floor 0) can never be deleted, since Lobby>, Mail>, and
Aide> all reside on the Main Floor and cannot be deleted.

 If the command succeeds, it will return OK.  Otherwise it will return
ERROR (plus perhaps HIGHER_ACCESS_REQUIRED or INVALID_FLOOR_OPERATION)
followed by a description of why the command failed.


 EFLR   (Edit a FLooR)

 Edit the parameters of a floor.  The client may pass one or more parameters
to this command:

 1. The number of the floor to be edited
 2. The desired new name

 More parameters may be added in the future.  Any parameters not passed to
the server will remain unchanged.  A minimal command would be EFLR and a
floor number -- which would do nothing.  EFLR plus the floor number plus a
floor name would change the floor's name.

 If the command succeeds, it will return OK.  Otherwise it will return
ERROR (plus perhaps HIGHER_ACCESS_REQUIRED or INVALID_FLOOR_OPERATION)


IDEN (IDENtify the client software)

 The client software has the option to identify itself to the server.
Currently, the server does nothing with this information except to write
it to the syslog to satisfy the system administrator's curiosity.  Other
uses might become apparent in the future.

 The IDEN command should contain five fields: a developer ID number (same as
the server developer ID numbers in the INFO command -- please obtain one if
you are a new developer), a client ID number (which does not have to be
globally unique - only unique within the domain of the developer number),
a version number, a free-form text string describing the client, and the name
of the host the user is located at.

 It is up to the server to determine whether to accept the host name or to
use the host name it has detected itself.  Generally, if the client is
running on a trusted host (either localhost or a well-known publically
accessible client) it should use the host name transmitted by IDEN,
otherwise it should use the host name it has detected itself.

 IDEN always returns OK, but since that's the only way it ever returns
there's no point in checking the result code.


IPGM (identify as an Internal ProGraM)

 IPGM is a low-level command that should not be used by normal user clients.
It is used for various utilities to communicate with the server on the same
host.  For example, the "sendcommand" utility logs onto the server as an
internal program in order to run arbitrary server commands.  Since user clients
do not utilize this command (or any of its companion commands), developers
writing Citadel-compatible servers need not implement it.

 The sole argument to IPGM is the system's internal program password.  This
password is generated by the setup program and stored in the config file.
Since internal programs have access to the config file, they know the correct
password to use.

 IPGM returns OK for a correct authentication or ERROR otherwise.


CHAT (enter CHAT mode)

 This command functions differently from every other command in the system.  It
is used to implement multi-user chat.  For this to function, a new transfer
mode, called START_CHAT_MODE, is implemented.  If a client does not support
chat mode, it should never send a CHAT command!

 In chat mode, messages may arrive asynchronously from the server at any
time.  The client may send messages at any time.  This allows the arrival of
messages without the client having to poll for them.  Arriving messages will
be of the form  "user|message", where the "user" portion is, of course, the
name of the user sending the message, and "message" is the message text.

 Chat mode ends when the server says it ends.  The server will signal the end
of chat mode by transmitting "000" on a line by itself.  When the client reads
this line, it must immediately exit from chat mode without sending any
further traffic to the server.  The next transmission sent to the server
will be a regular server command.

 The Citadel server understands the following commands:
 /quit   -   Exit from chat mode (causes the server to do an 000 end)
 /who    -   List users currently in chat
 /whobbs -   List users currently in chat and elsewhere
 /me     -   Do an irc-style action.
 /join   -   Join a new "room" in which all messages are only heard by
             people in that room.
 /msg    -   /msg <user> <msg> will send the msg to <user> only.
 /help   -   Print help information
 NOOP    -   Do nothing (silently)

 Any other non-empty string is treated as message text and will be broadcast
to other users currently in chat.


 SEXP   (Send instant message)

 This is one of two commands which implement instant messages (also known
as "paging").  Commands ending in "...EXP" are so-named because we called
them "express messages" before the industry standardized on the term
"instant messages."  When an instant message is sent, it will be
logged in user to another.  When an instant message is sent, it will be
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
transmitted, OK is returned.  If the target user is not logged in or if
anything else goes wrong, ERROR is returned.

 If the server supports extended paging, sending a zero-length message
merely checks for the presence of the requested user without actually sending
a message.  Sending a message consisting solely of a "-" (hyphen) will cause
the server to return SEND_LISTING if the requested user is logged in, and the
client can then transmit a multi-line page.

 The reserved name "broadcast" may be used instead of a user name, to
broadcast an instant message to all users currently connected to the server.

 Do be aware that if an instant message is transmitted to a user who is logged
in using a client that does not check for instant messages, the message will
never be received.  Also, instant messages are NOT sent via the following
transports:  SMTP, POP3.


 PEXP   (Print instant messages)   ***DEPRECATED***

 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 instant messages.  It returns ERROR if there is a problem,
otherwise it returns LISTING_FOLLOWS followed by all messages.

 So how does the client know there are instant messages waiting?  It could
execute a random PEXP 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 instant messages.


 EBIO   (Enter BIOgraphy)

 Transmit to the server a free-form text file containing a little bit of
information about the user for other users to browse.  This is typically
referred to as a 'bio' online.  EBIO returns SEND_LISTING if it succeeds,
after which the client is expected to transmit the file, or any of the usual
ERROR codes if it fails.


 RBIO   (Read BIOgraphy)

 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.
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)

 When in "stealth mode," a user will not show up in the "Who is online"
listing (the RWHO server command).  Only Aides may use stealth mode.  The
STEL command accepts one argument: a 1 indicating that the user wishes to
enter stealth mode, or a 0 indicating that the user wishes to exit stealth
mode.  STEL returns OK if the command succeeded, ERROR+NOT_LOGGED_IN if no
user is logged in, or ERROR+HIGHER_ACCESS_REQUIRED if the user is not an Aide;
followed by a 1 or 0 indicating the new state.

 If any value other than 1 or 0 is sent by the client, the server simply
replies with 1 or 0 to indicate the current state without changing it.

The STEL command also makes it so a user does not show up in the chat room
/who.


 LBIO   (List users who have BIOs on file)

 This command is self-explanatory.  Any user who has used EBIO to place a bio
on file is listed.  LBIO almost always returns LISTING_FOLLOWS followed by
this listing, unless it experiences an internal error in which case ERROR
is returned.


 MSG2   (read MeSsaGe, mode 2)

 MSG2 follows the same calling convention as MSG0.  The difference between
the two commands is that MSG2 outputs messages in standard RFC822 format
rather than in Citadel proprietary format.

 This command was implemented in order to make various gateway programs
easier to implement, and to provide some sort of multimedia support in the
future.  Keep in mind that when this command is used, all messages will be
output in fixed 80-column format.


 MSG3   (read MeSsaGe, mode 3 -- internal command)

 MSG3 is for use by internal programs only and should not be utilized by
user-mode clients.  It does require IPGM authentication.  MSG3 follows the
same calling convention as the other MSG commands, but upon success returns
BINARY_FOLLOWS followed by a data block containing the _raw_ message format
on disk.


 TERM   (TERMinate another session)

 In a multithreaded environment, it sometimes becomes necessary to terminate
a session that is unusable for whatever reason.  The TERM command performs
this task.  Naturally, only Aides can execute TERM.  The command should be
called with a single argument: the session ID (obtained from an RWHO command)
of the session to be terminated.

 TERM returns OK if the session was terminated, or ERROR otherwise.  Note that
a client program is prohibited from terminating the session it is currently
running on.

 See also: REQT


 DOWN   (shut DOWN the server)

 This command, which may only be executed by an Aide, immediately shuts down
the server.  It is only implemented on servers on which such an operation is
possible, such as a multithreaded Citadel engine.  The server does not restart.
DOWN returns OK if the user is allowed to shut down the server, in which case
the client program should expect the connection to be immediately broken.


 SCDN   (Schedule or Cancel a shutDowN)

 SCDN sets or clears the "scheduled shutdown" flag.  Pass this command a 1 or
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.


 HALT   (HALT the server without shutting it down)
 
 Identical to the DOWN command, except instead of exiting, the server process
cleans up and then suspends indefinitely.  This could potentially be useful for
shutdown scripts that don't want init to automatically respawn another citserver
process.


 EMSG   (Enter a system MeSsaGe)

 This is the opposite of the MESG command - it allows the creation and editing
of system messages.  The only argument passed to EMSG is the name of the
file being transmitted.  If the file exists in any system message directory
on the server it will be overwritten, otherwise a new file is created.  EMSG
returns SEND_LISTING on success or ERROR+HIGHER_ACCESS_REQUIRED if the user
is not an Aide.

 Typical client software would use MESG to retrieve any existing message into
an edit buffer, then present an editor to the user and run EMSG if the changes
are to be saved.


 UIMG   (Upload an IMaGe file)

 UIMG is complemenary to OIMG; it is used to upload an image to the server.
The first parameter supplied to UIMG should be 0 if the client is only checking
for permission to upload, or 1 if the client is actually attempting to begin
the upload operation.  The second argument is the name of the file to be
transmitted.  In Citadel, the filename is converted to all lower case,
appended with the characters ".gif", and stored in the "images" directory.

 UIMG returns OK if the client has permission to perform the requested upload,
or ERROR+HIGHER_ACCESS_REQUIRED otherwise.  If the client requested to begin
the operation (first parameter set to 1), an upload file is opened, and the
client should begin writing to it with WRIT commands, then close it with a
UCLS command.

 The supplied filename should be one of:

 ->  _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.


 HCHG   (Hostname CHanGe)

 HCHG is a command, usable by any user, that allows a user to change their RWHO
host value.  This will mask a client's originating hostname from normal
users; access level 6 and higher can see, in an extended wholist, the actual
hostname the user originates from.

 The format of an HCHG command is:

 HCHG <name>

 If a HCHG command is successful, the value OK (200) is returned.


 RCHG   (Roomname CHanGe)

 RCHG is a command, usable by any user, that allows a user to change their RWHO
room value.  This will mask a client's roomname from normal users; access
level 6 and higher can see, in an extended wholist, the actual room the user
is in.

 The format of an RCHG command is:

 RCHG <name>

 If a RCHG command is successful, the value OK (200) is returned.


 UCHG   (Username CHanGe)

 UCHG is an aide-level command which allows an aide to effectively change their
username.  If this value is blank, the user goes into stealth mode (see
STEL).  Posts
will show up as being from the real username in this mode, however.  In
addition, the RWHO listing will include both the spoofed and real usernames.

 The format of an UCHG command is:

 UCHG <name>

 If a UCHG command is successful, the value OK (200) is returned.


 TIME   (get server local TIME)

 TIME returns OK followed by the current time measured in seconds since
00:00:00 GMT, Jan 1, 1970 (standard Unix format).

 This is used in allowing a client to calculate idle times.


 AGUP   (Administrative Get User Parameters)
 ASUP   (Administrative Set User Parameters)

 These commands are only executable by Aides and by server extensions running
at system-level.  They are used to get/set any and all parameters relating to
a user account.  AGUP requires only one argument: the name of the user in
question.  SGUP requires all of the parameters to be set.  The parameters are
as follows, and are common to both commands:

 0 - User name
 1 - Password
 2 - Flags (see citadel.h)
 3 - Times called
 4 - Messages posted
 5 - Access level
 6 - User number
 7 - Timestamp of last call
 8 - Purge time (in days) for this user (or 0 to use system default)

 Upon success, AGUP returns OK followed by all these parameters, and ASUP
simply returns OK.  If the client has insufficient access to perform the
requested operation, ERROR+HIGHER_ACCESS_REQUIRED is returned.  If the
requested user does not exist, ERROR+NO_SUCH_USER is returned.



 GPEX   (Get Policy for message EXpiration)

 Returns the policy of the current room, floor, or site regarding the automatic
purging (expiration) of messages.  The following policies are available:
   0  -  Fall back to the policy of the next higher level.  If this is a room,
         use the floor's default policy.  If this is a floor, use the system
         default policy.  This is an invalid value for the system policy.
   1  -  Do not purge messages automatically.
   2  -  Purge by message count.  (Requires a value: number of messages)
   3  -  Purge by message age.  (Requires a value: number of days)

 The format of this command is:  GPEX <which>
 The value of <which> must be one of: "room" "floor" "site" "mailboxes"

 If successful, GPEX returns OK followed by <policy>|<value>.



 SPEX   (Set Policy for message EXpiration)

 Sets the policy of the current room, floor, or site regarding the automatic
purging (expiration) of messages.  See the writeup for the GPEX command for
the list of available policies.

 The format of this command is:  SPEX <which>|<policy>|<value>
 The value of <which> must be one of: "room" "floor" "site" "mailboxes"

 If successful, GPEX returns OK; otherwise, an ERROR code is returned.



 CONF   (get or set global CONFiguration options)

 Retrieves or sets various system-wide configuration and policy options.  This
command is only available to Aides.  The sole parameter accepted is a command,
which should be either GET or SET.  If the GET command succeeds, CONF will
return LISTING_FOLLOWS followed by the fields described below, one line at a
time.  If the SET command succeeds, CONF will return SEND_LISTING and expect
the fields described below, one line at a time (don't worry about other fields
being added in the future; if a 'short' configuration list is sent, the missing
values at the end will be left unchanged on the system).  If either command
fails for any reason, ERROR is returned.

 The configuration lines are as follows:

 0. Node name
 1. Fully qualified domain name
 2. Human-readable node name
 3. Landline telephone number of this system
 4. Flag (0 or 1) - creator of private room automatically becomes room aide
 5. Server connection idle timeout (in seconds)
 6. Initial access level for new users
 7. Flag (0 or 1) - require registration for new users
 8. Flag (0 or 1) - automatically move Problem User messages to twit room
 9. Name of twit room
 10. Text of <more> prompt
 11. Flag (0 or 1) - restrict access to Internet mail
 12. Geographic location of this system
 13. Name of the system administrator
 14. Number of maximum concurrent sessions allowed on the server
 15. (placeholder -- this field is no longer in use)
 16. Default purge time (in days) for users
 17. Default purge time (in days) for rooms
 18. Name of room to log instant messages to (or a zero-length name for none)
 19. Access level required to create rooms
 20. Maximum message length which may be entered into the system
 21. Minimum number of worker threads
 22. Maximum number of worker threads
 23. Port number for POP3 service
 24. Port number for SMTP service
 25. Flag (0 or 1) - strict RFC822 adherence - don't correct From: forgeries
 26. Flag (0 or 1) - allow Aides to zap (forget) rooms
 27. Port number for IMAP service
 28. How often (in seconds) to run the networker
 29. Flag (0 or 1) - disable self-service new user registration
 30. (placeholder -- this field is no longer in use)
 31. Hour (0 through 23) during which database auto-purge jobs are run
 32. Name of host where an LDAP service may be found
 33. Port number of LDAP service on above host
 34. LDAP Base DN
 35. LDAP Bind DN
 36. Password for LDAP Bind DN
 37. Server IP address to listen on (or "0.0.0.0" for all addresses)
 38. Port number for SMTP MSA service
 39. Port number for IMAPS (SSL-encrypted IMAP)
 40. Port number for POP3S (SSL-encrypted POP3)
 41. Port number for SMTPS (SSL-encrypted SMTP)
 42. Flag (0 or 1) - enable full text search index
 43. Flag (0 or 1) - automatically cull database log files
 44. Flag (0 or 1) - enable IMAP "instant expunge" of deleted messages
 45. Flag (0 or 1) - allow unauthenticated SMTP clients to spoof my domains
 46. Flag (0 or 1) - perform journaling of email messages
 47. Flag (0 or 1) - perform journaling of non-email messages
 48. Address to which journalized messages are to be sent
 49. Default time zone (Olsen database name) for unzoned calendar items
 50. Port number for Postfix TCP Dict (http://www.postfix.org/tcp_table.5.html)

 CONF also accepts two additional commands: GETSYS and PUTSYS followed by an
arbitrary MIME type (such as application/x-citadel-internet-config) which
provides a means of storing generic configuration data in the Global System
Configuration room without the need to add extra get/set commands to the
server.
 
 Please note that the LDAP-specific configs have no effect on Citadel servers
in which LDAP support is not enabled.



 MSG4   (read MeSsaGe, mode 4 -- output in preferred MIME format)

 This is the equivalent of MSG0, except it's a bit smarter about messages in
rich text formats.  Immediately following the "text" directive, the server
will output RFC822-like MIME part headers such as "Content-type:" and
"Content-length:".  MIME formats are chosen and/or converted based on the
client's preferred format settings, which are set using the MSGP command,
described below.
 
 The MSG4 command also accepts an optional second argument, which may be the
MIME part specifier of an encapsulated message/rfc822 message.  This is useful
for fetching the encapsulated message instead of the top-level message, for
example, when someone has forwarded a message as an attachment.  Note that the
only way for the client to know the part specifier is to fetch the top-level
message and then look for attachments of type message/rfc822, and then call
MSG4 again with that part specifier.




 MSGP   (set MeSsaGe Preferred MIME format)

 Client tells the server what MIME content types it knows how to handle, and
the order in which it prefers them.  This is similar to an HTTP "Accept:"
header.

 The parameters to a MSGP command are the client's acceptable MIME content
types, in the order it prefers them (from most preferred to least preferred).
For example:  MSGP text/html|text/plain

 The MSGP command always returns OK.



 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 instant messages)

 This is a more sophisticated way of retrieving instant messages than the old
PEXP method.  If there are no instant 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
     instant 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 instant message.

 So how does the client know there are instant 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 instant 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 receiving instant messages)

 DEXP sets or clears the "disable instant messages" flag.  Pass this command a
1 or 0 to respectively set or clear the flag.  When the "disable instant
messages" flag is set, no one except Aides may send the user instant 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.


 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 instant 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.


 GTSN   (GeT the list of SeeN messages)

 This command retrieves the list of "seen" (as opposed to unread) messages for
the current room.  It returns OK followed by an IMAP-format message list.


 SMTP   (utility commands for the SMTP gateway)

 This command, accessible only by Aides, supports several utility operations
which examine or manipulate Citadel's SMTP support.  The first command argument
is a subcommand telling the server what to do.  The following subcommands are
supported:

      SMTP mx|hostname             (display all MX hosts for 'hostname')
      SMTP runqueue                (attempt immediate delivery of all messages
                                    in the outbound SMTP queue, ignoring any
                                    retry times stored there)


 STLS   (Start Transport Layer Security)

 This command starts TLS on the current connection.  The current
implementation uses OpenSSL on both the client and server end.  For future
compatibility all clients must support at least TLSv1, and servers are
guaranteed to support TLSv1.  During TLS negotiation (see below) the server
and client may agree to use a different protocol.

 The server returns ERROR if it does not support SSL or SSL initialization
failed on the server; otherwise it returns OK.  Once the server returns OK and
the client has read the response, the server and client immediately negotiate
TLS (in OpenSSL, using SSL_connect() on the client and SSL_accept() on the
server).  If negotiation fails, the server and client should attempt to resume
the session unencrypted.  If either end is unable to resume the session, the
connection should be closed.

 This command may be run at any time.


 GTLS   (Get Transport Layer Security Status)

 This command returns information about the current connection.  The server
returns OK plus several parameters if the connection is encrypted, and ERROR
if the connection is not encrypted.  It is primarily used for debugging.  The
command may be run at any time.

 0 - Protocol name, e.g. "SSLv3"
 1 - Cipher suite name, e.g. "ADH-RC4-MD5"
 2 - Cipher strength bits, e.g. 128
 3 - Cipher strength bits actually in use, e.g. 128


 IGAB   (Initialize Global Address Book)

 This command creates, or re-creates, a database of Internet e-mail addresses
using the vCard information in the Global Address Book room.  This procedure
is normally run internally when the server determines it necessary, but is
also provided as a server command to be used as a troubleshooting/maintenenance
tool.  Only a system Aide can run the command.  It returns OK on success or
ERROR on failure.


 QDIR   (Query global DIRectory)

 Look up an internet address in the global directory.  Any logged-in user may
call QDIR with one parameter, the Internet e-mail address to look up.  QDIR
returns OK followed by a Citadel address if there is a match, otherwise it
returns ERROR+NOT_LOGGED_IN.


 ISME   (find out if an e-mail address IS ME)

 This is a quickie shortcut command to find out if a given e-mail address
belongs to the user currently logged in.  Its sole argument is an address to
parse.  The supplied address may be in any format (local, IGnet, or Internet).
The command returns OK if the address belongs to the user, ERROR otherwise.


 VIEW   (set the VIEW for a room)

 Set the preferred view for the current user in the current room.  Please see
views.txt for more information on views.  The sole parameter for this command
is the type of view requested.  VIEW returns OK on success or ERROR on failure.


 QNOP   (Quiet No OPeration)

 This command does nothing, similar to the NOOP command.  However, unlike the
NOOP command, it returns *absolutely no response* at all.  The client has no
way of knowing that the command executed.  It is intended for sending
"keepalives" in situations where a full NOOP would cause the client protocol
to get out of sync.

 Naturally, sending this command to a server that doesn't support it is an
easy way to mess things up.  Therefore, client software should first check
the output of an INFO command to ensure that the server supports quiet noops.



 ICAL   (Internet CALendaring commands)

 This command supports a number of subcommands which are used to process the
calendaring/scheduling support in Citadel.  Here are the subcommands which
may be issued:

 ICAL test
  Test server for calendaring support.  Always returns OK unless the server
  does not have the calendar module enabled.

 ICAL respond|msgnum|partnum|action
  Respond to a meeting request.  'msgnum' and 'partnum' refer to a MIME-encoded
  meeting invitation in the current room.  'action' must be set to either
  "accept" or "decline" to determine the action to take.  This subcommand will
  return either OK or ERROR.

 ICAL conflicts|msgnum|partnum
  Determine whether an incoming VEVENT will fit in the user's calendar by
  checking it against the existing VEVENTs.  'msgnum' and 'partnum' refer to
  a MIME-encoded meeting invitation in the current room (usually the inbox).
  This command may return ERROR if something went wrong, but usually it will
  return LISTING_FOLLOWS followed by a list of zero or more conflicting
  events.  A zero-length list means that there were no conflicts.
 
 ICAL handle_rsvp|msgnum|partnum
  Handle an incoming "reply" (or RSVP) to a meeting request you sent out.
  'msgnum' and 'partnum' refer to a MIME-encoded reply in the current room.
  'action' must be set to either "update" or "ignore" to determine the action
  to take.  If the action is "update" then the server will hunt for the meeting
  in the user's Calendar> room, and update the status for this attendee.  Either
  way, the reply message is deleted from the current room.  This subcommand will
  return either OK or ERROR.
 
 ICAL freebusy|username
  Output the free/busy times for the requested user.  If the user specified
  has a calendar available, this command will return LISTING_FOLLOWS and a
  compound VCALENDAR object.  That object, in turn, will contain VEVENT
  objects that have been stripped of all properties except for the bare
  minimum needed to learn free/busy times (such as DTSTART, DTEND, and
  TRANSP).  If there is no such user, or no calendar available, the usual
  ERROR codes will be returned.
 
 ICAL sgi|<bool>
  Readers who are paying attention will notice that there is no subcommand to
  send out meeting invitations.  This is because that task can be handled
  automatically by the Citadel server.  Issue this command with <bool> set to 1
  to enable Server Generated Invitations.  In this mode, when an event is saved
  to the user's Calendar> room and it contains attendees, Citadel will
  automatically turn the event into calendar REQUEST messages and mail them
  out to all listed attendees.  If for some reason the client needs to disable
  Server Generated Invitations, the command may be sent again with <bool> = 0.
 
 ICAL getics
  Output the contents of the entire calendar (assuming we are in a calendar
  room) as one big data stream.  All of the events (or tasks, etc.) in the room
  are combined into a single VCALENDAR object, which is then serialized and
  transmitted to the client.  This is suitable for subscribing to a calendar
  in third-party software.  This command will output LISTING_FOLLOWS followed
  by the calendar data stream, or ERROR if the requested operation is not
  permitted.
 
 ICAL putics
  Delete the entire contents of a calendar room and replace it with the calendar
  supplied by a client-input data stream.  This is suitable for publishing a
  calendar from third-party software.  This command will output SEND_LISTING and
  then expect the client to transmit the calendar data stream.  Alternatively,
  it will return ERROR if the requested operation is not permitted.



 MRTG   (Multi Router Traffic Grapher)

 Multi Router Traffic Grapher (please see http://www.mrtg.org for more info) is
a tool which creates pretty graphs of network activity, usually collected from
routers using SNMP.  However, its ability to call external scripts has spawned
a small community of people using it to graph anything which can be graphed.
The MRTG command can output Citadel server activity in the format MRTG expects.

 This format is as follows:

 LISTING_FOLLOWS
 Line 1: variable #1
 Line 2: variable #2
 Line 3: uptime of system
 Line 4: name of system
 000

 MRTG accepts two different keywords.  "MRTG users" will return two variables,
the number of connected users and the number of active users.  "MRTG messages"
will return one variable (and a zero in the second field), showing the current
highest message number on the system.  Any other keyword, or a missing keyword,
will cause the MRTG command to return an ERROR code.

 Please get in touch with the Citadel developers if you wish to experiment with
this.



 GNET   (Get NETwork configuration for this room)
 SNET   (Set NETwork configuration for this room)
 
 These commands get/set the network configuration for the current room.  Aide
or Room Aide privileges are required, otherwise an ERROR code is returned.
If the command succeeds, LISTING_FOLLOWS or SEND_LISTING is returned.  The
network configuration for a specific room includes neighbor nodes with whom
the room is shared, and mailing list recipients.  The format of the network
configuration is described in the file "netconfigs.txt".



 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.



 AUTO   (AUTOcompletion of email addresses)
 
 The AUTO command is used by clients which want to request a list of email
recipients whose names or email addresses match a partial string supplied by
the client.  This string is the only parameter passed to this command.  The
command will return ERROR if no user is logged in or if no address book could
be found; otherwise, it returns LISTING_FOLLOWS followed by zero or more
candidate recipients.



 SRCH   (SeaRCH the message base)
 
 This command's implementation is incomplete and will be documented when it
is finished.  The current implementation accepts a search string as its sole
argument, and will respond with LISTING_FOLLOWS followed by a list of
messages (globally, not just in the current room) which contain ALL of the
words in the search string.  If the client desires an "exact phrase" match,
it must then slow-search the text of each returned message for the exact
string.  The client should also compare the returned message numbers against
those which actually exist in the room or rooms being searched.  In
particular, clients should avoid telling the user about messages which exist
only in rooms to which the user does not have access.
 
 Again, keep in mind that this is a temporary implementation and is not
guaranteed to continue to exist in this form.



EUID   (get message number using an EUID)}

 Returns the message number, if present, of the message in the current room
which is indexed using the supplied EUID (exclusive message ID).  There can be
only one message in a room with any given EUID; if another message arrives
with the same EUID, the existing one is replaced.  This makes it possible to
reference things like calendar items using an immutable URL that does not
change even when the message number changes due to an update.

 The format of this command is:  EUID <euid>

 If successful, EUID returns OK followed by a message number.
 If no message exists in the current room with the supplied EUID, the command
returns ERROR+MESSAGE_NOT_FOUND.

 
 
 
 
 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:


 902  (instant message arriving)

 One or more instant messages have arrived for this client.