1 /* 2 This file is part of the KDE libraries 3 SPDX-FileCopyrightText: 2000-2005 David Faure <faure@kde.org> 4 5 SPDX-License-Identifier: LGPL-2.0-only 6 */ 7 #ifndef KIO_GLOBAL_H 8 #define KIO_GLOBAL_H 9 10 #include "kiocore_export.h" 11 12 #include <QFile> // for QFile::Permissions 13 #include <QString> 14 15 #include <KJob> 16 17 #include "jobtracker.h" // for source compat 18 #include "metadata.h" // for source compat 19 20 class QUrl; 21 22 class QTime; 23 24 #if defined(Q_OS_WIN) && defined(Q_CC_MSVC) 25 // on windows ssize_t is not defined, only SSIZE_T exists 26 #include <basetsd.h> 27 typedef SSIZE_T ssize_t; 28 #endif 29 30 /** 31 * @short A namespace for KIO globals 32 * 33 */ 34 namespace KIO 35 { 36 /// 64-bit file offset 37 typedef qlonglong fileoffset_t; 38 /// 64-bit file size 39 typedef qulonglong filesize_t; 40 41 /** 42 * Converts @p size from bytes to the string representation. 43 * 44 * @param size size in bytes 45 * @return converted size as a string - e.g. 123.4 KiB , 12.0 MiB 46 */ 47 KIOCORE_EXPORT QString convertSize(KIO::filesize_t size); 48 49 /** 50 * Converts a size to a string representation 51 * Not unlike QString::number(...) 52 * 53 * @param size size in bytes 54 * @return converted size as a string - e.g. 123456789 55 */ 56 KIOCORE_EXPORT QString number(KIO::filesize_t size); 57 58 /** 59 * Converts size from kibi-bytes (2^10) to the string representation. 60 * 61 * @param kibSize size in kibi-bytes (2^10) 62 * @return converted size as a string - e.g. 123.4 KiB , 12.0 MiB 63 */ 64 KIOCORE_EXPORT QString convertSizeFromKiB(KIO::filesize_t kibSize); 65 66 /** 67 * Calculates remaining time in seconds from total size, processed size and speed. 68 * 69 * @param totalSize total size in bytes 70 * @param processedSize processed size in bytes 71 * @param speed speed in bytes per second 72 * @return calculated remaining time in seconds 73 */ 74 KIOCORE_EXPORT unsigned int calculateRemainingSeconds(KIO::filesize_t totalSize, KIO::filesize_t processedSize, KIO::filesize_t speed); 75 76 /** 77 * Convert @p seconds to a string representing number of days, hours, minutes and seconds 78 * 79 * @param seconds number of seconds to convert 80 * @return string representation in a locale depending format 81 */ 82 KIOCORE_EXPORT QString convertSeconds(unsigned int seconds); 83 84 #if KIOCORE_ENABLE_DEPRECATED_SINCE(3, 4) 85 /** 86 * Calculates remaining time from total size, processed size and speed. 87 * 88 * @param totalSize total size in bytes 89 * @param processedSize processed size in bytes 90 * @param speed speed in bytes per second 91 * @return calculated remaining time 92 * @deprecated Since 3.4, use calculateRemainingSeconds() instead, as QTime is limited to 23:59:59 93 */ 94 KIOCORE_EXPORT 95 KIOCORE_DEPRECATED_VERSION(3, 4, "Use KIO::calculateRemainingSeconds(KIO::filesize_t, KIO::filesize_t, KIO::filesize_t") 96 QTime calculateRemaining(KIO::filesize_t totalSize, KIO::filesize_t processedSize, KIO::filesize_t speed); 97 #endif 98 99 /** 100 * Helper for showing information about a set of files and directories 101 * @param items the number of items (= @p files + @p dirs + number of symlinks :) 102 * @param files the number of files 103 * @param dirs the number of dirs 104 * @param size the sum of the size of the @p files 105 * @param showSize whether to show the size in the result 106 * @return the summary string 107 */ 108 KIOCORE_EXPORT QString itemsSummaryString(uint items, uint files, uint dirs, KIO::filesize_t size, bool showSize); 109 110 /** 111 * Encodes (from the text displayed to the real filename) 112 * This translates '/' into a "unicode fraction slash", QChar(0x2044). 113 * Used by KIO::link, for instance. 114 * @param str the file name to encode 115 * @return the encoded file name 116 */ 117 KIOCORE_EXPORT QString encodeFileName(const QString &str); 118 /** 119 * Decodes (from the filename to the text displayed) 120 * This doesn't do anything anymore, it used to do the opposite of encodeFileName 121 * when encodeFileName was using %2F for '/'. 122 * @param str the file name to decode 123 * @return the decoded file name 124 */ 125 KIOCORE_EXPORT QString decodeFileName(const QString &str); 126 127 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 61) 128 /** 129 * Given a directory path and a filename (which usually exists already), 130 * this function returns a suggested name for a file that doesn't exist 131 * in that directory. The existence is only checked for local urls though. 132 * The suggested file name is of the form "foo 1", "foo 2" etc. 133 * @since 5.0 134 * @deprecated since 5.61, use KFileUtils::suggestName() from KCoreAddons 135 */ 136 KIOCORE_EXPORT 137 KIOCORE_DEPRECATED_VERSION(5, 61, "Use KFileUtils::suggestName(const QUrl &, const QString &) from KCoreAddons") 138 QString suggestName(const QUrl &baseURL, const QString &oldName); 139 #endif 140 141 /** 142 * Error codes that can be emitted by KIO. 143 */ 144 enum Error { 145 ERR_CANNOT_OPEN_FOR_READING = KJob::UserDefinedError + 1, 146 ERR_CANNOT_OPEN_FOR_WRITING = KJob::UserDefinedError + 2, 147 ERR_CANNOT_LAUNCH_PROCESS = KJob::UserDefinedError + 3, 148 ERR_INTERNAL = KJob::UserDefinedError + 4, 149 ERR_MALFORMED_URL = KJob::UserDefinedError + 5, 150 ERR_UNSUPPORTED_PROTOCOL = KJob::UserDefinedError + 6, 151 ERR_NO_SOURCE_PROTOCOL = KJob::UserDefinedError + 7, 152 ERR_UNSUPPORTED_ACTION = KJob::UserDefinedError + 8, 153 ERR_IS_DIRECTORY = KJob::UserDefinedError + 9, ///< ... where a file was expected 154 ERR_IS_FILE = KJob::UserDefinedError + 10, ///< ... where a directory was expected (e.g. listing) 155 ERR_DOES_NOT_EXIST = KJob::UserDefinedError + 11, 156 ERR_FILE_ALREADY_EXIST = KJob::UserDefinedError + 12, 157 ERR_DIR_ALREADY_EXIST = KJob::UserDefinedError + 13, 158 ERR_UNKNOWN_HOST = KJob::UserDefinedError + 14, 159 ERR_ACCESS_DENIED = KJob::UserDefinedError + 15, 160 ERR_WRITE_ACCESS_DENIED = KJob::UserDefinedError + 16, 161 ERR_CANNOT_ENTER_DIRECTORY = KJob::UserDefinedError + 17, 162 ERR_PROTOCOL_IS_NOT_A_FILESYSTEM = KJob::UserDefinedError + 18, 163 ERR_CYCLIC_LINK = KJob::UserDefinedError + 19, 164 ERR_USER_CANCELED = KJob::KilledJobError, 165 ERR_CYCLIC_COPY = KJob::UserDefinedError + 21, 166 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 0) 167 ERR_COULD_NOT_CREATE_SOCKET KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use ERR_CANNOT_CREATE_SOCKET.") = 168 KJob::UserDefinedError + 22, ///< @deprecated Since 5.0, use ERR_CANNOT_CREATE_SOCKET 169 #endif 170 ERR_CANNOT_CREATE_SOCKET = KJob::UserDefinedError + 22, 171 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 0) 172 ERR_COULD_NOT_CONNECT KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use ERR_CANNOT_CONNECT.") = 173 KJob::UserDefinedError + 23, ///< @deprecated Since 5.0, use ERR_CANNOT_CONNECT 174 #endif 175 ERR_CANNOT_CONNECT = KJob::UserDefinedError + 23, 176 ERR_CONNECTION_BROKEN = KJob::UserDefinedError + 24, 177 ERR_NOT_FILTER_PROTOCOL = KJob::UserDefinedError + 25, 178 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 0) 179 ERR_COULD_NOT_MOUNT KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use ERR_CANNOT_MOUNT.") = 180 KJob::UserDefinedError + 26, ///< @deprecated Since 5.0, use ERR_CANNOT_MOUNT 181 #endif 182 ERR_CANNOT_MOUNT = KJob::UserDefinedError + 26, 183 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 0) 184 ERR_COULD_NOT_UNMOUNT KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use ERR_CANNOT_UNMOUNT.") = 185 KJob::UserDefinedError + 27, ///< @deprecated Since 5.0, use ERR_CANNOT_UNMOUNT 186 #endif 187 ERR_CANNOT_UNMOUNT = KJob::UserDefinedError + 27, 188 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 0) 189 ERR_COULD_NOT_READ KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use ERR_CANNOT_READ.") = 190 KJob::UserDefinedError + 28, ///< @deprecated Since 5.0, use ERR_CANNOT_READ 191 #endif 192 ERR_CANNOT_READ = KJob::UserDefinedError + 28, 193 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 0) 194 ERR_COULD_NOT_WRITE KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use ERR_CANNOT_WRITE.") = 195 KJob::UserDefinedError + 29, ///< @deprecated Since 5.0, use ERR_CANNOT_WRITE 196 #endif 197 ERR_CANNOT_WRITE = KJob::UserDefinedError + 29, 198 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 0) 199 ERR_COULD_NOT_BIND KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use ERR_CANNOT_BIND.") = 200 KJob::UserDefinedError + 30, ///< @deprecated Since 5.0, use ERR_CANNOT_BIND 201 #endif 202 ERR_CANNOT_BIND = KJob::UserDefinedError + 30, 203 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 0) 204 ERR_COULD_NOT_LISTEN KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use ERR_CANNOT_LISTEN.") = 205 KJob::UserDefinedError + 31, ///< @deprecated Since 5.0, use ERR_CANNOT_LISTEN 206 #endif 207 ERR_CANNOT_LISTEN = KJob::UserDefinedError + 31, 208 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 0) 209 ERR_COULD_NOT_ACCEPT KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use ERR_CANNOT_ACCEPT.") = 210 KJob::UserDefinedError + 32, ///< @deprecated Since 5.0, use ERR_CANNOT_ACCEPT 211 #endif 212 ERR_CANNOT_ACCEPT = KJob::UserDefinedError + 32, 213 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 0) 214 ERR_COULD_NOT_LOGIN KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use ERR_CANNOT_LOGIN.") = 215 KJob::UserDefinedError + 33, ///< @deprecated Since 5.0, use ERR_CANNOT_LOGIN 216 #endif 217 ERR_CANNOT_LOGIN = KJob::UserDefinedError + 33, 218 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 0) 219 ERR_COULD_NOT_STAT KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use ERR_CANNOT_STAT.") = 220 KJob::UserDefinedError + 34, ///< @deprecated Since 5.0, use ERR_CANNOT_STAT 221 #endif 222 ERR_CANNOT_STAT = KJob::UserDefinedError + 34, 223 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 0) 224 ERR_COULD_NOT_CLOSEDIR KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use ERR_CANNOT_CLOSEDIR.") = 225 KJob::UserDefinedError + 35, ///< @deprecated Since 5.0, use ERR_CANNOT_CLOSEDIR 226 #endif 227 ERR_CANNOT_CLOSEDIR = KJob::UserDefinedError + 35, 228 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 0) 229 ERR_COULD_NOT_MKDIR KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use ERR_CANNOT_AUTHENTICATE.") = 230 KJob::UserDefinedError + 37, ///< @deprecated Since 5.0, use ERR_CANNOT_MKDIR 231 #endif 232 ERR_CANNOT_MKDIR = KJob::UserDefinedError + 37, 233 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 0) 234 ERR_COULD_NOT_RMDIR KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use ERR_CANNOT_RMDIR.") = 235 KJob::UserDefinedError + 38, ///< @deprecated Since 5.0, use ERR_CANNOT_RMDIR 236 #endif 237 ERR_CANNOT_RMDIR = KJob::UserDefinedError + 38, 238 ERR_CANNOT_RESUME = KJob::UserDefinedError + 39, 239 ERR_CANNOT_RENAME = KJob::UserDefinedError + 40, 240 ERR_CANNOT_CHMOD = KJob::UserDefinedError + 41, 241 ERR_CANNOT_DELETE = KJob::UserDefinedError + 42, 242 // The text argument is the protocol that the dead slave supported. 243 // This means for example: file, ftp, http, ... 244 ERR_SLAVE_DIED = KJob::UserDefinedError + 43, 245 ERR_OUT_OF_MEMORY = KJob::UserDefinedError + 44, 246 ERR_UNKNOWN_PROXY_HOST = KJob::UserDefinedError + 45, 247 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 0) 248 ERR_COULD_NOT_AUTHENTICATE KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use ERR_CANNOT_AUTHENTICATE.") = 249 KJob::UserDefinedError + 46, ///< @deprecated Since 5.0, use ERR_CANNOT_AUTHENTICATE 250 #endif 251 ERR_CANNOT_AUTHENTICATE = KJob::UserDefinedError + 46, 252 ERR_ABORTED = KJob::UserDefinedError + 47, ///< Action got aborted from application side 253 ERR_INTERNAL_SERVER = KJob::UserDefinedError + 48, 254 ERR_SERVER_TIMEOUT = KJob::UserDefinedError + 49, 255 ERR_SERVICE_NOT_AVAILABLE = KJob::UserDefinedError + 50, 256 ERR_UNKNOWN = KJob::UserDefinedError + 51, 257 // (was a warning) ERR_CHECKSUM_MISMATCH = 52, 258 ERR_UNKNOWN_INTERRUPT = KJob::UserDefinedError + 53, 259 ERR_CANNOT_DELETE_ORIGINAL = KJob::UserDefinedError + 54, 260 ERR_CANNOT_DELETE_PARTIAL = KJob::UserDefinedError + 55, 261 ERR_CANNOT_RENAME_ORIGINAL = KJob::UserDefinedError + 56, 262 ERR_CANNOT_RENAME_PARTIAL = KJob::UserDefinedError + 57, 263 ERR_NEED_PASSWD = KJob::UserDefinedError + 58, 264 ERR_CANNOT_SYMLINK = KJob::UserDefinedError + 59, 265 ERR_NO_CONTENT = KJob::UserDefinedError + 60, ///< Action succeeded but no content will follow. 266 ERR_DISK_FULL = KJob::UserDefinedError + 61, 267 ERR_IDENTICAL_FILES = KJob::UserDefinedError + 62, ///< src==dest when moving/copying 268 ERR_SLAVE_DEFINED = KJob::UserDefinedError + 63, ///< for slave specified errors that can be 269 ///< rich text. Email links will be handled 270 ///< by the standard email app and all hrefs 271 ///< will be handled by the standard browser. 272 ///< <a href="exec:/khelpcenter ?" will be 273 ///< forked. 274 ERR_UPGRADE_REQUIRED = KJob::UserDefinedError + 64, ///< A transport upgrade is required to access this 275 ///< object. For instance, TLS is demanded by 276 ///< the server in order to continue. 277 ERR_POST_DENIED = KJob::UserDefinedError + 65, ///< Issued when trying to POST data to a certain Ports 278 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 0) 279 ERR_COULD_NOT_SEEK KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use ERR_CANNOT_SEEK.") = 280 KJob::UserDefinedError + 66, ///< @deprecated Since 5.0, use ERR_CANNOT_SEEK 281 #endif 282 // see job.cpp 283 ERR_CANNOT_SEEK = KJob::UserDefinedError + 66, 284 ERR_CANNOT_SETTIME = KJob::UserDefinedError + 67, ///< Emitted by setModificationTime 285 ERR_CANNOT_CHOWN = KJob::UserDefinedError + 68, 286 ERR_POST_NO_SIZE = KJob::UserDefinedError + 69, 287 ERR_DROP_ON_ITSELF = KJob::UserDefinedError + 70, ///< from KIO::DropJob, @since 5.6 288 ERR_CANNOT_MOVE_INTO_ITSELF = KJob::UserDefinedError + 71, ///< emitted by KIO::move, @since 5.18 289 ERR_PASSWD_SERVER = KJob::UserDefinedError + 72, ///< returned by SlaveBase::openPasswordDialogV2, @since 5.24 290 ERR_CANNOT_CREATE_SLAVE = KJob::UserDefinedError + 73, ///< used by Slave::createSlave, @since 5.30 291 ERR_FILE_TOO_LARGE_FOR_FAT32 = KJob::UserDefinedError + 74, ///< @since 5.54 292 ERR_OWNER_DIED = KJob::UserDefinedError 293 + 75, ///< Value used between kuiserver and views when the job owner disappears unexpectedly. It should not be emitted by slaves. @since 5.54 294 ERR_PRIVILEGE_NOT_REQUIRED = KJob::UserDefinedError + 76, ///< used by file ioslave, @since 5.60 295 ERR_CANNOT_TRUNCATE = KJob::UserDefinedError + 77, // used by FileJob::truncate, @since 5.66 296 /** 297 * Indicates failure to create a symlink due to the underlying filesystem (FAT/ExFAT) 298 * not supporting them. Used by e.g. CopyJob. 299 * @since 5.88 300 */ 301 ERR_SYMLINKS_NOT_SUPPORTED = KJob::UserDefinedError + 78 302 }; 303 304 /** 305 * Specifies how to use the cache. 306 * @see parseCacheControl() 307 * @see getCacheControlString() 308 */ 309 enum CacheControl { 310 CC_CacheOnly, ///< Fail request if not in cache 311 CC_Cache, ///< Use cached entry if available 312 CC_Verify, ///< Validate cached entry with remote site if expired 313 CC_Refresh, ///< Always validate cached entry with remote site 314 CC_Reload, ///< Always fetch from remote site. 315 }; 316 317 /** 318 * Specifies privilege file operation status. 319 * @since 5.43 320 */ 321 enum PrivilegeOperationStatus { 322 OperationAllowed = 1, 323 OperationCanceled, 324 OperationNotAllowed, 325 }; 326 327 /** 328 * Describes the fields that a stat command will retrieve 329 * @see UDSEntry 330 * @see StatDetails 331 * @since 5.69 332 */ 333 enum StatDetail { 334 /// No field returned, useful to check if a file exists 335 StatNoDetails = 0x0, 336 /// Filename, access, type, size, linkdest 337 StatBasic = 0x1, 338 /// uid, gid 339 StatUser = 0x2, 340 /// atime, mtime, btime 341 StatTime = 0x4, 342 /// Resolve symlinks 343 StatResolveSymlink = 0x8, 344 /// ACL data 345 StatAcl = 0x10, 346 /// dev, inode 347 StatInode = 0x20, 348 /// Recursive size 349 /// @since 5.70 350 StatRecursiveSize = 0x40, 351 /// Mime Type 352 /// @since 5.82 353 StatMimeType = 0x80, 354 355 /// Default StatDetail flag when creating a @c StatJob. 356 /// Equivalent to setting <tt>StatBasic | StatUser | StatTime | StatAcl | StatResolveSymlink</tt> 357 StatDefaultDetails = StatBasic | StatUser | StatTime | StatAcl | StatResolveSymlink, 358 }; 359 /** 360 * Stores a combination of #StatDetail values. 361 */ 362 Q_DECLARE_FLAGS(StatDetails, StatDetail) 363 364 Q_DECLARE_OPERATORS_FOR_FLAGS(KIO::StatDetails) 365 366 /** 367 * Parses the string representation of the cache control option. 368 * 369 * @param cacheControl the string representation 370 * @return the cache control value 371 * @see getCacheControlString() 372 */ 373 KIOCORE_EXPORT KIO::CacheControl parseCacheControl(const QString &cacheControl); 374 375 /** 376 * Returns a string representation of the given cache control method. 377 * 378 * @param cacheControl the cache control method 379 * @return the string representation 380 * @see parseCacheControl() 381 */ 382 KIOCORE_EXPORT QString getCacheControlString(KIO::CacheControl cacheControl); 383 384 /** 385 * Return the "favicon" (see http://www.favicon.com) for the given @p url, 386 * if available. Does NOT attempt to download the favicon, it only returns 387 * one that is already available. 388 * 389 * If unavailable, returns QString(). 390 * Use KIO::FavIconRequestJob instead of this method if you can wait 391 * for the favicon to be downloaded. 392 * 393 * @param url the URL of the favicon 394 * @return the path to the icon (to be passed to QIcon()), or QString() 395 * 396 * @since 5.0 397 */ 398 KIOCORE_EXPORT QString favIconForUrl(const QUrl &url); 399 400 /** 401 * Converts KIO file permissions from mode_t to QFile::Permissions format. 402 * 403 * This is a convenience function for converting KIO permissions parameter from 404 * mode_t to QFile::Permissions. 405 * 406 * @param permissions KIO file permissions. 407 * 408 * @return -1 if @p permissions is -1, otherwise its OR'ed QFile::Permission equivalent. 409 * @since 4.12 410 */ 411 KIOCORE_EXPORT QFile::Permissions convertPermissions(int permissions); 412 413 /** 414 * Return the icon name for a URL. 415 * Most of the time this returns the MIME type icon, 416 * but also has fallback to favicon and protocol-specific icon. 417 * 418 * Pass this to QIcon::fromTheme(). 419 * 420 * @since 5.0 421 */ 422 KIOCORE_EXPORT QString iconNameForUrl(const QUrl &url); 423 424 /** 425 * This function is useful to implement the "Up" button in a file manager for example. 426 * 427 * @return a URL that is a level higher 428 * 429 * @since 5.0 430 */ 431 KIOCORE_EXPORT QUrl upUrl(const QUrl &url); 432 433 } 434 #endif 435