SESSION LAYER PROTOCOL FOR CITADEL/UX
- (c) 1995-1998 by Art Cancro All Rights Reserved
+ (c) 1995-1999 by Art Cancro et. al. All Rights Reserved
INTRODUCTION
developments ahead of time, please at least send in an e-mail documenting
what you did, so that your new commands can be added to this document.
- The coordinator of the Citadel/UX project is Art Cancro <ajc@uncnsrd.mt-kisco.ny.us>.
+ The coordinator of the Citadel/UX project is Art Cancro
+<ajc@uncnsrd.mt-kisco.ny.us>.
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 to connect to a server is to use a set of pipes. This does of
-course assume that the client and server are running on the same computer.
-When the client starts up, the first thing that it does is create two pipes,
-which it temporarily dup()'s to stdin and stdout. Then it proceeds to
-fork() and exec() to a copy of the server program, which inherits the
-pipes as its standard input and output - exactly the desired effect. The
-client program can then re-connect its own stdin and stdout to where they're
-supposed to be, and use the pipes to send and receive server messages.
-
- Another 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 Citadel/UX 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
-Citadel/UX sessions. Since our session layer assumes a clean, reliable,
-sequenced connection, the use of UDP would render the server unstable and
-unusable. When operating in a TCP/IP environment, the port number officially
-assigned to Citadel is 504.
+document, but we will briefly cover the methodology employed by Citadel/UX.
+
+ Citadel/UX offers Citadel BBS service using TCP/IP. It does so via a
+multithreaded server listening on a TCP port. Older (4.xx) versions employed
+an inetd-based server.
+
+ The port number officially assigned to Citadel by the IANA is TCP/504. Since
+our session layer assumes a clean, reliable, sequenced connection, the use
+of UDP would render the server unstable and unusable, so we stick with TCP.
GENERAL INFORMATION ABOUT THE SERVER
it will also return the same parameters that PASS returns.
- AUTO (AUTOmatic login **OBSLETE** )
-
- Citadel/UX no longer supports this type of authentication. It was formerly
-used to automatically authenticate a user based on the user ID under which
-the server was running. Due to the new multithreaded architecture of the
-server, this is no longer possible.
-
-
SETP (SET new Password)
This command sets a new password for the currently logged in user. The
Other bits may be defined in the future. The listing terminates, as with
all listings, with "000" on a line by itself.
- Version 4.01 and above only:
-
Starting with version 4.01 and above, floors are supported. The first
argument to LKRN should be the number of the floor to list rooms from. Only
rooms from this floor will be listed. If no arguments are passed to LKRN, or
The third field displayed on each line is the number of the floor the room
is on. The LFLR command should be used to associate floor numbers with
floor names.
+
+ The fourth field displayed on each line is a "room listing order." Unless
+there is a compelling reason not to, clients should sort any received room
+listings by this value.
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
+ There are also two additional reserved room names:
+ "_MAIL_" translates to the system's designated room for e-mail messages.
+ "_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
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
This command obtains a listing of all the messages in the current room
which the client may request. This command may be passed a single parameter:
either "all", "old", or "new" to request all messages, only old messages, or
-new messages. Or it may be passed two parameters: "last" plus a number, in which
-case that many message pointers will be returned, or "first" plus a number, for
-the corresponding effect. If no parameters are specified, "all" is assumed.
+new messages. Or it may be passed two parameters: "last" plus a number, in
+which case that many message pointers will be returned, or "first" plus a
+number, for the corresponding effect. If no parameters are specified, "all"
+is assumed.
- In Citadel/UX 5.00 and above, the client may also specify "gt" plus a number, to
-list all messages in the current room with a message number greater than the one
-specified.
+ In Citadel/UX 5.00 and above, the client may also specify "gt" plus a number,
+to list all messages in the current room with a message number greater than
+the one specified.
+
+ The third argument, valid only in Citadel/UX 5.60 and above, may be either
+0 or 1. If it is 1, this command behaves differently: before a listing is
+returned, the client must transmit a list of fields to search for. The field
+headers are listed below in the writeup for the "MSG0" command.
- This command can return two possible results. An ERROR code may be returned
+ This command can return three possible results. An ERROR code may be returned
if no user is currently logged in or if something else went wrong. Otherwise,
LISTING_FOLLOWS will be returned, and the listing will consist of zero or
more message numbers, one per line. The listing ends, as always, with the
string "000" alone on a line by itself. The listed message numbers can be used
-to request messages from the system.
+to request messages from the system. If "search mode" is being used, the
+server will return START_CHAT_MODE, and the client is expected to transmit
+the search criteria, and then read the message list.
+
+ Since this is somewhat complex, here are some examples:
+
+ Example 1: Read all new messages
+
+ Client: MSGS NEW
+ Server: 100 Message list...
+ 523218
+ 523293
+ 523295
+ 000
+
+ Example 2: Read the last five messages
+
+ Client: MSGS LAST|5
+ Server: 100 Message list...
+ 523190
+ 523211
+ 523218
+ 523293
+ 523295
+ 000
+
+ Example 3: Read all messages written by "IGnatius T Foobar"
+
+ Client: MSGS ALL|0|1
+ Server: 800 Send template then receive message list
+ Client: from|IGnatius T Foobar
+ 000
+ Server: 518604
+ 519366
+ 519801
+ 520201
+ 520268
+ 520805
+ 520852
+ 521579
+ 521720
+ 522571
+ 000
+
+ Note that in "search mode" the client may specify any number of search
+criteria. These criteria are applied with an AND logic.
+
MSG0 (read MeSsaGe, mode 0)
This is a command used to read the text of a message. "Mode 0" implies that
LISTING_FOLLOWS code will be returned, followed by the contents of the message.
The following fields may be sent:
- type= Formatting type. Currently, there are two defined types. Type 0 is
-"traditional" Citadel formatting. This means that newlines should be treated
-as spaces UNLESS the first character on the next line is a space. In other
-words, only indented lines should generate a newline on the user's screen when
-the message is being displayed. This allows a message to be formatted to the
-reader's screen width. It also allows the use of proportional fonts.
-Type 1 is a simple fixed-format message. The message should be displayed to
+ type= Formatting type. The currently defined types are:
+ 0 = "traditional" Citadel formatting. This means that newlines should be
+treated as spaces UNLESS the first character on the next line is a space. In
+other words, only indented lines should generate a newline on the user's screen
+when the message is being displayed. This allows a message to be formatted to
+the reader's screen width. It also allows the use of proportional fonts.
+ 1 = a simple fixed-format message. The message should be displayed to
the user's screen as is, preferably in a fixed-width font that will fit 80
columns on a screen.
+ 4 = MIME format message. The message text is expected to contain a header
+with the "Content-type:" directive (and possibly others).
msgn= The message ID of this message on the system it originated on.
path= An e-mailable path back to the user who wrote the message.
room= The name of the room the message originated in.
node= The short node name of the system this message originated on.
hnod= The long node name of the system this message originated on.
+ zaps= The id/node of a message which this one zaps (supersedes).
text Note that there is no "=" after the word "text". This string
signifies that the message text begins on the next line.
Line 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 7 - The geographical location of the BBS (city and state if in the US)
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
-
- (version 4.01 and above only)
Line 11 - Floor Flag. 1 if the system supports floors, 0 otherwise.
+ Line 12 - Paging level. 0 if the system only supports inline paging,
+ 1 if the system supports "extended" paging (check-only and
+ multiline modes). See the SEXP command for further information.
*** NOTE! *** The "server type" code is intended to promote global
compatibility in a scenario in which developers have added proprietary
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 <ajc@uncnsrd.mt-kisco.ny.us>
- 1 Brian Ledbetter <brian@amaranth.com>
- 2 Matthew Scott <gldnspud@telcomplus.com>
- 3 Jesse Vincent <jrvincent@wesleyan.edu>
- 4 Brian Costello <btx@calyx.net>
- 5 Robert Abatecola <robert@tsgus.com>
-
+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)
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
+ 5. The room listing order
SETR (SET Room attributes)
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
+ 6. The room listing order
*Important: You should always use GETR to retrieve the current attributes of
the room, then change what you want to change, and then use SETR to write it
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 "apparant" post name if the user is privileged enough.
+server will accept an "apparent" post name if the user is privileged enough.
This post name is arg 4.
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
Delete a message from the current room. The one argument that should be
passed to this command is the message number of the message to be deleted.
The return value will be OK if the message was deleted, or an ERROR code.
+If the delete is successful, the message's reference count is decremented, and
+if the reference count reaches zero, the message is removed from the message
+base.
- MOVE (MOVE a message to a different room)
+ MOVE (MOVE or copy a message to a different room)
Move a message to a different room. The two arguments that should be passed
to this command are the message number of the message to be deleted, and the
usually means that either the user does not have permission to perform this
operation, or that the target room does not exist.
+ In Citadel/UX 5.55 and above, a third argument may be specified: 0 or 1 to
+designate whether the message should be moved (0) or copied (1) to the target
+room. In the case of a "copy" operation, the message's reference count is
+incremented, and a pointer to the message will exist in both the source *and*
+target rooms. In the case of a "move" operation, the message pointer is
+deleted from the source room and the reference count remains the same.
+
KILL (KILL current room)
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)
- 4 - Floor number on which the room should reside (optional, and in server
- version 4.01 and above only)
+ 4 - Floor number on which the room should reside (optional)
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
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).
+ (posting) and . (idle). (Citserver 5.02 and above)
The listing is terminated, as always, with the string "000" on a line by
itself.
OK (file is open)
If the file is successfully opened, OK will be returned, along with the
-size (in bytes) of the file, and (in version 5.00 and above) the time of last
-modification.
+size (in bytes) of the file, the time of last modification (if applicable),
+the filename (if known), and the MIME type of the file (if known).
CLOS (CLOSe the download file)
opposed to the floor picture's use in a floor listing).
-
- ---------------------------------------------------------------------------
- The following commands are available only in Citadel/UX server version 4.01
- and above.
- ---------------------------------------------------------------------------
-
NETP (authenticate as network session with system NET Password)
This command is used by client software to identify itself as a transport
If the command succeeds, it will return OK. Otherwise it will return
ERROR (plus perhaps HIGHER_ACCESS_REQUIRED or INVALID_FLOOR_OPERATION)
- ---------------------------------------------------------------------------
- The following commands are available only in Citadel/UX server version 4.02
- and above.
- ---------------------------------------------------------------------------
IDEN (IDENtify the client software)
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.
- ---------------------------------------------------------------------------
IPGM (identify as an Internal ProGraM)
This is one of two commands which implement "express messages" (also known
as "paging"). An express message is a near-real-time message sent from one
logged in user to another. When an express message is sent, it will be
-displayed the next time the target user executes a PEXP command.
+displayed the next time the target user executes a PEXP or GEXP command.
The SEXP command accepts two arguments: the name of the user to send the
message to, and the text of the message. If the message is successfully
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.
- In Citadel/UX 5.00 and above, the reserved name "broadcast" may be used
-instead of a user name, to broadcast an express message to all users
-currently connected to the server.
+ The reserved name "broadcast" may be used instead of a user name, to
+broadcast an express message to all users currently connected to the server.
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.
- PEXP (Print EXPress messages)
+ PEXP (Print EXPress 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.
- This command, called without any arguments, simply dumps out the contents
+ Called without any arguments, PEXP simply dumps out the contents
of any waiting express messages. It returns ERROR if there is a problem,
otherwise it returns LISTING_FOLLOWS followed by all messages.
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 available only in Citadel/UX server version 4.10
- and above.
- ---------------------------------------------------------------------------
EBIO (Enter BIOgraphy)
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 are available only in Citadel/UX server version 4.11
- and above.
- ---------------------------------------------------------------------------
STEL (enter STEaLth mode)
future. Keep in mind that when this command is used, all messages will be
output in fixed 80-column format.
- ---------------------------------------------------------------------------
- The following commands are available only in Citadel/UX server version 5.00
- and above.
- ---------------------------------------------------------------------------
MSG3 (read MeSsaGe, mode 3 -- internal command)
The following are for citserver 5.02 and above
----------------------------------------------
-HCHG (Hostname CHanGe)
+ HCHG (Hostname CHanGe)
-HCHG is a command, usable by any user, that allows a user to change their RWHO
+ 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 see an entry right underneath the spoofed
entry listing the actual hostname the user originates from.
-The format of an HCHG command is:
+ The format of an HCHG command is:
-HCHG <name>
+ HCHG <name>
+ If a HCHG command is successful, the value OK (200) is returned.
-If a HCHG command is successful, the value OK (200) is returned.
-RCHG (Roomname CHanGe)
+ RCHG (Roomname CHanGe)
-RCHG is a command, usable by any user, that allows a user to change their RWHO
+ 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 see an entry right underneath the spoofed entry listing
the actual room the user is in.
-The format of an RCHG command is:
+ The format of an RCHG command is:
-RCHG <name>
+ RCHG <name>
-If a RCHG command is successful, the value OK (200) is returned.
+ 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
+ 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:
+ 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)
-UCHG <name>
+ TIME returns OK followed by the current time measured in seconds since
+00:00:00 GMT, Jan 1, 1970 (standard Unix format).
-If a UCHG command is successful, the value OK (200) is returned.
+ This is used in allowing a client to calculate idle times.
-TIME (Get server local TIME)
-TIME returns a string in the following format:
+ 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)
- A|B
+ 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"
+
+ If successful, GPEX returns OK followed by <policy>|<value>.
-Where A is OK (200), B is the current time measured in seconds since
-00:00:00 GMT, Jan 1, 1970.
-This is used in allowing a client to calculate idle times.
+ SPEX (Set Polict 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"
+
+ 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:
+
+ 1. Node name
+ 2. Fully qualified domain name
+ 3. Human-readable node name
+ 4. Landline telephone number of this system
+ 5. Flag (0 or 1) - creator of private room automatically becomes room aide
+ 6. Server connection idle timeout (in seconds)
+ 7. Initial access level for new users
+ 8. Flag (0 or 1) - require registration for new users
+ 9. Flag (0 or 1) - automatically move Problem User messages to twit room
+ 10. Name of twit room
+ 11. Text of <more> prompt
+ 12. Flag (0 or 1) - restrict access to Internet mail
+ 13. Geographic location of this system
+ 14. Name of the system administrator
+ 15. Number of maximum concurrent sessions allowed on the server
+ 16. Password for server-to-server networking
+ 17. Default purge time (in days) for users
+ 18. Default purge time (in days) for rooms
+ 19. Name of room to log express messages to (or a zero-length name for none)
+ 20. Access level required to create rooms
+ 21. Maximum message length which may be entered into the system
+
+
+
+ EXPI (EXPIre system objects)
+
+ Begins purge operations for objects which, according to site policy, are
+"old" and should be removed. EXPI should be called with one argument, one of:
+
+ "messages" (purge old messages out of each room)
+ "users" (purge old users from the userlog)
+ "rooms" (remove rooms which have not been posted in for some time)
+ "visits" (purge dereferenced user/room relationship records)
+
+ EXPI returns OK (probably after a long delay while it does its work) if it
+succeeds; otherwise it returns an ERROR code.
+
+ This command is probably temporary, until we can work some sort of scheduler
+into the system. It is implemented in the serv_expire module.
+
+
+
+ MSG4 (read MeSsaGe, mode 4 -- enumerate MIME parts)
+
+ FIX ... do the writeup for this once it's done.
+
+
+
+ OPNA (OPeN Attachment)
+
+ Opens, as a download file, a component of a MIME-encoded message. The two
+parameters which must be passed to this command are the message number and the
+name of the desired section. If the message or section does not exist, an
+appropriate ERROR code will be returned; otherwise, if the open is successful,
+this command will succeed returning the same information as an OPEN command.
+
+
+ GEXP (Get EXPress messages)
+
+ This is a more sophisticated way of retrieving express messages than the old
+PEXP method. If there are no express messages waiting, PEXP returns ERROR;
+otherwise, it returns LISTING_FOLLOWS and the following arguments:
+
+ 0 - a boolean value telling the client whether there are any additional
+ express messages waiting following this one
+ 1 - a Unix-style timestamp
+ 2 - flags (see server.h for more info)
+ 3 - the name of the sender
+ 4 - the node this message originated on (for future support of PIP, ICQ, etc.)
+
+ The text sent to the client will be the body of the express message.
+
+ So how does the client know there are express messages waiting? It could
+execute a random GEXP every now and then. Or, it can check the byte in
+server return code messages, between the return code and the parameters. In
+much the same way as FTP uses "-" to signify a continuation, Citadel uses
+an "*" in this position to signify the presence of waiting express messages.
+
+
+
+ CICQ (Citadel ICQ metaclient setup)
+
+ ** WARNING **
+ This command is most likely a temporary one. Citadel will eventually have
+more robust functionality for abstract configuration screens, and when that
+happens, this command will certainly be migrated there. If you're developing
+a client, don't spend a lot of time working on ICQ screens.
+
+ If a Citadel server has the ICQ Metaclient installed, this command is used
+to configure it. It has several usages:
+
+ CICQ login|uin|pass
+
+ This tells Citadel the user's ICQ uin (second argument) and password (third
+argument). When called in this fashion, CICQ will return either OK or ERROR.
+It should be noted, however, that the only way an ERROR code can be returned
+is if the uin and/or password is not supplied. Authentication failures cannot
+be immediately detected, because the ICQ protocol is asynchronous.
+
+ CICQ getcl
+
+ Request the current contact list. If successful, CICQ will return
+LISTING_FOLLOWS followed by zero or more contacts in the format
+
+ uin|nickname|status
+
+ CICQ putcl
+
+ Upload a new contact list. If successful, CICQ will return SEND_LISTING
+after which the client should transmit zero or more uin's, one per line. The
+server will then attempt to contact the ICQ server to determine nicknames
+and statuses.
+
+ CICQ status
+
+ Always returns OK followed by a 1 (connected to ICQ) or 0 (not connected).
projects / citadel.git / blobdiff