APPLICATION LAYER PROTOCOL FOR THE CITADEL SYSTEM
- (c) 1995-2005 by Art Cancro et. al. All Rights Reserved
+ (c) 1995-2006 by Art Cancro et. al. All Rights Reserved
INTRODUCTION
#define 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)
There are also several additional reserved room names:
"_MAIL_" goes to the user's inbox (i.e. the Mail> room).
+ "_TRASH_" goes to the user's personal trashcan room (trash folder).
"_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.
10. The floor number this room resides on
11. The *current* "view" for this room (see views.txt for more info)
12. The *default* "view" for this room
+ 13. Boolian flag: 1 if this is the user's Trash folder, 0 otherwise.
The default view gives the client a hint as to what views the user should
be allowed to select. For example, it would be confusing to allow messages
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.
+
+ In addition, the first parameter may be set to "search", in which case the
+third parameter must be a search string. This will request all messages
+in the current room whose text contains the search string.
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
backward compatibility. The current implementation defines the following
parts of the listing:
- Line 1 - Your unique session ID on the server
- 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 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
- Line 11 - Floor Flag. 1 if the system supports floors, 0 otherwise.
- Line 12 - Paging level. 0 if the system only supports inline paging,
+ Line 0 - Your unique session ID on the server
+ Line 1 - The node name of the Citadel server
+ Line 2 - Human-readable node name of the Citadel server
+ Line 3 - The fully-qualified domain name (FQDN) of the server
+ Line 4 - The name of the server software, i.e. "Citadel 4.00"
+ Line 5 - (The revision level of the server code) * 100
+ Line 6 - The geographical location of the site (city and state if in the US)
+ Line 7 - The name of the system administrator
+ Line 8 - A number identifying the server type (see below)
+ Line 9 - The text of the system's paginator prompt
+ Line 10 - Floor Flag. 1 if the system supports floors, 0 otherwise.
+ Line 11 - 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.
- Line 13 - The "nonce" for this session, for support of APOP-style
+ Line 12 - The "nonce" for this session, for support of APOP-style
authentication. If this field is present, clients may authenticate
in this manner.
- Line 14 - Set to nonzero if this server supports the QNOP command.
- Line 15 - Set to nonzero if this server is capable of connecting to a
+ Line 13 - Set to nonzero if this server supports the QNOP command.
+ Line 14 - Set to nonzero if this server is capable of connecting to a
directory service using LDAP.
+ Line 15 - Set to nonzero if this server does *not* allow self-service
+ creation of new user accounts.
+ Line 16 - The default timezone for calendar items which do not have any
+ timezone specified and are not flagged as UTC. This will be a
+ zone name from the Olsen database.
*** NOTE! *** The "server type" code is intended to promote global
compatibility in a scenario in which developers have added proprietary
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.
+ 9 - Exclusive message ID. When a message is submitted with an Exclusive
+message ID, any existing messages with the same ID will automatically be
+deleted. This is only applicable for Wiki rooms; other types of rooms either
+ignore the supplied ID (such as message boards and mailboxes) or derive the
+ID from a UUID native to the objects stored in them (such as calendars and
+address books).
Possible result codes:
OK - The request is valid. (Client did not set the "post" flag, so the
DELE (DELEte a message)
- 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.
+ Delete one or more messages from the current room. The one argument that
+should be passed to this command is a message number, or a list of message
+numbers separated by commas, to be deleted.
+
+ The return value will be OK if one or more messages were deleted, or an ERROR
+code. If the delete is successful, the messages' reference counts are
+decremented, and if the reference count reaches zero, the messages are removed
+from the message base.
MOVE (MOVE or copy a message to a different room)
Move or copy a message to a different room. This command expects to be
passed three arguments:
- 0: the message number of the message to be moved or copied.
+ 0: the message number(s) of the message to be moved or copied.
1: the name of the target room.
2: flag: 0 to move the message, 1 to copy it without deleting from the
source room.
This command never creates or deletes copies of a message; it merely moves
around links. When a message is moved, its reference count remains the same.
When a message is copied, its reference count is incremented.
+
+ You can move/copy multiple messages with a single command by separating the
+message numbers with commas; for example: MOVE 112,113,114|Trash|0
KILL (KILL current room)
of the flag.
+ HALT (HALT the server without shutting it down)
+
+ Identical to the DOWN command, except instead of exiting, the server process
+cleans up and then suspends indefinitely. This could potentially be useful for
+shutdown scripts that don't want init to automatically respawn another citserver
+process.
+
+
EMSG (Enter a system MeSsaGe)
This is the opposite of the MESG command - it allows the creation and editing
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. (placeholder -- this field is no longer in use)
- 17. Default purge time (in days) for users
- 18. Default purge time (in days) for rooms
- 19. Name of room to log instant 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
- 22. Minimum number of worker threads
- 23. Maximum number of worker threads
- 24. Port number for POP3 service
- 25. Port number for SMTP service
- 26. Flag (0 or 1) - strict RFC822 adherence - don't correct From: forgeries
- 27. Flag (0 or 1) - allow Aides to zap (forget) rooms
- 28. Port number for IMAP service
- 29. How often (in seconds) to run the networker
- 30. Flag (0 or 1) - disable self-service new user registration
- 31. (placeholder -- this field is no longer in use)
- 32. Hour (0 through 23) during which database auto-purge jobs are run
- 33. Name of host where an LDAP service may be found
- 34. Port number of LDAP service on above host
- 35. LDAP Base DN
- 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
+ 0. Node name
+ 1. Fully qualified domain name
+ 2. Human-readable node name
+ 3. Landline telephone number of this system
+ 4. Flag (0 or 1) - creator of private room automatically becomes room aide
+ 5. Server connection idle timeout (in seconds)
+ 6. Initial access level for new users
+ 7. Flag (0 or 1) - require registration for new users
+ 8. Flag (0 or 1) - automatically move Problem User messages to twit room
+ 9. Name of twit room
+ 10. Text of <more> prompt
+ 11. Flag (0 or 1) - restrict access to Internet mail
+ 12. Geographic location of this system
+ 13. Name of the system administrator
+ 14. Number of maximum concurrent sessions allowed on the server
+ 15. (placeholder -- this field is no longer in use)
+ 16. Default purge time (in days) for users
+ 17. Default purge time (in days) for rooms
+ 18. Name of room to log instant messages to (or a zero-length name for none)
+ 19. Access level required to create rooms
+ 20. Maximum message length which may be entered into the system
+ 21. Minimum number of worker threads
+ 22. Maximum number of worker threads
+ 23. Port number for POP3 service
+ 24. Port number for SMTP service
+ 25. Flag (0 or 1) - strict RFC822 adherence - don't correct From: forgeries
+ 26. Flag (0 or 1) - allow Aides to zap (forget) rooms
+ 27. Port number for IMAP service
+ 28. How often (in seconds) to run the networker
+ 29. Flag (0 or 1) - disable self-service new user registration
+ 30. (placeholder -- this field is no longer in use)
+ 31. Hour (0 through 23) during which database auto-purge jobs are run
+ 32. Name of host where an LDAP service may be found
+ 33. Port number of LDAP service on above host
+ 34. LDAP Base DN
+ 35. LDAP Bind DN
+ 36. Password for LDAP Bind DN
+ 37. Server IP address to listen on (or "0.0.0.0" for all addresses)
+ 38. Port number for SMTP MSA service
+ 39. Port number for IMAPS (SSL-encrypted IMAP)
+ 40. Port number for POP3S (SSL-encrypted POP3)
+ 41. Port number for SMTPS (SSL-encrypted SMTP)
+ 42. Flag (0 or 1) - enable full text search index
+ 43. Flag (0 or 1) - automatically cull database log files
+ 44. Flag (0 or 1) - enable IMAP "instant expunge" of deleted messages
+ 45. Flag (0 or 1) - allow unauthenticated SMTP clients to spoof my domains
+ 46. Flag (0 or 1) - perform journaling of email messages
+ 47. Flag (0 or 1) - perform journaling of non-email messages
+ 48. Address to which journalized messages are to be sent
+ 49. Default time zone (Olsen database name) for unzoned calendar items
+ 50. Port number for Postfix TCP Dict (http://www.postfix.org/tcp_table.5.html)
CONF also accepts two additional commands: GETSYS and PUTSYS followed by an
arbitrary MIME type (such as application/x-citadel-internet-config) which
"Content-length:". MIME formats are chosen and/or converted based on the
client's preferred format settings, which are set using the MSGP command,
described below.
+
+ The MSG4 command also accepts an optional second argument, which may be the
+MIME part specifier of an encapsulated message/rfc822 message. This is useful
+for fetching the encapsulated message instead of the top-level message, for
+example, when someone has forwarded a message as an attachment. Note that the
+only way for the client to know the part specifier is to fetch the top-level
+message and then look for attachments of type message/rfc822, and then call
+MSG4 again with that part specifier.
+
this command will succeed returning the same information as an OPEN command.
+ DLAT (DownLoad ATtachment)
+
+ Similar to OPNA, and with the same calling syntax. The difference is that
+instead of opening a download file for block transfer, this command outputs the
+entire decoded MIME section at once, using a BINARY_FOLLOWS response. This is
+useful for outputting small objects such as calendar items.
+
+
GEXP (Get instant messages)
This is a more sophisticated way of retrieving instant messages than the old
ERROR codes will be returned.
ICAL sgi|<bool>
+ Readers who are paying attention will notice that there is no subcommand to
+ send out meeting invitations. This is because that task can be handled
+ automatically by the Citadel server. Issue this command with <bool> set to 1
+ to enable Server Generated Invitations. In this mode, when an event is saved
+ to the user's Calendar> room and it contains attendees, Citadel will
+ automatically turn the event into calendar REQUEST messages and mail them
+ out to all listed attendees. If for some reason the client needs to disable
+ Server Generated Invitations, the command may be sent again with <bool> = 0.
+
+ ICAL getics
+ Output the contents of the entire calendar (assuming we are in a calendar
+ room) as one big data stream. All of the events (or tasks, etc.) in the room
+ are combined into a single VCALENDAR object, which is then serialized and
+ transmitted to the client. This is suitable for subscribing to a calendar
+ in third-party software. This command will output LISTING_FOLLOWS followed
+ by the calendar data stream, or ERROR if the requested operation is not
+ permitted.
- Readers who are paying attention will notice that there is no subcommand to
-send out meeting invitations. This is because that task can be handled
-automatically by the Citadel server. Issue this command with <bool> set to 1
-to enable Server Generated Invitations. In this mode, when an event is saved
-to the user's Calendar> room and it contains attendees, Citadel will
-automatically turn the event into vCalendar REQUEST messages and mail them
-out to all listed attendees. If for some reason the client needs to disable
-Server Generated Invitations, the command may be sent again with <bool> = 0.
+ ICAL putics
+ Delete the entire contents of a calendar room and replace it with the calendar
+ supplied by a client-input data stream. This is suitable for publishing a
+ calendar from third-party software. This command will output SEND_LISTING and
+ then expect the client to transmit the calendar data stream. Alternatively,
+ it will return ERROR if the requested operation is not permitted.
Again, keep in mind that this is a temporary implementation and is not
guaranteed to continue to exist in this form.
+
+
+
+EUID (get message number using an EUID)}
+
+ Returns the message number, if present, of the message in the current room
+which is indexed using the supplied EUID (exclusive message ID). There can be
+only one message in a room with any given EUID; if another message arrives
+with the same EUID, the existing one is replaced. This makes it possible to
+reference things like calendar items using an immutable URL that does not
+change even when the message number changes due to an update.
+
+ The format of this command is: EUID <euid>
+
+ If successful, EUID returns OK followed by a message number.
+ If no message exists in the current room with the supplied EUID, the command
+returns ERROR+MESSAGE_NOT_FOUND.
+
+
+MSIV (Manage SIeVe scripts)
+
+This command is the interface to Citadel's implementation of Sieve, the
+mail filtering and sorting language. Clients may automate the handling
+of incoming messages to their inbox by administering one or more Sieve
+scripts. The available subcommands are:
+
+ MSIV putscript|<scriptname>
+
+ Add a new script or replace an existing one. Always returns
+SEND_LISTING and expects the client to transmit the script content.
+
+ MSIV listscripts
+
+ List the scripts which are available for this account. Returns
+LISTING_FOLLOWS followed by a list of available scripts. Each line of
+the output contains two parameters: the name of the script, and 0 or 1
+to indicate whether the script is active.
+
+ MSIV setactive|<scriptname>
+
+ Choose which script is to become the active one that handles the
+user's inbox. <scriptname> must be either the name of an existing
+script or an empty string to indicate that the user wishes to disable
+all scripts. Returns OK if successful, or ERROR if the supplied name
+is invalid.
+
+ MSIV getscript|<scriptname>
+
+ Output one of the existing scripts. Returns LISTING_FOLLOWS followed
+by the script, or ERROR if the named script does not exist.
+
+ MSIV deletescript|<scriptname>
+
+ Delete one of the existing scripts. Returns OK if the script was
+deleted, or ERROR if the named script does not exist or cannot be
+deleted because it is active.
projects / citadel.git / blobdiff