kio/kio/job.h

   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 );
  45
  46     /**
  47      * Removes a single directory.
  48      *
  49      * The directory is assumed to be empty.
  50      *
  51      *
  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     KIO_EXPORT_DEPRECATED StatJob * stat( const KUrl& url, bool sideIsSource,
 229                                           short int details, JobFlags flags = DefaultFlags );
 230
 231     /**
 232      * Get (a.k.a. read).
 233      *
 234      * The slave emits the data through data().
 235      * @param url the URL of the file
 236      * @param reload: Reload to reload the file, NoReload if it can be taken from the cache
 237      * @param flags Can be HideProgressInfo here
 238      * @return the job handling the operation.
 239      */
 240     KIO_EXPORT TransferJob *get( const KUrl& url, LoadType reload = NoReload, JobFlags flags = DefaultFlags );
 241
 242     /**
 243      * Open ( random access I/O )
 244      *
 245      * The file-job emits open() when opened
 246      * @param url the URL of the file
 247      * @param mode the access privileges: see \ref OpenMode
 248      *
 249      * @return The file-handling job. It will never return 0. Errors are handled asynchronously
 250      * (emitted as signals).
 251      */
 252     KIO_EXPORT FileJob *open(const KUrl &url, QIODevice::OpenMode mode);
 253
 254     /**
 255      * Put (a.k.a. write)
 256      *
 257      * @param url Where to write data.
 258      * @param permissions May be -1. In this case no special permission mode is set.
 259      * @param flags Can be HideProgressInfo, Overwrite and Resume here. WARNING:
 260      * Setting Resume means that the data will be appended to @p dest if @p dest exists.
 261      * @return the job handling the operation.
 262      * @see multi_get()
 263      */
 264     KIO_EXPORT TransferJob *put( const KUrl& url, int permissions,
 265                                  JobFlags flags = DefaultFlags );
 266
 267     /**
 268      * HTTP POST (for form data).
 269      *
 270      * Example:
 271      * \code
 272      *    job = KIO::http_post( url, postData, KIO::HideProgressInfo );
 273      *    job->addMetaData("content-type", contentType );
 274      *    job->addMetaData("referrer", referrerURL);
 275      * \endcode
 276      *
 277      * @p postData is the data that you want to send and
 278      * @p contentType is the complete HTTP header line that
 279      * specifies the content's MIME type, for example
 280      * "Content-Type: text/xml".
 281      *
 282      * You MUST specify content-type!
 283      *
 284      * Often @p contentType is
 285      * "Content-Type: application/x-www-form-urlencoded" and
 286      * the @p postData is then an ASCII string (without null-termination!)
 287      * with characters like space, linefeed and percent escaped like %20,
 288      * %0A and %25.
 289      *
 290      * @param url Where to write the data.
 291      * @param postData Encoded data to post.
 292      * @param flags Can be HideProgressInfo here
 293      * @return the job handling the operation.
 294      */
 295     KIO_EXPORT TransferJob *http_post( const KUrl& url, const QByteArray &postData,
 296                                        JobFlags flags = DefaultFlags );
 297
 298     /**
 299      * Get (a.k.a. read), into a single QByteArray.
 300      * @see StoredTransferJob
 301      *
 302      * @param url the URL of the file
 303      * @param reload: Reload to reload the file, NoReload if it can be taken from the cache
 304      * @param flags Can be HideProgressInfo here
 305      * @return the job handling the operation.
 306      */
 307     KIO_EXPORT StoredTransferJob *storedGet( const KUrl& url, LoadType reload = NoReload, JobFlags flags = DefaultFlags );
 308
 309     /**
 310      * Put (a.k.a. write) data from a single QByteArray.
 311      * @see StoredTransferJob
 312      *
 313      * @param arr The data to write
 314      * @param url Where to write data.
 315      * @param permissions May be -1. In this case no special permission mode is set.
 316      * @param flags Can be HideProgressInfo, Overwrite and Resume here. WARNING:
 317      * Setting Resume means that the data will be appended to @p dest if @p dest exists.
 318      * @return the job handling the operation.
 319      */
 320     KIO_EXPORT StoredTransferJob *storedPut( const QByteArray& arr, const KUrl& url, int permissions,
 321                                              JobFlags flags = DefaultFlags );
 322
 323     /**
 324      * HTTP POST (a.k.a. write) data from a single QByteArray.
 325      * @see StoredTransferJob
 326      *
 327      * @param arr The data to write
 328      * @param url Where to write data.
 329      * @param flags Can be HideProgressInfo here.
 330      * @return the job handling the operation.
 331      * @since 4.2
 332      */
 333     KIO_EXPORT StoredTransferJob *storedHttpPost( const QByteArray& arr, const KUrl& url,
 334                                                   JobFlags flags = DefaultFlags );
 335
 336     /**
 337      * Creates a new multiple get job.
 338      *
 339      * @param id the id of the get operation
 340      * @param url the URL of the file
 341      * @param metaData the MetaData associated with the file
 342      *
 343      * @return the job handling the operation.
 344      * @see get()
 345      */
 346     KIO_EXPORT MultiGetJob *multi_get( long id, const KUrl &url, const MetaData &metaData);
 347
 348     /**
 349      * Find mimetype for one file or directory.
 350      *
 351      * @param url the URL of the file
 352      * @param flags Can be HideProgressInfo here
 353      * @return the job handling the operation.
 354      */
 355     KIO_EXPORT MimetypeJob * mimetype( const KUrl& url,
 356                                        JobFlags flags = DefaultFlags );
 357
 358     /**
 359      * Copy a single file.
 360      *
 361      * Uses either SlaveBase::copy() if the slave supports that
 362      * or get() and put() otherwise.
 363      * @param src Where to get the file.
 364      * @param dest Where to put the file.
 365      * @param permissions May be -1. In this case no special permission mode is set.
 366      * @param flags Can be HideProgressInfo, Overwrite and Resume here. WARNING:
 367      * Setting Resume means that the data will be appended to @p dest if @p dest exists.
 368      * @return the job handling the operation.
 369      */
 370     KIO_EXPORT FileCopyJob *file_copy( const KUrl& src, const KUrl& dest, int permissions=-1,
 371                                        JobFlags flags = DefaultFlags );
 372
 373
 374     /**
 375      * Move a single file.
 376      *
 377      * Use either SlaveBase::rename() if the slave supports that,
 378      * or copy() and del() otherwise, or eventually get() & put() & del()
 379      * @param src Where to get the file.
 380      * @param dest Where to put the file.
 381      * @param permissions May be -1. In this case no special permission mode is set.
 382      * @param flags Can be HideProgressInfo, Overwrite and Resume here. WARNING:
 383      * Setting Resume means that the data will be appended to @p dest if @p dest exists.
 384      * @return the job handling the operation.
 385      */
 386     KIO_EXPORT FileCopyJob *file_move( const KUrl& src, const KUrl& dest, int permissions=-1,
 387                                        JobFlags flags = DefaultFlags );
 388
 389     /**
 390      * Overload for catching code mistakes. Do NOT call this method (it is not implemented),
 391      * insert a value for permissions (-1 by default) before the JobFlags.
 392      * @since 4.3
 393      */
 394     FileCopyJob *file_move( const KUrl& src, const KUrl& dest, JobFlags flags ); // not implemented - on purpose.
 395
 396
 397     /**
 398      * Delete a single file.
 399      *
 400      * @param src File to delete.
 401      * @param flags Can be HideProgressInfo here
 402      * @return the job handling the operation.
 403      */
 404     KIO_EXPORT SimpleJob *file_delete( const KUrl& src, JobFlags flags = DefaultFlags );
 405
 406     /**
 407      * List the contents of @p url, which is assumed to be a directory.
 408      *
 409      * "." and ".." are returned, filter them out if you don't want them.
 410      *
 411      *
 412      * @param url the url of the directory
 413      * @param flags Can be HideProgressInfo here
 414      * @param includeHidden true for all files, false to cull out UNIX hidden
 415      *                      files/dirs (whose names start with dot)
 416      * @return the job handling the operation.
 417      */
 418     KIO_EXPORT ListJob *listDir( const KUrl& url, JobFlags flags = DefaultFlags,
 419                                  bool includeHidden = true );
 420
 421     /**
 422      * The same as the previous method, but recurses subdirectories.
 423      * Directory links are not followed.
 424      *
 425      * "." and ".." are returned but only for the toplevel directory.
 426      * Filter them out if you don't want them.
 427      *
 428      * @param url the url of the directory
 429      * @param flags Can be HideProgressInfo here
 430      * @param includeHidden true for all files, false to cull out UNIX hidden
 431      *                      files/dirs (whose names start with dot)
 432      * @return the job handling the operation.
 433      */
 434     KIO_EXPORT ListJob *listRecursive( const KUrl& url, JobFlags flags = DefaultFlags,
 435                             bool includeHidden = true );
 436
 437 }
 438
 439 #endif
 440