• Skip to content
  • Skip to link menu
  • KDE API Reference
  • kdepimlibs-4.8.3 API Reference
  • KDE Home
  • Contact Us
 

akonadi

  • Akonadi
  • ResourceBase
Signals | Public Member Functions | Static Public Member Functions | Protected Types | Protected Slots | Protected Member Functions
Akonadi::ResourceBase Class Reference

#include <resourcebase.h>

Inheritance diagram for Akonadi::ResourceBase:
Inheritance graph
[legend]

List of all members.

Signals

void attributesSynchronized (qlonglong collectionId)
void collectionTreeSynchronized ()
void nameChanged (const QString &name)
void synchronized ()

Public Member Functions

QString name () const
void setAutomaticProgressReporting (bool enabled)
void setName (const QString &name)

Static Public Member Functions

template<typename T >
static int init (int argc, char **argv)

Protected Types

enum  SchedulePriority { Prepend, AfterChangeReplay, Append }

Protected Slots

void abortActivity ()
void retrieveCollectionAttributes (const Akonadi::Collection &collection)
virtual void retrieveCollections ()=0
virtual bool retrieveItem (const Akonadi::Item &item, const QSet< QByteArray > &parts)=0
virtual void retrieveItems (const Akonadi::Collection &collection)=0

Protected Member Functions

 ResourceBase (const QString &id)
 ~ResourceBase ()
void cancelTask ()
void cancelTask (const QString &error)
void changeCommitted (const Item &item)
void changeCommitted (const Collection &collection)
void clearCache ()
void collectionAttributesRetrieved (const Collection &collection)
void collectionsRetrievalDone ()
void collectionsRetrieved (const Collection::List &collections)
void collectionsRetrievedIncremental (const Collection::List &changedCollections, const Collection::List &removedCollections)
Collection currentCollection () const
Item currentItem () const
void deferTask ()
void doSetOnline (bool online)
QString dumpNotificationListToString () const
QString dumpSchedulerToString () const
void invalidateCache (const Collection &collection)
void itemRetrieved (const Item &item)
void itemsRetrievalDone ()
void itemsRetrieved (const Item::List &items)
void itemsRetrievedIncremental (const Item::List &changedItems, const Item::List &removedItems)
void scheduleCustomTask (QObject *receiver, const char *method, const QVariant &argument, SchedulePriority priority=Append)
void setCollectionStreamingEnabled (bool enable)
void setHierarchicalRemoteIdentifiersEnabled (bool enable)
void setItemStreamingEnabled (bool enable)
void setItemSynchronizationFetchScope (const ItemFetchScope &fetchScope)
void setItemTransactionMode (ItemSync::TransactionMode mode)
void setTotalItems (int amount)
void synchronize ()
void synchronizeCollection (qint64 id)
void synchronizeCollection (qint64 id, bool recursive)
void synchronizeCollectionAttributes (qint64 id)
void synchronizeCollectionTree ()
void taskDone ()

Detailed Description

The base class for all Akonadi resources.

This class should be used as a base class by all resource agents, because it encapsulates large parts of the protocol between resource agent, agent manager and the Akonadi 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.

Todo:
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=<supported-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()

Note that these three functions don't get the full payload of the items by default, you need to change the item fetch scope of the change recorder to fetch the full payload. This can be expensive with big payloads, though.
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.
Todo:
Convenience base class for collection-less resources

Definition at line 146 of file resourcebase.h.


Member Enumeration Documentation

enum Akonadi::ResourceBase::SchedulePriority [protected]

Describes the scheduling priority of a task that has been queued for execution.

See also:
scheduleCustomTask
Since:
4.4
Enumerator:
Prepend 

The task will be executed as soon as the current task has finished.

AfterChangeReplay 

The task is scheduled after the last ChangeReplay task in the queue.

Append 

The task will be executed after all tasks currently in the queue are finished.

Definition at line 570 of file resourcebase.h.


