Akonadi::ResourceBase Class

Member Function Documentation

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

Creates a base resource.

id The instance id of the resource.

[override virtual noexcept protected] ResourceBase::~ResourceBase()

Destroys the base resource.

[virtual protected slot] void ResourceBase::abortActivity()

Abort any activity in progress in the backend. By default this method does nothing.

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

Emitted when a collection attributes synchronization has been completed.

collectionId The identifier of the collection whose attributes got synchronized.

[protected] void ResourceBase::cancelTask()

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

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

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

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

Call whenever you have successfully handled or ignored a collection change notification.

This will update the remote identifier of \p collection if necessary, as well as any other collection attributes. This implicitly calls changeProcessed(). collection The collection which changes have been handled.

[protected] void ResourceBase::changeCommitted(const Akonadi::Item &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.

[protected] void ResourceBase::changeCommitted(const Akonadi::Tag &tag)

Resets the dirty flag of the given tag and updates the remote id.

Call whenever you have successfully written changes back to the server. This implicitly calls changeProcessed(). tag Changed tag.

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

Resets the dirty flag of all given items and updates remote ids.

Call whenever you have successfully written changes back to the server. This implicitly calls changeProcessed(). items Changed items

[protected] void ResourceBase::clearCache()

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

The method should not be used anymore

\seeinvalidateCache()

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

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

collection The collection whose attributes got retrieved.

[signal] void ResourceBase::collectionTreeSynchronized()

Emitted when a collection tree synchronization has been completed.

[protected] void ResourceBase::collectionsRetrievalDone()

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

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

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

collections A list of collections. \see collectionsRetrievedIncremental()

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

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

[protected] Akonadi::Collection ResourceBase::currentCollection() const

Returns the collection that is currently synchronized.

[protected] Akonadi::Item ResourceBase::currentItem() const

Returns the item that is currently retrieved.

[protected] Akonadi::Item::List ResourceBase::currentItems() const

Returns the items that are currently retrieved.

[protected] void ResourceBase::deferTask()

Suspends the execution of the current task and tries again to execute it.

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

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

Reimplements: AgentBase::doSetOnline(bool online).

Inherited from AgentBase.

When going offline, the scheduler aborts the current task, so you should do the same in your resource, if the task implementation is asynchronous.

[protected] void ResourceBase::dumpMemoryInfo() const

Dumps memory usage information to stdout. For now it outputs the result of glibc's mallinfo(). This is useful to check if your memory problems are due to poor management by glibc. Look for a high value on fsmblks when interpreting results. man mallinfo for more details.

[protected] QString ResourceBase::dumpMemoryInfoToString() const

Returns a string with memory usage information. \see dumpMemoryInfo()

[protected] QString ResourceBase::dumpNotificationListToString() const

Dump the contents of the current ChangeReplay

[virtual protected] QString ResourceBase::dumpResourceToString() const

Dump resource internals, for debugging.

[protected] QString ResourceBase::dumpSchedulerToString() const

Dump the state of the scheduler

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

Call this method to invalidate all cached content in \p collection.

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

collection parent of the content to be invalidated in cache

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

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

item The retrieved item.

[protected] int ResourceBase::itemSyncBatchSize() const

Returns the batch size used during the item sync.

This can be used to throttle the item delivery.

\seeretrieveNextItemSyncBatch(int), retrieveItems(Akonadi::Collection)

See also setItemSyncBatchSize().

[protected] void ResourceBase::itemsRetrievalDone()

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

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

Call this method to supply the full collection listing from the remote server. Items not present in the list will be dropped from the Akonadi database.

If the remote server supports incremental listing, it's strongly recommended to use itemsRetrievedIncremental() instead. items A list of items. \see itemsRetrievedIncremental().

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

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

changedItems Items changed in the backend. removedItems Items removed from the backend.

QString ResourceBase::name() const

Returns the name of the resource.

See also setName().

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

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

name The new name of the resource.

[virtual protected slot] void ResourceBase::retrieveCollectionAttributes(const Akonadi::Collection &collection)

Retrieve the attributes of a single collection from the backend. The collection to retrieve attributes for is provided as \p collection. Add the attributes parts and call collectionAttributesRetrieved() when done.

collection The collection whose attributes should be retrieved. \see collectionAttributesRetrieved()

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

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

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

Retrieve a single item from the backend. The item to retrieve is provided as \p item. Add the requested payload parts and call itemRetrieved() when done. item The 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. parts The item parts that should be retrieved. Returns false if there is an immediate error when retrieving the item. \see itemRetrieved() @deprecated Use retrieveItems(const Akonadi::Item::List &, const QSet<QByteArray> &) instead.

[pure virtual protected slot] void ResourceBase::retrieveItems(const Akonadi::Collection &collection)

Retrieve all (new/changed) items in collection \p 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. collection The collection whose items to retrieve. \see itemsRetrieved( const Item::List& ), itemsRetrievedIncremental(), itemsRetrieved(), currentCollection(), batchSize()

 // Connect using qOverload:
 connect(sender, &SenderClass::signal,
         resourceBase, qOverload(&ResourceBase::retrieveItems));

 // Or using a lambda as wrapper:
 connect(sender, &SenderClass::signal,
         resourceBase, [receiver = resourceBase](const Akonadi::Collection &collection) { receiver->retrieveItems(collection); });

[virtual protected slot] bool ResourceBase::retrieveItems(const Akonadi::Item::List &items, const QSet<QByteArray> &parts)

Retrieve given \p items from the backend. Add the requested payload parts and call itemsRetrieved() when done. It is guaranteed that all \p items in the list belong to the same Collection.

If the items are retrieved synchronously in this method, in case of an error emit error(const QString &) and return false, which will cancel the current task. If the items are retrieved asynchronously, in case of an non-immediate error you need to call cancelTask() or cancelTask(const QString&) in the respective handler methods explicitly.

items The items whose payload should be retrieved. Use those objects when delivering the result instead of creating new items to ensure conflict detection will work. parts The item parts that should be retrieved. Returns false if there is an immediate error when retrieving the items. \see itemsRetrieved()

\todo: Make this method pure virtual once retrieveItem() is gone

 // Connect using qOverload:
 connect(sender, &SenderClass::signal,
         resourceBase, qOverload &>(&ResourceBase::retrieveItems));

 // Or using a lambda as wrapper:
 connect(sender, &SenderClass::signal,
         resourceBase, [receiver = resourceBase](const Akonadi::Item::List &items, const QSet &parts) { receiver->retrieveItems(items, parts); });

[signal] void ResourceBase::retrieveNextItemSyncBatch(int remainingBatchSize)

Emitted when the item synchronization processed the current batch and is ready for a new one. Use this to throttle the delivery to not overload Akonadi.

Throttling can be used during item retrieval (retrieveItems(Akonadi::Collection)) in streaming mode. To throttle only deliver itemSyncBatchSize() items, and wait for this signal, then again deliver remainingBatchSize items.

By always only providing the number of items required to process the batch, the items don't pile up in memory and items are only provided as fast as Akonadi can process them.

\seebatchSize()

[virtual protected slot] void ResourceBase::retrieveTags()

Retrieve all tags from the backend \see tagsRetrieved()

[protected] void ResourceBase::scheduleCustomTask(QObject *receiver, const char *method, const QVariant &argument, Akonadi::ResourceBase::SchedulePriority priority = Append)

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 SchedulePriority receiver The object the slot should be called on. method The 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. argument A QVariant argument passed to the method specified above. Use this to pass task parameters. priority Priority of the task. Use this to influence the position in the execution queue.

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.

enabled Whether or not automatic emission of the signals is enabled.

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

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(). enable true if collection streaming should be enabled, false by default

[protected] void ResourceBase::setDisableAutomaticItemDeliveryDone(bool disable)

Disables the automatic completion of the item sync, based on the number of delivered items.

This ensures that the item sync only finishes once itemsRetrieved() is called, while still making it possible to use the automatic progress reporting based on setTotalItems().

\seesetTotalItems(int)

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

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.

enable whether to enable use of hierarchical remote identifiers

[protected] void ResourceBase::setItemMergingMode(Akonadi::ItemSync::MergeMode mode)

Set merge mode for item sync'ing.

Default merge mode is RIDMerge.

mode Item merging mode (see ItemCreateJob for details on item merging) \see Akonadi::ItemSync::MergeMode

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

Enable item streaming, which is disabled by default. Item streaming means that the resource can call setTotalItems(), and then itemsRetrieved() or itemsRetrievedIncremental() multiple times, in chunks. When all is done, the resource should call itemsRetrievalDone(). enable true if items are delivered in chunks rather in one big block. \see setTotalItems(int)

[protected slot] void ResourceBase::setItemSyncBatchSize(int batchSize)

Set the batch size used during the item sync. The default is 10.

\seeretrieveNextItemSyncBatch(int)

See also itemSyncBatchSize().

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

Set transaction mode for item sync'ing. mode item transaction mode \see Akonadi::ItemSync::TransactionMode

[protected] void ResourceBase::setKeepLocalCollectionChanges(const QSet<QByteArray> &parts)

Allows to keep locally changed collection parts during the collection sync.

This is useful for resources to be able to provide default values during the collection sync, while preserving eventual more up-to date values.

Valid values are attribute types and "CONTENTMIMETYPE" for the collections content mimetypes.

By default this is enabled for the EntityDisplayAttribute.

parts A set parts for which local changes should be preserved.

void ResourceBase::setName(const QString &name)

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

See also name().

[protected slot] void ResourceBase::setScheduleAttributeSyncBeforeItemSync(bool)

Set to true to schedule an attribute sync before every item sync. The default is false.

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

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.

 setDisableAutomaticItemDeliveryDone(true);
 setItemStreamingEnabled(true);
 setTotalItems(X); // X = sum of all items in all batches
 while (...) {
    itemsRetrievedIncremental(...);
    // or itemsRetrieved(...);
  }
 itemsRetrievalDone();

amount number of items that will arrive in streaming mode \see setDisableAutomaticItemDeliveryDone(bool) \see setItemStreamingEnabled(bool)

[protected] void ResourceBase::synchronize()

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

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

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

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

This method is called whenever the collection with the given \p id shall be synchronized. recursive if true, a recursive synchronization is done

[protected] void ResourceBase::synchronizeCollectionAttributes(const Akonadi::Collection &col)

Synchronizes the collection attributes.

col The id of the collection to synchronize

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

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

id The id of the collection to synchronize

[protected] void ResourceBase::synchronizeCollectionTree()

Refetches the Collections.

[protected] void ResourceBase::synchronizeTags()

Refetches Tags.

[signal] void ResourceBase::synchronized()

Emitted when a full synchronization has been completed.

[protected] void ResourceBase::taskDone()

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.