kio/kio/global.h

   1 // -*- c-basic-offset: 2 -*-
   2 /* This file is part of the KDE libraries
   3    Copyright (C) 2000-2005 David Faure <faure@kde.org>
   4
   5    This library is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU Library General Public
   7    License version 2 as published by the Free Software Foundation.
   8
   9    This library is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12    Library General Public License for more details.
  13
  14    You should have received a copy of the GNU Library General Public License
  15    along with this library; see the file COPYING.LIB.  If not, write to
  16    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17    Boston, MA 02110-1301, USA.
  18 */
  19 #ifndef KIO_GLOBAL_H
  20 #define KIO_GLOBAL_H
  21
  22 #include <kio/kio_export.h>
  23
  24 #include <QtCore/QString>
  25 #include <QtCore/QHash>
  26 #include <QtCore/QMap>
  27 #include <QtCore/QList>
  28
  29 #include <kiconloader.h>
  30 #include <QtGui/QPixmap> // for pixmapForUrl
  31
  32 #include <sys/stat.h>  // S_ISDIR
  33 #include <sys/types.h> // mode_t
  34
  35 #include <kjob.h>
  36
  37 #ifdef Q_OS_WIN
  38 template class KDE_EXPORT QMap<QString, QString>;
  39 #endif
  40
  41 class KUrl;
  42 class KJobTrackerInterface;
  43
  44 class QTime;
  45
  46 /**
  47  * @short A namespace for KIO globals
  48  *
  49  */
  50 namespace KIO
  51 {
  52   /// 64-bit file offset
  53   typedef qlonglong fileoffset_t;
  54   /// 64-bit file size
  55   typedef qulonglong filesize_t;
  56
  57   /**
  58    * Converts @p size from bytes to the string representation.
  59    *
  60    * @param  size  size in bytes
  61    * @return converted size as a string - e.g. 123.4 KiB , 12.0 MiB
  62    */
  63   KIO_EXPORT QString convertSize( KIO::filesize_t size );
  64
  65   /**
  66    * Converts a size to a string representation
  67    * Not unlike QString::number(...)
  68    *
  69    * @param size size in bytes
  70    * @return  converted size as a string - e.g. 123456789
  71    */
  72   KIO_EXPORT QString number( KIO::filesize_t size );
  73
  74   /**
  75    * Converts size from kibi-bytes (2^10) to the string representation.
  76    *
  77    * @param  kibSize  size in kibi-bytes (2^10)
  78    * @return converted size as a string - e.g. 123.4 KiB , 12.0 MiB
  79    */
  80    KIO_EXPORT QString convertSizeFromKiB( KIO::filesize_t kibSize );
  81
  82   /**
  83    * Calculates remaining time in seconds from total size, processed size and speed.
  84    *
  85    * @param  totalSize      total size in bytes
  86    * @param  processedSize  processed size in bytes
  87    * @param  speed          speed in bytes per second
  88    * @return calculated remaining time in seconds
  89    */
  90   KIO_EXPORT unsigned int calculateRemainingSeconds( KIO::filesize_t totalSize,
  91                                                      KIO::filesize_t processedSize, KIO::filesize_t speed );
  92
  93   /**
  94    * Convert @p seconds to a string representing number of days, hours, minutes and seconds
  95    *
  96    * @param  seconds number of seconds to convert
  97    * @return string representation in a locale depending format
  98    */
  99   KIO_EXPORT QString convertSeconds( unsigned int seconds );
 100
 101   /**
 102    * Calculates remaining time from total size, processed size and speed.
 103    * Warning: As QTime is limited to 23:59:59, use calculateRemainingSeconds() instead
 104    *
 105    * @param  totalSize      total size in bytes
 106    * @param  processedSize  processed size in bytes
 107    * @param  speed          speed in bytes per second
 108    * @return calculated remaining time
 109    */
 110   KIO_EXPORT_DEPRECATED QTime calculateRemaining( KIO::filesize_t totalSize, KIO::filesize_t processedSize, KIO::filesize_t speed );
 111
 112   /**
 113    * Helper for showing information about a set of files and directories
 114    * @param items the number of items (= @p files + @p dirs + number of symlinks :)
 115    * @param files the number of files
 116    * @param dirs the number of dirs
 117    * @param size the sum of the size of the @p files
 118    * @param showSize whether to show the size in the result
 119    * @return the summary string
 120    */
 121   KIO_EXPORT QString itemsSummaryString(uint items, uint files, uint dirs, KIO::filesize_t size, bool showSize);
 122
 123   /**
 124    * Encodes (from the text displayed to the real filename)
 125    * This translates % into %% and / into %2f
 126    * Used by KIO::link, for instance.
 127    * @param str the file name to encode
 128    * @return the encoded file name
 129    */
 130   KIO_EXPORT QString encodeFileName( const QString & str );
 131   /**
 132    * Decodes (from the filename to the text displayed)
 133    * This translates %2[fF] into / and %% into %
 134    * @param str the file name to decode
 135    * @return the decoded file name
 136    */
 137   KIO_EXPORT QString decodeFileName( const QString & str );
 138
 139   /**
 140    * @internal
 141    * Commands that can be invoked by a job.
 142    *
 143    * (Move this to a non-public header)
 144    */
 145   enum Command {
 146     CMD_HOST = '0', // 48
 147     CMD_CONNECT = '1', // 49
 148     CMD_DISCONNECT = '2', // 50
 149     CMD_SLAVE_STATUS = '3', // 51
 150     CMD_SLAVE_CONNECT = '4', // 52
 151     CMD_SLAVE_HOLD = '5', // 53
 152     CMD_NONE = 'A', // 65
 153     CMD_TESTDIR = 'B', // 66
 154     CMD_GET = 'C', // 67
 155     CMD_PUT = 'D', // 68
 156     CMD_STAT = 'E', // 69
 157     CMD_MIMETYPE = 'F', // 70
 158     CMD_LISTDIR = 'G', // 71
 159     CMD_MKDIR = 'H', // 72
 160     CMD_RENAME = 'I', // 73
 161     CMD_COPY = 'J', // 74
 162     CMD_DEL = 'K', // 75
 163     CMD_CHMOD = 'L', // 76
 164     CMD_SPECIAL = 'M', // 77
 165     CMD_SETMODIFICATIONTIME = 'N', // 78
 166     CMD_REPARSECONFIGURATION = 'O', // 79
 167     CMD_META_DATA = 'P', // 80
 168     CMD_SYMLINK = 'Q', // 81
 169     CMD_SUBURL = 'R', // 82  Inform the slave about the url it is streaming on.
 170     CMD_MESSAGEBOXANSWER = 'S', // 83
 171     CMD_RESUMEANSWER = 'T', // 84
 172     CMD_CONFIG = 'U', // 85
 173     CMD_MULTI_GET = 'V', // 86
 174     CMD_SETLINKDEST = 'W', // 87
 175     CMD_OPEN = 'X', // 88
 176     CMD_CHOWN = 'Y', // 89
 177     CMD_READ = 'Z', // 90
 178     CMD_WRITE = 91,
 179     CMD_SEEK = 92,
 180     CMD_CLOSE = 93,
 181     CMD_HOST_INFO = 94
 182     // Add new ones here once a release is done, to avoid breaking binary compatibility.
 183     // Note that protocol-specific commands shouldn't be added here, but should use special.
 184   };
 185
 186   /**
 187    * Error codes that can be emitted by KIO.
 188    */
 189   enum Error {
 190     ERR_CANNOT_OPEN_FOR_READING = KJob::UserDefinedError + 1,
 191     ERR_CANNOT_OPEN_FOR_WRITING = KJob::UserDefinedError + 2,
 192     ERR_CANNOT_LAUNCH_PROCESS = KJob::UserDefinedError + 3,
 193     ERR_INTERNAL = KJob::UserDefinedError + 4,
 194     ERR_MALFORMED_URL = KJob::UserDefinedError + 5,
 195     ERR_UNSUPPORTED_PROTOCOL = KJob::UserDefinedError + 6,
 196     ERR_NO_SOURCE_PROTOCOL = KJob::UserDefinedError + 7,
 197     ERR_UNSUPPORTED_ACTION = KJob::UserDefinedError + 8,
 198     ERR_IS_DIRECTORY = KJob::UserDefinedError + 9, // ... where a file was expected
 199     ERR_IS_FILE = KJob::UserDefinedError + 10, // ... where a directory was expected (e.g. listing)
 200     ERR_DOES_NOT_EXIST = KJob::UserDefinedError + 11,
 201     ERR_FILE_ALREADY_EXIST = KJob::UserDefinedError + 12,
 202     ERR_DIR_ALREADY_EXIST = KJob::UserDefinedError + 13,
 203     ERR_UNKNOWN_HOST = KJob::UserDefinedError + 14,
 204     ERR_ACCESS_DENIED = KJob::UserDefinedError + 15,
 205     ERR_WRITE_ACCESS_DENIED = KJob::UserDefinedError + 16,
 206     ERR_CANNOT_ENTER_DIRECTORY = KJob::UserDefinedError + 17,
 207     ERR_PROTOCOL_IS_NOT_A_FILESYSTEM = KJob::UserDefinedError + 18,
 208     ERR_CYCLIC_LINK = KJob::UserDefinedError + 19,
 209     ERR_USER_CANCELED = KJob::KilledJobError,
 210     ERR_CYCLIC_COPY = KJob::UserDefinedError + 21,
 211     ERR_COULD_NOT_CREATE_SOCKET = KJob::UserDefinedError + 22, // KDE4: s/COULD_NOT/CANNOT/ or the other way round
 212     ERR_COULD_NOT_CONNECT = KJob::UserDefinedError + 23,
 213     ERR_CONNECTION_BROKEN = KJob::UserDefinedError + 24,
 214     ERR_NOT_FILTER_PROTOCOL = KJob::UserDefinedError + 25,
 215     ERR_COULD_NOT_MOUNT = KJob::UserDefinedError + 26,
 216     ERR_COULD_NOT_UNMOUNT = KJob::UserDefinedError + 27,
 217     ERR_COULD_NOT_READ = KJob::UserDefinedError + 28,
 218     ERR_COULD_NOT_WRITE = KJob::UserDefinedError + 29,
 219     ERR_COULD_NOT_BIND = KJob::UserDefinedError + 30,
 220     ERR_COULD_NOT_LISTEN = KJob::UserDefinedError + 31,
 221     ERR_COULD_NOT_ACCEPT = KJob::UserDefinedError + 32,
 222     ERR_COULD_NOT_LOGIN = KJob::UserDefinedError + 33,
 223     ERR_COULD_NOT_STAT = KJob::UserDefinedError + 34,
 224     ERR_COULD_NOT_CLOSEDIR = KJob::UserDefinedError + 35,
 225     ERR_COULD_NOT_MKDIR = KJob::UserDefinedError + 37,
 226     ERR_COULD_NOT_RMDIR = KJob::UserDefinedError + 38,
 227     ERR_CANNOT_RESUME = KJob::UserDefinedError + 39,
 228     ERR_CANNOT_RENAME = KJob::UserDefinedError + 40,
 229     ERR_CANNOT_CHMOD = KJob::UserDefinedError + 41,
 230     ERR_CANNOT_DELETE = KJob::UserDefinedError + 42,
 231     // The text argument is the protocol that the dead slave supported.
 232     // This means for example: file, ftp, http, ...
 233     ERR_SLAVE_DIED = KJob::UserDefinedError + 43,
 234     ERR_OUT_OF_MEMORY = KJob::UserDefinedError + 44,
 235     ERR_UNKNOWN_PROXY_HOST = KJob::UserDefinedError + 45,
 236     ERR_COULD_NOT_AUTHENTICATE = KJob::UserDefinedError + 46,
 237     ERR_ABORTED = KJob::UserDefinedError + 47, // Action got aborted from application side
 238     ERR_INTERNAL_SERVER = KJob::UserDefinedError + 48,
 239     ERR_SERVER_TIMEOUT = KJob::UserDefinedError + 49,
 240     ERR_SERVICE_NOT_AVAILABLE = KJob::UserDefinedError + 50,
 241     ERR_UNKNOWN = KJob::UserDefinedError + 51,
 242     // (was a warning) ERR_CHECKSUM_MISMATCH = 52,
 243     ERR_UNKNOWN_INTERRUPT = KJob::UserDefinedError + 53,
 244     ERR_CANNOT_DELETE_ORIGINAL = KJob::UserDefinedError + 54,
 245     ERR_CANNOT_DELETE_PARTIAL = KJob::UserDefinedError + 55,
 246     ERR_CANNOT_RENAME_ORIGINAL = KJob::UserDefinedError + 56,
 247     ERR_CANNOT_RENAME_PARTIAL = KJob::UserDefinedError + 57,
 248     ERR_NEED_PASSWD = KJob::UserDefinedError + 58,
 249     ERR_CANNOT_SYMLINK = KJob::UserDefinedError + 59,
 250     ERR_NO_CONTENT = KJob::UserDefinedError + 60, // Action succeeded but no content will follow.
 251     ERR_DISK_FULL = KJob::UserDefinedError + 61,
 252     ERR_IDENTICAL_FILES = KJob::UserDefinedError + 62, // src==dest when moving/copying
 253     ERR_SLAVE_DEFINED = KJob::UserDefinedError + 63, // for slave specified errors that can be
 254                                                      // rich text.  Email links will be handled
 255                                                      // by the standard email app and all hrefs
 256                                                      // will be handled by the standard browser.
 257                                                      // <a href="exec:/khelpcenter ?" will be
 258                                                      // forked.
 259     ERR_UPGRADE_REQUIRED = KJob::UserDefinedError + 64, // A transport upgrade is required to access this
 260                                                         // object.  For instance, TLS is demanded by
 261                                                         // the server in order to continue.
 262     ERR_POST_DENIED = KJob::UserDefinedError + 65, // Issued when trying to POST data to a certain Ports
 263                                                   // see job.cpp
 264     ERR_COULD_NOT_SEEK = KJob::UserDefinedError + 66,
 265     ERR_CANNOT_SETTIME = KJob::UserDefinedError + 67, // Emitted by setModificationTime
 266     ERR_CANNOT_CHOWN = KJob::UserDefinedError + 68
 267   };
 268
 269   /**
 270    * Returns a translated error message for @p errorCode using the
 271    * additional error information provided by @p errorText.
 272    * @param errorCode the error code
 273    * @param errorText the additional error text
 274    * @return the created error string
 275    */
 276   KIO_EXPORT QString buildErrorString(int errorCode, const QString &errorText);
 277
 278   /**
 279    * Returns a translated html error message for @p errorCode using the
 280    * additional error information provided by @p errorText , @p reqUrl
 281    * (the request URL), and the ioslave @p method .
 282    * @param errorCode the error code
 283    * @param errorText the additional error text
 284    * @param reqUrl the request URL
 285    * @param method the ioslave method
 286    * @return the created error string
 287    */
 288   KIO_EXPORT QString buildHTMLErrorString(int errorCode, const QString &errorText,
 289                                 const KUrl *reqUrl = 0L, int method = -1 );
 290
 291   /**
 292    * Returns translated error details for @p errorCode using the
 293    * additional error information provided by @p errorText , @p reqUrl
 294    * (the request URL), and the ioslave @p method .
 295    *
 296    * @param errorCode the error code
 297    * @param errorText the additional error text
 298    * @param reqUrl the request URL
 299    * @param method the ioslave method
 300    * @return the following data:
 301    * @li QString errorName - the name of the error
 302    * @li QString techName - if not null, the more technical name of the error
 303    * @li QString description - a description of the error
 304    * @li QStringList causes - a list of possible causes of the error
 305    * @li QStringList solutions - a liso of solutions for the error
 306    */
 307   KIO_EXPORT QByteArray rawErrorDetail(int errorCode, const QString &errorText,
 308                                 const KUrl *reqUrl = 0L, int method = -1 );
 309
 310   /**
 311    * Returns an appropriate error message if the given command @p cmd
 312    * is an unsupported action (ERR_UNSUPPORTED_ACTION).
 313    * @param protocol name of the protocol
 314    * @param cmd given command
 315    * @see enum Command
 316    */
 317   KIO_EXPORT QString unsupportedActionErrorString(const QString &protocol, int cmd);
 318
 319   /**
 320    * Specifies how to use the cache.
 321    * @see parseCacheControl()
 322    * @see getCacheControlString()
 323    */
 324   enum CacheControl
 325   {
 326       CC_CacheOnly, ///< Fail request if not in cache
 327       CC_Cache,     ///< Use cached entry if available
 328       CC_Verify,    ///< Validate cached entry with remote site if expired
 329       CC_Refresh,   ///< Always validate cached entry with remote site
 330       CC_Reload     ///< Always fetch from remote site.
 331   };
 332
 333   /**
 334    * Parses the string representation of the cache control option.
 335    *
 336    * @param cacheControl the string representation
 337    * @return the cache control value
 338    * @see getCacheControlString()
 339    */
 340   KIO_EXPORT KIO::CacheControl parseCacheControl(const QString &cacheControl);
 341
 342   /**
 343    * Returns a string representation of the given cache control method.
 344    *
 345    * @param cacheControl the cache control method
 346    * @return the string representation
 347    * @see parseCacheControl()
 348    */
 349   KIO_EXPORT QString getCacheControlString(KIO::CacheControl cacheControl);
 350
 351   /**
 352    * Convenience method to find the pixmap for a URL.
 353    *
 354    * Call this one when you don't know the mimetype.
 355    *
 356    * @param _url URL for the file.
 357    * @param _mode the mode of the file. The mode may modify the icon
 358    *              with overlays that show special properties of the
 359    *              icon. Use 0 for default
 360    * @param _group The icon group where the icon is going to be used.
 361    * @param _force_size Override globally configured icon size.
 362    *        Use 0 for the default size
 363    * @param _state The icon state, one of: KIconLoader::DefaultState,
 364    * KIconLoader::ActiveState or KIconLoader::DisabledState.
 365    * @param _path Output parameter to get the full path. Seldom needed.
 366    *              Ignored if 0
 367    * @return the pixmap of the URL, can be a default icon if not found
 368    */
 369   KIO_EXPORT QPixmap pixmapForUrl( const KUrl & _url, mode_t _mode = 0, KIconLoader::Group _group = KIconLoader::Desktop,
 370                                    int _force_size = 0, int _state = 0, QString * _path = 0 );
 371
 372   KIO_EXPORT KJobTrackerInterface *getJobTracker();
 373
 374
 375 /**
 376  * MetaData is a simple map of key/value strings.
 377  */
 378 class KIO_EXPORT MetaData : public QMap<QString, QString>
 379 {
 380 public:
 381   /**
 382    * Creates an empty meta data map.
 383    */
 384    MetaData() : QMap<QString, QString>() { }
 385   /**
 386    * Copy constructor.
 387    */
 388    MetaData(const QMap<QString, QString>&metaData) :
 389      QMap<QString, QString>(metaData) { }
 390
 391    /**
 392     * Adds the given meta data map to this map.
 393     * @param metaData the map to add
 394     * @return this map
 395     */
 396    MetaData & operator+= ( const QMap<QString,QString> &metaData )
 397    {
 398       QMap<QString,QString>::ConstIterator it;
 399       for(it = metaData.constBegin(); it !=  metaData.constEnd(); ++it)
 400       {
 401          insert(it.key(), it.value());
 402       }
 403       return *this;
 404    }
 405 };
 406
 407 }
 408 #endif