1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2006 Allan Sandfeld Jensen <kde@carewolf.com>
4
5 SPDX-License-Identifier: LGPL-2.0-only
6*/
7
8#ifndef KIO_FILEJOB_H
9#define KIO_FILEJOB_H
10
11#include "kiocore_export.h"
12#include "simplejob.h"
13
14namespace KIO
15{
16class FileJobPrivate;
17/**
18 * @class KIO::FileJob filejob.h <KIO/FileJob>
19 *
20 * The file-job is an asynchronous version of normal file handling.
21 * It allows block-wise reading and writing, and allows seeking and truncation. Results are returned through signals.
22 *
23 * Should always be created using KIO::open(const QUrl&, QIODevice::OpenMode).
24 */
25
26class KIOCORE_EXPORT FileJob : public SimpleJob
27{
28 Q_OBJECT
29
30public:
31 ~FileJob() override;
32
33 /**
34 * This function attempts to read up to \p size bytes from the URL passed to
35 * KIO::open() and returns the bytes received via the data() signal.
36 *
37 * The read operation commences at the current file offset, and the file
38 * offset is incremented by the number of bytes read, but this change in the
39 * offset does not result in the position() signal being emitted.
40 *
41 * If the current file offset is at or past the end of file (i.e. EOD), no
42 * bytes are read, and the data() signal returns an empty QByteArray.
43 *
44 * On error the data() signal is not emitted. To catch errors please connect
45 * to the result() signal.
46 *
47 * @param size the requested amount of data to read
48 *
49 */
50 void read(KIO::filesize_t size);
51
52 /**
53 * This function attempts to write all the bytes in \p data to the URL
54 * passed to KIO::open() and returns the bytes written received via the
55 * written() signal.
56 *
57 * The write operation commences at the current file offset, and the file
58 * offset is incremented by the number of bytes read, but this change in the
59 * offset does not result in the position() being emitted.
60 *
61 * On error the written() signal is not emitted. To catch errors please
62 * connect to the result() signal.
63 *
64 * @param data the data to write
65 */
66 void write(const QByteArray &data);
67
68 /**
69 * Closes the file KIO worker.
70 *
71 * The worker emits close() and result().
72 */
73 void close();
74
75 /**
76 * Seek
77 *
78 * The worker emits position() on successful seek to the specified \p offset.
79 *
80 * On error the position() signal is not emitted. To catch errors please
81 * connect to the result() signal.
82 *
83 * @param offset the position from start to go to
84 */
85 void seek(KIO::filesize_t offset);
86
87 /**
88 * Truncate
89 *
90 * The worker emits truncated() on successful truncation to the specified \p length.
91 *
92 * On error the truncated() signal is not emitted. To catch errors please
93 * connect to the result() signal.
94 *
95 * @param length the desired length to truncate to
96 * @since 5.66
97 */
98 void truncate(KIO::filesize_t length);
99
100 /**
101 * Size
102 *
103 * @return the file size
104 */
105 KIO::filesize_t size();
106
107Q_SIGNALS:
108 /**
109 * Data from the worker has arrived. Emitted after read().
110 *
111 * Unless a read() request was sent for 0 bytes, End of data (EOD) has been
112 * reached if data.size() == 0
113 *
114 * @param job the job that emitted this signal
115 * @param data data received from the worker.
116 *
117 */
118 void data(KIO::Job *job, const QByteArray &data);
119
120 /**
121 * Signals the file is a redirection.
122 * Follow this url manually to reach data
123 * @param job the job that emitted this signal
124 * @param url the new URL
125 */
126 void redirection(KIO::Job *job, const QUrl &url);
127
128 /**
129 * MIME type determined.
130 * @param job the job that emitted this signal
131 * @param mimeType the MIME type
132 * @since 5.78
133 */
134 void mimeTypeFound(KIO::Job *job, const QString &mimeType);
135
136 /**
137 * File is open, metadata has been determined and the
138 * file KIO worker is ready to receive commands.
139 * @param job the job that emitted this signal
140 */
141 void open(KIO::Job *job);
142
143 /**
144 * \p written bytes were written to the file. Emitted after write().
145 * @param job the job that emitted this signal
146 * @param written bytes written.
147 */
148 void written(KIO::Job *job, KIO::filesize_t written);
149
150 /**
151 * Signals that the file is closed and will accept no more commands.
152 *
153 * @param job the job that emitted this signal
154 *
155 * @since 5.79
156 */
157 void fileClosed(KIO::Job *job);
158
159 /**
160 * The file has reached this position. Emitted after seek().
161 * @param job the job that emitted this signal
162 * @param offset the new position
163 */
164 void position(KIO::Job *job, KIO::filesize_t offset);
165
166 /**
167 * The file has been truncated to this point. Emitted after truncate().
168 * @param job the job that emitted this signal
169 * @param length the new length of the file
170 * @since 5.66
171 */
172 void truncated(KIO::Job *job, KIO::filesize_t length);
173
174protected:
175 KIOCORE_NO_EXPORT explicit FileJob(FileJobPrivate &dd);
176
177private:
178 Q_DECLARE_PRIVATE(FileJob)
179};
180
181/**
182 * Open ( random access I/O )
183 *
184 * The file-job emits open() when opened
185 *
186 * On error the open() signal is not emitted. To catch errors please
187 * connect to the result() signal.
188 *
189 * @param url the URL of the file
190 * @param mode the access privileges: see \ref OpenMode
191 *
192 * @return The file-handling job. It will never return 0. Errors are handled asynchronously
193 * (emitted as signals).
194 */
195KIOCORE_EXPORT FileJob *open(const QUrl &url, QIODevice::OpenMode mode);
196
197} // namespace
198
199#endif
200

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