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

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