The Akonadi Server Protocol ============================ This document is the official specification of the Akonadi server protocol in version 17. Table of Contents ------------------- 1. General Information 2. Commands 2.1 States 2.2 Scopes 2.3 Command Descriptions 1) General Information ======================= The protocol used for the communication between the applications and the Akonadi server has its roots in the IMAP protocol [RFC 3501], therefor the overall command structure is quite similar and existing IMAP libraries can be abused by extending them with the additional, Akonadi specific commands. However in some parts, the IMAP standard has been extended or changed to better match the requirements of Akonadi's data transport mechanisms. The connection to the Akonadi server is established via a UnixDomain Socket under *nix or a NamedPipe under Windows. After the connection is up, the server initializes the protocol by sending the greeting message * OK Akonadi Almost IMAP Server [PROTOCOL 17] that includes the number of the protocol version, which is 17 in this example. Clients should always check that version number and avoid communication if their minimum requirement is not met. In the next step the client can start with sending commands to the server to continue communication. 2) Commands ============ The basic commands of IMAP have been reused, sometimes with slightly different semantics. For example the LOGIN command does not take user credentials as arguments, as every user runs its own Akonadi server and an authentication is pointless in this case. Instead a session identifier is passed, that allowas easy management of parallel communication. 2.1) States ------------ Like in IMAP, the Akonadi server protocol categorizes the allowed commands into 3 states: - Always - UnAuthenticated - Authenticated Commands from the 'Always' category can be send to the server at any time, independent of any other state information. Examples are the NOOP command, that does nothing then keeping the connection alive. Commands from the 'UnAuthenticated' category can only be executed if the connection is in the UnAuthenticated state. That's the case after the connection has been initialized or after the command LOGOUT has been executed. In this state the command LOGIN can be used to switch into the third state Authenticated, in which most of the other commands can be executed. 2.2) Scopes ------------ In opposite to the IMAP protocol, the Akonadi server protocol supports so called scopes. That are status information that influence how the parameter of commands are interpreted by the server. Scope identifiers can be prepended to the command strings and are valid for a single command call. Available scopes are - Empty scope - Uid scope - Rid scope Uid scope means that identifiers that are passed as arguments to a command are interpreted as the unique identifier that every item and collection inside Akonadi has. The Rid scope means that the passed identifier is the remote identifier of the item or collection. The different behaviour will be explained in detail in the descriptions of the single commands. 2.3) Commands -------------- To describe the commands extensivly we introduce an abstract description of the following form: DESCRIPTION: A short textual description of what the commands is supposed to do COMMAND: The literal command string that is send to the server STATES: A list of states in which the commands can be used, possible values are: Always, UnAuthenticated, Authenticated SCOPES: A list of scopes that can be passed together with the command ARGUMENTS: A formal description of the arguments that can be passed with the command EXAMPLES: Some example command calls that shall improve the understanding RESPONSES: Possible responses of the example calls DETAILS: Further descriptions of the command 2.3.X) The LOGIN command ------------------------ DESCRIPTION: COMMAND: LOGIN STATES: UnAuthenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The LOGOUT command ------------------------ DESCRIPTION: COMMAND: LOGOUT STATES: Always SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The CAPABILITY command ------------------------ DESCRIPTION: COMMAND: CAPABILITY STATES: Always SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The SELECT command -------------------------- DESCRIPTION: COMMAND: SELECT STATES: Authenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The LIST command ---------------------------- DESCRIPTION: COMMAND: LIST STATES: Authenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The LSUB command ---------------------------- DESCRIPTION: COMMAND: LSUB STATES: Authenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The SEARCH_STORE command -------------------------------- DESCRIPTION: COMMAND: SEARCH_STORE STATES: Authenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The STATUS command -------------------------- DESCRIPTION: COMMAND: STATUS STATES: Authenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The BEGIN command ------------------------- DESCRIPTION: COMMAND: BEGIN STATES: Authenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The ROLLBACK command ---------------------------- DESCRIPTION: COMMAND: ROLLBACK STATES: Authenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The COMMIT command -------------------------- DESCRIPTION: COMMAND: COMMIT STATES: Authenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The SUBSCRIBE command ----------------------------- DESCRIPTION: COMMAND: SUBSCRIBE STATES: Authenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The UNSUBSCRIBE command ------------------------------- DESCRIPTION: COMMAND: UNSUBSCRIBE STATES: Authenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The LINK command ------------------------ DESCRIPTION: COMMAND: LINK STATES: Authenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The UNLINK command -------------------------- DESCRIPTION: COMMAND: UNLINK STATES: Authenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The COLCOPY command -------------------------- DESCRIPTION: Copies a collection in the storage COMMAND: COLCOPY STATES: Authenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The CREATE command -------------------------- DESCRIPTION: Creates a new collection in the storage COMMAND: CREATE STATES: Authenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The DELETE command -------------------------- DESCRIPTION: Deletes a collection in the storage COMMAND: DELETE STATES: Authenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The MODIFY command -------------------------- DESCRIPTION: Modifies the properties of a collection in the storage COMMAND: MODIFY STATES: Authenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The COLMOVE command -------------------------- DESCRIPTION: Moves a collection in the storage COMMAND: COLMOVE STATES: Authenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The COPY command -------------------------- DESCRIPTION: Copies an item in the storage COMMAND: COPY STATES: Authenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The X-AKAPPEND command -------------------------- DESCRIPTION: Creates a new item in the storage COMMAND: X-AKAPPEND STATES: Authenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The REMOVE command -------------------------- DESCRIPTION: Deletes an item from the storage COMMAND: REMOVE STATES: Authenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The FETCH command -------------------------- DESCRIPTION: Fetches the data of an item from the storage COMMAND: FETCH STATES: Authenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The STORE command -------------------------- DESCRIPTION: Modifies the properties of an item in the storage COMMAND: STORE STATES: Authenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: 2.3.X) The MOVE command -------------------------- DESCRIPTION: Moves an item in the storage COMMAND: MOVE STATES: Authenticated SCOPES: ARGUMENTS: EXAMPLES: RESPONSES: DETAILS: #define AKONADI_CMD_RESOURCESELECT "RESSELECT"