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 | |
14 | namespace KIO |
15 | { |
16 | class 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 | */ |
28 | class KIOCORE_EXPORT TransferJob : public SimpleJob |
29 | { |
30 | Q_OBJECT |
31 | |
32 | public: |
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 | |
98 | protected: |
99 | bool doResume() override; |
100 | |
101 | Q_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 | |
176 | protected 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 | |
199 | protected: |
200 | KIOCORE_NO_EXPORT explicit TransferJob(TransferJobPrivate &dd); |
201 | |
202 | private: |
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 | */ |
238 | KIOCORE_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 | */ |
255 | KIOCORE_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 | */ |
290 | KIOCORE_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 | */ |
313 | KIOCORE_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 | */ |
331 | KIOCORE_EXPORT TransferJob *http_delete(const QUrl &url, JobFlags flags = DefaultFlags); |
332 | |
333 | } |
334 | |
335 | #endif |
336 | |