Akonadi::ResourceBase

#include <resourcebase.h>

Inheritance diagram for Akonadi::ResourceBase:

[legend]

Signals
void	attributesSynchronized (qlonglong collectionId)

void	collectionTreeSynchronized ()

void	nameChanged (const QString &name)

void	retrieveNextItemSyncBatch (int remainingBatchSize)

void	synchronized ()

Signals inherited from Akonadi::AgentBase
void	abortRequested ()

void	advancedStatus (const QVariantMap &status)

void	agentActivitiesChanged (const QStringList &activities)

void	agentActivitiesEnabledChanged (bool enabled)

void	agentNameChanged (const QString &name)

void	configurationDialogAccepted ()

void	configurationDialogRejected ()

void	error (const QString &message)

void	onlineChanged (bool online)

void	percent (int progress)

void	reloadConfiguration ()

void	status (int status, const QString &message=QString())

void	warning (const QString &message)

Public Member Functions
QStringList	activities () const

bool	activitiesEnabled () const

QString	name () const

void	setActivities (const QStringList &activities)

void	setActivitiesEnabled (bool enable)

void	setAutomaticProgressReporting (bool enabled)

void	setName (const QString &name)

Public Member Functions inherited from Akonadi::AgentBase
QStringList	activities () const

bool	activitiesEnabled () const

QString	agentName () const

virtual void	cleanup ()

QString	identifier () const

virtual int	progress () const

virtual QString	progressMessage () const

void	registerObserver (Observer *observer)

void	setActivities (const QStringList &activities)

void	setActivitiesEnabled (bool enabled)

void	setAgentName (const QString &name)

virtual int	status () const

virtual QString	statusMessage () const

WId	winIdForDialogs () const

Public Member Functions inherited from QObject
	QObject (QObject *parent)

QBindable< QString >	bindableObjectName ()

bool	blockSignals (bool block)

const QObjectList &	children () const const

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const const

void	deleteLater ()

void	destroyed (QObject *obj)

bool	disconnect (const char signal, const QObject receiver, const char *method) const const

bool	disconnect (const QObject receiver, const char method) const const

void	dumpObjectInfo () const const

void	dumpObjectTree () const const

QList< QByteArray >	dynamicPropertyNames () const const

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

T	findChild (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (Qt::FindChildOptions options) const const

bool	inherits (const char *className) const const

void	installEventFilter (QObject *filterObj)

bool	isQuickItemType () const const

bool	isWidgetType () const const

bool	isWindowType () const const

void	killTimer (int id)

virtual const QMetaObject *	metaObject () const const

void	moveToThread (QThread *targetThread)

QString	objectName () const const

void	objectNameChanged (const QString &objectName)

QObject *	parent () const const

QVariant	property (const char *name) const const

	Q_CLASSINFO (Name, Value)

	Q_EMIT Q_EMIT

	Q_ENUM (...)

	Q_ENUM_NS (...)

	Q_ENUMS (...)

	Q_FLAG (...)

	Q_FLAG_NS (...)

	Q_FLAGS (...)

	Q_GADGET Q_GADGET

	Q_GADGET_EXPORT (EXPORT_MACRO)

	Q_INTERFACES (...)

	Q_INVOKABLE Q_INVOKABLE

	Q_MOC_INCLUDE Q_MOC_INCLUDE

	Q_NAMESPACE Q_NAMESPACE

	Q_NAMESPACE_EXPORT (EXPORT_MACRO)

	Q_OBJECT Q_OBJECT

	Q_PROPERTY (...)

	Q_REVISION Q_REVISION

	Q_SET_OBJECT_NAME (Object)

	Q_SIGNAL Q_SIGNAL

	Q_SIGNALS Q_SIGNALS

	Q_SLOT Q_SLOT

	Q_SLOTS Q_SLOTS

T	qobject_cast (const QObject *object)

T	qobject_cast (QObject *object)

	QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT

void	removeEventFilter (QObject *obj)

void	setObjectName (const QString &name)

void	setObjectName (QAnyStringView name)

void	setParent (QObject *parent)

bool	setProperty (const char *name, const QVariant &value)

bool	setProperty (const char *name, QVariant &&value)

bool	signalsBlocked () const const

int	startTimer (int interval, Qt::TimerType timerType)

int	startTimer (std::chrono::milliseconds interval, Qt::TimerType timerType)

QThread *	thread () const const

Static Public Member Functions
template<typename T >
static int	init (int argc, char **argv)

Static Public Member Functions inherited from Akonadi::AgentBase
template<typename T >
static int	init (int argc, char **argv)

Static Public Member Functions inherited from QObject
QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject context, Functor functor, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)