Constructor & Destructor Documentation

ResourceBase::ResourceBase ( const QString &  id) [protected]

Creates a base resource.

Parameters:
idThe instance id of the resource.

Definition at line 296 of file resourcebase.cpp.

ResourceBase::~ResourceBase ( ) [protected]

Destroys the base resource.

Definition at line 355 of file resourcebase.cpp.


Member Function Documentation

void Akonadi::ResourceBase::abortActivity ( ) [protected, slot]

Abort any activity in progress in the backend.

By default this method does nothing.

Since:
4.6

Definition at line 995 of file resourcebase.cpp.

void Akonadi::ResourceBase::attributesSynchronized ( qlonglong  collectionId) [signal]

Emitted when a collection attributes synchronization has been completed.

Parameters:
collectionIdThe identifier of the collection whose attributes got synchronized.
Since:
4.6
void ResourceBase::cancelTask ( ) [protected]

Stops the execution of the current task and continues with the next one.

Definition at line 789 of file resourcebase.cpp.

void Akonadi::ResourceBase::cancelTask ( const QString &  error) [protected]

Stops the execution of the current task and continues with the next one.

Additionally an error message is emitted.

void ResourceBase::changeCommitted ( const Item &  item) [protected]

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().

Parameters:
itemThe changed item.

Definition at line 530 of file resourcebase.cpp.

void ResourceBase::changeCommitted ( const Collection &  collection) [protected]

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().

Parameters:
collectionThe collection which changes have been handled.

Definition at line 540 of file resourcebase.cpp.

void ResourceBase::clearCache ( ) [protected]

Call this method to remove all items and collections of the resource from the server cache.

The method should not be used anymore

See also:
invalidateCache()
Since:
4.3

Definition at line 754 of file resourcebase.cpp.

void ResourceBase::collectionAttributesRetrieved ( const Collection &  collection) [protected]

Call this method from retrieveCollectionAttributes() once the result is available.

Parameters:
itemThe collection whose attributes got retrieved.
Since:
4.6

Definition at line 460 of file resourcebase.cpp.

void ResourceBase::collectionsRetrievalDone ( ) [protected]

Call this method to indicate you finished synchronizing the collection tree.

This is not needed if you use the built in syncing without collection streaming and call collectionsRetrieved() or collectionRetrievedIncremental() instead. If collection streaming is enabled, call this method once all collections have been delivered using collectionsRetrieved() or collectionsRetrievedIncremental().

Definition at line 628 of file resourcebase.cpp.

void ResourceBase::collectionsRetrieved ( const Collection::List &  collections) [protected]

Call this to supply the full folder tree retrieved from the remote server.

Parameters:
collectionsA list of collections.
See also:
collectionsRetrievedIncremental()

Definition at line 579 of file resourcebase.cpp.

void ResourceBase::collectionsRetrievedIncremental ( const Collection::List &  changedCollections,
const Collection::List &  removedCollections 
) [protected]

Call this to supply incrementally retrieved collections from the remote server.

Parameters:
changedCollectionsCollections that have been added or changed.
removedCollectionsCollections that have been deleted.
See also:
collectionsRetrieved()

Definition at line 595 of file resourcebase.cpp.

void Akonadi::ResourceBase::collectionTreeSynchronized ( ) [signal]

Emitted when a collection tree synchronization has been completed.

Since:
4.8
Collection ResourceBase::currentCollection ( ) const [protected]

Returns the collection that is currently synchronized.

Note:
Calling this method is only allowed during a collection synchronization task, that is directly or indirectly from retrieveItems().

Definition at line 766 of file resourcebase.cpp.

Item ResourceBase::currentItem ( ) const [protected]

Returns the item that is currently retrieved.

Note:
Calling this method is only allowed during fetching a single item, that is directly or indirectly from retrieveItem().

Definition at line 775 of file resourcebase.cpp.

void ResourceBase::deferTask ( ) [protected]

