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
27namespace 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