Akonadi::ResourceBase

#include <resourcebase.h>

Inheritance diagram for Akonadi::ResourceBase:

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

QString name () const
 
void setAutomaticProgressReporting (bool enabled)
 
void setName (const QString &name)
 
- Public Member Functions inherited from Akonadi::AgentBase
QString agentName () const
 
virtual void cleanup ()
 
QString identifier () const
 
virtual int progress () const
 
virtual QString progressMessage () const
 
void registerObserver (Observer *observer)
 
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)
 
bool blockSignals (bool block)
 
const QObjectListchildren () 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 ()
 
void dumpObjectInfo () const const
 
void dumpObjectTree ()
 
void dumpObjectTree () const const
 
QList< QByteArraydynamicPropertyNames () const const
 
virtual bool event (QEvent *e)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
findChild (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const
 
bool inherits (const char *className) const const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const const
 
bool isWindowType () const const
 
void killTimer (int id)
 
virtual const QMetaObjectmetaObject () const const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const const
 
void objectNameChanged (const QString &objectName)
 
QObjectparent () const const
 
QVariant property (const char *name) const const
 
 Q_CLASSINFO (Name, Value)
 
 Q_DISABLE_COPY (Class)
 
 Q_DISABLE_COPY_MOVE (Class)
 
 Q_DISABLE_MOVE (Class)
 
 Q_EMIT Q_EMIT
 
 Q_ENUM (...)
 
 Q_ENUM_NS (...)
 
 Q_ENUMS (...)
 
 Q_FLAG (...)
 
 Q_FLAG_NS (...)
 
 Q_FLAGS (...)
 
 Q_GADGET Q_GADGET
 
 Q_INTERFACES (...)
 
 Q_INVOKABLE Q_INVOKABLE
 
 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
 
qFindChild (const QObject *obj, const QString &name)
 
QList< T > qFindChildren (const QObject *obj, const QRegExp &regExp)
 
QList< T > qFindChildren (const QObject *obj, const QString &name)
 
qobject_cast (QObject *object)
 
qobject_cast (const QObject *object)
 
 QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const char *name, const QVariant &value)
 
bool signalsBlocked () const const
 
int startTimer (int interval, Qt::TimerType timerType)
 
int startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)
 
QThreadthread () 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 *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
 
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, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
 
bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
 
QString tr (const char *sourceText, const char *disambiguation, int n)
 
QString trUtf8 (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 retrieveRelations ()
 
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 Item &item)
 
void changeCommitted (const Tag &tag)
 
void changeCommitted (const Collection &collection)
 
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 relationsRetrieved (const Relation::List &relations)
 
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 setItemSynchronizationFetchScope (const ItemFetchScope &fetchScope)
 
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 (qint64 id)
 
void synchronizeCollectionAttributes (const Akonadi::Collection &col)
 
void synchronizeCollectionTree ()
 
void synchronizeRelations ()
 
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 ()
 
virtual KAboutData aboutData () const
 
virtual void aboutToQuit ()
 
void changeProcessed ()
 
ChangeRecorderchangeRecorder () 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
 
QObjectsender () 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 QDBusMessagemessage () const const
 
void sendErrorReply (QDBusError::ErrorType type, const QString &msg) const const
 
void sendErrorReply (const QString &name, 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 }
 
- Properties inherited from QObject
 objectName
 
- Public Slots inherited from Akonadi::AgentBase
virtual void configure (WId windowId)
 
- Public Attributes inherited from QObject
typedef QObjectList
 

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

Member Enumeration Documentation

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

ResourceBase::~ResourceBase ( )
overrideprotecteddefault

Destroys the base resource.

Member Function Documentation

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

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
erroradditional error message to be emitted

Definition at line 1219 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
itemThe changed item.

Definition at line 674 of file resourcebase.cpp.

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
tagChanged tag.
Since
4.13

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

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
itemsChanged items
Since
4.11

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

void ResourceBase::collectionAttributesRetrieved ( const Collection collection)
protected

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

Parameters
collectionThe collection whose attributes got retrieved.
Since
4.6

Definition at line 605 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 797 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 746 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 763 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 1140 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 1149 of file resourcebase.cpp.

Item::List ResourceBase::currentItems ( ) const
protected

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

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

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

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

QString ResourceBase::dumpMemoryInfoToString ( ) const
protected

Returns a string with memory usage information.

See also
dumpMemoryInfo()
Since
4.11

