Akonadi

job.h
1 /*
2  SPDX-FileCopyrightText: 2006 Tobias Koenig <[email protected]>
3  2006 Marc Mutz <[email protected]>
4  2006 - 2007 Volker Krause <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 
9 #pragma once
10 
11 #include "akonadicore_export.h"
12 
13 #include <KCompositeJob>
14 
15 class QString;
16 
17 namespace Akonadi
18 {
19 namespace Protocol
20 {
21 class Command;
22 using CommandPtr = QSharedPointer<Command>;
23 }
24 
25 class JobPrivate;
26 class Session;
27 class SessionPrivate;
28 
29 /**
30  * @short Base class for all actions in the Akonadi storage.
31  *
32  * This class encapsulates a request to the pim storage service,
33  * the code looks like
34  *
35  * @code
36  *
37  * Akonadi::Job *job = new Akonadi::SomeJob( some parameter );
38  * connect( job, SIGNAL(result(KJob*)),
39  * this, SLOT(slotResult(KJob*)) );
40  *
41  * @endcode
42  *
43  * The job is queued for execution as soon as the event loop is entered
44  * again.
45  *
46  * And the slotResult is usually at least:
47  *
48  * @code
49  *
50  * if ( job->error() ) {
51  * // handle error...
52  * }
53  *
54  * @endcode
55  *
56  * With the synchronous interface the code looks like
57  *
58  * @code
59  * Akonadi::SomeJob *job = new Akonadi::SomeJob( some parameter );
60  * if ( !job->exec() ) {
61  * qDebug() << "Error:" << job->errorString();
62  * } else {
63  * // do something
64  * }
65  * @endcode
66  *
67  * @warning Using the synchronous method is error prone, use this only
68  * if the asynchronous access is not possible. See the documentation of
69  * KJob::exec() for more details.
70  *
71  * Subclasses must reimplement doStart().
72  *
73  * @note KJob-derived objects delete itself, it is thus not possible
74  * to create job objects on the stack!
75  *
76  * @author Volker Krause <[email protected]>, Tobias Koenig <[email protected]>, Marc Mutz <[email protected]>
77  */
78 class AKONADICORE_EXPORT Job : public KCompositeJob
79 {
80  Q_OBJECT
81 
82  friend class Session;
83  friend class SessionPrivate;
84 
85 public:
86  /**
87  * Describes a list of jobs.
88  */
89  using List = QList<Job *>;
90 
91  /**
92  * Describes the error codes that can be emitted by this class.
93  * Subclasses can provide additional codes, starting from UserError
94  * onwards
95  */
96  enum Error {
97  ConnectionFailed = UserDefinedError, ///< The connection to the Akonadi server failed.
98  ProtocolVersionMismatch, ///< The server protocol version is too old or too new.
99  UserCanceled, ///< The user canceled this job.
100  Unknown, ///< Unknown error.
101  UserError = UserDefinedError + 42 ///< Starting point for error codes defined by sub-classes.
102  };
103 
104  /**
105  * Creates a new job.
106  *
107  * If the parent object is a Job object, the new job will be a subjob of @p parent.
108  * If the parent object is a Session object, it will be used for server communication
109  * instead of the default session.
110  *
111  * @param parent The parent object, job or session.
112  */
113  explicit Job(QObject *parent = nullptr);
114 
115  /**
116  * Destroys the job.
117  */
118  ~Job() override;
119 
120  /**
121  * Jobs are started automatically once entering the event loop again, no need
122  * to explicitly call this.
123  */
124  void start() override;
125 
126  /**
127  * Returns the error string, if there has been an error, an empty
128  * string otherwise.
129  */
130  Q_REQUIRED_RESULT QString errorString() const final;
131 
132 Q_SIGNALS:
133  /**
134  * This signal is emitted directly before the job will be started.
135  *
136  * @param job The started job.
137  */
138  void aboutToStart(Akonadi::Job *job);
139 
140  /**
141  * This signal is emitted if the job has finished all write operations, ie.
142  * if this signal is emitted, the job guarantees to not call writeData() again.
143  * Do not emit this signal directly, call emitWriteFinished() instead.
144  *
145  * @param job This job.
146  * @see emitWriteFinished()
147  */
148  void writeFinished(Akonadi::Job *job);
149 
150 protected:
151  /**
152  * This method must be reimplemented in the concrete jobs. It will be called
153  * after the job has been started and a connection to the Akonadi backend has
154  * been established.
155  */
156  virtual void doStart() = 0;
157 
158  /**
159  * This method should be reimplemented in the concrete jobs in case you want
160  * to handle incoming data. It will be called on received data from the backend.
161  * The default implementation does nothing.
162  *
163  * @param tag The tag of the corresponding command, empty if this is an untagged response.
164  * @param response The received response
165  *
166  * @return Implementations should return true if the last response was processed and
167  * the job can emit result. Return false if more responses from server are expected.
168  */
169  virtual bool doHandleResponse(qint64 tag, const Protocol::CommandPtr &response);
170 
171  /**
172  * Adds the given job as a subjob to this job. This method is automatically called
173  * if you construct a job using another job as parent object.
174  * The base implementation does the necessary setup to share the network connection
175  * with the backend.
176  *
177  * @param job The new subjob.
178  */
179  bool addSubjob(KJob *job) override;
180 
181  /**
182  * Removes the given subjob of this job.
183  *
184  * @param job The subjob to remove.
185  */
186  bool removeSubjob(KJob *job) override;
187 
188  /**
189  * Kills the execution of the job.
190  */
191  bool doKill() override;
192 
193  /**
194  * Call this method to indicate that this job will not call writeData() again.
195  * @see writeFinished()
196  */
197  void emitWriteFinished();
198 
199 protected Q_SLOTS:
200  void slotResult(KJob *job) override;
201 
202 protected:
203  /// @cond PRIVATE
204  Job(JobPrivate *dd, QObject *parent);
205  JobPrivate *const d_ptr;
206  /// @endcond
207 
208 private:
209  Q_DECLARE_PRIVATE(Job)
210 
211  /// @cond PRIVATE
212  Q_PRIVATE_SLOT(d_func(), void startNext())
213  Q_PRIVATE_SLOT(d_func(), void signalCreationToJobTracker())
214  Q_PRIVATE_SLOT(d_func(), void signalStartedToJobTracker())
215  Q_PRIVATE_SLOT(d_func(), void delayedEmitResult())
216  /// @endcond
217 };
218 
219 }
220 
The server protocol version is too old or too new.
Definition: job.h:98
Unknown error.
Definition: job.h:100
Base class for all actions in the Akonadi storage.
Definition: job.h:78
A communication session with the Akonadi storage.
Definition: core/session.h:53
ASAP CLI session.
Helper integration between Akonadi and Qt.
The user canceled this job.
Definition: job.h:99
Error
Describes the error codes that can be emitted by this class.
Definition: job.h:96
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Wed Jun 23 2021 23:17:24 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.