bool	disconnect (const QMetaObject::Connection &connection)

bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char method)

bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method)

bool	disconnect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method)

QString	tr (const char sourceText, const char disambiguation, int n)

Protected Types
enum	SchedulePriority { Prepend , AfterChangeReplay , Append }

Protected Slots
virtual void	abortActivity ()

virtual QString	dumpResourceToString () const

int	itemSyncBatchSize () const

virtual void	retrieveCollectionAttributes (const Akonadi::Collection &collection)

virtual void	retrieveCollections ()=0

virtual AKONADIAGENTBASE_DEPRECATED bool	retrieveItem (const Akonadi::Item &item, const QSet< QByteArray > &parts)

virtual void	retrieveItems (const Akonadi::Collection &collection)=0

virtual bool	retrieveItems (const Akonadi::Item::List &items, const QSet< QByteArray > &parts)

virtual void	retrieveTags ()

void	setItemSyncBatchSize (int batchSize)

void	setScheduleAttributeSyncBeforeItemSync (bool)

Protected Member Functions
	ResourceBase (const QString &id)

	~ResourceBase () override

void	cancelTask ()

void	cancelTask (const QString &error)

void	changeCommitted (const Collection &collection)

void	changeCommitted (const Item &item)

void	changeCommitted (const Tag &tag)

void	changesCommitted (const Item::List &items)

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

AKONADIAGENTBASE_DEPRECATED Item	currentItem () const

Item::List	currentItems () const

void	deferTask ()

void	doSetOnline (bool online) override

void	dumpMemoryInfo () const

QString	dumpMemoryInfoToString () const

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	setDisableAutomaticItemDeliveryDone (bool disable)

void	setHierarchicalRemoteIdentifiersEnabled (bool enable)

void	setItemMergingMode (ItemSync::MergeMode mode)

void	setItemStreamingEnabled (bool enable)

void	setItemTransactionMode (ItemSync::TransactionMode mode)

void	setKeepLocalCollectionChanges (const QSet< QByteArray > &parts)

void	setTotalItems (int amount)

void	synchronize ()

void	synchronizeCollection (qint64 id)

void	synchronizeCollection (qint64 id, bool recursive)

void	synchronizeCollectionAttributes (const Akonadi::Collection &col)

void	synchronizeCollectionAttributes (qint64 id)

void	synchronizeCollectionTree ()

void	synchronizeTags ()

void	tagsRetrieved (const Tag::List &tags, const QHash< QString, Item::List > &tagMembers)

void	taskDone ()

Protected Member Functions inherited from Akonadi::AgentBase
	AgentBase (const QString &id)

	~AgentBase () override

virtual KAboutData	aboutData () const

virtual void	aboutToQuit ()

void	changeProcessed ()

ChangeRecorder *	changeRecorder () const

KSharedConfigPtr	config ()

bool	isOnline () const

void	setNeedsNetwork (bool needsNetwork)

void	setOnline (bool state)

void	setTemporaryOffline (int makeOnlineInSeconds=300)

Protected Member Functions inherited from QObject
virtual void	childEvent (QChildEvent *event)

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	customEvent (QEvent *event)

virtual void	disconnectNotify (const QMetaMethod &signal)

