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_TRANSFERJOB_H
10#define KIO_TRANSFERJOB_H
11
12#include "simplejob.h"
13
14namespace KIO
15{
16class TransferJobPrivate;
17/*!
18 * \class KIO::TransferJob
19 * \inheaderfile KIO/TransferJob
20 * \inmodule KIOCore
21 *
22 * \brief The transfer job pumps data into and/or out of a KIO worker.
23 *
24 * Data is sent to the worker on request of the worker ( dataReq).
25 * If data coming from the worker can not be handled, the
26 * reading of data from the worker should be suspended.
27 */
28class KIOCORE_EXPORT TransferJob : public SimpleJob
29{
30 Q_OBJECT
31
32public:
33 ~TransferJob() override;
34
35 /*!
36 * Sets the modification time of the file to be created (by KIO::put)
37 * Note that some KIO workers might ignore this.
38 */
39 void setModificationTime(const QDateTime &mtime);
40
41#if KIOCORE_ENABLE_DEPRECATED_SINCE(6, 3)
42 /*!
43 * Checks whether we got an error page. This currently only happens
44 * with HTTP urls. Call this from your slot connected to result().
45 *
46 * Returns \c true if we got an (HTML) error page from the server
47 * instead of what we asked for.
48 *
49 * Not implemented.
50 *
51 * \deprecated[6.3]
52 */
53 KIOCORE_DEPRECATED_VERSION(6, 3, "Not implemented")
54 bool isErrorPage() const;
55#endif
56
57 /*!
58 * Enable the async data mode.
59 * When async data is enabled, data should be provided to the job by
60 * calling sendAsyncData() instead of returning data in the
61 * dataReq() signal.
62 */
63 void setAsyncDataEnabled(bool enabled);
64
65 /*!
66 * Provide data to the job when async data is enabled.
67 * Should be called exactly once after receiving a dataReq signal
68 * Sending an empty block indicates end of data.
69 */
70 void sendAsyncData(const QByteArray &data);
71
72 /*!
73 * Call this in the slot connected to result,
74 * and only after making sure no error happened.
75 *
76 * Returns the MIME type of the URL
77 */
78 QString mimetype() const;
79
80 /*!
81 * After the job has finished, it will return the final url in case a redirection
82 * has happened.
83 *
84 * Returns the final url that can be empty in case no redirection has happened.
85 *
86 * \since 5.0
87 */
88 QUrl redirectUrl() const;
89
90 /*!
91 * Set the total size of data that we are going to send
92 * in a put job. Helps getting proper progress information.
93 *
94 * \since 4.2.1
95 */
96 void setTotalSize(KIO::filesize_t bytes);
97
98protected:
99 bool doResume() override;
100
101Q_SIGNALS:
102 /*!
103 * Data from the worker has arrived.
104 *
105 * \a job the job that emitted this signal
106 *
107 * \a data data received from the worker.
108 *
109 * End of data (EOD) has been reached if data.size() == 0, however, you
110 * should not be certain of data.size() == 0 ever happening (e.g. in case
111 * of an error), so you should rely on result() instead.
112 */
113 void data(KIO::Job *job, const QByteArray &data);
114
115 /*!
116 * Request for data.
117 *
118 * Please note, that you shouldn't put too large chunks
119 * of data in it as this requires copies within the frame
120 * work, so you should rather split the data you want
121 * to pass here in reasonable chunks (about 1MB maximum)
122 *
123 * \a job the job that emitted this signal
124 *
125 * \a data buffer to fill with data to send to the
126 * worker. An empty buffer indicates end of data. (EOD)
127 */
128 void dataReq(KIO::Job *job, QByteArray &data);
129
130 /*!
131 * Signals a redirection.
132 *
133 * Use to update the URL shown to the user.
134 * The redirection itself is handled internally.
135 *
136 * \a job the job that emitted this signal
137 *
138 * \a url the new URL
139 */
140 void redirection(KIO::Job *job, const QUrl &url);
141
142 /*!
143 * Signals a permanent redirection.
144 *
145 * The redirection itself is handled internally.
146 *
147 * \a job the job that emitted this signal
148 *
149 * \a fromUrl the original URL
150 *
151 * \a toUrl the new URL
152 */
153 void permanentRedirection(KIO::Job *job, const QUrl &fromUrl, const QUrl &toUrl);
154
155 /*!
156 * MIME type determined.
157 *
158 * \a job the job that emitted this signal
159 *
160 * \a mimeType the MIME type
161 *
162 * \since 5.78
163 */
164 void mimeTypeFound(KIO::Job *job, const QString &mimeType);
165
166 /*!
167 * \internal
168 *
169 * Emitted if the "put" job found an existing partial file
170 * (in which case offset is the size of that file)
171 * and emitted by the "get" job if it supports resuming to
172 * the given offset - in this case \a offset is unused)
173 */
174 void canResume(KIO::Job *job, KIO::filesize_t offset);
175
176protected Q_SLOTS:
177 /*!
178 *
179 */
180 virtual void slotRedirection(const QUrl &url);
181
182 void slotFinished() override;
183
184 /*!
185 *
186 */
187 virtual void slotData(const QByteArray &data);
188
189 /*!
190 *
191 */
192 virtual void slotDataReq();
193
194 /*!
195 *
196 */
197 virtual void slotMimetype(const QString &mimetype);
198
199protected:
200 KIOCORE_NO_EXPORT explicit TransferJob(TransferJobPrivate &dd);
201
202private:
203 Q_DECLARE_PRIVATE(TransferJob)
204
205 // A FileCopyJob may control one or more TransferJobs
206 friend class FileCopyJob;
207 friend class FileCopyJobPrivate;
208};
209
210/*!
211 * \relates KIO::TransferJob
212 *
213 * Get (means: read).
214 * This is the job to use in order to "download" a file into memory.
215 * The worker emits the data through the data() signal.
216 *
217 * Special case: if you want to determine the MIME type of the file first,
218 * and then read it with the appropriate component, you can still use
219 * a KIO::get() directly. When that job emits the mimeType signal, (which is
220 * guaranteed to happen before it emits any data), put the job on hold:
221 *
222 * \code
223 * job->putOnHold();
224 * \endcode
225 *
226 * and forget about the job. The next time someone does a KIO::get() on the
227 * same URL (even in another process) this job will be resumed. This saves KIO
228 * from doing two requests to the server.
229 *
230 * \a url the URL of the file
231 *
232 * \a reload Reload to reload the file, NoReload if it can be taken from the cache
233 *
234 * \a flags Can be HideProgressInfo here
235 *
236 * Returns the job handling the operation.
237 */
238KIOCORE_EXPORT TransferJob *get(const QUrl &url, LoadType reload = NoReload, JobFlags flags = DefaultFlags);
239
240/*!
241 * \relates KIO::TransferJob
242 *
243 * Put (means: write)
244 *
245 * \a url Where to write data.
246 *
247 * \a permissions May be -1. In this case no special permission mode is set.
248 *
249 * \a flags Can be HideProgressInfo, Overwrite and Resume here.
250 *
251 * \warning Setting Resume means that the data will be appended to \a url if \a url exists.
252 *
253 * Returns the job handling the operation.
254 */
255KIOCORE_EXPORT TransferJob *put(const QUrl &url, int permissions, JobFlags flags = DefaultFlags);
256
257/*!
258 * \relates KIO::TransferJob
259 *
260 * HTTP POST (for form data).
261 *
262 * Example:
263 * \code
264 * job = KIO::http_post( url, postData, KIO::HideProgressInfo );
265 * job->addMetaData("content-type", contentType );
266 * \endcode
267 *
268 * \a postData is the data that you want to send and
269 *
270 * \c contentType is the complete HTTP header line that
271 * specifies the content's MIME type, for example
272 * "Content-Type: text/xml".
273 *
274 * You MUST specify content-type!
275 *
276 * Often \c contentType is
277 * "Content-Type: application/x-www-form-urlencoded" and
278 * the \a postData is then an ASCII string (without null-termination!)
279 * with characters like space, linefeed and percent escaped like %20,
280 * %0A and %25.
281 *
282 * \a url Where to write the data.
283 *
284 * \a postData Encoded data to post.
285 *
286 * \a flags Can be HideProgressInfo here
287 *
288 * Returns the job handling the operation.
289 */
290KIOCORE_EXPORT TransferJob *http_post(const QUrl &url, const QByteArray &postData, JobFlags flags = DefaultFlags);
291
292/*!
293 * \relates KIO::TransferJob
294 *
295 * HTTP POST.
296 *
297 * This function, unlike the one that accepts a QByteArray, accepts an IO device
298 * from which to read the encoded data to be posted to the server in order to
299 * to avoid holding the content of very large post requests, e.g. multimedia file
300 * uploads, in memory.
301 *
302 * \a url Where to write the data.
303 *
304 * \a device the device to read from
305 *
306 * \a size Size of the encoded post data.
307 *
308 * \a flags Can be HideProgressInfo here
309 *
310 * Returns the job handling the operation.
311 *
312 */
313KIOCORE_EXPORT TransferJob *http_post(const QUrl &url, QIODevice *device, qint64 size = -1, JobFlags flags = DefaultFlags);
314
315/*!
316 * \relates KIO::TransferJob
317 *
318 * HTTP DELETE.
319 *
320 * Though this function servers the same purpose as KIO::file_delete, unlike
321 * file_delete it accommodates HTTP specific actions such as redirections.
322 *
323 * \a url url resource to delete.
324 *
325 * \a flags Can be HideProgressInfo here
326 *
327 * Returns the job handling the operation.
328 *
329 * \since 4.7.3
330 */
331KIOCORE_EXPORT TransferJob *http_delete(const QUrl &url, JobFlags flags = DefaultFlags);
332
333}
334
335#endif
336

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