Contents

Akonadi::Job Class

class Akonadi::Job

Base class for all actions in the Akonadi storage. More...

Header: #include <Job>
CMake: find_package(KPim6 REQUIRED COMPONENTS AkonadiCore)
target_link_libraries(mytarget PRIVATE KPim6::AkonadiCore)
Inherited By:

Akonadi::CollectionCopyJob, Akonadi::CollectionCreateJob, Akonadi::CollectionDeleteJob, Akonadi::CollectionFetchJob, Akonadi::CollectionModifyJob, Akonadi::CollectionMoveJob, Akonadi::CollectionStatisticsJob, Akonadi::InvalidateCacheJob, Akonadi::ItemCopyJob, Akonadi::ItemCreateJob, Akonadi::ItemDeleteJob, Akonadi::ItemFetchJob, Akonadi::ItemModifyJob, Akonadi::ItemMoveJob, Akonadi::ItemSearchJob, Akonadi::ItemSync, Akonadi::LinkJob, Akonadi::SearchCreateJob, Akonadi::TagCreateJob, Akonadi::TagDeleteJob, Akonadi::TagFetchJob, Akonadi::TagModifyJob, Akonadi::TagSync, Akonadi::TransactionJob, Akonadi::TransactionSequence, Akonadi::TrashJob, Akonadi::TrashRestoreJob, and Akonadi::UnlinkJob

Public Types

enum Error { ConnectionFailed, ProtocolVersionMismatch, UserCanceled, Unknown, UserError }

Public Functions

Job(QObject *parent = nullptr)
virtual ~Job() override

Reimplemented Public Functions

virtual QString errorString() const override
virtual void start() override

Signals

void aboutToStart(Akonadi::Job *job)
void writeFinished(Akonadi::Job *job)

Protected Functions

virtual bool doHandleResponse(qint64 tag, const Akonadi::Protocol::CommandPtr &response)
virtual void doStart() = 0
void emitWriteFinished()

Reimplemented Protected Functions

virtual bool addSubjob(KJob *job) override
virtual bool doKill() override
virtual bool removeSubjob(KJob *job) override

Detailed Description

This class encapsulates a request to the pim storage service, the code looks like

 Akonadi::Job *job = new Akonadi::SomeJob( some parameter );
 connect(job, &KJob::result, this, &MyClass::slotResult);

The job is queued for execution as soon as the event loop is entered again.

And the slotResult is usually at least:

 if ( job->error() ) {
   // handle error...
 }

With the synchronous interface the code looks like

 Akonadi::SomeJob *job = new Akonadi::SomeJob( some parameter );
 if ( !job->exec() ) {
   qDebug() << "Error:" << job->errorString();
 } else {
   // do something
 }

Warning: Using the synchronous method is error prone, use this only if the asynchronous access is not possible. See the documentation of KJob::exec() for more details.

Subclasses must reimplement doStart().

Note: KJob-derived objects delete itself, it is thus not possible to create job objects on the stack!

Author: Volker Krause <vkrause@kde.org>, Tobias Koenig <tokoe@kde.org>, Marc Mutz <mutz@kde.org>

Member Type Documentation

enum Job::Error

Describes the error codes that can be emitted by this class. Subclasses can provide additional codes, starting from UserError onwards

Member Function Documentation

[explicit] Job::Job(QObject *parent = nullptr)

Creates a new job.

If the parent object is a Job object, the new job will be a subjob of parent. If the parent object is a Session object, it will be used for server communication instead of the default session.

parent The parent object, job or session.

[override virtual noexcept] Job::~Job()

Destroys the job.

[signal] void Job::aboutToStart(Akonadi::Job *job)

This signal is emitted directly before the job will be started.

job The started job.

[override virtual protected] bool Job::addSubjob(KJob *job)

Adds the given job as a subjob to this job. This method is automatically called if you construct a job using another job as parent object. The base implementation does the necessary setup to share the network connection with the backend.

job The new subjob.

[virtual protected] bool Job::doHandleResponse(qint64 tag, const Akonadi::Protocol::CommandPtr &response)

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.

tag The tag of the corresponding command, empty if this is an untagged response. response The 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.

[override virtual protected] bool Job::doKill()

Kills the execution of the job.

[pure virtual protected] void Job::doStart()

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.

[protected] void Job::emitWriteFinished()

Call this method to indicate that this job will not call writeData() again.

See also writeFinished().

[override virtual] QString Job::errorString() const

Returns the error string, if there has been an error, an empty string otherwise.

[override virtual protected] bool Job::removeSubjob(KJob *job)

Removes the given subjob of this job.

job The subjob to remove.

[override virtual] void Job::start()

Jobs are started automatically once entering the event loop again, no need to explicitly call this.

[signal] void Job::writeFinished(Akonadi::Job *job)

This signal is emitted if the job has finished all write operations, ie. if this signal is emitted, the job guarantees to not call writeData() again. Do not emit this signal directly, call emitWriteFinished() instead.

job This job.

See also emitWriteFinished().