Stops the execution of the current task and continues with the next one.

The current task will be tried again later.

This can be used to delay the task processing until the resource has reached a safe state, e.g. login to a server succeeded.

Note:
This does not change the order of tasks so if there is no task with higher priority e.g. a custom task added with #Prepend the deferred task will be processed again.
Since:
4.3

Definition at line 825 of file resourcebase.cpp.

void ResourceBase::doSetOnline ( bool  online) [protected, virtual]

Inherited from AgentBase.

Reimplemented from Akonadi::AgentBase.

Definition at line 831 of file resourcebase.cpp.

QString ResourceBase::dumpNotificationListToString ( ) const [protected]

Dump the contents of the current ChangeReplay.

Since:
4.8.1

Definition at line 1020 of file resourcebase.cpp.

QString ResourceBase::dumpSchedulerToString ( ) const [protected]

Dump the state of the scheduler.

Since:
4.8.1

Definition at line 1026 of file resourcebase.cpp.

template<typename T >
static int Akonadi::ResourceBase::init ( int  argc,
char **  argv 
) [inline, static]

Use this method in the main function of your resource application to initialize your resource subclass.

This method also takes care of creating a KApplication object and parsing command line arguments.

Note:
In case the given class is also derived from AgentBase::Observer it gets registered as its own observer (see AgentBase::Observer), e.g. resourceInstance->registerObserver( resourceInstance );
   class MyResource : public ResourceBase
   {
     ...
   };

   int main( int argc, char **argv )
   {
     return ResourceBase::init<MyResource>( argc, argv );
   }

Reimplemented from Akonadi::AgentBase.

Definition at line 176 of file resourcebase.h.

void ResourceBase::invalidateCache ( const Collection &  collection) [protected]

Call this method to invalidate all cached content in collection.

The method should be used when the backend indicated that the cached content is no longer valid.

Since:
4.8

Definition at line 760 of file resourcebase.cpp.

void ResourceBase::itemRetrieved ( const Item &  item) [protected]

Call this method from retrieveItem() once the result is available.

Parameters:
itemThe retrieved item.

Definition at line 425 of file resourcebase.cpp.

void ResourceBase::itemsRetrievalDone ( ) [protected]

Call this method to indicate you finished synchronizing the current collection.

This is not needed if you use the built in syncing without item streaming and call itemsRetrieved() or itemsRetrievedIncremental() instead. If item streaming is enabled, call this method once all items have been delivered using itemsRetrieved() or itemsRetrievedIncremental().

See also:
retrieveItems()

Definition at line 741 of file resourcebase.cpp.

void ResourceBase::itemsRetrieved ( const Item::List &  items) [protected]

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.

Parameters:
itemsA list of items.
See also:
itemsRetrievedIncremental().

Definition at line 906 of file resourcebase.cpp.

void ResourceBase::itemsRetrievedIncremental ( const Item::List &  changedItems,
const Item::List &  removedItems 
) [protected]

Call this method to supply incrementally retrieved items from the remote server.

Parameters:
changedItemsItems changed in the backend.
removedItemsItems removed from the backend.

Definition at line 915 of file resourcebase.cpp.

QString ResourceBase::name ( ) const

Returns the name of the resource.

Definition at line 369 of file resourcebase.cpp.

void Akonadi::ResourceBase::nameChanged ( const QString &  name) [signal]

This signal is emitted whenever the name of the resource has changed.

Parameters:
nameThe new name of the resource.
void ResourceBase::retrieveCollectionAttributes ( const Akonadi::Collection &  collection) [protected, slot]

Retrieve the attributes of a single collection from the backend.

The collection to retrieve attributes for is provided as collection. Add the attributes parts and call collectionAttributesRetrieved() when done.

Parameters:
collectionThe collection whose attributes should be retrieved.
See also:
collectionAttributesRetrieved()
Since:
4.6

Definition at line 990 of file resourcebase.cpp.

