Akonadi::ItemModifyJob

Search for usage in LXR

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
 
qint64 elapsedTime () const
 
int error () const
 
QString errorText () const
 
bool exec ()
 
bool isAutoDelete () const
 
bool isFinishedNotificationHidden () const
 
bool isStartedWithExec () const
 
bool isSuspended () const
 
unsigned long percent () const
 
Q_SCRIPTABLE qulonglong processedAmount (Unit unit) const
 
void setAutoDelete (bool autodelete)
 
void setFinishedNotificationHidden (bool hide=true)
 
void setUiDelegate (KJobUiDelegate *delegate)
 
Q_SCRIPTABLE qulonglong totalAmount (Unit unit) const
 
KJobUiDelegateuiDelegate () const
 
- Public Member Functions inherited from QObject
 QObject (QObject *parent)
 
QBindable< QStringbindableObjectName ()
 
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 () const const
 
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 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 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_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
 
qobject_cast (const QObject *object)
 
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)
 
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)
 
bool isFinished () const
 
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 setProgressUnit (Unit unit)
 
void setTotalAmount (Unit unit, qulonglong amount)
 
void startElapsedTimer ()
 
- 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
}
 
using List = QList<Job *>
 
- Public Types inherited from KJob
typedef QFlags< CapabilityCapabilities
 
enum  Capability
 
enum  Unit
 
- Public Types inherited from QObject
typedef  QObjectList
 
- 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 &message)
 
void percentChanged (KJob *job, unsigned long percent)
 
void processedAmountChanged (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 totalAmountChanged (KJob *job, KJob::Unit unit, qulonglong amount)
 
void totalSize (KJob *job, qulonglong size)
 
void warning (KJob *job, const QString &message)
 
- Public Slots inherited from KJob
bool kill (KJob::KillVerbosity verbosity=KJob::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 *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)
 
- Public Attributes inherited from KJob
 Bytes
 
 Directories
 
 Files
 
 Items
 
 Killable
 
 NoCapabilities
 
 Suspendable
 
 UnitsCount
 
- Protected Slots inherited from Akonadi::Job
void slotResult (KJob *job) override
 
- Protected Slots inherited from KCompositeJob
virtual void slotInfoMessage (KJob *job, const QString &message)
 
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
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";
}
Job that fetches items from the Akonadi storage.
Item::List items() const
Returns the fetched items.
Job that modifies an existing item in the Akonadi storage.
Item item() const
Returns the modified and stored item including the changed revision number.
Represents a PIM item stored in Akonadi storage.
Definition item.h:100
void setFlag(const QByteArray &name)
Sets the flag with the given name in the item.
Definition item.cpp:180
int error() const
void result(KJob *job)
const_reference at(qsizetype i) const const
QMetaObject::Connection connect(const QObject *sender, PointerToMemberFunction signal, Functor functor)
T qobject_cast(QObject *object)

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.nosp@m.se@k.nosp@m.de.or.nosp@m.g

Definition at line 81 of file itemmodifyjob.h.

Constructor & Destructor Documentation

◆ ItemModifyJob() [1/2]

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 100 of file itemmodifyjob.cpp.

◆ ItemModifyJob() [2/2]

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

Definition at line 116 of file itemmodifyjob.cpp.

◆ ~ItemModifyJob()

ItemModifyJob::~ItemModifyJob ( )
override

Destroys the item modify job.

Definition at line 134 of file itemmodifyjob.cpp.

Member Function Documentation

◆ disableAutomaticConflictHandling()

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 393 of file itemmodifyjob.cpp.

◆ disableRevisionCheck()

void ItemModifyJob::disableRevisionCheck ( )

Disables the check of the revision number.

Note
If disabled, no conflict detection is available.

Definition at line 386 of file itemmodifyjob.cpp.

◆ doHandleResponse()

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 266 of file itemmodifyjob.cpp.

◆ doStart()

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 244 of file itemmodifyjob.cpp.

◆ ignorePayload()

bool ItemModifyJob::ignorePayload ( ) const
nodiscard

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

Definition at line 363 of file itemmodifyjob.cpp.

◆ item()

Item ItemModifyJob::item ( ) const
nodiscard

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 400 of file itemmodifyjob.cpp.

◆ items()

Item::List ItemModifyJob::items ( ) const
nodiscard

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

Since
4.6

Definition at line 408 of file itemmodifyjob.cpp.

◆ setIgnorePayload()

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 346 of file itemmodifyjob.cpp.

◆ setUpdateGid()

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 370 of file itemmodifyjob.cpp.

◆ updateGid()

bool ItemModifyJob::updateGid ( ) const
nodiscard

Returns whether the GID should be updated.

Since
4.12

Definition at line 380 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-2024 The KDE developers.
Generated on Mon Nov 4 2024 16:31:59 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.