KIO

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

KDE's Doxygen guidelines are available online.