virtual void Akonadi::ResourceBase::retrieveCollections ( ) [protected, pure virtual, slot]

Retrieve the collection tree from the remote server and supply it via collectionsRetrieved() or collectionsRetrievedIncremental().

See also:
collectionsRetrieved(), collectionsRetrievedIncremental()
virtual bool Akonadi::ResourceBase::retrieveItem ( const Akonadi::Item &  item,
const QSet< QByteArray > &  parts 
) [protected, pure virtual, slot]

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.

Parameters:
itemThe empty item whose payload should be retrieved. Use this object when delivering the result instead of creating a new item to ensure conflict detection will work.
partsThe item parts that should be retrieved.
Returns:
false if there is an immediate error when retrieving the item.
See also:
itemRetrieved()
virtual void Akonadi::ResourceBase::retrieveItems ( const Akonadi::Collection &  collection) [protected, pure virtual, slot]

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 items already existing locally. In case you don't want to use the built-in item syncing code, store the retrieved items manually and call itemsRetrieved() once you are done.

Parameters:
collectionThe collection whose items to retrieve.
See also:
itemsRetrieved( const Item::List& ), itemsRetrievedIncremental(), itemsRetrieved(), currentCollection()
void ResourceBase::scheduleCustomTask ( QObject *  receiver,
const char *  method,
const QVariant &  argument,
SchedulePriority  priority = Append 
) [protected]

Schedules a custom task in the internal scheduler.

It will be queued with all other tasks such as change replays and retrieval requests and eventually executed by calling the specified method. With the priority parameter the time of execution of the Task can be influenced.

See also:
SchedulePriority
Parameters:
receiverThe object the slot should be called on.
methodThe name of the method (and only the name, not signature, not SLOT(...) macro), that should be called to execute this task. The method has to be a slot and take a QVariant as argument.
argumentA QVariant argument passed to the method specified above. Use this to pass task parameters.
priorityPriority of the task. Use this to influence the position in the execution queue.
Since:
4.4

Definition at line 978 of file resourcebase.cpp.

void ResourceBase::setAutomaticProgressReporting ( bool  enabled)

Enable or disable automatic progress reporting.

By default, it is enabled. When enabled, the resource will automatically emit the signals percent() and status() while syncing items or collections.

The automatic progress reporting is done on a per item / per collection basis, so if a finer granularity is desired, automatic reporting should be disabled and the subclass should emit the percent() and status() signals itself.

Parameters:
enabledWhether or not automatic emission of the signals is enabled.
Since:
4.7

Definition at line 1014 of file resourcebase.cpp.

void ResourceBase::setCollectionStreamingEnabled ( bool  enable) [protected]

Enable collection streaming, that is collections don't have to be delivered at once as result of a retrieveCollections() call but can be delivered by multiple calls to collectionsRetrieved() or collectionsRetrievedIncremental().

When all collections have been retrieved, call collectionsRetrievalDone().

Parameters:
enabletrue if collection streaming should be enabled, false by default

Definition at line 612 of file resourcebase.cpp.

void ResourceBase::setHierarchicalRemoteIdentifiersEnabled ( bool  enable) [protected]

Indicate the use of hierarchical remote identifiers.

This means that it is possible to have two different items with the same remoteId in different Collections.

This should be called in the resource constructor as needed.

Since:
4.4

Definition at line 972 of file resourcebase.cpp.

void ResourceBase::setItemStreamingEnabled ( bool  enable) [protected]

Enable item streaming.

Item streaming is disabled by default.

Parameters:
enabletrue if items are delivered in chunks rather in one big block.

Definition at line 897 of file resourcebase.cpp.

void ResourceBase::setItemSynchronizationFetchScope ( const ItemFetchScope &  fetchScope) [protected]

Set the fetch scope applied for item synchronization.