Definition at line 1531 of file resourcebase.cpp.

QString ResourceBase::dumpNotificationListToString ( ) const
protected

Dump the contents of the current ChangeReplay.

Since
4.8.1

Definition at line 1513 of file resourcebase.cpp.

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

Dump resource internals, for debugging.

Since
4.9

Definition at line 372 of file resourcebase.h.

QString ResourceBase::dumpSchedulerToString ( ) const
protected

Dump the state of the scheduler.

Since
4.8.1

Definition at line 1519 of file resourcebase.cpp.

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
argcnumber of arguments
argvstring arguments

Definition at line 168 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.

Parameters
collectionparent of the content to be invalidated in cache
Since
4.8

Definition at line 1134 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 572 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 1113 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.

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
itemsA list of items.
See also
itemsRetrievedIncremental().

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

int ResourceBase::itemSyncBatchSize ( ) const
protectedslot

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

QString ResourceBase::name ( ) const

Returns the name of the resource.

Definition at line 512 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)
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
collectionThe collection whose attributes should be retrieved.
See also
collectionAttributesRetrieved()
Since
4.6

Definition at line 1433 of file resourcebase.cpp.

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()
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
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()
Deprecated:
Use retrieveItems(const Akonadi::Item::List &, const QSet<QByteArray> &) instead.

Definition at line 1450 of file resourcebase.cpp.

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
collectionThe collection whose items to retrieve.
See also
itemsRetrieved( const Item::List& ), itemsRetrievedIncremental(), itemsRetrieved(), currentCollection(), batchSize()
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.

Parameters
itemsThe items whose payload should be retrieved. Use those objects when delivering the result instead of creating new items to ensure conflict detection will work.
partsThe 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 1466 of file resourcebase.cpp.

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

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
void ResourceBase::retrieveRelations ( )
protectedvirtualslot

Retrieve all relations from the backend.

See also
relationsRetrieved()

Definition at line 1444 of file resourcebase.cpp.

void ResourceBase::retrieveTags ( )
protectedvirtualslot

Retrieve all tags from the backend.

See also
tagsRetrieved()

Definition at line 1438 of file resourcebase.cpp.

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 1421 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 1507 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 781 of file resourcebase.cpp.

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

Parameters
enablewhether to enable use of hierarchical remote identifiers
Since
4.4

Definition at line 1415 of file resourcebase.cpp.

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
modeItem merging mode (see ItemCreateJob for details on item merging)
See also
Akonadi::ItemSync::MergeMode
Since
4.14.11

Definition at line 1501 of file resourcebase.cpp.

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
enabletrue if items are delivered in chunks rather in one big block.
See also
setTotalItems(int)

Definition at line 1320 of file resourcebase.cpp.

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

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

Set transaction mode for item sync'ing.

Parameters
modeitem transaction mode
See also
Akonadi::ItemSync::TransactionMode
Since
4.6

Definition at line 1486 of file resourcebase.cpp.

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
partsA set parts for which local changes should be preserved.
Since
4.14

Definition at line 814 of file resourcebase.cpp.

void ResourceBase::setName ( const QString name)

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

Definition at line 507 of file resourcebase.cpp.

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

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:
setTotalItems(X); // X = sum of all items in all batches
while (...) {
// or itemsRetrieved(...);
}
Parameters
amountnumber of items that will arrive in streaming mode
See also
setDisableAutomaticItemDeliveryDone(bool)
setItemStreamingEnabled(bool)

Definition at line 1301 of file resourcebase.cpp.

void ResourceBase::synchronize ( )
protected

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

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

void 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

Definition at line 1246 of file resourcebase.cpp.

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

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

Synchronizes the collection attributes.

Parameters
colThe id of the collection to synchronize
Since
4.15

Definition at line 1274 of file resourcebase.cpp.

void ResourceBase::synchronizeCollectionTree ( )
protected

Refetches the Collections.

Definition at line 1167 of file resourcebase.cpp.

void Akonadi::ResourceBase::synchronized ( )
signal

Emitted when a full synchronization has been completed.

void ResourceBase::synchronizeRelations ( )
protected

Refetches Relations.

Definition at line 1177 of file resourcebase.cpp.

void ResourceBase::synchronizeTags ( )
protected

Refetches Tags.

Definition at line 1172 of file resourcebase.cpp.

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:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Sat Jul 4 2020 23:16:54 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.