bool	isSignalConnected (const QMetaMethod &signal) const const

int	receivers (const char *signal) const const

QObject *	sender () const const

int	senderSignalIndex () const const

virtual void	timerEvent (QTimerEvent *event)

Protected Member Functions inherited from QDBusContext
bool	calledFromDBus () const const

QDBusConnection	connection () const const

bool	isDelayedReply () const const

const QDBusMessage &	message () const const

void	sendErrorReply (const QString &name, const QString &msg) const const

void	sendErrorReply (QDBusError::ErrorType type, const QString &msg) const const

void	setDelayedReply (bool enable) const const

Additional Inherited Members
Public Types inherited from Akonadi::AgentBase
enum	Status { Idle = 0 , Running , Broken , NotConfigured }

Public Types inherited from QObject
typedef	QObjectList

Properties inherited from QObject
	objectName

Public Slots inherited from Akonadi::AgentBase
virtual void	configure (WId windowId)

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]

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

Icon

Resource

Akonadi
Helper integration between Akonadi and Qt.

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 itemAdded() and itemChanged(), call changeCommitted(). Once you have handled changes in itemRemoved(), call changeProcessed(); 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 collectionAdded() and collectionChanged(), call changeCommitted(). Once you have handled changes in collectionRemoved(), call changeProcessed(); 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 134 of file resourcebase.h.

Member Enumeration Documentation

◆ SchedulePriority

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 766 of file resourcebase.h.

Constructor & Destructor Documentation

◆ ResourceBase()

ResourceBase::ResourceBase ( const QString & id )

protected

Creates a base resource.

Parameters

id	The instance id of the resource.

Definition at line 442 of file resourcebase.cpp.

◆ ~ResourceBase()

ResourceBase::~ResourceBase ( )

overrideprotecteddefault

Destroys the base resource.

Member Function Documentation

◆ abortActivity

void Akonadi::ResourceBase::abortActivity ( )

protectedvirtualslot

Abort any activity in progress in the backend.

By default this method does nothing.

Since: 4.6

Definition at line 1478 of file resourcebase.cpp.

◆ activities()

QStringList ResourceBase::activities ( ) const

nodiscard

return list of activities.

Definition at line 514 of file resourcebase.cpp.

◆ activitiesEnabled()

bool ResourceBase::activitiesEnabled ( ) const

nodiscard

Returns true if activities is enabled.

Definition at line 524 of file resourcebase.cpp.

◆ attributesSynchronized

void Akonadi::ResourceBase::attributesSynchronized ( qlonglong collectionId )

signal

Emitted when a collection attributes synchronization has been completed.

Parameters

collectionId The identifier of the collection whose attributes got synchronized.

Since: 4.6

◆ cancelTask() [1/2]

void ResourceBase::cancelTask ( )

protected

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

Definition at line 1183 of file resourcebase.cpp.

◆ cancelTask() [2/2]

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.

Parameters

error additional error message to be emitted

Definition at line 1220 of file resourcebase.cpp.

◆ changeCommitted() [1/3]

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 708 of file resourcebase.cpp.

◆ changeCommitted() [2/3]

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 688 of file resourcebase.cpp.

◆ changeCommitted() [3/3]

void ResourceBase::changeCommitted ( const Tag & tag )

protected

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

Parameters

tag	Changed tag.

Since: 4.13

Definition at line 737 of file resourcebase.cpp.

◆ changesCommitted()

void ResourceBase::changesCommitted ( const Item::List & items )

protected

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

Parameters

items Changed items

Since: 4.11

Definition at line 693 of file resourcebase.cpp.

◆ clearCache()

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 1134 of file resourcebase.cpp.

◆ collectionAttributesRetrieved()

void ResourceBase::collectionAttributesRetrieved ( const Collection & collection )

protected

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

Parameters

collection The collection whose attributes got retrieved.

Since: 4.6

Definition at line 618 of file resourcebase.cpp.

◆ collectionsRetrievalDone()

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 815 of file resourcebase.cpp.

◆ collectionsRetrieved()

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 765 of file resourcebase.cpp.

◆ collectionsRetrievedIncremental()

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 782 of file resourcebase.cpp.

◆ collectionTreeSynchronized

void Akonadi::ResourceBase::collectionTreeSynchronized ( )

signal

Emitted when a collection tree synchronization has been completed.

Since: 4.8

◆ currentCollection()

Collection ResourceBase::currentCollection ( ) const

nodiscardprotected

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 1146 of file resourcebase.cpp.

◆ currentItem()

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 1155 of file resourcebase.cpp.

◆ currentItems()

Item::List ResourceBase::currentItems ( ) const

nodiscardprotected

Returns the items that are currently retrieved.

Note: Calling this method is only allowed during item fetch, that is directly or indirectly from retrieveItems(Akonadi::Item::List,QSet<QByteArray>)

Definition at line 1164 of file resourcebase.cpp.

◆ deferTask()

void ResourceBase::deferTask ( )

protected

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.

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 1227 of file resourcebase.cpp.

◆ doSetOnline()

void ResourceBase::doSetOnline ( bool online )

overrideprotectedvirtual

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.

Reimplemented from Akonadi::AgentBase.

Definition at line 1237 of file resourcebase.cpp.

◆ dumpMemoryInfo()

void ResourceBase::dumpMemoryInfo ( ) const

protected

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.

Since: 4.11

Definition at line 1512 of file resourcebase.cpp.

◆ dumpMemoryInfoToString()

QString ResourceBase::dumpMemoryInfoToString ( ) const

nodiscardprotected

Returns a string with memory usage information.

See also: dumpMemoryInfo()

Since: 4.11

Definition at line 1518 of file resourcebase.cpp.

◆ dumpNotificationListToString()

QString ResourceBase::dumpNotificationListToString ( ) const

nodiscardprotected

Dump the contents of the current ChangeReplay.

Since: 4.8.1

Definition at line 1500 of file resourcebase.cpp.

◆ dumpResourceToString

virtual QString Akonadi::ResourceBase::dumpResourceToString ( ) const

inlineprotectedvirtualslot

Dump resource internals, for debugging.

Since: 4.9

Definition at line 390 of file resourcebase.h.

◆ dumpSchedulerToString()

QString ResourceBase::dumpSchedulerToString ( ) const

nodiscardprotected

Dump the state of the scheduler.

Since: 4.8.1

Definition at line 1506 of file resourcebase.cpp.

◆ init()

template<typename T >

static int Akonadi::ResourceBase::init	(	int	argc,
		char **	argv )

inlinestatic

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 );
}

Parameters

argc	number of arguments
argv	string arguments

Definition at line 167 of file resourcebase.h.

◆ invalidateCache()

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.

Parameters

collection parent of the content to be invalidated in cache

Since: 4.8

Definition at line 1140 of file resourcebase.cpp.

◆ itemRetrieved()

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 585 of file resourcebase.cpp.

◆ itemsRetrievalDone()

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 1119 of file resourcebase.cpp.

◆ itemsRetrieved()

void ResourceBase::itemsRetrieved ( const Item::List & items )

protected

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.

Parameters

items A list of items.

See also: itemsRetrievedIncremental().

Definition at line 1330 of file resourcebase.cpp.

◆ itemsRetrievedIncremental()

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 1357 of file resourcebase.cpp.

◆ itemSyncBatchSize

int ResourceBase::itemSyncBatchSize ( ) const

nodiscardprotectedslot

Returns the batch size used during the item sync.

This can be used to throttle the item delivery.

See also: retrieveNextItemSyncBatch(int), retrieveItems(Akonadi::Collection)

Since: 4.14

Definition at line 963 of file resourcebase.cpp.

◆ name()

QString ResourceBase::name ( ) const

nodiscard

Returns the name of the resource.