By default, the one set on the changeRecorder() is used. However, it can make sense to specify a specialized fetch scope for synchronization to improve performance. The rule of thumb is to remove anything from this fetch scope that does not provide additional information regarding whether and item has changed or not. This is primarily relevant for backends not supporting incremental retrieval.

Parameters:
fetchScopeThe fetch scope to use by the internal Akonadi::ItemSync instance.
See also:
Akonadi::ItemSync
Since:
4.6

Definition at line 1006 of file resourcebase.cpp.

void ResourceBase::setItemTransactionMode ( ItemSync::TransactionMode  mode) [protected]

Set transaction mode for item sync'ing.

See also:
Akonadi::ItemSync::TransactionMode
Since:
4.6

Definition at line 1000 of file resourcebase.cpp.

void ResourceBase::setName ( const QString &  name)

This method is used to set the name of the resource.

Definition at line 364 of file resourcebase.cpp.

void ResourceBase::setTotalItems ( int  amount) [protected]

Call this method when you want to use the itemsRetrieved() method in streaming mode and indicate the amount of items that will arrive that way.

Deprecated:
Use setItemStreamingEnabled( true ) + itemsRetrieved[Incremental]()
  • itemsRetrieved() instead.

Definition at line 887 of file resourcebase.cpp.

void ResourceBase::synchronize ( ) [protected]

This method is called whenever the resource should start synchronize all data.

Definition at line 359 of file resourcebase.cpp.

void Akonadi::ResourceBase::synchronizeCollection ( qint64  id) [protected]

This method is called whenever the collection with the given id shall be synchronized.

void Akonadi::ResourceBase::synchronizeCollection ( qint64  id,
bool  recursive 
) [protected]

This method is called whenever the collection with the given id shall be synchronized.

Parameters:
recursiveif true, a recursive synchronization is done
void ResourceBase::synchronizeCollectionAttributes ( qint64  id) [protected]

This method is called whenever the collection with the given id shall have its attributes synchronized.

Parameters:
idThe id of the collection to synchronize
Since:
4.6

Definition at line 867 of file resourcebase.cpp.

void ResourceBase::synchronizeCollectionTree ( ) [protected]

Refetches the Collections.

Definition at line 784 of file resourcebase.cpp.

void Akonadi::ResourceBase::synchronized ( ) [signal]

Emitted when a full synchronization has been completed.

void ResourceBase::taskDone ( ) [protected]

Indicate that the current task is finished.

Use this method from the slot called via scheduleCustomTaks(). As with all the other callbacks, make sure to either call taskDone() or cancelTask()/deferTask() on all exit paths, otherwise the resource will hang.

Since:
4.4

Definition at line 984 of file resourcebase.cpp.


The documentation for this class was generated from the following files:
  • resourcebase.h
  • resourcebase.cpp
This file is part of the KDE documentation.
Documentation copyright © 1996-2012 The KDE developers.
Generated on Mon Apr 30 2012 21:49:17 by doxygen 1.8.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.

akonadi

Skip menu "akonadi"
  • Main Page
  • Namespace List
  • Namespace Members
  • Alphabetical List
  • Class List
  • Class Hierarchy
  • Class Members
  • File List
  • Modules
  • Related Pages

kdepimlibs-4.8.3 API Reference

Skip menu "kdepimlibs-4.8.3 API Reference"
  • akonadi
  •   contact
  •   kmime
  • kabc
  • kalarmcal
  • kblog
  • kcal
  • kcalcore
  • kcalutils
  • kholidays
  • kimap
  • kioslave
  •   imap4
  •   mbox
  •   nntp
  • kldap
  • kmbox
  • kmime
  • kontactinterface
  • kpimidentities
  • kpimtextedit
  •   richtextbuilders
  • kpimutils
  • kresources
  • ktnef
  • kxmlrpcclient
  • mailtransport
  • microblog
  • qgpgme
  • syndication
  •   atom
  •   rdf
  •   rss2
Report problems with this website to our bug tracking system.
Contact the specific authors with questions and comments about the page contents.

KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal