class ResourceBaseabstract |
|
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 resourceThe 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 FrameworkThe 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
Handling PIM ItemsTo 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 CollectionsTo 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 |
|
Creates a base resource.
id - The instance id of the resource. |
|
Destroys the base resource. |
|
Stops the execution of the current task and continues with the next one. |
|
Stops the execution of the current task and continues with the next one. Additionally an error message is emitted. |
|
Resets the dirty flag of the given item and updates the remote id.
Call whenever you have successfully written changes back to the server. This implicitly calls changeProcessed(). item - The changed item. |
|
Call whenever you have successfully handled or ignored a collection
change notification.
This will update the remote identifier of collection if necessary, as well as any other collection attributes. This implicitly calls changeProcessed(). collection - The collection which changes have been handled. |
|
Call this to supply the full folder tree retrieved from the remote server.
collections - A list of collections. See also collectionsRetrievedIncremental() |
|
Call this to supply incrementally retrieved collections from the remote server.
changedCollections - Collections that have been added or changed. removedCollections - Collections that have been deleted. See also collectionsRetrieved() |
|
Returns the collection that is currently synchronized. |
|
Returns the item that is currently retrieved. |
|
Inherited from AgentBase. |
|
Call this method from retrieveItem() once the result is available.
item - The retrieved item. |
|
Call this method to supply a part of the collection listing from the remote server.
Set the total amount of items you are going to pass via subsequent calls to this
method by calling setTotalItems() first.
If the remote server supports incremental listing, it's strongly recommended to use itemsRetrievedIncremental() instead. items - A list of items. See also itemsRetrievedIncremental(). |
|
Call this method to indicate you finished synchronizing the current collection.
This is not needed if you use the built in syncing and call itemsRetrieved() or itemsRetrievedIncremental() instead. See also retrieveItems() |
|
Call this method to supply the full collection listing from the remote server.
If the remote server supports incremental listing, it's strongly recommended to use itemsRetrievedIncremental() instead. items - A list of items. See also itemsRetrievedIncremental(). |
|
Call this method to supply incrementally retrieved items from the remote server.
changedItems - Items changed in the backend removedItems - Items removed from the backend |
|
Returns the name of the resource. |
|
This signal is emitted whenever the name of the resource has changed.
name - The new name of the resource. |
|
Retrieve the collection tree from the remote server and supply it via
collectionsRetrieved() or collectionsRetrievedIncremental().
See also collectionsRetrieved(), collectionsRetrievedIncremental() |
|
Retrieve a single item from the backend. The item to retrieve is provided as item.
Add the requested payload parts and call itemRetrieved() when done.
item - The empty item which payload should be retrieved. Use this object when delivering the result instead of creating a new item to ensure conflict detection to work. parts - The item parts that should be retrieved. Returns false if there is an immediate error when retrieving the item. See also itemRetrieved() |
|
Retrieve all (new/changed) items in collection collection.
It is recommended to use incremental retrieval if the backend supports that
and provide the result by calling itemsRetrievedIncremental().
If incremental retrieval is not possible, provide the full listing by calling
itemsRetrieved( const Item.List& ).
In any case, ensure that all items have a correctly set remote identifier
to allow synchronizing with already locally existing items.
In case you don't want to use the built-in item syncing code, store the retrived
items manually and call itemsRetrieved() once you are done.
collection - The collection to sync. See also itemsRetrieved( const Item.List &), itemsRetrievedIncremental(), itemsRetrieved(), currentCollection() |
|
This method is used to set the name of the resource. |
|
Call this method when you want to use the itemsPartlyRetrieved() method and indicate the amount of items that will arrive that way. |
|
This method is called whenever the resource should start synchronize all data. |
|
This method is called whenever the collection with the given id shall be synchronized. |
|
Refetches the Collections. |