Akonadi client library

Introduction

libakonadi is the client access library for using the Akonadi PIM data server. All processes accessing Akonadi, including those which communicate with a remote server (agents), are considered clients.

Functionality provided by libakonadi:

• Akonadi Objects
• Collection retrieval and manipulation
• PIM item retrieval and manipulation
• Low-level access to the Akonadi server
• Change notifications
• PIM item serializer
• Agents and Resources
• Integration in your Application

Additional information about Akonadi:

• Akonadi Server documentation
• Historical Background
• Website
• Wiki

Tools for developers:

• CDash
• Bugtracker

Akonadi Objects

Akonadi works on two basic object types: collections and items.

Collections are comparable to folders in a file system and are represented by the class Akonadi::Collection. Every collection has an associated cache policy represented by the class Akonadi::CachePolicy which defines what part of its content is cached for how long. All available ways to work with collections are listed in the Collections section.

Akonadi items are comparable to files in a file system and are represented by the class Akonadi::Item. Each item represents a single PIM object such as a mail or a contact. The actual object it represents is its so-called payload. All available ways to work with items are listed in the Items section.

Both items and collections are identified by a persistent unique identifier. Also, they can contain arbitrary attributes (derived from Akonadi::Attribute) to attach general or application specific meta data to them. Functionality common to both is provided by their base class Akonadi::Entity.

Collection retrieval and manipulation

A collection is represented by the Akonadi::Collection class.

Classes to retrieve information about collections:

• Akonadi::CollectionFetchJob
• Akonadi::CollectionSelectJob
• Akonadi::CollectionStatisticsJob

Classes to manipulate collections:

• Akonadi::CollectionCreateJob
• Akonadi::CollectionCopyJob
• Akonadi::CollectionModifyJob
• Akonadi::CollectionDeleteJob

There is also Akonadi::CollectionModel, which is a self-updating model class which can be used in combination with Akonadi::CollectionView. Akonadi::CollectionFilterProxyModel can be used to limit a displayed collection tree to collections supporting a certain type of PIM items. Akonadi::CollectionPropertiesDialog provides an extensible properties dialog for collections. Often needed KAction for collection operations are provided by Akonadi::StandardActionManager.

PIM item retrieval and manipulation

PIM items are represented by classes derived from Akonadi::Item. Items can be retrieved using Akonadi::ItemFetchJob.

The following classes are provided to manipulate PIM items:

• Akonadi::ItemCreateJob
• Akonadi::ItemCopyJob
• Akonadi::ItemModifyJob
• Akonadi::ItemDeleteJob

Akonadi::ItemModel provides a self-updating model class which can be used to display the content of a collection. Akonadi::ItemView is the base class for a corresponding view. Often needed KAction for item operations are provided by Akonadi::StandardActionManager.

Low-level access to the Akonadi server

Accessing the Akonadi server is done using job classes derived from Akonadi::Job. The communication channel with the server is provided by Akonadi::Session.

To use server-side transactions, the following jobs are provided:

• Akonadi::TransactionBeginJob
• Akonadi::TransactionCommitJob
• Akonadi::TransactionRollbackJob

There also is Akonadi::TransactionSequence which can be used to automatically group a set of jobs into a single transaction.

Change notifications

The Akonadi::Monitor class allows you to monitor specific resources, collections and PIM items for changes. Akonadi::ChangeRecorder augments this by providing a way to record and replay change notifications.

PIM item serializer

The class Akonadi::ItemSerializer is responsible for converting between the stored (binary) representation of a PIM item and the objects used to handle these items provided by the corresponding libraries (kabc, kcal, etc.).

Serializer plugins allow you to add support for new kinds of PIM items to Akonadi. Akonadi::ItemSerializerPlugin can be used as a base class for such a plugin.

Agents and Resources

Agents are independent processes that watch the Akonadi store for changes and react to them if necessary. Example: The Nepomuk feeder (kdepim/runtime/agents/nepomukfeeder/) is an agent that watches Akonadi for new emails, retrieves the new items, and feeds them to Nepomuk for indexing.

The class Akonadi::AgentBase is the common base class for all agents. It provides commonly needed functionality such as change monitoring and recording.

Resources are a special kind of agents. They are used as the actual backend for whatever data the resource represents. In this situation the akonadi server acts more like a proxy service. It caches data on behalf of its clients (client here being the Resource), not permanently storing it. The Akonadi server forwards item retrieval requests to the corresponding resource, if the item is not in the cache. Example: The imap resource is responsible for storing and fetching emails from an imap server.

Akonadi::ResourceBase is the base class for them. It provides the necessary interfaces to the server as well as many convenience functions to make implementing a new resource as easy as possible. Note that a collection contains items belonging to a single resource, although there are plans in the future for 'virtual' collections which will contain the results of a search query spanning multiple resources.

A resource can support multiple mimetypes. There are two places where a resource can specify mimetypes: in its desktop files, and in the content mimetypes field of collections created by it. The ones in the desktop file are used for filtering agent types, e.g. in the resource creation dialogs. The collection content mimetypes specify what you can actually put into a collection, which is not necessarily the same (e.g. the Kolab resource supports contacts and events, but not in the same folder).