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

KDE's Doxygen guidelines are available online.