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

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