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

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