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 | class QUrl; |
18 | class 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> |
23 | typedef SSIZE_T ssize_t; |
24 | #endif |
25 | |
26 | /*! |
27 | * \namespace KIO |
28 | * \inmodule KIOCore |
29 | * \brief A namespace for KIO globals. |
30 | */ |
31 | namespace KIO |
32 | { |
33 | /// 64-bit file offset |
34 | typedef qlonglong fileoffset_t; |
35 | /// 64-bit file size |
36 | typedef 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 | */ |
45 | KIOCORE_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 | */ |
55 | KIOCORE_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 | */ |
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 | * \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 | */ |
77 | KIOCORE_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 | */ |
86 | KIOCORE_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 | */ |
102 | KIOCORE_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 | */ |
113 | KIOCORE_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 | */ |
123 | KIOCORE_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 | */ |
208 | enum 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 | */ |
302 | KIOCORE_DEPRECATED_VERSION(6, 6, "Not used" ) |
303 | enum 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 | */ |
320 | enum 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 | */ |
343 | enum 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 | }; |
355 | Q_DECLARE_FLAGS(StatDetails, StatDetail) |
356 | |
357 | Q_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 | */ |
372 | KIOCORE_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 | */ |
388 | KIOCORE_DEPRECATED_VERSION(6, 6, "Not used" ) |
389 | KIOCORE_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 | */ |
407 | KIOCORE_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 | */ |
419 | KIOCORE_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 | */ |
430 | KIOCORE_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 | */ |
439 | KIOCORE_EXPORT QUrl upUrl(const QUrl &url); |
440 | |
441 | } |
442 | #endif |
443 | |