Akonadi::ItemModifyJob

Akonadi::ItemModifyJob Class Reference

#include <itemmodifyjob.h>

Inheritance diagram for Akonadi::ItemModifyJob:

Public Member Functions

 ItemModifyJob (const Item &item, QObject *parent=nullptr)
 
 ItemModifyJob (const Item::List &items, QObject *parent=nullptr)
 
 ~ItemModifyJob () override
 
void disableAutomaticConflictHandling ()
 
void disableRevisionCheck ()
 
bool ignorePayload () const
 
Item item () const
 
Item::List items () const
 
void setIgnorePayload (bool ignore)
 
void setUpdateGid (bool update)
 
bool updateGid () const
 
- Public Member Functions inherited from Akonadi::Job
 Job (QObject *parent=nullptr)
 
 ~Job () override
 
QString errorString () const final
 
void start () override
 
- Public Member Functions inherited from KCompositeJob
 KCompositeJob (QObject *parent=nullptr)
 
- Public Member Functions inherited from KJob
 KJob (QObject *parent=nullptr)
 
Capabilities capabilities () const
 
int error () const
 
QString errorText () const
 
bool exec ()
 
bool isAutoDelete () const
 
bool isSuspended () const
 
unsigned long percent () const
 
Q_SCRIPTABLE qulonglong processedAmount (Unit unit) const
 
void setAutoDelete (bool autodelete)
 
void setUiDelegate (KJobUiDelegate *delegate)
 
Q_SCRIPTABLE qulonglong totalAmount (Unit unit) const
 
KJobUiDelegateuiDelegate () 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
 

Protected Member Functions

bool doHandleResponse (qint64 tag, const Protocol::CommandPtr &response) override
 
void doStart () override
 
- Protected Member Functions inherited from Akonadi::Job
bool addSubjob (KJob *job) override
 
bool doKill () override
 
void emitWriteFinished ()
 
bool removeSubjob (KJob *job) override
 
- Protected Member Functions inherited from KCompositeJob
void clearSubjobs ()
 
bool hasSubjobs () const
 
const QList< KJob * > & subjobs () const
 
- Protected Member Functions inherited from KJob
virtual bool doResume ()
 
virtual bool doSuspend ()
 
void emitPercent (qulonglong processedAmount, qulonglong totalAmount)
 
void emitResult ()
 
void emitSpeed (unsigned long speed)
 
void setCapabilities (Capabilities capabilities)
 
void setError (int errorCode)
 
void setErrorText (const QString &errorText)
 
void setPercent (unsigned long percentage)
 
void setProcessedAmount (Unit unit, qulonglong amount)
 
void setTotalAmount (Unit unit, qulonglong amount)
 
- 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)
 

Additional Inherited Members

- Public Types inherited from Akonadi::Job
enum  Error {
  ConnectionFailed = UserDefinedError, ProtocolVersionMismatch, UserCanceled, Unknown,
  UserError = UserDefinedError + 42
}
 
typedef QList< Job * > List
 
- Public Types inherited from KJob
typedef QFlags< CapabilityCapabilities
 
enum  Capability
 
enum  Unit
 
- Properties inherited from QObject
 objectName
 
- Signals inherited from Akonadi::Job
void aboutToStart (Akonadi::Job *job)
 
void writeFinished (Akonadi::Job *job)
 
- Signals inherited from KJob
void description (KJob *job, const QString &title, const QPair< QString, QString > &field1=QPair< QString, QString >(), const QPair< QString, QString > &field2=QPair< QString, QString >())
 
void finished (KJob *job)
 
void infoMessage (KJob *job, const QString &plain, const QString &rich=QString())
 
void percent (KJob *job, unsigned long percent)
 
void processedAmount (KJob *job, KJob::Unit unit, qulonglong amount)
 
void processedSize (KJob *job, qulonglong size)
 
void result (KJob *job)
 
void resumed (KJob *job)
 
void speed (KJob *job, unsigned long speed)
 
void suspended (KJob *job)
 
void totalAmount (KJob *job, KJob::Unit unit, qulonglong amount)
 
void totalSize (KJob *job, qulonglong size)
 
void warning (KJob *job, const QString &plain, const QString &rich=QString())
 
- Public Slots inherited from KJob
bool kill (KillVerbosity verbosity=Quietly)
 
bool resume ()
 
bool suspend ()
 
- 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)
 
- Public Attributes inherited from KJob
 Bytes
 
 Directories
 
 Files
 
 Items
 
 Killable
 
 NoCapabilities
 
 Suspendable
 
- Public Attributes inherited from QObject
typedef QObjectList
 
- Protected Slots inherited from Akonadi::Job
void slotResult (KJob *job) override
 
- Protected Slots inherited from KCompositeJob
virtual void slotInfoMessage (KJob *job, const QString &plain, const QString &rich)
 
virtual void slotResult (KJob *job)
 

Detailed Description

Job that modifies an existing item in the Akonadi storage.

This job is used to writing back items to the Akonadi storage, after the user has changed them in any way. For performance reasons either the full item (including the full payload) can written back or only the meta data of the item.

Example:

