Home Download News FAQ / Knowledge Base Screenshots Documentation Support Site map
philosophical imaginary
Table of Contents

Rooms and Floor Directory Commands

Floor Commands

Floors are the top Layer Directory Elements in citadels hirarchical storage system. Rooms may derive or overwrite configurations from them.

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:

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:

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)

List Commands

Various commands listing Rooms to you.

Reply Syntax

ColumnnameValue
NAMEActual name of this room; may include '\' to separate trees
FLAGQRFlags of this room
FLOORThe floor number its on
LISTORDER?
ACLthe Access control list
CURVIEWcurrently viewed as..
DEFVIEWby default viewet as..
LASTCHANGElast write access

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:

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


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

Flag Name integer Value Meaning
QR2_SYSTEM 1 System room; hide by default
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:

Flag Name integer Value Meaning
UA_KNOWN 2 Known room
UA_GOTOALLOWED 4 Access will be granted to this room if the user calls it up by name
UA_HASNEWMSGS 8 Unread messages exist in room
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.

Commands manipulaing One rooom

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:

filez.tgz|2345678|application/x-tar|Hey all, have a look at that cool stuff

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.

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:

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 ValueMeaning
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:

  1. The name of the room
  2. The room's password (if it's a passworded room)
  3. The name of the room's directory (if it's a directory room)
  4. Various flags (bits) associated with the room (see LKRN cmd above)
  5. The floor number on which the room resides
  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

SETR (SET Room attributes)

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

  1. The name of the room
  2. The room's password (if it's a passworded room)
  3. The name of the room's directory (if it's a directory room)
  4. Various flags (bits) associated with the room (see LKRN cmd above)
  5. “Bump” flag (see below)
  6. The floor number on which the room should reside
  7. The room listing order
  8. The default view for the room (see views.txt)
  9. 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.

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

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:

CodeMeaning
ERROR + NOT_LOGGED_IN Not logged in.
ERROR + HIGHER_ACCESS_REQUIRED Higher access required.
ERROR + NOT_HERE Room cannot be edited.
OK Command succeeded.

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:

No.Access TypeValue
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:
0Public
1Private; can be entered by guessing the room's name
2Private; can be entered by knowing the name and password
3Private; invitation only (sometimes called “exclusive”)
4Personal (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 rooml 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).

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)

To get a list of users available on your citadel. see LIST for details.

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.

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.

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.

Files belonging to rooms

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.

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, the second argument is the MimmeType of the file and the third 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.

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 should specify the mimetype of the Image. The third argument is the name of the file to be transmitted. In Citadel, the filename is converted to all lower case 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:

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.

In the case of Citadel, the server will convert the supplied filename to all lower case 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).
Copyright © 1987-2014 Uncensored Communications Group. All rights reserved.     Login (site admin)