class ResourceBase


abstract

Module akonadi
Namespace Akonadi
Class ResourceBase
Inherits Akonadi::AgentBase
This class should be used as a base class by all resource agents, since it encapsulates large parts of the protocol between resource agent, agent manager and storage.

It provides many convenience methods to make implementing a new Akonadi resource agent as simple as possible.

How to write a resource

The following provides an overview of what you need to do to implement your own Akonadi resource. In the following, the term 'backend' refers to the entity the resource connects with Akonadi, be it a single file or a remote server.

To do: Complete this (online/offline state management)

Basic %Resource Framework

The following is needed to create a new resource: - A new class deriving from Akonadi.ResourceBase, implementing at least all pure-virtual methods, see below for further details. - call init() in your main() function. - a .desktop file similar to the following example

[Desktop Entry]
Encoding=UTF-8
Name=My Akonadi Resource
Type=AkonadiResource
Exec=akonadi_my_resource
Icon=my-icon

X-Akonadi-MimeTypes= X-Akonadi-Capabilities=Resource X-Akonadi-Identifier=akonadi_my_resource

Handling PIM Items

To follow item changes in the backend, the following steps are necessary: - Implement retrieveItems() to synchronize all items in the given collection. If the backend supports incremental retrieval, implementing support for that is recommended to improve performance. - Convert the items provided by the backend to Akonadi items. This typically happens either in retrieveItems() if you retrieved the collection synchronously (not recommended for network backends) or in the result slot of the asynchronous retrieval job. Converting means to create Akonadi.Item objects for every retrieved item. It's very important that every object has its remote identifier set. - Call itemsRetrieved() or itemsRetrievedIncremental() respectively with the item objects created above. The Akonadi storage will then be updated automatically. Note that it is usually not necessary to manipulate any item in the Akonadi storage manually.

To fetch item data on demand, the method retrieveItem() needs to be reimplemented. Fetch the requested data there and call itemRetrieved() with the result item.

To write local changes back to the backend, you need to re-implement the following three methods: - itemAdded() - itemChanged() - itemRemoved() Once you have handled changes in these methods call changeCommitted(). These methods are called whenever a local item related to this resource is added, modified or deleted. They are only called if the resource is online, otherwise all changes are recorded and replayed as soon the resource is online again.

Handling Collections

To follow collection changes in the backend, the following steps are necessary: - Implement retrieveCollections() to retrieve collections from the backend. If the backend supports incremental collections updates, implementing support for that is recommended to improve performance. - Convert the collections of the backend to Akonadi collections. This typically happens either in retrieveCollections() if you retrieved the collection synchronously (not recommended for network backends) or in the result slot of the asynchronous retrieval job. Converting means to create Akonadi.Collection objects for every retrieved collection. It's very important that every object has its remote identifier and its parent remote identifier set. - Call collectionsRetrieved() or collectionsRetrievedIncremental() respectively with the collection objects created above. The Akonadi storage will then be updated automatically. Note that it is usually not necessary to manipulate any collection in the Akonadi storage manually.

To write local collection changes back to the backend, you need to re-implement the following three methods: - collectionAdded() - collectionChanged() - collectionRemoved() Once you have handled changes in these methods call changeCommitted(). These methods are called whenever a local collection related to this resource is added, modified or deleted. They are only called if the resource is online, otherwise all changes are recorded and replayed as soon the resource is online again.

To do: Convenience base class for collection-less resources



methods