// Fetch item with unique id 125
Akonadi::ItemFetchJob *fetchJob = new Akonadi::ItemFetchJob( Akonadi::Item( 125 ) );
connect( fetchJob, SIGNAL(result(KJob*)), SLOT(fetchFinished(KJob*)) );
...
MyClass::fetchFinished( KJob *job )
{
if ( job->error() )
return;
Akonadi::Item item = fetchJob->items().at(0);
// Set a custom flag
item.setFlag( "\GotIt" );
// Store back modified item
connect( modifyJob, SIGNAL(result(KJob*)), SLOT(modifyFinished(KJob*)) );
}
MyClass::modifyFinished( KJob *job )
{
if ( job->error() )
qDebug() << "Error occurred";
else
qDebug() << "Item modified successfully";
}

Conflict Resolution

When the job is executed, a check is made to ensure that the Item contained in the job is not older than the version of the Item already held in the Akonadi database. If it is older, a conflict resolution dialog is displayed for the user to choose which version of the Item to use, unless disableAutomaticConflictHandling() has been called to disable the dialog, or disableRevisionCheck() has been called to disable version checking altogether.

The item version is checked by comparing the Item::revision() values in the job and in the database. To ensure that two successive ItemModifyJobs for the same Item work correctly, the revision number of the Item supplied to the second ItemModifyJob should be set equal to the Item's revision number on completion of the first ItemModifyJob. This can be obtained by, for example, calling item().revision() in the job's result slot.

Author
Volker Krause vkrau[email protected][email protected][email protected]de.or[email protected]g

Definition at line 83 of file itemmodifyjob.h.

Constructor & Destructor Documentation

ItemModifyJob::ItemModifyJob ( const Item &  item,
QObject parent = nullptr 
)
explicit

Creates a new item modify job.

Parameters
itemThe modified item object to store.
parentThe parent object.

Definition at line 105 of file itemmodifyjob.cpp.

Akonadi::ItemModifyJob::ItemModifyJob ( const Item::List &  items,
QObject parent = nullptr 
)
explicit

Creates a new item modify job for bulk modifications.

Using this is different from running a modification job per item. Use this when applying the same change to a set of items, such as a mass-change of item flags, not if you just want to store a bunch of randomly modified items.

Currently the following modifications are supported:

  • flag changes
Note
Since this does not do payload modifications, it implies setIgnorePayload( true ) and disableRevisionCheck().
Parameters
itemsThe list of items to modify, must not be empty.
Since
4.6
ItemModifyJob::~ItemModifyJob ( )
override

Destroys the item modify job.

Definition at line 139 of file itemmodifyjob.cpp.

Member Function Documentation

void ItemModifyJob::disableAutomaticConflictHandling ( )

Disables the automatic handling of conflicts.

By default the item modify job will bring up a dialog to resolve a conflict that might happen when modifying an item. Calling this method will avoid that and the job returns with an error in case of a conflict.

Since
4.6

Definition at line 394 of file itemmodifyjob.cpp.

void ItemModifyJob::disableRevisionCheck ( )

Disables the check of the revision number.

Note
If disabled, no conflict detection is available.

Definition at line 387 of file itemmodifyjob.cpp.

bool ItemModifyJob::doHandleResponse ( qint64  tag,
const Protocol::CommandPtr response 
)
overrideprotectedvirtual

This method should be reimplemented in the concrete jobs in case you want to handle incoming data.

It will be called on received data from the backend. The default implementation does nothing.

Parameters
tagThe tag of the corresponding command, empty if this is an untagged response.
responseThe received response
Returns
Implementations should return true if the last response was processed and the job can emit result. Return false if more responses from server are expected.

Reimplemented from Akonadi::Job.

Definition at line 270 of file itemmodifyjob.cpp.

void ItemModifyJob::doStart ( )
overrideprotectedvirtual

This method must be reimplemented in the concrete jobs.

It will be called after the job has been started and a connection to the Akonadi backend has been established.

Implements Akonadi::Job.

Definition at line 248 of file itemmodifyjob.cpp.

bool ItemModifyJob::ignorePayload ( ) const

Returns whether the payload of the modified item shall be omitted from transmission to the Akonadi storage.

Definition at line 364 of file itemmodifyjob.cpp.

Item ItemModifyJob::item ( ) const

Returns the modified and stored item including the changed revision number.

Note
Use this method only when using the single item constructor.

Definition at line 401 of file itemmodifyjob.cpp.

Item::List ItemModifyJob::items ( ) const

Returns the modified and stored items including the changed revision number.

Since
4.6

Definition at line 409 of file itemmodifyjob.cpp.

void ItemModifyJob::setIgnorePayload ( bool  ignore)

Sets whether the payload of the modified item shall be omitted from transmission to the Akonadi storage.

The default is false, however it can be set for performance reasons.

Parameters
ignoreignores payload if set as true

Definition at line 347 of file itemmodifyjob.cpp.

void ItemModifyJob::setUpdateGid ( bool  update)

Sets whether the GID shall be updated either from the gid parameter or by extracting it from the payload.

The default is false to avoid unnecessarily update the GID, as it should never change once set, and the ItemCreateJob already sets it.

Parameters
updateupdate the GID if set as true
Note
If disabled the GID will not be updated, but still be used for identification of the item.
Since
4.12

Definition at line 371 of file itemmodifyjob.cpp.

bool ItemModifyJob::updateGid ( ) const

Returns whether the GID should be updated.

Since
4.12

Definition at line 381 of file itemmodifyjob.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 Mon Aug 3 2020 23:15:46 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.