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