© 1995-2007 by the citadel.org development team. All Rights Reserved. This document is provided to you under the terms of the GNU General Public License.
This is a specification of the application layer protocol used by Citadel client software to connect to Citadel servers. It is intended as a resource for programmers who intend to develop their own Citadel clients, but it may have other uses as well.
Developers will find this protocol refreshingly simple to implement. Unlike over-enginnered XML and IMAP technologies, there is no need to write a language parser in order to speak the Citadel protocol. Data is transmitted back and forth in a delimited format that is easy to load into your program's own data structures using little more than a string tokenizer.
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.
You can get in touch with a coordinator via the Citadel Support forum.
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 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 via citadel.socket.
The port number officially assigned to Citadel by the IANA is 504 / TCP. Since 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.
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.
The server is connection-oriented and stateful: each client requires its own 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 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 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.) This keeps protocol administration straightforward, as it can traverse firewalls without any special protocol support on the firewall except for opening the port number.
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 second and third digits may provide a reason as to why a command succeeded or failed. See ipcdef.h 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.
- ASYNC_MESSAGE_FOLLOWS means that an asynchronous, or unsolicited, message follows. The next line will be one of the above codes, and if a data transfer is involved it must be handled immediately. Note that the client will not receive this type of response unless it indicates to the server that it is capable of handling them; see the writeup of the ASYN command later in this document.
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:
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:
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.
Citadel orders data into containers called Rooms. Its top level folders are called Floors, and they may just contain rooms. Rooms may have a Description Text, and an Image file. Users may invite other Users to view or view and create Messages in their Rooms. Citadel supports sharing of rooms between different nodes. A user always is known to be 'inside' a room, which is an implicit Parameter to most of the commands of the citadel protocol.