KIO

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

KDE's Doxygen guidelines are available online.