1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
|
/*
Copyright (c) 2006 Tobias Koenig <tokoe@kde.org>
2006 Marc Mutz <mutz@kde.org>
2006 - 2007 Volker Krause <vkrause@kde.org>
This library is free software; you can redistribute it and/or modify it
under the terms of the GNU Library General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
License for more details.
You should have received a copy of the GNU Library General Public License
along with this library; see the file COPYING.LIB. If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301, USA.
*/
#ifndef AKONADI_JOB_H
#define AKONADI_JOB_H
#include "akonadi_export.h"
#include <kcompositejob.h>
class QString;
namespace Akonadi {
class JobPrivate;
class Session;
class SessionPrivate;
/**
* @short Base class for all actions in the Akonadi storage.
*
* This class encapsulates a request to the pim storage service,
* the code looks like
*
* @code
*
* Akonadi::Job *job = new Akonadi::SomeJob( some parameter );
* connect( job, SIGNAL(result(KJob*)),
* this, SLOT(slotResult(KJob*)) );
*
* @endcode
*
* The job is queued for execution as soon as the event loop is entered
* again.
*
* And the slotResult is usually at least:
*
* @code
*
* if ( job->error() ) {
* // handle error...
* }
*
* @endcode
*
* With the synchronous interface the code looks like
*
* @code
* Akonadi::SomeJob *job = new Akonadi::SomeJob( some parameter );
* if ( !job->exec() ) {
* qDebug() << "Error:" << job->errorString();
* } else {
* // do something
* }
* @endcode
*
* @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>
*/
class AKONADI_EXPORT Job : public KCompositeJob
{
Q_OBJECT
friend class Session;
friend class SessionPrivate;
public:
/**
* Describes a list of jobs.
*/
typedef QList<Job *> List;
/**
* Describes the error codes that can be emitted by this class.
* Subclasses can provide additional codes, starting from UserError
* onwards
*/
enum Error {
ConnectionFailed = UserDefinedError, ///< The connection to the Akonadi server failed.
ProtocolVersionMismatch, ///< The server protocol version is too old or too new.
UserCanceled, ///< The user canceld this job.
Unknown, ///< Unknown error.
UserError = UserDefinedError + 42 ///< Starting point for error codes defined by sub-classes.
};
/**
* Creates a new job.
*
* If the parent object is a Job object, the new job will be a subjob of @p parent.
* If the parent object is a Session object, it will be used for server communication
* instead of the default session.
*
* @param parent The parent object, job or session.
*/
explicit Job(QObject *parent = 0);
/**
* Destroys the job.
*/
virtual ~Job();
/**
* Jobs are started automatically once entering the event loop again, no need
* to explicitly call this.
*/
void start();
/**
* Returns the error string, if there has been an error, an empty
* string otherwise.
*/
virtual QString errorString() const;
Q_SIGNALS:
/**
* This signal is emitted directly before the job will be started.
*
* @param job The started job.
*/
void aboutToStart(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.
*
* @param job This job.
* @see emitWriteFinished()
*/
void writeFinished(Akonadi::Job *job);
protected:
/**
* 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.
*/
virtual void doStart() = 0;
/**
* 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.
*
* @param tag The tag of the corresponding command, empty if this is an untagged response.
* @param data The received data.
*/
virtual void doHandleResponse(const QByteArray &tag, const QByteArray &data);
/**
* 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.
*
* @param job The new subjob.
*/
virtual bool addSubjob(KJob *job);
/**
* Removes the given subjob of this job.
*
* @param job The subjob to remove.
*/
virtual bool removeSubjob(KJob *job);
/**
* Kills the execution of the job.
*/
virtual bool doKill();
/**
* Call this method to indicate that this job will not call writeData() again.
* @see writeFinished()
*/
void emitWriteFinished();
protected Q_SLOTS:
virtual void slotResult(KJob *job);
protected:
//@cond PRIVATE
Job(JobPrivate *dd, QObject *parent);
JobPrivate *const d_ptr;
//@endcond
private:
Q_DECLARE_PRIVATE(Job)
//@cond PRIVATE
Q_PRIVATE_SLOT(d_func(), void slotSubJobAboutToStart(Akonadi::Job *))
Q_PRIVATE_SLOT(d_func(), void startNext())
Q_PRIVATE_SLOT(d_func(), void signalCreationToJobTracker())
Q_PRIVATE_SLOT(d_func(), void signalStartedToJobTracker())
Q_PRIVATE_SLOT(d_func(), void delayedEmitResult())
//@endcond
};
}
#endif
|
