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

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