Table of Contents

Instant Messaging & Chat Commands

CHAT (enter CHAT mode)

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

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

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

The Citadel server understands the following commands:

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

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

SEXP (Send instant message)

This is one of two commands which implement instant messages (also known as “paging”). Commands ending in ”…EXP” are so-named because we called them “express messages” before the industry standardized on the term “instant messages.” When an instant message is sent, it will be logged in user to another. When an instant message is sent, it will be displayed the next time the target user executes a PEXP or GEXP command.

The SEXP command accepts two arguments: the name of the user to send the message to, and the text of the message. If the message is successfully transmitted, OK is returned. If the target user is not logged in or if anything else goes wrong, ERROR is returned.

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

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

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

GEXP (Get instant messages)

This is a more sophisticated way of retrieving instant messages than the old PEXP method. If there are no instant messages waiting, PEXP returns ERROR; otherwise, it returns LISTING_FOLLOWS and the following arguments:

0a boolean value telling the client whether there are any additional instant messages waiting following this one
1a Unix-style timestamp
2flags (see server.h for more info)
3the name of the sender
4the node this message originated on (deprecated, do not use)
5the email address or XMPP JID of the sender

The text sent to the client will be the body of the instant message.

So how does the client know there are instant messages waiting? It could execute a random GEXP every now and then. Or, it can check the byte in server return code messages, between the return code and the parameters. In much the same way as FTP uses ”-” to signify a continuation, Citadel uses an “*” in this position to signify the presence of waiting instant messages.

DEXP (Disable receiving instant messages)

DEXP sets or clears the “disable instant messages” flag. Pass this command a 1 or 0 to respectively set or clear the flag. When the “disable instant messages” flag is set, no one except Aides may send the user instant messages. Any value other than 0 or 1 will not change the flag, only report its state. The command returns ERROR if it fails; otherwise, it returns OK followed by a number representing the current state of the flag.

ASYN (ASYNchronous message support)

Negotiate the use of asynchronous, or unsolicited, protocol messages. The only parameter specified should be 1 or 0 to indicate that the client can or cannot handle this type of messages. The server will reply OK followed by a 1 or 0 to tell the client which mode it is now operating in.

If the command is not available on the server (i.e. it returns ERROR), or if the command has not been executed by the client, it should be assumed that this mode of operation is NOT in effect.

The client may also send any value other than 0 or 1 to simply cause the server to output its current state without changing it.

When asynchronous protocol mode is in effect, the client MUST handle any asynchronous messages as they arrive, before doing anything else.


When the client protocol is operating in asynchronous mode (please refer to the writeup of the ASYN command above), the following messages may arrive at any time:

902 (instant message arriving)

One or more instant messages have arrived for this client.