Katana_mirror/kde-playground
1
0
Fork 0
mirror of https://bitbucket.org/smil3y/kde-playground.git synced 2025-02-23 18:32:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
kde-playground/akonadi/server/AkonadiServerProtocol.txt
Ivailo Monev 438d2bd635 akonadi: import 1.13.0
2015-09-23 09:37:02 +00:00

578 lines
9.1 KiB
Text
Raw Permalink Blame History

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"
Reference in a new issue View git blame Copy permalink