Changeset View
Changeset View
Standalone View
Standalone View
src/core/filejob.h
Show All 39 Lines | |||||
40 | class KIOCORE_EXPORT FileJob : public SimpleJob | 40 | class KIOCORE_EXPORT FileJob : public SimpleJob | ||
41 | { | 41 | { | ||
42 | Q_OBJECT | 42 | Q_OBJECT | ||
43 | 43 | | |||
44 | public: | 44 | public: | ||
45 | ~FileJob(); | 45 | ~FileJob(); | ||
46 | 46 | | |||
47 | /** | 47 | /** | ||
48 | * Read block | 48 | * This function attempts to read up to \p size bytes from the URL passed to | ||
49 | * KIO::open() and returns the bytes received via the data() signal. | ||||
50 | * | ||||
51 | * The read operation commences at the current file offset, and the file | ||||
52 | * offset is incremented by the number of bytes read, but this change in the | ||||
53 | * offset does not result in the position() signal being emitted. | ||||
54 | * | ||||
55 | * If the current file offset is at or past the end of file (i.e. EOD), no | ||||
56 | * bytes are read, and the data() signal returns an empty QByteArray. | ||||
57 | * | ||||
58 | * On error the data() signal is not emitted. To catch errors please connect | ||||
59 | * to the result() signal. | ||||
60 | * | ||||
61 | * @param size the requested amount of data to read | ||||
chinmoyr: Document the methods in SlaveBase as well. | |||||
I've used @see to help me out. Is that enough? I don't want to duplicate the docs, especially if someone changes it and forgets to change the other... feverfew: I've used @see to help me out. Is that enough? I don't want to duplicate the docs, especially… | |||||
dfaure: Makes sense to me. | |||||
49 | * | 62 | * | ||
50 | * The slave emits the data through data(). | | |||
51 | * @param size the requested amount of data | | |||
52 | */ | 63 | */ | ||
53 | void read(KIO::filesize_t size); | 64 | void read(KIO::filesize_t size); | ||
54 | 65 | | |||
55 | /** | 66 | /** | ||
56 | * Write block | 67 | * This function attempts to write all the bytes in \p data to the URL | ||
68 | * passed to KIO::open() and returns the bytes written received via the | ||||
69 | * written() signal. | ||||
70 | * | ||||
71 | * The write operation commences at the current file offset, and the file | ||||
72 | * offset is incremented by the number of bytes read, but this change in the | ||||
73 | * offset does not result in the position() being emitted. | ||||
74 | * | ||||
75 | * On error the written() signal is not emitted. To catch errors please | ||||
76 | * connect to the result() signal. | ||||
57 | * | 77 | * | ||
58 | * @param data the data to write | 78 | * @param data the data to write | ||
59 | */ | 79 | */ | ||
60 | void write(const QByteArray &data); | 80 | void write(const QByteArray &data); | ||
61 | 81 | | |||
62 | /** | 82 | /** | ||
63 | * Close | | |||
64 | * | | |||
65 | * Closes the file-slave | 83 | * Closes the file-slave | ||
84 | * | ||||
85 | * The slave emits close() and result(). | ||||
66 | */ | 86 | */ | ||
67 | void close(); | 87 | void close(); | ||
68 | 88 | | |||
69 | /** | 89 | /** | ||
70 | * Seek | 90 | * Seek | ||
71 | * | 91 | * | ||
72 | * The slave emits position() | 92 | * The slave emits position() on successful seek to the specified \p offset. | ||
93 | * | ||||
94 | * On error the position() signal is not emitted. To catch errors please | ||||
95 | * connect to the result() signal. | ||||
96 | * | ||||
73 | * @param offset the position from start to go to | 97 | * @param offset the position from start to go to | ||
74 | */ | 98 | */ | ||
75 | void seek(KIO::filesize_t offset); | 99 | void seek(KIO::filesize_t offset); | ||
76 | 100 | | |||
77 | /** | 101 | /** | ||
78 | * Size | 102 | * Size | ||
79 | * | 103 | * | ||
80 | * @return the file size | 104 | * @return the file size | ||
81 | */ | 105 | */ | ||
82 | KIO::filesize_t size(); | 106 | KIO::filesize_t size(); | ||
83 | 107 | | |||
84 | Q_SIGNALS: | 108 | Q_SIGNALS: | ||
85 | /** | 109 | /** | ||
86 | * Data from the slave has arrived. | 110 | * Data from the slave has arrived. Emitted after read(). | ||
111 | * | ||||
112 | * Unless a read() request was sent for 0 bytes, End of data (EOD) has been | ||||
Why would someone request reading 0 bytes? That doesn't seem sensible to me. dfaure: Why would someone request reading 0 bytes? That doesn't seem sensible to me. | |||||
Well it can happen and this is technically more correct than saying that an empty QByteArray() is always EOD. In fact, the one of the motivations for this patch was that for KIOFuse, we do read 0 bytes in case the user truncates to 0, otherwise we'd have to have a workaround if it didn't work (for example, before this patch, we'd get both an empty QByteArray() and the error signal...). feverfew: Well it can happen and this is technically more correct than saying that an empty `QByteArray… | |||||
113 | * reached if data.size() == 0 | ||||
114 | * | ||||
dfaure: emitted -> Emitted | |||||
87 | * @param job the job that emitted this signal | 115 | * @param job the job that emitted this signal | ||
88 | * @param data data received from the slave. | 116 | * @param data data received from the slave. | ||
117 | * | ||||
89 | */ | 118 | */ | ||
90 | void data(KIO::Job *job, const QByteArray &data); | 119 | void data(KIO::Job *job, const QByteArray &data); | ||
91 | 120 | | |||
92 | /** | 121 | /** | ||
93 | * Signals the file is a redirection. | 122 | * Signals the file is a redirection. | ||
94 | * Follow this url manually to reach data | 123 | * Follow this url manually to reach data | ||
95 | * @param job the job that emitted this signal | 124 | * @param job the job that emitted this signal | ||
96 | * @param url the new URL | 125 | * @param url the new URL | ||
Show All 10 Lines | |||||
107 | /** | 136 | /** | ||
108 | * File is open, metadata has been determined and the | 137 | * File is open, metadata has been determined and the | ||
109 | * file-slave is ready to receive commands. | 138 | * file-slave is ready to receive commands. | ||
110 | * @param job the job that emitted this signal | 139 | * @param job the job that emitted this signal | ||
111 | */ | 140 | */ | ||
112 | void open(KIO::Job *job); | 141 | void open(KIO::Job *job); | ||
113 | 142 | | |||
114 | /** | 143 | /** | ||
115 | * Bytes written to the file. | 144 | * \p written bytes were written to the file. Emitted after write(). | ||
dfaure: s/;/./ | |||||
116 | * @param job the job that emitted this signal | 145 | * @param job the job that emitted this signal | ||
117 | * @param written bytes written. | 146 | * @param written bytes written. | ||
118 | */ | 147 | */ | ||
119 | void written(KIO::Job *job, KIO::filesize_t written); | 148 | void written(KIO::Job *job, KIO::filesize_t written); | ||
120 | 149 | | |||
121 | /** | 150 | /** | ||
122 | * File is closed and will accept no more commands | 151 | * File is closed and will accept no more commands | ||
123 | * @param job the job that emitted this signal | 152 | * @param job the job that emitted this signal | ||
124 | */ | 153 | */ | ||
125 | void close(KIO::Job *job); | 154 | void close(KIO::Job *job); | ||
126 | 155 | | |||
127 | /** | 156 | /** | ||
128 | * The file has reached this position. Emitted after seek. | 157 | * The file has reached this position. Emitted after seek(). | ||
129 | * @param job the job that emitted this signal | 158 | * @param job the job that emitted this signal | ||
130 | * @param offset the new position | 159 | * @param offset the new position | ||
131 | */ | 160 | */ | ||
132 | void position(KIO::Job *job, KIO::filesize_t offset); | 161 | void position(KIO::Job *job, KIO::filesize_t offset); | ||
133 | 162 | | |||
134 | protected: | 163 | protected: | ||
135 | FileJob(FileJobPrivate &dd); | 164 | FileJob(FileJobPrivate &dd); | ||
136 | 165 | | |||
Show All 9 Lines | 166 | private: | |||
146 | 175 | | |||
147 | Q_DECLARE_PRIVATE(FileJob) | 176 | Q_DECLARE_PRIVATE(FileJob) | ||
148 | }; | 177 | }; | ||
149 | 178 | | |||
150 | /** | 179 | /** | ||
151 | * Open ( random access I/O ) | 180 | * Open ( random access I/O ) | ||
152 | * | 181 | * | ||
153 | * The file-job emits open() when opened | 182 | * The file-job emits open() when opened | ||
183 | * | ||||
184 | * On error the open() signal is not emitted. To catch errors please | ||||
185 | * connect to the result() signal. | ||||
(OK -- that's supposed to be a known fact from the base class KJob, but I'm not opposed to saying it again ;) dfaure: (OK -- that's supposed to be a known fact from the base class KJob, but I'm not opposed to… | |||||
186 | * | ||||
154 | * @param url the URL of the file | 187 | * @param url the URL of the file | ||
155 | * @param mode the access privileges: see \ref OpenMode | 188 | * @param mode the access privileges: see \ref OpenMode | ||
156 | * | 189 | * | ||
157 | * @return The file-handling job. It will never return 0. Errors are handled asynchronously | 190 | * @return The file-handling job. It will never return 0. Errors are handled asynchronously | ||
158 | * (emitted as signals). | 191 | * (emitted as signals). | ||
159 | */ | 192 | */ | ||
160 | KIOCORE_EXPORT FileJob *open(const QUrl &url, QIODevice::OpenMode mode); | 193 | KIOCORE_EXPORT FileJob *open(const QUrl &url, QIODevice::OpenMode mode); | ||
161 | 194 | | |||
162 | } // namespace | 195 | } // namespace | ||
163 | 196 | | |||
164 | #endif | 197 | #endif |
Document the methods in SlaveBase as well.