SESSION LAYER PROTOCOL FOR HALIDEL (c) 1995-1997 by Art Cancro All Rights Reserved (c) 2003 by Mark Smith and Josh Hill INTRODUCTION ------------ This document is a modified version of the "sessions.txt" file from the original Citadel/UX v4.x package. We've taken the protocol as documented by Art Cancro, removed many features that will not be implimented by Halidel (at least in the first release) and have provided more security restrictions on each. IMPORTANT NOTE TO DEVELOPERS! ----------------------------- This note has been left in the document from sessions.txt. We have not done this yet and probably won't. Our modifications, while remaining compliant for the client, will break all sorts of other foward compatability requirements. Halidel is effectively branching from Citadel/UX v4.x and will not try to retain compatability past Phase 1 of the Halidel project. --- Snip --- 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/UX project is Art Cancro . --- Snip --- CONNECTING TO A SERVER ---------------------- The protocols used below the session layer are beyond the scope of this document, but we will briefly cover a few of the currently used methods. Keep in mind that the server program itself does not speak any protocols lower than the session layer. Instead, it reads all input from stdin, and writes all output to stdout. This implies that it is the responsibility of other programs to provide a usable transport to the client programs. One way is to use TCP/IP. Under Unix-like systems this is easily accomplished using the "inetd" superserver program, which can take programs like the Halidel server and offer connections to clients over a TCP or UDP port. See the install documentation (or the inetd documentation from your OS) for information on how to do this. Always use TCP ports for Halidel sessions. Since our session layer assumes a clean, reliable, sequenced connection, the use of UDP would render the server unstable and unusable. Another alternative to inetd (and its successor, xinetd) is the use of tcpserver by D. J. Berstein, part of the ucspi-tcp package available from http://cr.yp.to/ GENERAL INFORMATION ABOUT THE SERVER ------------------------------------ The server is not stateless. Instead, a separate copy of the server program is executed for each client that opens a connection. Since most modern operating systems offer shared code pages, this shouldn't be a problem unless you're running the server on a very old computer or operating system. The session 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.) We do this to allow the server to function over transports which can only handle one session at a time (such as a dialup connection). 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 (included below) 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. #define LISTING_FOLLOWS 100 #define OK 200 #define MORE_DATA 300 #define SEND_LISTING 400 #define ERROR 500 #define BINARY_FOLLOWS 600 #define SEND_BINARY 700 #define START_CHAT_MODE 800 #define INTERNAL_ERROR 10 #define NOT_LOGGED_IN 20 #define CMD_NOT_SUPPORTED 30 #define PASSWORD_REQUIRED 40 #define HIGHER_ACCESS_REQUIRED 50 #define MAX_SESSIONS_EXCEEDED 51 #define NOT_HERE 60 #define INVALID_FLOOR_OPERATION 61 #define NO_SUCH_USER 70 #define FILE_NOT_FOUND 71 #define ROOM_NOT_FOUND 72 #define NO_SUCH_SYSTEM 73 #define ALREADY_EXISTS 74 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. PROTOCOL STATES -------------- The protocol state machine is as follows: Start (TCP Connect) | v ------> Not Logged In------------- | (NLI) ^ | LOUT| | \ | | |USER \LOUT |NEWU | | \ | | v \ | |<---- Not Authenticated - Set Password | (NA) (SP) | | | | |PASS |SETP | | | | v | --------- Logged In <------------- (LI) There are four states: - Not Logged In (NLI) - Not Authenticated (NA) - Logged In (LI) - Set Password (SP) The commands requires to move from one state to the next are listed in the diagram next to the connections between states. In addition to these state transitions, each state has a list of commands that can be used in that given state that does not change the protocol state. Each command as described below will list the states in which it can be used. There are two other codes used below to describe the permissions of a command: - Aide (A) - Room Aide (RA) COMMANDS -------- This is a listing of all the commands that a Halidel server can execute. NOOP (NO OPeration) All States 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) All States This command also does nothing. It simply returns OK followed by whatever its arguments are. QUIT (QUIT) All States Terminate the server connection. This command takes no arguments. It returns OK and closes the connection immediately. LOUT (LogOUT) All States Log out the user without closing the server connection. It always returns OK even if no user is logged in. USER (send USER name) NLI 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 is returned. PASS (send PASSword) NA 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, or if a USER command has not been executed yet, ERROR 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 NEWU (create NEW User account) NLI 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, or ERROR if another user already exists with this name. If OK, it will also return the same parameters that PASS returns. When the new account is created, the default password is set to some value that prevents the user from logging in until it has been changed. SETP (SET new Password) SP, LI 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. LKRN (List Known Rooms with New messages) LI List known rooms with new messages. If the client is not logged in, ERROR 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 */ Other bits may be defined in the future. The listing terminates, as with all listings, with "000" on a line by itself. LKRO (List Known Rooms with Old [no new] messages) LI This follows the same usage and format as LKRN. LZRM (List Zapped RooMs) LI This follows the same usage and format as LKRN and LKRO. LKRA (List All Known Rooms) LI Same format. Lists all known rooms, with or without new messages. LRMS (List all accessible RooMS) LI 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. GETU (GET User configuration) LI This command retrieves the screen dimensions and user options for the currently logged in account. ERROR will be returned if no user is logged in, of course. Otherwise, OK will be returned, followed by three parameters. 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) LI 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). 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) LI 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. Citadel/UX server v4.01 and above, also has two additional reserved room names. "_MAIL_" translates to the system's designated room for e-mail messages, and "_BITBUCKET_" goes to whatever room has been chosen for messages without a home. 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 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. NO_SUCH_ROOM - 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). ...and in server 4.01 and above: 9. The number of new Mail messages the user has (useful for alerting the user to the arrival of new mail during a session) ...and in server 4.03 and above: 10. The floor number this room resides on MSGS (get pointers to MeSsaGeS in this room) LI This command obtains a listing of all the messages in the current room which the client may request. This command may be passed a single parameter: either "all", "old", or "new" to request all messages, only old messages, or new messages. Or it may be passed two parameters: "last" plus a number, in which case that many message pointers will be returned, or "first" plus a number, for the corresponding effect. If no parameters are specified, "all" is assumed. This command can return two possible results. An ERROR code may be returned if no user is currently logged in or if something else went wrong. Otherwise, LISTING_FOLLOWS will be returned, and the listing will consist of zero or more message numbers, one per line. The listing ends, as always, with the string "000" alone on a line by itself. The listed message numbers can be used to request messages from the system. MSG0 (read MeSsaGe, mode 0) LI 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. In server version 4.04 and above, the second argument may be set to either 0 to read the entire message, or 1 to read the headers only. The server should, of course, make sure that the client actually has access to the message being requested before honoring this request. Citadel/UX does so by checking the message number against the contents of the current room. If it's not there, the request is denied. If the request is denied, an ERROR code will be returned. Otherwise, the LISTING_FOLLOWS code will be returned, followed by the contents of the message. The following fields may be sent: type= Formatting type. Currently, there are two defined types. Type 0 is "traditional" Citadel formatting. This means that newlines should be treated as spaces UNLESS the first character on the next line is a space. In other words, only indented lines should generate a newline on the user's screen when the message is being displayed. This allows a message to be formatted to the reader's screen width. It also allows the use of proportional fonts. Type 1 is a simple fixed-format message. The message should be displayed to the user's screen as is, preferably in a fixed-width font that will fit 80 columns on a screen. 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. 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) LI, A, RA 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) LI, NLI? 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 1 - The process ID (pid) of the server program on the host computer Line 2 - The node name of the server BBS Line 3 - Human-readable node name of the server BBS Line 4 - The fully-qualified domain name (FQDN) of the server Line 5 - The name of the server software, i.e. "Citadel/UX 4.00" Line 6 - (The revision level of the server code) * 100 Line 7 - The geographical location of the BBS (for USA: city and state) Line 8 - The name of the system administrator Line 9 - A number identifying the server type (see below) Line 10 - The text of the system's paginator prompt *** 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 BBS 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 and obtain a unique server type code, which can be assigned to your server program. -> If you document what you did in detail, perhaps it can be added to a future release of the Citadel/UX program, so everyone can enjoy it. 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. The server type codes currently defined are: Type Developer ---- --------------------------------------- 0 Art Cancro 1 Brian Ledbetter 2 Matthew Scott 3 Jesse Vincent 4 btx 5 Robert Abatecola SLRP (Set Last-message-Read Pointer) LI This command is used to mark messages as having been read. 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 oto command). The command will return OK if the pointer was set, or ERROR if something went wrong. 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) LI, A, RA 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, or ERROR if it did not. ERROR+HIGHER_ACCESS_REQUIRED may also 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) LI, A, RA 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 apped the room - a non-stupid user can simply un-zap the room to get back in. GETR (GET Room attributes) LI, A 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. ERROR+NOT_HERE - Lobby>, Mail>, and Aide> cannot be edited. 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) (And on server version 4.01 and above ... ) 4. The floor number on which the room resides SETR (SET Room attributes) LI, A 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) (And on server version 4.01 and above, the client may also send ... ) 5. The floor number on which the room should reside *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. 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 LI 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, ERROR if there is no current room, or OK if the command succeeded. Along with OK there will be returned one parameter: the name of the Room Aide. SETA LI, A, RA 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/UX, 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 (No current room, or room cannot be edited. Under Citadel/UX, the Lobby> Mail> and Aide> rooms are non-editable.) OK (Command succeeded.) ENT0 (ENTer message, mode 0) LI 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. 1 - Recipient. This argument is utilized only for private mail messages. It is ignored for public messages. It contains, of course, the name of the recipient 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/UX format type may be used (this will typically be 0; see the MSG0 command above). 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). ERROR - Miscellaneous error. (Explanation probably follows.) 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. Halidel does _NOT_ format text on the server the way that Citadel/UX did. The server makes no changes to the formatting of the text and leaves that tast to the client. DELE (DELEte a message) LI, A, RA Delete a message from the current room. The one argument that should be passed to this command is the message number of the message to be deleted. The return value will be OK if the message was deleted, or an ERROR code. MOVE (MOVE a message to a different room) LI, A, RA in both rooms Move a message to a different room. The two arguments that should be passed to this command are the message number of the message to be deleted, and the name of the target room. If the operation succeeds, the message will be deleted from the current room and moved to the target room. An ERROR code usually means that either the user does not have permission to perform this operation, or that the target room does not exist. KILL (KILL current room) LI, A 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) LI 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") 3 - Password for new room (if it is a type 2 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. If a user creates a Private; invitation only room, they automatically become the Room Aide for that room. FORG (FORGet the current room) LI 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) All States 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/UX 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. ---- Snip ---- Citadel/UX provides these for the Citadel/UX 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. ---- Snip ---- Lame. Will be changed when we start editing the client. GNUR (Get Next Unvalidated User) LI, A 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) LI (A for users other than self.) 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 (fake) 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 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) LI, A 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. LIST (user LISTing) LI 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 Unlisted entries will also be listed to Aides logged into the server, but not to ordinary users. REGI (send REGIstration) LI 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 CHEK (CHEcK various things) LI 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 RWHO (Read WHO's online) LI 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/UX 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. Halidel Changes this to be the idle time of the user. 4 - (server v4.04 and above) Description of the client software being used The listing is terminated, as always, with the string "000" on a line by itself. QUSR (Query for a USeR) (Check if the client uses this. If so, then we impliment. Otherwise, it's gone.) 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. IDEN (IDENtify the client software) All States 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. --------------------------------------------------------------------------- The following commands are available only in Citadel/UX server version 4.03 and above. --------------------------------------------------------------------------- SEXP (Send EXPress messages) LI This is one of two commands which implement "express messages" (also known as "paging"). An express message is a near-real-time message sent from one logged in user to another. When an express message is sent, it will be displayed the next time the target user executes a PEXP command. 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. Do be aware that if an express message is transmitted to a user who is logged in using a client that does not check for express messages, the message will never be received. Halidel adds a Time Stamp to the message and does page ageing so old pages don't stick around. PEXP (Print EXPress messages) LI This command, called without any arguments, simply dumps out the contents of any waiting express messages. It returns ERROR if there is a problem, otherwise it returns LISTING_FOLLOWS followed by all messages. So how does the client know there are express 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 express messages. --------------------------------------------------------------------------- The following commands are interesting and we want to keep them, but since they don't currently get used, we're not going to worry about implimenting them in the first draft of Halidel. These features will be saved for a later version. --------------------------------------------------------------------------- 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. 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). 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. 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, ERROR+NO_SUCH_USER if the named user does not exist, or ERROR+FILE_NOT_FOUND if the user exists but has no bio on file. --------------------------------------------------------------------------- The following commands have been removed, never to return. --------------------------------------------------------------------------- AUTO RDIR DELF MOVF NETF OPEN CLOS READ UOPN UCLS WRIT OIMG NETP NUOP NDOP LFLR CFLR KFLR EFLR IPGM CHAT STEL MSG2