KIO

transferjob.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2000 Stephan Kulow <[email protected]>
4  SPDX-FileCopyrightText: 2000-2013 David Faure <[email protected]>
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 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  */
25 class KIOCORE_EXPORT TransferJob : public SimpleJob
26 {
27  Q_OBJECT
28 
29 public:
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 #if KIOCORE_ENABLE_DEPRECATED_SINCE(4, 3)
63  /**
64  * When enabled, the job reports the amount of data that has been sent,
65  * instead of the amount of data that has been received.
66  * @see slotProcessedSize
67  * @see slotSpeed
68  * @deprecated since 4.2.1, this is unnecessary (it is always false for
69  * KIO::get and true for KIO::put)
70  */
71  KIOCORE_DEPRECATED_VERSION(4, 3, "No longer needed")
72  void setReportDataSent(bool enabled);
73 #endif
74 
75 #if KIOCORE_ENABLE_DEPRECATED_SINCE(4, 3)
76  /**
77  * Returns whether the job reports the amount of data that has been
78  * sent (true), or whether the job reports the amount of data that
79  * has been received (false)
80  * @deprecated since 4.2.1, this is unnecessary (it is always false for
81  * KIO::get and true for KIO::put)
82  */
83  KIOCORE_DEPRECATED_VERSION(4, 3, "No longer needed")
84  bool reportDataSent() const;
85 #endif
86 
87  /**
88  * Call this in the slot connected to result,
89  * and only after making sure no error happened.
90  * @return the MIME type of the URL
91  */
92  QString mimetype() const;
93 
94  /**
95  * After the job has finished, it will return the final url in case a redirection
96  * has happened.
97  * @return the final url that can be empty in case no redirection has happened.
98  * @since 5.0
99  */
100  QUrl redirectUrl() const;
101 
102  /**
103  * Set the total size of data that we are going to send
104  * in a put job. Helps getting proper progress information.
105  * @since 4.2.1
106  */
107  void setTotalSize(KIO::filesize_t bytes);
108 
109 protected:
110  /**
111  * Called when m_subJob finishes.
112  * @param job the job that finished
113  */
114  void slotResult(KJob *job) override;
115 
116  /**
117  * Reimplemented for internal reasons
118  */
119  bool doResume() override;
120 
121 Q_SIGNALS:
122  /**
123  * Data from the worker has arrived.
124  * @param job the job that emitted this signal
125  * @param data data received from the worker.
126  *
127  * End of data (EOD) has been reached if data.size() == 0, however, you
128  * should not be certain of data.size() == 0 ever happening (e.g. in case
129  * of an error), so you should rely on result() instead.
130  */
131  void data(KIO::Job *job, const QByteArray &data);
132 
133  /**
134  * Request for data.
135  * Please note, that you shouldn't put too large chunks
136  * of data in it as this requires copies within the frame
137  * work, so you should rather split the data you want
138  * to pass here in reasonable chunks (about 1MB maximum)
139  *
140  * @param job the job that emitted this signal
141  * @param data buffer to fill with data to send to the
142  * worker. An empty buffer indicates end of data. (EOD)
143  */
144  void dataReq(KIO::Job *job, QByteArray &data);
145 
146  /**
147  * Signals a redirection.
148  * Use to update the URL shown to the user.
149  * The redirection itself is handled internally.
150  * @param job the job that emitted this signal
151  * @param url the new URL
152  */
153  void redirection(KIO::Job *job, const QUrl &url);
154 
155  /**
156  * Signals a permanent redirection.
157  * The redirection itself is handled internally.
158  * @param job the job that emitted this signal
159  * @param fromUrl the original URL
160  * @param toUrl the new URL
161  */
162  void permanentRedirection(KIO::Job *job, const QUrl &fromUrl, const QUrl &toUrl);
163 
164 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 78)
165  /**
166  * MIME type determined.
167  * @param job the job that emitted this signal
168  * @param mimeType the MIME type
169  * @deprecated Since 5.78, use mimeTypeFound(KIO::Job *, const QString &)
170  */
171  KIOCORE_DEPRECATED_VERSION(5, 78, "Use KIO::TransferJob::mimeTypeFound(KIO::Job *, const QString &)")
172  void mimetype(KIO::Job *job, const QString &mimeType); // clazy:exclude=overloaded-signal
173 #endif
174 
175  /**
176  * MIME type determined.
177  * @param job the job that emitted this signal
178  * @param mimeType the MIME type
179  * @since 5.78
180  */
181  void mimeTypeFound(KIO::Job *job, const QString &mimeType);
182 
183  /**
184  * @internal
185  * Emitted if the "put" job found an existing partial file
186  * (in which case offset is the size of that file)
187  * and emitted by the "get" job if it supports resuming to
188  * the given offset - in this case @p offset is unused)
189  */
190  void canResume(KIO::Job *job, KIO::filesize_t offset);
191 
192 protected Q_SLOTS:
193  virtual void slotRedirection(const QUrl &url);
194  void slotFinished() override;
195  virtual void slotData(const QByteArray &data);
196  virtual void slotDataReq();
197  virtual void slotMimetype(const QString &mimetype);
198 #if KIOCORE_BUILD_DEPRECATED_SINCE(5, 101) // override no longer needed
199  void slotMetaData(const KIO::MetaData &_metaData) override;
200 #endif
201 
202 protected:
203  TransferJob(TransferJobPrivate &dd);
204 
205 private:
206  Q_DECLARE_PRIVATE(TransferJob)
207 
208  // A FileCopyJob may control one or more TransferJobs
209  friend class FileCopyJob;
210  friend class FileCopyJobPrivate;
211 };
212 
213 /**
214  * Get (means: read).
215  * This is the job to use in order to "download" a file into memory.
216  * The worker emits the data through the data() signal.
217  *
218  * Special case: if you want to determine the MIME type of the file first,
219  * and then read it with the appropriate component, you can still use
220  * a KIO::get() directly. When that job emits the mimeType signal, (which is
221  * guaranteed to happen before it emits any data), put the job on hold:
222  *
223  * @code
224  * job->putOnHold();
225  * KIO::Scheduler::publishSlaveOnHold();
226  * @endcode
227  *
228  * and forget about the job. The next time someone does a KIO::get() on the
229  * same URL (even in another process) this job will be resumed. This saves KIO
230  * from doing two requests to the server.
231  *
232  * @param url the URL of the file
233  * @param reload Reload to reload the file, NoReload if it can be taken from the cache
234  * @param flags Can be HideProgressInfo here
235  * @return the job handling the operation.
236  */
237 KIOCORE_EXPORT TransferJob *get(const QUrl &url, LoadType reload = NoReload, JobFlags flags = DefaultFlags);
238 
239 /**
240  * Put (means: write)
241  *
242  * @param url Where to write data.
243  * @param permissions May be -1. In this case no special permission mode is set.
244  * @param flags Can be HideProgressInfo, Overwrite and Resume here. WARNING:
245  * Setting Resume means that the data will be appended to @p dest if @p dest exists.
246  * @return the job handling the operation.
247  * @see multi_get()
248  */
249 KIOCORE_EXPORT TransferJob *put(const QUrl &url, int permissions, JobFlags flags = DefaultFlags);
250 
251 /**
252  * HTTP POST (for form data).
253  *
254  * Example:
255  * \code
256  * job = KIO::http_post( url, postData, KIO::HideProgressInfo );
257  * job->addMetaData("content-type", contentType );
258  * job->addMetaData("referrer", referrerURL);
259  * \endcode
260  *
261  * @p postData is the data that you want to send and
262  * @p contentType is the complete HTTP header line that
263  * specifies the content's MIME type, for example
264  * "Content-Type: text/xml".
265  *
266  * You MUST specify content-type!
267  *
268  * Often @p contentType is
269  * "Content-Type: application/x-www-form-urlencoded" and
270  * the @p postData is then an ASCII string (without null-termination!)
271  * with characters like space, linefeed and percent escaped like %20,
272  * %0A and %25.
273  *
274  * @param url Where to write the data.
275  * @param postData Encoded data to post.
276  * @param flags Can be HideProgressInfo here
277  * @return the job handling the operation.
278  */
279 KIOCORE_EXPORT TransferJob *http_post(const QUrl &url, const QByteArray &postData, JobFlags flags = DefaultFlags);
280 
281 /**
282  * HTTP POST.
283  *
284  * This function, unlike the one that accepts a QByteArray, accepts an IO device
285  * from which to read the encoded data to be posted to the server in order to
286  * to avoid holding the content of very large post requests, e.g. multimedia file
287  * uploads, in memory.
288  *
289  * @param url Where to write the data.
290  * @param device the device to read from
291  * @param size Size of the encoded post data.
292  * @param flags Can be HideProgressInfo here
293  * @return the job handling the operation.
294  *
295  * @since 4.7
296  */
297 KIOCORE_EXPORT TransferJob *http_post(const QUrl &url, QIODevice *device, qint64 size = -1, JobFlags flags = DefaultFlags);
298 
299 /**
300  * HTTP DELETE.
301  *
302  * Though this function servers the same purpose as KIO::file_delete, unlike
303  * file_delete it accommodates HTTP specific actions such as redirections.
304  *
305  * @param url url resource to delete.
306  * @param flags Can be HideProgressInfo here
307  * @return the job handling the operation.
308  *
309  * @since 4.7.3
310  */
311 KIOCORE_EXPORT TransferJob *http_delete(const QUrl &url, JobFlags flags = DefaultFlags);
312 
313 }
314 
315 #endif
KIOCORE_EXPORT TransferJob * http_delete(const QUrl &url, JobFlags flags=DefaultFlags)
HTTP DELETE.
KIOCORE_EXPORT TransferJob * put(const QUrl &url, int permissions, JobFlags flags=DefaultFlags)
Put (means: write)
KIOCORE_EXPORT SimpleJob * setModificationTime(const QUrl &url, const QDateTime &mtime)
Changes the modification time on a file or directory.
Definition: simplejob.cpp:356
qulonglong filesize_t
64-bit file size
Definition: global.h:39
KIOCORE_EXPORT TransferJob * get(const QUrl &url, LoadType reload=NoReload, JobFlags flags=DefaultFlags)
Get (means: read).
@ DefaultFlags
Show the progress info GUI, no Resume and no Overwrite.
Definition: job_base.h:269
KIOCORE_EXPORT MimetypeJob * mimetype(const QUrl &url, JobFlags flags=DefaultFlags)
Find MIME type for one file or directory.
Definition: mimetypejob.cpp:85
A namespace for KIO globals.
KIOCORE_EXPORT TransferJob * http_post(const QUrl &url, const QByteArray &postData, JobFlags flags=DefaultFlags)
HTTP POST (for form data).
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Feb 6 2023 04:00:02 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.