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

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