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

source code of kio/src/core/global.h