Definition at line 504 of file resourcebase.cpp.

◆ nameChanged

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.

◆ retrieveCollectionAttributes

void ResourceBase::retrieveCollectionAttributes ( const Akonadi::Collection & collection )

protectedvirtualslot

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

collection The collection whose attributes should be retrieved.

See also: collectionAttributesRetrieved()

Since: 4.6

Definition at line 1433 of file resourcebase.cpp.

◆ retrieveCollections

virtual void Akonadi::ResourceBase::retrieveCollections ( )

protectedpure virtualslot

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

See also: collectionsRetrieved(), collectionsRetrievedIncremental()

◆ retrieveItem

bool ResourceBase::retrieveItem	(	const Akonadi::Item &	item,
		const QSet< QByteArray > &	parts )

protectedvirtualslot

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

Deprecated: Use retrieveItems(const Akonadi::Item::List &, const QSet<QByteArray> &) instead.

Definition at line 1444 of file resourcebase.cpp.

◆ retrieveItems [1/2]

virtual void Akonadi::ResourceBase::retrieveItems ( const Akonadi::Collection & collection )

protectedpure virtualslot

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

collection The collection whose items to retrieve.

See also: itemsRetrieved( const Item::List& ), itemsRetrievedIncremental(), itemsRetrieved(), currentCollection(), batchSize()

◆ retrieveItems [2/2]

bool ResourceBase::retrieveItems	(	const Akonadi::Item::List &	items,
		const QSet< QByteArray > &	parts )

protectedvirtualslot

Retrieve given items from the backend.

Add the requested payload parts and call itemsRetrieved() when done. It is guaranteed that all 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.

Parameters

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

Since: 5.4

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

Definition at line 1462 of file resourcebase.cpp.

◆ retrieveNextItemSyncBatch

void Akonadi::ResourceBase::retrieveNextItemSyncBatch ( int remainingBatchSize )

signal

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

Parameters

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.

See also: batchSize()

Since: 4.14

◆ retrieveTags

void ResourceBase::retrieveTags ( )

protectedvirtualslot

Retrieve all tags from the backend.

See also: tagsRetrieved()

Definition at line 1438 of file resourcebase.cpp.

◆ scheduleCustomTask()

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

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.

Since: 4.4

Definition at line 1421 of file resourcebase.cpp.

◆ setActivities()

void ResourceBase::setActivities ( const QStringList & activities )

This method sets list of activities.

Definition at line 509 of file resourcebase.cpp.

◆ setActivitiesEnabled()

void ResourceBase::setActivitiesEnabled ( bool enable )

This method enables or not activities support.

Definition at line 519 of file resourcebase.cpp.

◆ setAutomaticProgressReporting()

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

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

Since: 4.7

Definition at line 1494 of file resourcebase.cpp.

◆ setCollectionStreamingEnabled()

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

enable true if collection streaming should be enabled, false by default

Definition at line 799 of file resourcebase.cpp.

◆ setDisableAutomaticItemDeliveryDone()

void ResourceBase::setDisableAutomaticItemDeliveryDone ( bool disable )

protected

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

Note: This needs to be called once, before the item sync is started.

See also: setTotalItems(int)

Since: 4.14

Definition at line 1312 of file resourcebase.cpp.

◆ setHierarchicalRemoteIdentifiersEnabled()

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.

Parameters

enable whether to enable use of hierarchical remote identifiers

Since: 4.4

Definition at line 1415 of file resourcebase.cpp.

◆ setItemMergingMode()

void ResourceBase::setItemMergingMode ( ItemSync::MergeMode mode )

protected

Set merge mode for item sync'ing.

Default merge mode is RIDMerge.

Note: This method must be called before first call to itemRetrieved(), itemsRetrieved() or itemsRetrievedIncremental().

Parameters

mode	Item merging mode (see ItemCreateJob for details on item merging)

See also: Akonadi::ItemSync::MergeMode

