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 | |
15 | namespace KIO |
16 | { |
17 | class JobUiDelegateExtension; |
18 | |
19 | class 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 | */ |
45 | class KIOCORE_EXPORT Job : public KCompositeJob |
46 | { |
47 | Q_OBJECT |
48 | |
49 | protected: |
50 | Job(); |
51 | // used also from KIOGui's PreviewJob, so needs to be exported |
52 | explicit Job(JobPrivate &dd); |
53 | |
54 | public: |
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 | |
73 | protected: |
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 | |
93 | public: |
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 | |
215 | protected: |
216 | Q_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 | |
226 | protected: |
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 | |
251 | protected: |
252 | JobPrivate *const d_ptr; |
253 | |
254 | private: |
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 | */ |
273 | enum JobFlag { |
274 | DefaultFlags = 0, |
275 | HideProgressInfo = 1, |
276 | Resume = 2, |
277 | Overwrite = 4, |
278 | NoPrivilegeExecution = 8, |
279 | }; |
280 | |
281 | Q_DECLARE_FLAGS(JobFlags, JobFlag) |
282 | Q_DECLARE_OPERATORS_FOR_FLAGS(JobFlags) |
283 | |
284 | /*! |
285 | * \value Reload |
286 | * \value NoReload |
287 | */ |
288 | enum LoadType { |
289 | Reload, |
290 | NoReload |
291 | }; |
292 | } |
293 | |
294 | #endif |
295 | |