# 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

- ResourceBase (id)

  returns ctor

  Argument | Type | Default
  --- | --- | ---
  id | QString |

  Creates a base resource.

  id - The instance id of the resource.

- ResourceBase ( )

  returns dtor

  Destroys the base resource.

- cancelTask ( )

  returns Nothing

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

- cancelTask (error)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  error | QString |

  Stops the execution of the current task and continues with the next one. Additionally an error message is emitted.

- changeCommitted (item)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  item | Akonadi.Item |

  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.

- changeCommitted (collection)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  collection | Akonadi.Collection |

  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.

- collectionsRetrieved (collections)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  collections | Akonadi.Collection.List |

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

  collections - A list of collections.

  See also collectionsRetrievedIncremental()

- collectionsRetrievedIncremental (changedCollections, removedCollections)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  changedCollections | Akonadi.Collection.List |
  removedCollections | Akonadi.Collection.List |

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

- currentCollection ( )

  returns Akonadi.Collection

  Returns the collection that is currently synchronized.

- currentItem ( )

  returns Akonadi.Item

  Returns the item that is currently retrieved.

- doSetOnline (online)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  online | bool |

  Inherited from AgentBase.

- itemRetrieved (item)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  item | Akonadi.Item |

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

  item - The retrieved item.

- itemsPartlyRetrieved (items)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  items | Akonadi.Item.List |

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

- itemsRetrievalDone ( )

  returns Nothing

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

- itemsRetrieved (items)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  items | Akonadi.Item.List |

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

- itemsRetrievedIncremental (changedItems, removedItems)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  changedItems | Akonadi.Item.List |
  removedItems | Akonadi.Item.List |

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

  changedItems - Items changed in the backend

  removedItems - Items removed from the backend

- name ( )

  returns QString

  Returns the name of the resource.

- nameChanged (name)

  returns Nothing
  SIGNAL ("nameChanged (const QString&)")

  Argument | Type | Default
  --- | --- | ---
  name | QString |

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

  name - The new name of the resource.

- retrieveCollections ( )

  returns Nothing
  pure virtual

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

  See also collectionsRetrieved(), collectionsRetrievedIncremental()

- retrieveItem (item, parts)

  returns bool
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  item | Akonadi.Item |
  parts | QSet<QByteArray> |

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

- retrieveItems (collection)

  returns Nothing
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  collection | Akonadi.Collection |

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

- setName (name)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  name | QString |

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

- setTotalItems (amount)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  amount | int |

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

- synchronize ( )

  returns Nothing

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

- synchronizeCollection (id)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  id | qint64 |

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

- synchronizeCollectionTree ( )

  returns Nothing

  Refetches the Collections.