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"
