APPLICATION LAYER PROTOCOL FOR THE CITADEL SYSTEM
- (c) 1995-2004 by Art Cancro et. al. All Rights Reserved
+ (c) 1995-2005 by Art Cancro et. al. All Rights Reserved
INTRODUCTION
------------
- This is an attempt to document the session layer protocol used by the
+ This is an attempt to document the application layer protocol used by the
Citadel system, beginning with version 4.00, which is the first version
to implement a client/server paradigm. It is intended as a resource for
programmers who intend to develop their own Citadel clients, but it may have
CONNECTING TO A SERVER
----------------------
- The protocols used below the session layer are beyond the scope of this
+ The protocols used below the application layer are beyond the scope of this
document, but we will briefly cover the methodology employed by Citadel.
- Citadel offers Citadel BBS service using TCP/IP. It does so via a
+ Citadel offers its client protocol using TCP/IP. It does so via a
multithreaded server listening on a TCP port. Local connections may also
be made using the same protocol using Unix domain sockets.
The port number officially assigned to Citadel by the IANA is 504/tcp. Since
-our session layer assumes a clean, reliable, sequenced connection, the use
+our application layer assumes a clean, reliable, sequenced connection, the use
of UDP would render the server unstable and unusable, so we stick with TCP.
+ CHARACTER SETS
+ --------------
+
+ The native character set for the Citadel system is UTF-8. Unless otherwise
+specified, all data elements are expected to be in the UTF-8 character set.
+Specifically, all non-MIME messages should be assumed to be in UTF-8. MIME
+messages may be in whatever character set is specified by the MIME header, of
+course; however, some clients (such as WebCit) will automatically convert
+messages from other character sets before displaying them.
+
+
GENERAL INFORMATION ABOUT THE SERVER
------------------------------------
connection to a server process, and when a command is sent, the client must
read the response, and then transfer data or change modes if necessary.
- The session layer is very much like other Internet protocols such as SMTP
+ The application layer is very much like other Internet protocols such as SMTP
or NNTP. A client program sends one-line commands to the server, and the
server responds with a three-digit numeric result code followed by a message
describing what happened. This cycle continues until the end of the
* if the user calls it up by name */
#define UA_HASNEWMSGS 8 /* Unread messages exist in room */
#define UA_ZAPPED 16 /* Zapped from known rooms list */
-
+
+ The sixth field is the user's current view for the room. (See VIEW command)
LKRO (List Known Rooms with Old [no new] messages)
allow client software to return to the base room when it doesn't know
where else to go.
- 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.
+ There are also several additional reserved room names:
+ "_MAIL_" goes to the user's inbox (i.e. the Mail> room).
+ "_BITBUCKET_" goes to a room that has been chosen for messages without a home.
+ "_CALENDAR_" goes to the user's primary personal calendar.
+ "_CONTACTS_" goes to the user's primary personal address book.
+ "_NOTES_" goes to the user's primary personal notes room.
+ "_TASKS_" goes to the user's primary personal task list.
+
The second (and optional) parameter is a password, if one is required for
access to the room. This allows for all types of rooms to be accessed via
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.
-
- In Citadel 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 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.
+which case that many message pointers will be returned; "first" plus a
+number, for the corresponding effect; or "gt" plus a number, to list all
+messages in the current room with a message number greater than the one
+specified. If no parameters are specified, "all" is assumed.
+
+ The third argument, may be either 0 or 1. If it is 1, this command behaves
+differently: before a listing is returned, the client must transmit a list
+of fields to search for. The field headers are listed below in the writeup
+for the "MSG0" command.
+
+ The optional fourth argument may also be either 0 or 1. If it is 1, the
+output of this command will include not only a list of message numbers, but
+a simple header summary of each message as well. This is somewhat resource
+intensive so you shouldn't do this unless you absolutely need all the headers
+immediately. The fields which are output (in the usual delimited fashion, of
+course) are: message number, timestamp, display name, node name, Internet
+email address (if present), subject (if present).
This command can return three possible results. ERROR + NOT_LOGGED_IN will
be returned if no user is currently logged in. Otherwise, LISTING_FOLLOWS
parts of the listing:
Line 1 - Your unique session ID on the server
- Line 2 - The node name of the server BBS
- Line 3 - Human-readable node name of the server BBS
+ Line 2 - The node name of the Citadel server
+ Line 3 - Human-readable node name of the Citadel server
Line 4 - The fully-qualified domain name (FQDN) of the server
Line 5 - The name of the server software, i.e. "Citadel 4.00"
Line 6 - (The revision level of the server code) * 100
- Line 7 - The geographical location of the BBS (city and state if in the US)
+ Line 7 - The geographical location of the site (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
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
+each Citadel they use. *Please*, if you are a developer and plan to add
proprietary features:
-> Your client programs should still be able to utilize servers other than
The server message contained on the same line with LISTING_FOLLOWS will
contain the name of the system and the name of the directory, such as:
- uncensored.citadel.org|/usr/bbs/files/my_room_directory
+ uncensored.citadel.org|/usr/local/citadel/files/my_room_directory
SLRP (Set Last-message-Read Pointer)
in vain that will not be permitted to be saved. If it is set to 2, the
server will accept an "apparent" post name if the user is privileged enough.
This post name is arg 5.
- 1 - Recipient. 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.
+ 1 - Recipient (To: field). This argument is utilized only for private
+mail. It is ignored for public messages. It contains, of course, the name
+of the recipient(s) of the message.
2 - Anonymous flag. This argument is ignored unless the room allows
anonymous messages. In such rooms, this flag may be set to 1 to flag a
message as anonymous, otherwise 0 for a normal message.
the message.
5 - Post name. When postflag is 2, this is the name you are posting as.
This is an Aide only command.
+ 6 - Do Confirmation. NOTE: this changes the protocol semantics! When
+you set this to nonzero, ENT0 will reply with a confirmation message after
+you submit the message text. The reply code for the ENT0 command will be
+START_CHAT_MODE instead of SEND_LISTING.
+ 7 - Recipient (Cc: field). This argument is utilized only for private
+mail. It is ignored for public messages. It contains, of course, the name
+of the recipient(s) of the message.
+ 8 - Recipient (Bcc: field). This argument is utilized only for private
+mail. It is ignored for public messages. It contains, of course, the name
+of the recipient(s) of the message.
Possible result codes:
OK - The request is valid. (Client did not set the "post" flag, so the
having his/her mail forwarded, the forwarding address will be returned.
SEND_LISTING - The request is valid. The client should now transmit
the text of the message (ending with a 000 on a line by itself, as usual).
+ START_CHAT_MODE - The request is valid. The client should now transmit
+the text of the message, ending with a 000 on a line by itself. After
+transmitting the 000 terminator, the client MUST read in the confirmation
+from the server, which will also end with 000 on a line by itself. The format
+of the confirmation appears below.
ERROR + NOT_LOGGED_IN - Not logged in.
ERROR + HIGHER_ACCESS_REQUIRED - Higher access is required. An
explanation follows, worded in a form that can be displayed to the user.
ERROR + NO_SUCH_USER - The specified recipient does not exist.
+The format of the confirmation message, if requested, is as follows:
+Line 1: The new message number on the server for the message. It will be
+ positive for a real message number, or negative to denote
+ that an error occurred. If an error occurred, the message was
+ not saved.
+Line 2: A human-readable confirmation or error message.
+Line 3: The resulting Exclusive UID of the message, if present.
+(More may be added to this in the future, so do not assume that there will
+only be these lines output. Keep reading until 000 is received.)
+
RINF (read Room INFormation file)
Unlisted entries will also be listed to Aides logged into the server, but
not to ordinary users.
+
+ The LIST command accepts an optional single argument, which is a simple,
+case-insensitive search string. If this argument is present, only usernames
+in which the search string is present will be returned. It is a simple
+substring search, not a regular expression search. If this string is empty
+or not present, all users will be returned.
REGI (send REGIstration)
NETP (authenticate as network session with connection NET Password)
This command is used by client software to identify itself as a transport
-session for IGnet/Open BBS to BBS networking. It should be called with
+session for Citadel site-to-site networking. It should be called with
two arguments: the node name of the calling system, and the "shared secret"
password for that connection. If the authentication succeeds, NETP will
return OK, otherwise, it returns ERROR.
identified itself as a network session using the NETP command. If the command
returns OK, the client may begin transmitting IGnet/Open spool data using
a series of WRIT commands. When a UCLS command is issued, the spooled data
-is entered into the BBS if the argument to UCLS is 1 or discarded if the
+is entered into the server if the argument to UCLS is 1 or discarded if the
argument to UCLS is 0. If the client has not authenticated itself with a
NETP command, ERROR+HIGHER_ACCESS_REQUIRED will be returned.
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 on the bbs
+ /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.
36. LDAP Bind DN
37. Password for LDAP Bind DN
38. Server IP address to listen on (or "0.0.0.0" for all addresses)
+ 39. Port number for SMTP MSA service
+ 40. Port number for IMAPS (SSL-encrypted IMAP)
+ 41. Port number for POP3S (SSL-encrypted POP3)
+ 42. Port number for SMTPS (SSL-encrypted SMTP)
+ 43. Flag (0 or 1) - enable full text search index
+ 44. Flag (0 or 1) - automatically cull database log files
+ 45. Flag (0 or 1) - enable IMAP "instant expunge" of deleted messages
+ 46. Flag (0 or 1) - allow unauthenticated SMTP clients to spoof my domains
CONF also accepts two additional commands: GETSYS and PUTSYS followed by an
arbitrary MIME type (such as application/x-citadel-internet-config) which
+ AUTO (AUTOcompletion of email addresses)
+
+ The AUTO command is used by clients which want to request a list of email
+recipients whose names or email addresses match a partial string supplied by
+the client. This string is the only parameter passed to this command. The
+command will return ERROR if no user is logged in or if no address book could
+be found; otherwise, it returns LISTING_FOLLOWS followed by zero or more
+candidate recipients.
+
+
+ SRCH (SeaRCH the message base)
+
+ This command's implementation is incomplete and will be documented when it
+is finished. The current implementation accepts a search string as its sole
+argument, and will respond with LISTING_FOLLOWS followed by a list of
+messages (globally, not just in the current room) which contain ALL of the
+words in the search string. If the client desires an "exact phrase" match,
+it must then slow-search the text of each returned message for the exact
+string. The client should also compare the returned message numbers against
+those which actually exist in the room or rooms being searched. In
+particular, clients should avoid telling the user about messages which exist
+only in rooms to which the user does not have access.
+
+ Again, keep in mind that this is a temporary implementation and is not
+guaranteed to continue to exist in this form.
+
+
+
+
ASYNCHRONOUS MESSAGES
---------------------
projects / citadel.git / blobdiff