File indexing completed on 2024-04-21 03:55:03
0001 /* 0002 This file is part of the KDE libraries 0003 SPDX-FileCopyrightText: 2000-2005 David Faure <faure@kde.org> 0004 0005 SPDX-License-Identifier: LGPL-2.0-only 0006 */ 0007 #ifndef KIO_GLOBAL_H 0008 #define KIO_GLOBAL_H 0009 0010 #include "kiocore_export.h" 0011 0012 #include <QFile> // for QFile::Permissions 0013 #include <QString> 0014 0015 #include <KJob> 0016 0017 class QUrl; 0018 class QTime; 0019 0020 #if defined(Q_OS_WIN) && defined(Q_CC_MSVC) 0021 // on windows ssize_t is not defined, only SSIZE_T exists 0022 #include <basetsd.h> 0023 typedef SSIZE_T ssize_t; 0024 #endif 0025 0026 /** 0027 * @short A namespace for KIO globals 0028 * 0029 */ 0030 namespace KIO 0031 { 0032 /// 64-bit file offset 0033 typedef qlonglong fileoffset_t; 0034 /// 64-bit file size 0035 typedef qulonglong filesize_t; 0036 0037 /** 0038 * Converts @p size from bytes to the string representation. 0039 * 0040 * @param size size in bytes 0041 * @return converted size as a string - e.g. 123.4 KiB , 12.0 MiB 0042 */ 0043 KIOCORE_EXPORT QString convertSize(KIO::filesize_t size); 0044 0045 /** 0046 * Converts a size to a string representation 0047 * Not unlike QString::number(...) 0048 * 0049 * @param size size in bytes 0050 * @return converted size as a string - e.g. 123456789 0051 */ 0052 KIOCORE_EXPORT QString number(KIO::filesize_t size); 0053 0054 /** 0055 * Converts size from kibi-bytes (2^10) to the string representation. 0056 * 0057 * @param kibSize size in kibi-bytes (2^10) 0058 * @return converted size as a string - e.g. 123.4 KiB , 12.0 MiB 0059 */ 0060 KIOCORE_EXPORT QString convertSizeFromKiB(KIO::filesize_t kibSize); 0061 0062 /** 0063 * Calculates remaining time in seconds from total size, processed size and speed. 0064 * 0065 * @param totalSize total size in bytes 0066 * @param processedSize processed size in bytes 0067 * @param speed speed in bytes per second 0068 * @return calculated remaining time in seconds 0069 */ 0070 KIOCORE_EXPORT unsigned int calculateRemainingSeconds(KIO::filesize_t totalSize, KIO::filesize_t processedSize, KIO::filesize_t speed); 0071 0072 /** 0073 * Convert @p seconds to a string representing number of days, hours, minutes and seconds 0074 * 0075 * @param seconds number of seconds to convert 0076 * @return string representation in a locale depending format 0077 */ 0078 KIOCORE_EXPORT QString convertSeconds(unsigned int seconds); 0079 0080 /** 0081 * Helper for showing information about a set of files and directories 0082 * @param items the number of items (= @p files + @p dirs + number of symlinks :) 0083 * @param files the number of files 0084 * @param dirs the number of dirs 0085 * @param size the sum of the size of the @p files 0086 * @param showSize whether to show the size in the result 0087 * @return the summary string 0088 */ 0089 KIOCORE_EXPORT QString itemsSummaryString(uint items, uint files, uint dirs, KIO::filesize_t size, bool showSize); 0090 0091 /** 0092 * Encodes (from the text displayed to the real filename) 0093 * This translates '/' into a "unicode fraction slash", QChar(0x2044). 0094 * Used by KIO::link, for instance. 0095 * @param str the file name to encode 0096 * @return the encoded file name 0097 */ 0098 KIOCORE_EXPORT QString encodeFileName(const QString &str); 0099 /** 0100 * Decodes (from the filename to the text displayed) 0101 * This doesn't do anything anymore, it used to do the opposite of encodeFileName 0102 * when encodeFileName was using %2F for '/'. 0103 * @param str the file name to decode 0104 * @return the decoded file name 0105 */ 0106 KIOCORE_EXPORT QString decodeFileName(const QString &str); 0107 0108 /** 0109 * Error codes that can be emitted by KIO. 0110 */ 0111 enum Error { 0112 ERR_CANNOT_OPEN_FOR_READING = KJob::UserDefinedError + 1, 0113 ERR_CANNOT_OPEN_FOR_WRITING = KJob::UserDefinedError + 2, 0114 ERR_CANNOT_LAUNCH_PROCESS = KJob::UserDefinedError + 3, 0115 ERR_INTERNAL = KJob::UserDefinedError + 4, 0116 ERR_MALFORMED_URL = KJob::UserDefinedError + 5, 0117 ERR_UNSUPPORTED_PROTOCOL = KJob::UserDefinedError + 6, 0118 ERR_NO_SOURCE_PROTOCOL = KJob::UserDefinedError + 7, 0119 ERR_UNSUPPORTED_ACTION = KJob::UserDefinedError + 8, 0120 ERR_IS_DIRECTORY = KJob::UserDefinedError + 9, ///< ... where a file was expected 0121 ERR_IS_FILE = KJob::UserDefinedError + 10, ///< ... where a directory was expected (e.g.\ listing) 0122 ERR_DOES_NOT_EXIST = KJob::UserDefinedError + 11, 0123 ERR_FILE_ALREADY_EXIST = KJob::UserDefinedError + 12, 0124 ERR_DIR_ALREADY_EXIST = KJob::UserDefinedError + 13, 0125 ERR_UNKNOWN_HOST = KJob::UserDefinedError + 14, 0126 ERR_ACCESS_DENIED = KJob::UserDefinedError + 15, 0127 ERR_WRITE_ACCESS_DENIED = KJob::UserDefinedError + 16, 0128 ERR_CANNOT_ENTER_DIRECTORY = KJob::UserDefinedError + 17, 0129 ERR_PROTOCOL_IS_NOT_A_FILESYSTEM = KJob::UserDefinedError + 18, 0130 ERR_CYCLIC_LINK = KJob::UserDefinedError + 19, 0131 ERR_USER_CANCELED = KJob::KilledJobError, 0132 ERR_CYCLIC_COPY = KJob::UserDefinedError + 21, 0133 ERR_CANNOT_CREATE_SOCKET = KJob::UserDefinedError + 22, 0134 ERR_CANNOT_CONNECT = KJob::UserDefinedError + 23, 0135 ERR_CONNECTION_BROKEN = KJob::UserDefinedError + 24, 0136 ERR_NOT_FILTER_PROTOCOL = KJob::UserDefinedError + 25, 0137 ERR_CANNOT_MOUNT = KJob::UserDefinedError + 26, 0138 ERR_CANNOT_UNMOUNT = KJob::UserDefinedError + 27, 0139 ERR_CANNOT_READ = KJob::UserDefinedError + 28, 0140 ERR_CANNOT_WRITE = KJob::UserDefinedError + 29, 0141 ERR_CANNOT_BIND = KJob::UserDefinedError + 30, 0142 ERR_CANNOT_LISTEN = KJob::UserDefinedError + 31, 0143 ERR_CANNOT_ACCEPT = KJob::UserDefinedError + 32, 0144 ERR_CANNOT_LOGIN = KJob::UserDefinedError + 33, 0145 ERR_CANNOT_STAT = KJob::UserDefinedError + 34, 0146 ERR_CANNOT_CLOSEDIR = KJob::UserDefinedError + 35, 0147 ERR_CANNOT_MKDIR = KJob::UserDefinedError + 37, 0148 ERR_CANNOT_RMDIR = KJob::UserDefinedError + 38, 0149 ERR_CANNOT_RESUME = KJob::UserDefinedError + 39, 0150 ERR_CANNOT_RENAME = KJob::UserDefinedError + 40, 0151 ERR_CANNOT_CHMOD = KJob::UserDefinedError + 41, 0152 ERR_CANNOT_DELETE = KJob::UserDefinedError + 42, 0153 // The text argument is the protocol that the dead worker supported. 0154 // This means for example: file, ftp, http, ... 0155 ERR_WORKER_DIED = KJob::UserDefinedError + 43, ///< @since 5.96 0156 ERR_OUT_OF_MEMORY = KJob::UserDefinedError + 44, 0157 ERR_UNKNOWN_PROXY_HOST = KJob::UserDefinedError + 45, 0158 ERR_CANNOT_AUTHENTICATE = KJob::UserDefinedError + 46, 0159 ERR_ABORTED = KJob::UserDefinedError + 47, ///< Action got aborted from application side 0160 ERR_INTERNAL_SERVER = KJob::UserDefinedError + 48, 0161 ERR_SERVER_TIMEOUT = KJob::UserDefinedError + 49, 0162 ERR_SERVICE_NOT_AVAILABLE = KJob::UserDefinedError + 50, 0163 ERR_UNKNOWN = KJob::UserDefinedError + 51, 0164 // (was a warning) ERR_CHECKSUM_MISMATCH = 52, 0165 ERR_UNKNOWN_INTERRUPT = KJob::UserDefinedError + 53, 0166 ERR_CANNOT_DELETE_ORIGINAL = KJob::UserDefinedError + 54, 0167 ERR_CANNOT_DELETE_PARTIAL = KJob::UserDefinedError + 55, 0168 ERR_CANNOT_RENAME_ORIGINAL = KJob::UserDefinedError + 56, 0169 ERR_CANNOT_RENAME_PARTIAL = KJob::UserDefinedError + 57, 0170 ERR_NEED_PASSWD = KJob::UserDefinedError + 58, 0171 ERR_CANNOT_SYMLINK = KJob::UserDefinedError + 59, 0172 ERR_NO_CONTENT = KJob::UserDefinedError + 60, ///< Action succeeded but no content will follow. 0173 ERR_DISK_FULL = KJob::UserDefinedError + 61, 0174 ERR_IDENTICAL_FILES = KJob::UserDefinedError + 62, ///< src==dest when moving/copying 0175 /** 0176 * For worker specified errors that can be 0177 * rich text. Email links will be handled 0178 * by the standard email app and all hrefs 0179 * will be handled by the standard browser. 0180 * <a href="exec:/khelpcenter ?" will be 0181 * forked. 0182 * @since 5.96 0183 */ 0184 ERR_WORKER_DEFINED = KJob::UserDefinedError + 63, 0185 ERR_UPGRADE_REQUIRED = KJob::UserDefinedError + 64, ///< A transport upgrade is required to access this 0186 ///< object. For instance, TLS is demanded by 0187 ///< the server in order to continue. 0188 ERR_POST_DENIED = KJob::UserDefinedError + 65, ///< Issued when trying to POST data to a certain Ports 0189 // see job.cpp 0190 ERR_CANNOT_SEEK = KJob::UserDefinedError + 66, 0191 ERR_CANNOT_SETTIME = KJob::UserDefinedError + 67, ///< Emitted by setModificationTime 0192 ERR_CANNOT_CHOWN = KJob::UserDefinedError + 68, 0193 ERR_POST_NO_SIZE = KJob::UserDefinedError + 69, 0194 ERR_DROP_ON_ITSELF = KJob::UserDefinedError + 70, ///< from KIO::DropJob, @since 5.6 0195 ERR_CANNOT_MOVE_INTO_ITSELF = KJob::UserDefinedError + 71, ///< emitted by KIO::move, @since 5.18 0196 ERR_PASSWD_SERVER = KJob::UserDefinedError + 72, ///< returned by WorkerBase::openPasswordDialog, @since 5.24 0197 ERR_CANNOT_CREATE_WORKER = KJob::UserDefinedError + 73, ///< used by Worker::createWorker, @since 5.96 0198 ERR_FILE_TOO_LARGE_FOR_FAT32 = KJob::UserDefinedError + 74, ///< @since 5.54 0199 ERR_OWNER_DIED ///< Value used between kuiserver and views when the job owner disappears unexpectedly. It should not be emitted by workers. @since 5.54 0200 = KJob::UserDefinedError + 75, 0201 ERR_PRIVILEGE_NOT_REQUIRED = KJob::UserDefinedError + 76, ///< used by file ioworker, @since 5.60 0202 ERR_CANNOT_TRUNCATE = KJob::UserDefinedError + 77, // used by FileJob::truncate, @since 5.66 0203 /** 0204 * Indicates failure to create a symlink due to the underlying filesystem (FAT/ExFAT) 0205 * not supporting them. Used by e.g. CopyJob. 0206 * @since 5.88 0207 */ 0208 ERR_SYMLINKS_NOT_SUPPORTED = KJob::UserDefinedError + 78, 0209 0210 /** 0211 * Moving files/dirs to the Trash failed due to size constraints. 0212 * 0213 * @since 5.100 0214 */ 0215 ERR_TRASH_FILE_TOO_LARGE = KJob::UserDefinedError + 79, 0216 }; 0217 0218 /** 0219 * Specifies how to use the cache. 0220 * @see parseCacheControl() 0221 * @see getCacheControlString() 0222 */ 0223 enum CacheControl { 0224 CC_CacheOnly, ///< Fail request if not in cache 0225 CC_Cache, ///< Use cached entry if available 0226 CC_Verify, ///< Validate cached entry with remote site if expired 0227 CC_Refresh, ///< Always validate cached entry with remote site 0228 CC_Reload, ///< Always fetch from remote site. 0229 }; 0230 0231 /** 0232 * Specifies privilege file operation status. 0233 * @since 5.43 0234 */ 0235 enum PrivilegeOperationStatus { 0236 OperationAllowed = 1, 0237 OperationCanceled, 0238 OperationNotAllowed, 0239 }; 0240 0241 /** 0242 * Describes the fields that a stat command will retrieve 0243 * @see UDSEntry 0244 * @see StatDetails 0245 * @since 5.69 0246 */ 0247 enum StatDetail { 0248 /// No field returned, useful to check if a file exists 0249 StatNoDetails = 0x0, 0250 /// Filename, access, type, size, linkdest 0251 StatBasic = 0x1, 0252 /// uid, gid 0253 StatUser = 0x2, 0254 /// atime, mtime, btime 0255 StatTime = 0x4, 0256 /// Resolve symlinks 0257 StatResolveSymlink = 0x8, 0258 /// ACL data 0259 StatAcl = 0x10, 0260 /// dev, inode 0261 StatInode = 0x20, 0262 /// Recursive size 0263 /// @since 5.70 0264 StatRecursiveSize = 0x40, 0265 /// MIME type 0266 /// @since 5.82 0267 StatMimeType = 0x80, 0268 0269 /// Default StatDetail flag when creating a @c StatJob. 0270 /// Equivalent to setting <tt>StatBasic | StatUser | StatTime | StatAcl | StatResolveSymlink</tt> 0271 StatDefaultDetails = StatBasic | StatUser | StatTime | StatAcl | StatResolveSymlink, 0272 }; 0273 /** 0274 * Stores a combination of #StatDetail values. 0275 */ 0276 Q_DECLARE_FLAGS(StatDetails, StatDetail) 0277 0278 Q_DECLARE_OPERATORS_FOR_FLAGS(KIO::StatDetails) 0279 0280 /** 0281 * Parses the string representation of the cache control option. 0282 * 0283 * @param cacheControl the string representation 0284 * @return the cache control value 0285 * @see getCacheControlString() 0286 */ 0287 KIOCORE_EXPORT KIO::CacheControl parseCacheControl(const QString &cacheControl); 0288 0289 /** 0290 * Returns a string representation of the given cache control method. 0291 * 0292 * @param cacheControl the cache control method 0293 * @return the string representation 0294 * @see parseCacheControl() 0295 */ 0296 KIOCORE_EXPORT QString getCacheControlString(KIO::CacheControl cacheControl); 0297 0298 /** 0299 * Return the "favicon" (see http://www.favicon.com) for the given @p url, 0300 * if available. Does NOT attempt to download the favicon, it only returns 0301 * one that is already available. 0302 * 0303 * If unavailable, returns QString(). 0304 * Use KIO::FavIconRequestJob instead of this method if you can wait 0305 * for the favicon to be downloaded. 0306 * 0307 * @param url the URL of the favicon 0308 * @return the path to the icon (to be passed to QIcon()), or QString() 0309 * 0310 * @since 5.0 0311 */ 0312 KIOCORE_EXPORT QString favIconForUrl(const QUrl &url); 0313 0314 /** 0315 * Converts KIO file permissions from mode_t to QFile::Permissions format. 0316 * 0317 * This is a convenience function for converting KIO permissions parameter from 0318 * mode_t to QFile::Permissions. 0319 * 0320 * @param permissions KIO file permissions. 0321 * 0322 * @return -1 if @p permissions is -1, otherwise its OR'ed QFile::Permission equivalent. 0323 */ 0324 KIOCORE_EXPORT QFile::Permissions convertPermissions(int permissions); 0325 0326 /** 0327 * Return the icon name for a URL. 0328 * Most of the time this returns the MIME type icon, 0329 * but also has fallback to favicon and protocol-specific icon. 0330 * 0331 * Pass this to QIcon::fromTheme(). 0332 * 0333 * @since 5.0 0334 */ 0335 KIOCORE_EXPORT QString iconNameForUrl(const QUrl &url); 0336 0337 /** 0338 * This function is useful to implement the "Up" button in a file manager for example. 0339 * 0340 * @return a URL that is a level higher 0341 * 0342 * @since 5.0 0343 */ 0344 KIOCORE_EXPORT QUrl upUrl(const QUrl &url); 0345 0346 } 0347 #endif