1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2000 Stephan Kulow <coolo@kde.org>
4 SPDX-FileCopyrightText: 2000-2009 David Faure <faure@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8
9#ifndef KIO_JOB_BASE_H
10#define KIO_JOB_BASE_H
11
12#include <KCompositeJob>
13#include <kio/metadata.h>
14
15namespace KIO
16{
17class JobUiDelegateExtension;
18
19class JobPrivate;
20/*!
21 * \class KIO::Job
22 * \inheaderfile KIO/Job
23 * \inmodule KIOCore
24 *
25 * The base class for all jobs.
26 * For all jobs created in an application, the code looks like
27 *
28 * \code
29 * KIO::Job* job = KIO::someoperation(some parameters);
30 * connect(job, &KJob::result, this, &MyClass::slotResult);
31 * \endcode
32 * (other connects, specific to the job)
33 *
34 * And slotResult is usually at least:
35 *
36 * \code
37 * void MyClass::slotResult(KJob *job)
38 * {
39 * if (job->error()) {
40 * job->uiDelegate()->showErrorMessage();
41 * }
42 * }
43 * \endcode
44 */
45class KIOCORE_EXPORT Job : public KCompositeJob
46{
47 Q_OBJECT
48
49protected:
50 Job();
51 // used also from KIOGui's PreviewJob, so needs to be exported
52 explicit Job(JobPrivate &dd);
53
54public:
55 ~Job() override;
56 void start() override
57 {
58 } // Since KIO autostarts its jobs
59
60 /*!
61 * Retrieves the UI delegate extension used by this job.
62 * \since 5.0
63 */
64 JobUiDelegateExtension *uiDelegateExtension() const;
65
66 /*!
67 * Sets the UI delegate extension to be used by this job.
68 *
69 * The default UI delegate extension is KIO::defaultJobUiDelegateExtension()
70 */
71 void setUiDelegateExtension(JobUiDelegateExtension *extension);
72
73protected:
74 /*!
75 * Abort this job.
76 *
77 * This kills all subjobs and deletes the job.
78 */
79 bool doKill() override;
80
81 /*!
82 * Suspend this job
83 * \sa resume()
84 */
85 bool doSuspend() override;
86
87 /*!
88 * Resume this job
89 * \sa suspend()
90 */
91 bool doResume() override;
92
93public:
94 /*!
95 * Converts an error code and a non-i18n error message into an
96 * error message in the current language. The low level (non-i18n)
97 * error message (usually a url) is put into the translated error
98 * message using %1.
99 *
100 * Example for errid == ERR_CANNOT_OPEN_FOR_READING:
101 * \code
102 * i18n("Could not read\n%1", errortext);
103 * \endcode
104 * Use this to display the error yourself, but for a dialog box
105 * use uiDelegate()->showErrorMessage(). Do not call it if error()
106 * is not 0.
107 *
108 * Returns the error message and if there is no error, a message
109 * telling the user that the app is broken, so check with
110 * error() whether there is an error
111 */
112 QString errorString() const override;
113
114 /*!
115 * Converts an error code and a non-i18n error message into i18n
116 * strings suitable for presentation in a detailed error message box.
117 *
118 * \a reqUrl the request URL that generated this error message
119 *
120 * \a method the method that generated this error message
121 * (unimplemented)
122 *
123 * Returns the following strings: title, error + description,
124 * causes+solutions
125 */
126 QStringList detailedErrorStrings(const QUrl *reqUrl = nullptr, int method = -1) const;
127
128 /*!
129 * Set the parent Job.
130 * One example use of this is when FileCopyJob calls RenameDialog::open,
131 * it must pass the correct progress ID of the parent CopyJob
132 * (to hide the progress dialog).
133 * You can set the parent job only once. By default a job does not
134 * have a parent job.
135 *
136 * \a parentJob the new parent job
137 */
138 void setParentJob(Job *parentJob);
139
140 /*!
141 * Returns the parent job, or \c nullptr if there is none
142 * \sa setParentJob
143 */
144 Job *parentJob() const;
145
146 /*!
147 * Set meta data to be sent to the worker, replacing existing
148 * meta data.
149 *
150 * \a metaData the meta data to set
151 *
152 * \sa addMetaData()
153 * \sa mergeMetaData()
154 */
155 void setMetaData(const KIO::MetaData &metaData);
156
157 /*!
158 * Add key/value pair to the meta data that is sent to the worker.
159 *
160 * \a key the key of the meta data
161 *
162 * \a value the value of the meta data
163 *
164 * \sa setMetaData()
165 * \sa mergeMetaData()
166 */
167 void addMetaData(const QString &key, const QString &value);
168
169 /*!
170 * Add key/value pairs to the meta data that is sent to the worker.
171 * If a certain key already existed, it will be overridden.
172 *
173 * \a values the meta data to add
174 *
175 * \sa setMetaData()
176 * \sa mergeMetaData()
177 */
178 void addMetaData(const QMap<QString, QString> &values);
179
180 /*!
181 * Add key/value pairs to the meta data that is sent to the worker.
182 * If a certain key already existed, it will remain unchanged.
183 *
184 * \a values the meta data to merge
185 *
186 * \sa setMetaData()
187 * \sa addMetaData()
188 */
189 void mergeMetaData(const QMap<QString, QString> &values);
190
191 /*!
192 * \internal. For the scheduler. Do not use.
193 */
194 MetaData outgoingMetaData() const;
195
196 /*!
197 * Get meta data received from the worker.
198 * (Valid when first data is received and/or worker is finished)
199 *
200 * Returns the job's meta data
201 */
202 MetaData metaData() const;
203
204 /*!
205 * Query meta data received from the worker.
206 * (Valid when first data is received and/or worker is finished)
207 *
208 * \a key the key of the meta data to retrieve
209 *
210 * Returns the value of the meta data, or QString() if the
211 * \a key does not exist
212 */
213 QString queryMetaData(const QString &key);
214
215protected:
216Q_SIGNALS:
217 /*!
218 * Emitted when the worker successfully connected to the host.
219 * There is no guarantee the worker will send this, and this is
220 * currently unused (in the applications).
221 *
222 * \a job the job that emitted this signal
223 */
224 void connected(KIO::Job *job);
225
226protected:
227 /*!
228 * Add a job that has to be finished before a result
229 * is emitted. This has obviously to be called before
230 * the finish signal is emitted by the worker.
231 *
232 * \a job the subjob to add
233 *
234 * \reimp
235 */
236 bool addSubjob(KJob *job) override;
237
238 /*!
239 * Mark a sub job as being done.
240 *
241 * Note that this does not terminate the parent job, even if \a job
242 * is the last subjob. emitResult must be called to indicate that
243 * the job is complete.
244 *
245 * \a job the subjob to remove
246 *
247 * \reimp
248 */
249 bool removeSubjob(KJob *job) override;
250
251protected:
252 JobPrivate *const d_ptr;
253
254private:
255 Q_DECLARE_PRIVATE(Job)
256};
257
258/*!
259 * Flags for the job properties.
260 * Not all flags are supported in all cases. Please see documentation of
261 * the calling function!
262 *
263 * \value DefaultFlags Show the progress info GUI, no Resume and no Overwrite
264 * \value HideProgressInfo Hide progress information dialog, i.e. don't show a GUI.
265 * \value Resume When set, automatically append to the destination file if it exists already. WARNING: this is NOT the builtin support for offering the user to
266 * resume a previous partial download. The Resume option is much less used, it allows to append to an existing file. This is used by KIO::put(),
267 * KIO::file_copy(), KIO::file_move()
268 * \value Overwrite When set, automatically overwrite the destination if it exists already. This is used by KIO::rename(), KIO::put(), KIO::file_copy(),
269 * KIO::file_move(), KIO::symlink(). Otherwise the operation will fail with ERR_FILE_ALREADY_EXIST or ERR_DIR_ALREADY_EXIST
270 * \value [since 5.43] NoPrivilegeExecution When set, notifies the worker that application/job does not want privilege execution. So in case of failure due to
271 * insufficient privileges show an error without attempting to run the operation as root first
272 */
273enum JobFlag {
274 DefaultFlags = 0,
275 HideProgressInfo = 1,
276 Resume = 2,
277 Overwrite = 4,
278 NoPrivilegeExecution = 8,
279};
280
281Q_DECLARE_FLAGS(JobFlags, JobFlag)
282Q_DECLARE_OPERATORS_FOR_FLAGS(JobFlags)
283
284/*!
285 * \value Reload
286 * \value NoReload
287 */
288enum LoadType {
289 Reload,
290 NoReload
291};
292}
293
294#endif
295

source code of kio/src/core/job_base.h