Since: 4.14.11

Definition at line 1488 of file resourcebase.cpp.

◆ setItemStreamingEnabled()

void ResourceBase::setItemStreamingEnabled ( bool enable )

protected

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

Parameters

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

See also: setTotalItems(int)

Definition at line 1321 of file resourcebase.cpp.

◆ setItemSyncBatchSize

void ResourceBase::setItemSyncBatchSize ( int batchSize )

protectedslot

Set the batch size used during the item sync.

The default is 10.

See also: retrieveNextItemSyncBatch(int)

Since: 4.14

Definition at line 969 of file resourcebase.cpp.

◆ setItemTransactionMode()

void ResourceBase::setItemTransactionMode ( ItemSync::TransactionMode mode )

protected

Set transaction mode for item sync'ing.

Parameters

mode	item transaction mode

See also: Akonadi::ItemSync::TransactionMode

Since: 4.6

Definition at line 1482 of file resourcebase.cpp.

◆ setKeepLocalCollectionChanges()

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

protected

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.

Parameters

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

Since: 4.14

Definition at line 831 of file resourcebase.cpp.

◆ setName()

void ResourceBase::setName ( const QString & name )

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

Definition at line 499 of file resourcebase.cpp.

◆ setScheduleAttributeSyncBeforeItemSync

void ResourceBase::setScheduleAttributeSyncBeforeItemSync ( bool enable )

protectedslot

Set to true to schedule an attribute sync before every item sync.

The default is false.

Since: 4.15

Definition at line 975 of file resourcebase.cpp.

◆ setTotalItems()

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.

Warning: By default this will end the item sync automatically once sufficient items were delivered. To disable this and only make use of the progress reporting, use setDisableAutomaticItemDeliveryDone()

Note: The recommended way is therefore:
setDisableAutomaticItemDeliveryDone(true);

setItemStreamingEnabled(true);

setTotalItems(X); // X = sum of all items in all batches

while (...) {

itemsRetrievedIncremental(...);

// or itemsRetrieved(...);

}

itemsRetrievalDone();

Akonadi::ResourceBase::setDisableAutomaticItemDeliveryDone
void setDisableAutomaticItemDeliveryDone(bool disable)
Disables the automatic completion of the item sync, based on the number of delivered items.
Definition resourcebase.cpp:1312

Akonadi::ResourceBase::itemsRetrievalDone
void itemsRetrievalDone()
Call this method to indicate you finished synchronizing the current collection.
Definition resourcebase.cpp:1119

Akonadi::ResourceBase::setTotalItems
void setTotalItems(int amount)
Call this method when you want to use the itemsRetrieved() method in streaming mode and indicate the ...
Definition resourcebase.cpp:1302

Akonadi::ResourceBase::setItemStreamingEnabled
void setItemStreamingEnabled(bool enable)
Enable item streaming, which is disabled by default.
Definition resourcebase.cpp:1321

Akonadi::ResourceBase::itemsRetrievedIncremental
void itemsRetrievedIncremental(const Item::List &changedItems, const Item::List &removedItems)
Call this method to supply incrementally retrieved items from the remote server.
Definition resourcebase.cpp:1357

Parameters

amount number of items that will arrive in streaming mode

See also: setDisableAutomaticItemDeliveryDone(bool); setItemStreamingEnabled(bool)

Definition at line 1302 of file resourcebase.cpp.

◆ synchronize()

void ResourceBase::synchronize ( )

protected

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

Definition at line 494 of file resourcebase.cpp.

◆ synchronizeCollection() [1/2]

void ResourceBase::synchronizeCollection ( qint64 id )

protected

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

Definition at line 1242 of file resourcebase.cpp.

◆ synchronizeCollection() [2/2]

void ResourceBase::synchronizeCollection	(	qint64	id,
		bool	recursive )

protected

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

Parameters

recursive if true, a recursive synchronization is done

Definition at line 1247 of file resourcebase.cpp.

