• Skip to content
  • Skip to link menu
KDE 4.1 API Reference
  • KDE API Reference
  • KDE-PIM Libraries
  • Sitemap
  • Contact Us
 

akonadi

Akonadi::ResourceBase

Akonadi::ResourceBase Class Reference

#include <resourcebase.h>

Inheritance diagram for Akonadi::ResourceBase:

Inheritance graph
[legend]

List of all members.


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() 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 141 of file resourcebase.h.


Signals

void nameChanged (const QString &name)

Public Member Functions

QString name () const
void setName (const QString &name)

Static Public Member Functions

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

Protected Slots

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

void cancelTask (const QString &error)
void cancelTask ()
void changeCommitted (const Collection &collection)
void changeCommitted (const Item &item)
void collectionsRetrieved (const Collection::List &collections)
void collectionsRetrievedIncremental (const Collection::List &changedCollections, const Collection::List &removedCollections)
Collection currentCollection () const
Item currentItem () const
void doSetOnline (bool online)
void itemRetrieved (const Item &item)
void itemsRetrievalDone ()
void itemsRetrieved (const Item::List &items)
void itemsRetrievedIncremental (const Item::List &changedItems, const Item::List &removedItems)
 ResourceBase (const QString &id)
void setItemStreamingEnabled (bool enable)
void setTotalItems (int amount)
void synchronize ()
void synchronizeCollection (qint64 id)
void synchronizeCollectionTree ()
 ~ResourceBase ()

Constructor & Destructor Documentation

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

Creates a base resource.

Parameters:
id The instance id of the resource.

Definition at line 103 of file resourcebase.cpp.

ResourceBase::~ResourceBase (  )  [protected]

Destroys the base resource.

Definition at line 138 of file resourcebase.cpp.


Member Function Documentation

void 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.

Definition at line 406 of file resourcebase.cpp.

void ResourceBase::cancelTask (  )  [protected]

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

Definition at line 401 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:
collection The collection which changes have been handled.

Definition at line 267 of file resourcebase.cpp.

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:
item The changed item.

Definition at line 258 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:
collections A list of collections.
See also:
collectionsRetrievedIncremental()

Definition at line 300 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:
changedCollections Collections that have been added or changed.
removedCollections Collections that have been deleted.
See also:
collectionsRetrieved()

Definition at line 308 of file resourcebase.cpp.

Collection ResourceBase::currentCollection (  )  const [protected]

Returns the collection that is currently synchronized.

Definition at line 378 of file resourcebase.cpp.

Item ResourceBase::currentItem (  )  const [protected]

Returns the item that is currently retrieved.

Definition at line 387 of file resourcebase.cpp.

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

Inherited from AgentBase.

Reimplemented from Akonadi::AgentBase.

Definition at line 413 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 171 of file resourcebase.h.

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

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

Parameters:
item The retrieved item.

Definition at line 217 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 363 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:
items A list of items.
See also:
itemsRetrievedIncremental().

Definition at line 459 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:
changedItems Items changed in the backend.
removedItems Items removed from the backend.

Definition at line 473 of file resourcebase.cpp.

QString ResourceBase::name (  )  const

Returns the name of the resource.

Definition at line 166 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:
name The new name of the resource.

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

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

Parameters:
collection The collection to sync.
See also:
itemsRetrieved( const Item::List &), itemsRetrievedIncremental(), itemsRetrieved(), currentCollection()

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

Enable item streaming.

Item streaming is disabled by default.

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

Definition at line 445 of file resourcebase.cpp.

void ResourceBase::setName ( const QString &  name  ) 

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

Definition at line 147 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 437 of file resourcebase.cpp.

void ResourceBase::synchronize (  )  [protected]

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

Definition at line 142 of file resourcebase.cpp.

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

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

Definition at line 418 of file resourcebase.cpp.

void ResourceBase::synchronizeCollectionTree (  )  [protected]

Refetches the Collections.

Definition at line 396 of file resourcebase.cpp.


The documentation for this class was generated from the following files:
  • resourcebase.h
  • resourcebase.cpp

akonadi

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

KDE-PIM Libraries

Skip menu "KDE-PIM Libraries"
  • akonadi
  • kabc
  • kblog
  • kcal
  • kimap
  • kioslave
  •   imap4
  •   mbox
  • kldap
  • kmime
  • kpimidentities
  • kpimutils
  • kresources
  • ktnef
  • kxmlrpcclient
  • mailtransport
  • qgpgme
  • syndication
  •   atom
  •   rdf
  •   rss2
Generated for KDE-PIM Libraries by doxygen 1.5.4
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal