1 | // -*- c++ -*- |
2 | /* This file is part of the KDE libraries |
3 | Copyright (C) 2000 Stephan Kulow <coolo@kde.org> |
4 | 2000-2009 David Faure <faure@kde.org> |
5 | |
6 | This library is free software; you can redistribute it and/or |
7 | modify it under the terms of the GNU Library General Public |
8 | License as published by the Free Software Foundation; either |
9 | version 2 of the License, or (at your option) any later version. |
10 | |
11 | This library is distributed in the hope that it will be useful, |
12 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
14 | Library General Public License for more details. |
15 | |
16 | You should have received a copy of the GNU Library General Public License |
17 | along with this library; see the file COPYING.LIB. If not, write to |
18 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
19 | Boston, MA 02110-1301, USA. |
20 | */ |
21 | |
22 | #ifndef KIO_JOB_H |
23 | #define KIO_JOB_H |
24 | |
25 | #include <kio/jobclasses.h> |
26 | |
27 | namespace KIO { |
28 | |
29 | enum LoadType { Reload, NoReload }; |
30 | |
31 | class FileJob; |
32 | |
33 | /** |
34 | * Creates a single directory. |
35 | * |
36 | * |
37 | * |
38 | * |
39 | * @param url The URL of the directory to create. |
40 | * @param permissions The permissions to set after creating the |
41 | * directory (unix-style), -1 for default permissions. |
42 | * @return A pointer to the job handling the operation. |
43 | */ |
44 | KIO_EXPORT SimpleJob * mkdir( const KUrl& url, int permissions = -1 ); // TODO KDE5: return a MkdirJob and make that class public again |
45 | |
46 | /** |
47 | * Removes a single directory. |
48 | * |
49 | * The directory is assumed to be empty. |
50 | * The job will fail if the directory is not empty. |
51 | * Use KIO::del() (DeleteJob) to delete non-empty directories. |
52 | * |
53 | * @param url The URL of the directory to remove. |
54 | * @return A pointer to the job handling the operation. |
55 | */ |
56 | KIO_EXPORT SimpleJob * rmdir( const KUrl& url ); |
57 | |
58 | /** |
59 | * Changes permissions on a file or directory. |
60 | * See the other chmod in chmodjob.h for changing many files |
61 | * or directories. |
62 | * |
63 | * @param url The URL of file or directory. |
64 | * @param permissions The permissions to set. |
65 | * @return the job handling the operation. |
66 | */ |
67 | KIO_EXPORT SimpleJob * chmod( const KUrl& url, int permissions ); |
68 | |
69 | /** |
70 | * Changes ownership and group of a file or directory. |
71 | * |
72 | * @param url The URL of file or directory. |
73 | * @param owner the new owner |
74 | * @param group the new group |
75 | * @return the job handling the operation. |
76 | */ |
77 | KIO_EXPORT SimpleJob * chown( const KUrl& url, const QString& owner, const QString& group ); |
78 | |
79 | /** |
80 | * Changes the modification time on a file or directory. |
81 | * |
82 | * @param url The URL of file or directory. |
83 | * @param permissions The permissions to set. |
84 | * @return the job handling the operation. |
85 | */ |
86 | KIO_EXPORT SimpleJob *setModificationTime( const KUrl& url, const QDateTime& mtime ); |
87 | |
88 | |
89 | /** |
90 | * Rename a file or directory. |
91 | * Warning: this operation fails if a direct renaming is not |
92 | * possible (like with files or dirs on separate partitions) |
93 | * Use move or file_move in this case. |
94 | * |
95 | * @param src The original URL |
96 | * @param dest The final URL |
97 | * @param flags Can be Overwrite here |
98 | * @return the job handling the operation. |
99 | */ |
100 | KIO_EXPORT SimpleJob * rename( const KUrl& src, const KUrl & dest, JobFlags flags = DefaultFlags ); |
101 | |
102 | /** |
103 | * Create or move a symlink. |
104 | * This is the lowlevel operation, similar to file_copy and file_move. |
105 | * It doesn't do any check (other than those the slave does) |
106 | * and it doesn't show rename and skip dialogs - use KIO::link for that. |
107 | * @param target The string that will become the "target" of the link (can be relative) |
108 | * @param dest The symlink to create. |
109 | * @param flags Can be Overwrite and HideProgressInfo |
110 | * @return the job handling the operation. |
111 | */ |
112 | KIO_EXPORT SimpleJob * symlink( const QString & target, const KUrl& dest, JobFlags flags = DefaultFlags ); |
113 | |
114 | /** |
115 | * Execute any command that is specific to one slave (protocol). |
116 | * |
117 | * Examples are : HTTP POST, mount and unmount (kio_file) |
118 | * |
119 | * @param url The URL isn't passed to the slave, but is used to know |
120 | * which slave to send it to :-) |
121 | * @param data Packed data. The meaning is completely dependent on the |
122 | * slave, but usually starts with an int for the command number. |
123 | * @param flags Can be HideProgressInfo here |
124 | * @return the job handling the operation. |
125 | */ |
126 | KIO_EXPORT SimpleJob * special( const KUrl& url, const QByteArray & data, JobFlags flags = DefaultFlags ); |
127 | |
128 | /** |
129 | * Mount filesystem. |
130 | * |
131 | * Special job for @p kio_file. |
132 | * |
133 | * @param ro Mount read-only if @p true. |
134 | * @param fstype File system type (e.g. "ext2", can be empty). |
135 | * @param dev Device (e.g. /dev/sda0). |
136 | * @param point Mount point, can be @p null. |
137 | * @param flags Can be HideProgressInfo here |
138 | * @return the job handling the operation. |
139 | */ |
140 | KIO_EXPORT SimpleJob *mount( bool ro, const QByteArray& fstype, const QString& dev, const QString& point, JobFlags flags = DefaultFlags ); |
141 | |
142 | /** |
143 | * Unmount filesystem. |
144 | * |
145 | * Special job for @p kio_file. |
146 | * |
147 | * @param point Point to unmount. |
148 | * @param flags Can be HideProgressInfo here |
149 | * @return the job handling the operation. |
150 | */ |
151 | KIO_EXPORT SimpleJob *unmount( const QString & point, JobFlags flags = DefaultFlags ); |
152 | |
153 | /** |
154 | * HTTP cache update |
155 | * |
156 | * @param url Url to update, protocol must be "http". |
157 | * @param no_cache If true, cache entry for @p url is deleted. |
158 | * @param expireDate Local machine time indicating when the entry is |
159 | * supposed to expire. |
160 | * @return the job handling the operation. |
161 | */ |
162 | KIO_EXPORT SimpleJob *http_update_cache( const KUrl& url, bool no_cache, time_t expireDate); |
163 | |
164 | /** |
165 | * Find all details for one file or directory. |
166 | * |
167 | * @param url the URL of the file |
168 | * @param flags Can be HideProgressInfo here |
169 | * @return the job handling the operation. |
170 | */ |
171 | KIO_EXPORT StatJob * stat( const KUrl& url, JobFlags flags = DefaultFlags ); |
172 | /** |
173 | * Find all details for one file or directory. |
174 | * This version of the call includes two additional booleans, @p sideIsSource and @p details. |
175 | * |
176 | * @param url the URL of the file |
177 | * @param side is SourceSide when stating a source file (we will do a get on it if |
178 | * the stat works) and DestinationSide when stating a destination file (target of a copy). |
179 | * The reason for this parameter is that in some cases the kioslave might not |
180 | * be able to determine a file's existence (e.g. HTTP doesn't allow it, FTP |
181 | * has issues with case-sensitivity on some systems). |
182 | * When the slave can't reliably determine the existence of a file, it will: |
183 | * @li be optimistic if SourceSide, i.e. it will assume the file exists, |
184 | * and if it doesn't this will appear when actually trying to download it |
185 | * @li be pessimistic if DestinationSide, i.e. it will assume the file |
186 | * doesn't exist, to prevent showing "about to overwrite" errors to the user. |
187 | * If you simply want to check for existence without downloading/uploading afterwards, |
188 | * then you should use DestinationSide. |
189 | * |
190 | * @param details selects the level of details we want. |
191 | * By default this is 2 (all details wanted, including modification time, size, etc.), |
192 | * setDetails(1) is used when deleting: we don't need all the information if it takes |
193 | * too much time, no need to follow symlinks etc. |
194 | * setDetails(0) is used for very simple probing: we'll only get the answer |
195 | * "it's a file or a directory or a symlink, or it doesn't exist". This is used by KRun and DeleteJob. |
196 | * @param flags Can be HideProgressInfo here |
197 | * @return the job handling the operation. |
198 | */ |
199 | KIO_EXPORT StatJob * stat( const KUrl& url, KIO::StatJob::StatSide side, |
200 | short int details, JobFlags flags = DefaultFlags ); |
201 | /** |
202 | * Find all details for one file or directory. |
203 | * This version of the call includes two additional booleans, @p sideIsSource and @p details. |
204 | * |
205 | * @param url the URL of the file |
206 | * @param sideIsSource is true when stating a source file (we will do a get on it if |
207 | * the stat works) and false when stating a destination file (target of a copy). |
208 | * The reason for this parameter is that in some cases the kioslave might not |
209 | * be able to determine a file's existence (e.g. HTTP doesn't allow it, FTP |
210 | * has issues with case-sensitivity on some systems). |
211 | * When the slave can't reliably determine the existence of a file, it will: |
212 | * @li be optimistic if sideIsSource=true, i.e. it will assume the file exists, |
213 | * and if it doesn't this will appear when actually trying to download it |
214 | * @li be pessimistic if sideIsSource=false, i.e. it will assume the file |
215 | * doesn't exist, to prevent showing "about to overwrite" errors to the user. |
216 | * If you simply want to check for existence without downloading/uploading afterwards, |
217 | * then you should use sideIsSource=false. |
218 | * |
219 | * @param details selects the level of details we want. |
220 | * By default this is 2 (all details wanted, including modification time, size, etc.), |
221 | * setDetails(1) is used when deleting: we don't need all the information if it takes |
222 | * too much time, no need to follow symlinks etc. |
223 | * setDetails(0) is used for very simple probing: we'll only get the answer |
224 | * "it's a file or a directory, or it doesn't exist". This is used by KRun. |
225 | * @param flags Can be HideProgressInfo here |
226 | * @return the job handling the operation. |
227 | */ |
228 | #ifndef KDE_NO_DEPRECATED |
229 | KIO_EXPORT_DEPRECATED StatJob * stat( const KUrl& url, bool sideIsSource, |
230 | short int details, JobFlags flags = DefaultFlags ); |
231 | #endif |
232 | |
233 | /** |
234 | * Get (a.k.a. read). |
235 | * This is the job to use in order to "download" a file into memory. |
236 | * The slave emits the data through the data() signal. |
237 | * |
238 | * Special case: if you want to determine the mimetype of the file first, |
239 | * and then read it with the appropriate component, you can still use |
240 | * a KIO::get() directly. When that job emits the mimeType signal, (which is |
241 | * guaranteed to happen before it emits any data), put the job on hold: |
242 | * <code> |
243 | * job->putOnHold(); |
244 | * KIO::Scheduler::publishSlaveOnHold(); |
245 | * </code> |
246 | * and forget about the job. The next time someone does a KIO::get() on the |
247 | * same URL (even in another process) this job will be resumed. This saves KIO |
248 | * from doing two requests to the server. |
249 | * |
250 | * @param url the URL of the file |
251 | * @param reload: Reload to reload the file, NoReload if it can be taken from the cache |
252 | * @param flags Can be HideProgressInfo here |
253 | * @return the job handling the operation. |
254 | */ |
255 | KIO_EXPORT TransferJob *get( const KUrl& url, LoadType reload = NoReload, JobFlags flags = DefaultFlags ); |
256 | |
257 | /** |
258 | * Open ( random access I/O ) |
259 | * |
260 | * The file-job emits open() when opened |
261 | * @param url the URL of the file |
262 | * @param mode the access privileges: see \ref OpenMode |
263 | * |
264 | * @return The file-handling job. It will never return 0. Errors are handled asynchronously |
265 | * (emitted as signals). |
266 | */ |
267 | KIO_EXPORT FileJob *open(const KUrl &url, QIODevice::OpenMode mode); |
268 | |
269 | /** |
270 | * Put (a.k.a. write) |
271 | * |
272 | * @param url Where to write data. |
273 | * @param permissions May be -1. In this case no special permission mode is set. |
274 | * @param flags Can be HideProgressInfo, Overwrite and Resume here. WARNING: |
275 | * Setting Resume means that the data will be appended to @p dest if @p dest exists. |
276 | * @return the job handling the operation. |
277 | * @see multi_get() |
278 | */ |
279 | KIO_EXPORT TransferJob *put( const KUrl& url, int permissions, |
280 | JobFlags flags = DefaultFlags ); |
281 | |
282 | /** |
283 | * HTTP POST (for form data). |
284 | * |
285 | * Example: |
286 | * \code |
287 | * job = KIO::http_post( url, postData, KIO::HideProgressInfo); |
288 | * job->addMetaData("content-type", contentType); |
289 | * job->addMetaData("referrer", referrerURL); |
290 | * \endcode |
291 | * |
292 | * You MUST specify the "content-type" meta data. It is mandatory. |
293 | * It can be preceeded with the optional text "Content-Type:", e.g. |
294 | * "Content-Type: application/x-www-form-urlencoded". |
295 | * |
296 | * @p postData is usually an encoded ASCII string (without null-termination!) |
297 | * and can contain spaces, linefeeds and percent escaped characters such as %20, |
298 | * %0A and %25. |
299 | * |
300 | * @param url Where to write the data. |
301 | * @param postData Encoded data to post. |
302 | * @param flags Can be HideProgressInfo here |
303 | * @return the job handling the operation. |
304 | */ |
305 | KIO_EXPORT TransferJob *http_post( const KUrl& url, const QByteArray &postData, |
306 | JobFlags flags = DefaultFlags ); |
307 | |
308 | /** |
309 | * HTTP POST. |
310 | * |
311 | * This function, unlike the one that accepts a QByteArray, accepts an IO device |
312 | * from which to read the encoded data to be posted to the server in order to |
313 | * to avoid holding the content of very large post requests, e.g. multimedia file |
314 | * uploads, in memory. |
315 | * |
316 | * Example: |
317 | * \code |
318 | * job = KIO::http_post( url, device, device->size(), KIO::HideProgressInfo); |
319 | * job->addMetaData("content-type", contentType); |
320 | * job->addMetaData("referrer", referrerURL); |
321 | * \endcode |
322 | * |
323 | * You MUST specify the "content-type" meta data. It is mandatory. |
324 | * It can be preceeded with the optional text "Content-Type:", e.g. |
325 | * "Content-Type: application/x-www-form-urlencoded". |
326 | * |
327 | * @param url Where to write the data. |
328 | * @param device the QIODevice that provides the encoded post data. |
329 | * @param size Size of the encoded post data. |
330 | * @param flags Can be HideProgressInfo here |
331 | * @return the job handling the operation. |
332 | * |
333 | * @since 4.7 |
334 | */ |
335 | KIO_EXPORT TransferJob *http_post( const KUrl& url, QIODevice* device, |
336 | qint64 size = -1, JobFlags flags = DefaultFlags ); |
337 | |
338 | /** |
339 | * HTTP DELETE. |
340 | * |
341 | * Though this function servers the same purpose as KIO::file_delete, unlike |
342 | * file_delete it accomodates HTTP sepecific actions such as redirections. |
343 | * |
344 | * @param src url resource to delete. |
345 | * @param flags Can be HideProgressInfo here |
346 | * @return the job handling the operation. |
347 | * |
348 | * @since 4.7.3 |
349 | */ |
350 | KIO_EXPORT TransferJob *http_delete( const KUrl& url, JobFlags flags = DefaultFlags ); |
351 | |
352 | /** |
353 | * Get (a.k.a. read), into a single QByteArray. |
354 | * @see StoredTransferJob |
355 | * |
356 | * @param url the URL of the file |
357 | * @param reload: Reload to reload the file, NoReload if it can be taken from the cache |
358 | * @param flags Can be HideProgressInfo here |
359 | * @return the job handling the operation. |
360 | */ |
361 | KIO_EXPORT StoredTransferJob *storedGet( const KUrl& url, LoadType reload = NoReload, JobFlags flags = DefaultFlags ); |
362 | |
363 | /** |
364 | * Put (a.k.a. write) data from a single QByteArray. |
365 | * @see StoredTransferJob |
366 | * |
367 | * @param arr The data to write |
368 | * @param url Where to write data. |
369 | * @param permissions May be -1. In this case no special permission mode is set. |
370 | * @param flags Can be HideProgressInfo, Overwrite and Resume here. WARNING: |
371 | * Setting Resume means that the data will be appended to @p dest if @p dest exists. |
372 | * @return the job handling the operation. |
373 | */ |
374 | KIO_EXPORT StoredTransferJob *storedPut( const QByteArray& arr, const KUrl& url, int permissions, |
375 | JobFlags flags = DefaultFlags ); |
376 | |
377 | /** |
378 | * HTTP POST (a.k.a. write) data from a single QByteArray. |
379 | * @see StoredTransferJob |
380 | * |
381 | * @param arr The data to write |
382 | * @param url Where to write data. |
383 | * @param flags Can be HideProgressInfo here. |
384 | * @return the job handling the operation. |
385 | * @since 4.2 |
386 | */ |
387 | KIO_EXPORT StoredTransferJob *storedHttpPost( const QByteArray& arr, const KUrl& url, |
388 | JobFlags flags = DefaultFlags ); |
389 | /** |
390 | * HTTP POST (a.k.a. write) data from the given IO device. |
391 | * @see StoredTransferJob |
392 | * |
393 | * @param device Device from which the encoded data to be posted is read. |
394 | * @param url Where to write data. |
395 | * @param size Size of the encoded data to be posted. |
396 | * @param flags Can be HideProgressInfo here. |
397 | * @return the job handling the operation. |
398 | * |
399 | * @since 4.7 |
400 | */ |
401 | KIO_EXPORT StoredTransferJob *storedHttpPost( QIODevice* device, const KUrl& url, |
402 | qint64 size = -1, JobFlags flags = DefaultFlags ); |
403 | |
404 | /** |
405 | * Creates a new multiple get job. |
406 | * |
407 | * @param id the id of the get operation |
408 | * @param url the URL of the file |
409 | * @param metaData the MetaData associated with the file |
410 | * |
411 | * @return the job handling the operation. |
412 | * @see get() |
413 | */ |
414 | KIO_EXPORT MultiGetJob *multi_get( long id, const KUrl &url, const MetaData &metaData); |
415 | |
416 | /** |
417 | * Find mimetype for one file or directory. |
418 | * |
419 | * If you are going to download the file right after determining its mimetype, |
420 | * then don't use this, prefer using a KIO::get() job instead. See the note |
421 | * about putting the job on hold once the mimetype is determined. |
422 | * |
423 | * @param url the URL of the file |
424 | * @param flags Can be HideProgressInfo here |
425 | * @return the job handling the operation. |
426 | */ |
427 | KIO_EXPORT MimetypeJob * mimetype( const KUrl& url, |
428 | JobFlags flags = DefaultFlags ); |
429 | |
430 | /** |
431 | * Copy a single file. |
432 | * |
433 | * Uses either SlaveBase::copy() if the slave supports that |
434 | * or get() and put() otherwise. |
435 | * @param src Where to get the file. |
436 | * @param dest Where to put the file. |
437 | * @param permissions May be -1. In this case no special permission mode is set. |
438 | * @param flags Can be HideProgressInfo, Overwrite and Resume here. WARNING: |
439 | * Setting Resume means that the data will be appended to @p dest if @p dest exists. |
440 | * @return the job handling the operation. |
441 | */ |
442 | KIO_EXPORT FileCopyJob *file_copy( const KUrl& src, const KUrl& dest, int permissions=-1, |
443 | JobFlags flags = DefaultFlags ); |
444 | |
445 | /** |
446 | * Overload for catching code mistakes. Do NOT call this method (it is not implemented), |
447 | * insert a value for permissions (-1 by default) before the JobFlags. |
448 | * @since 4.5 |
449 | */ |
450 | FileCopyJob *file_copy( const KUrl& src, const KUrl& dest, JobFlags flags ); // not implemented - on purpose. |
451 | |
452 | /** |
453 | * Move a single file. |
454 | * |
455 | * Use either SlaveBase::rename() if the slave supports that, |
456 | * or copy() and del() otherwise, or eventually get() & put() & del() |
457 | * @param src Where to get the file. |
458 | * @param dest Where to put the file. |
459 | * @param permissions May be -1. In this case no special permission mode is set. |
460 | * @param flags Can be HideProgressInfo, Overwrite and Resume here. WARNING: |
461 | * Setting Resume means that the data will be appended to @p dest if @p dest exists. |
462 | * @return the job handling the operation. |
463 | */ |
464 | KIO_EXPORT FileCopyJob *file_move( const KUrl& src, const KUrl& dest, int permissions=-1, |
465 | JobFlags flags = DefaultFlags ); |
466 | |
467 | /** |
468 | * Overload for catching code mistakes. Do NOT call this method (it is not implemented), |
469 | * insert a value for permissions (-1 by default) before the JobFlags. |
470 | * @since 4.3 |
471 | */ |
472 | FileCopyJob *file_move( const KUrl& src, const KUrl& dest, JobFlags flags ); // not implemented - on purpose. |
473 | |
474 | |
475 | /** |
476 | * Delete a single file. |
477 | * |
478 | * @param src File to delete. |
479 | * @param flags Can be HideProgressInfo here |
480 | * @return the job handling the operation. |
481 | */ |
482 | KIO_EXPORT SimpleJob *file_delete( const KUrl& src, JobFlags flags = DefaultFlags ); |
483 | |
484 | /** |
485 | * List the contents of @p url, which is assumed to be a directory. |
486 | * |
487 | * "." and ".." are returned, filter them out if you don't want them. |
488 | * |
489 | * |
490 | * @param url the url of the directory |
491 | * @param flags Can be HideProgressInfo here |
492 | * @param includeHidden true for all files, false to cull out UNIX hidden |
493 | * files/dirs (whose names start with dot) |
494 | * @return the job handling the operation. |
495 | */ |
496 | KIO_EXPORT ListJob *listDir( const KUrl& url, JobFlags flags = DefaultFlags, |
497 | bool includeHidden = true ); |
498 | |
499 | /** |
500 | * The same as the previous method, but recurses subdirectories. |
501 | * Directory links are not followed. |
502 | * |
503 | * "." and ".." are returned but only for the toplevel directory. |
504 | * Filter them out if you don't want them. |
505 | * |
506 | * @param url the url of the directory |
507 | * @param flags Can be HideProgressInfo here |
508 | * @param includeHidden true for all files, false to cull out UNIX hidden |
509 | * files/dirs (whose names start with dot) |
510 | * @return the job handling the operation. |
511 | */ |
512 | KIO_EXPORT ListJob *listRecursive( const KUrl& url, JobFlags flags = DefaultFlags, |
513 | bool includeHidden = true ); |
514 | |
515 | /** |
516 | * Tries to map a local URL for the given URL, using a KIO job. |
517 | * |
518 | * Starts a (stat) job for determining the "most local URL" for a given URL. |
519 | * Retrieve the result with StatJob::mostLocalUrl in the result slot. |
520 | * @param url The URL we are testing. |
521 | * \since 4.4 |
522 | */ |
523 | KIO_EXPORT StatJob* mostLocalUrl(const KUrl& url, JobFlags flags = DefaultFlags); |
524 | |
525 | } |
526 | |
527 | #endif |
528 | |
529 | |