◆ synchronizeCollectionAttributes() [1/2]

void ResourceBase::synchronizeCollectionAttributes ( const Akonadi::Collection & col )

protected

Synchronizes the collection attributes.

Parameters

col	The id of the collection to synchronize

Since: 4.15

Definition at line 1275 of file resourcebase.cpp.

◆ synchronizeCollectionAttributes() [2/2]

void ResourceBase::synchronizeCollectionAttributes ( qint64 id )

protected

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

Parameters

id	The id of the collection to synchronize

Since: 4.6

Definition at line 1281 of file resourcebase.cpp.

◆ synchronizeCollectionTree()

void ResourceBase::synchronizeCollectionTree ( )

protected

Refetches the Collections.

Definition at line 1173 of file resourcebase.cpp.

◆ synchronized

void Akonadi::ResourceBase::synchronized ( )

signal

Emitted when a full synchronization has been completed.

◆ synchronizeTags()

void ResourceBase::synchronizeTags ( )

protected

Refetches Tags.

Definition at line 1178 of file resourcebase.cpp.

◆ tagsRetrieved()

void ResourceBase::tagsRetrieved	(	const Tag::List &	tags,
		const QHash< QString, Item::List > &	tagMembers )

protected

Definition at line 1524 of file resourcebase.cpp.

◆ taskDone()

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 1427 of file resourcebase.cpp.

The documentation for this class was generated from the following files:

KDE's Doxygen guidelines are available online.

Class Picker

Quick Links

About Akonadi

Akonadi::ResourceBase

Signals

Public Member Functions

Static Public Member Functions

Protected Types

Protected Slots

Protected Member Functions

Additional Inherited Members

Detailed Description

How to write a resource

Basic Resource Framework

Handling PIM Items

Handling Collections

Member Enumeration Documentation

◆ SchedulePriority

Constructor & Destructor Documentation

◆ ResourceBase()

◆ ~ResourceBase()

Member Function Documentation

◆ abortActivity

◆ activities()

◆ activitiesEnabled()

◆ attributesSynchronized

◆ cancelTask() [1/2]

◆ cancelTask() [2/2]

◆ changeCommitted() [1/3]

◆ changeCommitted() [2/3]

◆ changeCommitted() [3/3]

◆ changesCommitted()

◆ clearCache()

◆ collectionAttributesRetrieved()

◆ collectionsRetrievalDone()

◆ collectionsRetrieved()

◆ collectionsRetrievedIncremental()

◆ collectionTreeSynchronized

◆ currentCollection()

◆ currentItem()

◆ currentItems()

◆ deferTask()

◆ doSetOnline()

◆ dumpMemoryInfo()

◆ dumpMemoryInfoToString()

◆ dumpNotificationListToString()

◆ dumpResourceToString

◆ dumpSchedulerToString()

◆ init()

◆ invalidateCache()

◆ itemRetrieved()

◆ itemsRetrievalDone()

◆ itemsRetrieved()

◆ itemsRetrievedIncremental()

◆ itemSyncBatchSize

◆ name()

◆ nameChanged

◆ retrieveCollectionAttributes

◆ retrieveCollections

◆ retrieveItem

◆ retrieveItems [1/2]

◆ retrieveItems [2/2]

◆ retrieveNextItemSyncBatch

◆ retrieveTags

◆ scheduleCustomTask()

◆ setActivities()

◆ setActivitiesEnabled()

◆ setAutomaticProgressReporting()

◆ setCollectionStreamingEnabled()

◆ setDisableAutomaticItemDeliveryDone()

◆ setHierarchicalRemoteIdentifiersEnabled()

◆ setItemMergingMode()

◆ setItemStreamingEnabled()

◆ setItemSyncBatchSize

◆ setItemTransactionMode()

◆ setKeepLocalCollectionChanges()

◆ setName()

◆ setScheduleAttributeSyncBeforeItemSync

◆ setTotalItems()

◆ synchronize()