1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2000 Stephan Kulow <coolo@kde.org>
4 SPDX-FileCopyrightText: 2000-2013 David Faure <faure@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8
9#ifndef KIO_SIMPLEJOB_H
10#define KIO_SIMPLEJOB_H
11
12#include "job_base.h"
13#include <kio/global.h> // filesize_t
14
15namespace KIO
16{
17class SimpleJobPrivate;
18/*!
19 * \class KIO::SimpleJob
20 * \inheaderfile KIO/SimpleJob
21 * \inmodule KIOCore
22 *
23 * \brief A simple job (one url and one command).
24 *
25 * This is the base class for all jobs that are scheduled.
26 * Other jobs are high-level jobs (CopyJob, DeleteJob, FileCopyJob...)
27 * that manage subjobs but aren't scheduled directly.
28 */
29class KIOCORE_EXPORT SimpleJob : public KIO::Job
30{
31 Q_OBJECT
32
33public:
34 ~SimpleJob() override;
35
36protected:
37 bool doSuspend() override;
38
39 bool doResume() override;
40
41 bool doKill() override;
42
43public:
44 /*!
45 * Returns the SimpleJob's URL
46 */
47 const QUrl &url() const;
48
49 /*!
50 * Abort job.
51 * Suspends worker to be reused by another job for the same request.
52 */
53 virtual void putOnHold();
54
55 /*!
56 * Discard suspended worker.
57 */
58 static void removeOnHold();
59
60 /*!
61 * Returns true when redirections are handled internally, the default.
62 */
63 bool isRedirectionHandlingEnabled() const;
64
65 /*!
66 * Set \a handle to false to prevent the internal handling of redirections.
67 *
68 * When this flag is set, redirection requests are simply forwarded to the
69 * caller instead of being handled internally.
70 *
71 */
72 void setRedirectionHandlingEnabled(bool handle);
73
74public Q_SLOTS:
75 /*!
76 * \internal
77 * Called on a worker's error.
78 * Made public for the scheduler.
79 */
80 void slotError(int, const QString &);
81
82protected Q_SLOTS:
83 /*!
84 * Called when the worker marks the job
85 * as finished.
86 */
87 virtual void slotFinished();
88
89 /*!
90 * \internal
91 * Called on a worker's warning.
92 */
93 virtual void slotWarning(const QString &);
94
95 /*!
96 * MetaData from the worker is received.
97 *
98 * \a _metaData the meta data
99 * \sa metaData()
100 */
101 virtual void slotMetaData(const KIO::MetaData &_metaData);
102
103protected:
104 /*!
105 * Creates a new simple job. You don't need to use this constructor,
106 * unless you create a new job that inherits from SimpleJob.
107 * \internal
108 */
109 KIOCORE_NO_EXPORT explicit SimpleJob(SimpleJobPrivate &dd);
110
111private:
112 Q_DECLARE_PRIVATE(SimpleJob)
113};
114
115/*!
116 * \relates KIO::SimpleJob
117 *
118 * Removes a single directory.
119 *
120 * The directory is assumed to be empty.
121 * The job will fail if the directory is not empty.
122 * Use KIO::del() (DeleteJob) to delete non-empty directories.
123 *
124 * \a url The URL of the directory to remove.
125 *
126 * Returns a pointer to the job handling the operation.
127 */
128KIOCORE_EXPORT SimpleJob *rmdir(const QUrl &url);
129
130/*!
131 * \relates KIO::SimpleJob
132 *
133 * Changes permissions on a file or directory.
134 * See the other chmod in chmodjob.h for changing many files
135 * or directories.
136 *
137 * \a url The URL of file or directory.
138 *
139 * \a permissions The permissions to set.
140 *
141 * Returns the job handling the operation.
142 */
143KIOCORE_EXPORT SimpleJob *chmod(const QUrl &url, int permissions);
144
145/*!
146 * \relates KIO::SimpleJob
147 *
148 * Changes ownership and group of a file or directory.
149 *
150 * \a url The URL of file or directory.
151 *
152 * \a owner the new owner
153 *
154 * \a group the new group
155 *
156 * Returns the job handling the operation.
157 */
158KIOCORE_EXPORT SimpleJob *chown(const QUrl &url, const QString &owner, const QString &group);
159
160/*!
161 * \relates KIO::SimpleJob
162 *
163 * Changes the modification time on a file or directory.
164 *
165 * \a url The URL of file or directory.
166 *
167 * \a mtime The modification time to set.
168 *
169 * Returns the job handling the operation.
170 */
171KIOCORE_EXPORT SimpleJob *setModificationTime(const QUrl &url, const QDateTime &mtime);
172
173/*!
174 * \relates KIO::SimpleJob
175 *
176 * Rename a file or directory.
177 * Warning: this operation fails if a direct renaming is not
178 * possible (like with files or dirs on separate partitions)
179 * Use move or file_move in this case.
180 *
181 * \a src The original URL
182 *
183 * \a dest The final URL
184 *
185 * \a flags Can be Overwrite here
186 *
187 * Returns the job handling the operation.
188 */
189KIOCORE_EXPORT SimpleJob *rename(const QUrl &src, const QUrl &dest, JobFlags flags = DefaultFlags);
190
191/*!
192 * \relates KIO::SimpleJob
193 *
194 * Create or move a symlink.
195 * This is the lowlevel operation, similar to file_copy and file_move.
196 * It doesn't do any check (other than those the worker does)
197 * and it doesn't show rename and skip dialogs - use KIO::link for that.
198 *
199 * \a target The string that will become the "target" of the link (can be relative)
200 *
201 * \a dest The symlink to create.
202 *
203 * \a flags Can be Overwrite and HideProgressInfo
204 *
205 * Returns the job handling the operation.
206 */
207KIOCORE_EXPORT SimpleJob *symlink(const QString &target, const QUrl &dest, JobFlags flags = DefaultFlags);
208
209/*!
210 * \relates KIO::SimpleJob
211 *
212 * Execute any command that is specific to one worker (protocol).
213 *
214 * Examples are : HTTP POST, mount and unmount (kio_file)
215 *
216 * \a url The URL isn't passed to the worker, but is used to know
217 * which worker to send it to :-)
218 *
219 * \a data Packed data. The meaning is completely dependent on the
220 * worker, but usually starts with an int for the command number.
221 *
222 * \a flags Can be HideProgressInfo here
223 *
224 * Returns the job handling the operation.
225 */
226KIOCORE_EXPORT SimpleJob *special(const QUrl &url, const QByteArray &data, JobFlags flags = DefaultFlags);
227
228/*!
229 * \relates KIO::SimpleJob
230 *
231 * Mount filesystem.
232 *
233 * Special job for kio_file.
234 *
235 * \a ro Mount read-only if \c true.
236 *
237 * \a fstype File system type (e.g. "ext2", can be empty).
238 *
239 * \a dev Device (e.g. /dev/sda0).
240 *
241 * \a point Mount point, can be \c null.
242 *
243 * \a flags Can be HideProgressInfo here
244 *
245 * Returns the job handling the operation.
246 */
247KIOCORE_EXPORT SimpleJob *mount(bool ro, const QByteArray &fstype, const QString &dev, const QString &point, JobFlags flags = DefaultFlags);
248
249/*!
250 * \relates KIO::SimpleJob
251 *
252 * Unmount filesystem.
253 *
254 * Special job for kio_file.
255 *
256 * \a point Point to unmount.
257 *
258 * \a flags Can be HideProgressInfo here
259 *
260 * Returns the job handling the operation.
261 */
262KIOCORE_EXPORT SimpleJob *unmount(const QString &point, JobFlags flags = DefaultFlags);
263
264#if KIOCORE_ENABLE_DEPRECATED_SINCE(6, 9)
265/*!
266 * \relates KIO::SimpleJob
267 *
268 * HTTP cache update
269 *
270 * Not implemented.
271 *
272 * \a url Url to update, protocol must be "http".
273 *
274 * \a no_cache If true, cache entry for \c url is deleted.
275 *
276 * \a expireDate Local machine time indicating when the entry is
277 * supposed to expire.
278 *
279 * Returns the job handling the operation.
280 * \deprecated[6.9]
281 */
282KIOCORE_DEPRECATED_VERSION(6, 9, "Not implemented")
283KIOCORE_EXPORT SimpleJob *http_update_cache(const QUrl &url, bool no_cache, const QDateTime &expireDate);
284#endif
285
286/*!
287 * \relates KIO::SimpleJob
288 *
289 * Delete a single file.
290 *
291 * \a src File to delete.
292 *
293 * \a flags Can be HideProgressInfo here
294 *
295 * Returns the job handling the operation.
296 */
297KIOCORE_EXPORT SimpleJob *file_delete(const QUrl &src, JobFlags flags = DefaultFlags);
298
299}
300
301#endif
302

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