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 | |
14 | namespace KIO |
15 | { |
16 | class 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 | |
28 | class KIOCORE_EXPORT FileJob : public SimpleJob |
29 | { |
30 | Q_OBJECT |
31 | |
32 | public: |
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 | |
99 | Q_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 | |
180 | protected: |
181 | KIOCORE_NO_EXPORT explicit FileJob(FileJobPrivate &dd); |
182 | |
183 | private: |
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 | */ |
204 | KIOCORE_EXPORT FileJob *open(const QUrl &url, QIODevice::OpenMode mode); |
205 | |
206 | } // namespace |
207 | |
208 | #endif |
209 | |