1// -*- c-basic-offset: 2 -*-
2/* This file is part of the KDE libraries
3 Copyright (C) 2000-2005 David Faure <faure@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License version 2 as published by the Free Software Foundation.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 Boston, MA 02110-1301, USA.
18*/
19#ifndef KIO_GLOBAL_H
20#define KIO_GLOBAL_H
21
22#include <kio/kio_export.h>
23
24#include <QtCore/QString>
25#include <QtCore/QHash>
26#include <QtCore/QMap>
27#include <QtCore/QList>
28#include <QtCore/QVariant>
29#include <QtCore/QFile> // for QFile::Permissions
30
31#include <kiconloader.h>
32#include <QtGui/QPixmap> // for pixmapForUrl
33
34#include <sys/stat.h> // S_ISDIR
35#include <sys/types.h> // mode_t
36
37#include <kjob.h>
38
39#ifdef Q_CC_MSVC
40template class KDE_EXPORT QMap<QString, QString>;
41#endif
42
43class KUrl;
44class KJobTrackerInterface;
45
46class QTime;
47
48/**
49 * @short A namespace for KIO globals
50 *
51 */
52namespace KIO
53{
54 /// 64-bit file offset
55 typedef qlonglong fileoffset_t;
56 /// 64-bit file size
57 typedef qulonglong filesize_t;
58
59 /**
60 * Converts @p size from bytes to the string representation.
61 *
62 * @param size size in bytes
63 * @return converted size as a string - e.g. 123.4 KiB , 12.0 MiB
64 */
65 KIO_EXPORT QString convertSize( KIO::filesize_t size );
66
67 /**
68 * Converts a size to a string representation
69 * Not unlike QString::number(...)
70 *
71 * @param size size in bytes
72 * @return converted size as a string - e.g. 123456789
73 */
74 KIO_EXPORT QString number( KIO::filesize_t size );
75
76 /**
77 * Converts size from kibi-bytes (2^10) to the string representation.
78 *
79 * @param kibSize size in kibi-bytes (2^10)
80 * @return converted size as a string - e.g. 123.4 KiB , 12.0 MiB
81 */
82 KIO_EXPORT QString convertSizeFromKiB( KIO::filesize_t kibSize );
83
84 /**
85 * Calculates remaining time in seconds from total size, processed size and speed.
86 *
87 * @param totalSize total size in bytes
88 * @param processedSize processed size in bytes
89 * @param speed speed in bytes per second
90 * @return calculated remaining time in seconds
91 */
92 KIO_EXPORT unsigned int calculateRemainingSeconds( KIO::filesize_t totalSize,
93 KIO::filesize_t processedSize, KIO::filesize_t speed );
94
95 /**
96 * Convert @p seconds to a string representing number of days, hours, minutes and seconds
97 *
98 * @param seconds number of seconds to convert
99 * @return string representation in a locale depending format
100 */
101 KIO_EXPORT QString convertSeconds( unsigned int seconds );
102
103 /**
104 * Calculates remaining time from total size, processed size and speed.
105 * Warning: As QTime is limited to 23:59:59, use calculateRemainingSeconds() instead
106 *
107 * @param totalSize total size in bytes
108 * @param processedSize processed size in bytes
109 * @param speed speed in bytes per second
110 * @return calculated remaining time
111 */
112#ifndef KDE_NO_DEPRECATED
113 KIO_EXPORT_DEPRECATED QTime calculateRemaining( KIO::filesize_t totalSize, KIO::filesize_t processedSize, KIO::filesize_t speed );
114#endif
115
116 /**
117 * Helper for showing information about a set of files and directories
118 * @param items the number of items (= @p files + @p dirs + number of symlinks :)
119 * @param files the number of files
120 * @param dirs the number of dirs
121 * @param size the sum of the size of the @p files
122 * @param showSize whether to show the size in the result
123 * @return the summary string
124 */
125 KIO_EXPORT QString itemsSummaryString(uint items, uint files, uint dirs, KIO::filesize_t size, bool showSize);
126
127 /**
128 * Encodes (from the text displayed to the real filename)
129 * This translates '/' into a "unicode fraction slash", QChar(0x2044).
130 * Used by KIO::link, for instance.
131 * @param str the file name to encode
132 * @return the encoded file name
133 */
134 KIO_EXPORT QString encodeFileName( const QString & str );
135 /**
136 * Decodes (from the filename to the text displayed)
137 * This doesn't do anything anymore, it used to do the opposite of encodeFileName
138 * when encodeFileName was using %2F for '/'.
139 * @param str the file name to decode
140 * @return the decoded file name
141 */
142 KIO_EXPORT QString decodeFileName( const QString & str );
143
144 /**
145 * @internal
146 * Commands that can be invoked by a job.
147 *
148 * (Move this to a non-public header)
149 */
150 enum Command {
151 CMD_HOST = '0', // 48
152 CMD_CONNECT = '1', // 49
153 CMD_DISCONNECT = '2', // 50
154 CMD_SLAVE_STATUS = '3', // 51
155 CMD_SLAVE_CONNECT = '4', // 52
156 CMD_SLAVE_HOLD = '5', // 53
157 CMD_NONE = 'A', // 65
158 CMD_TESTDIR = 'B', // 66
159 CMD_GET = 'C', // 67
160 CMD_PUT = 'D', // 68
161 CMD_STAT = 'E', // 69
162 CMD_MIMETYPE = 'F', // 70
163 CMD_LISTDIR = 'G', // 71
164 CMD_MKDIR = 'H', // 72
165 CMD_RENAME = 'I', // 73
166 CMD_COPY = 'J', // 74
167 CMD_DEL = 'K', // 75
168 CMD_CHMOD = 'L', // 76
169 CMD_SPECIAL = 'M', // 77
170 CMD_SETMODIFICATIONTIME = 'N', // 78
171 CMD_REPARSECONFIGURATION = 'O', // 79
172 CMD_META_DATA = 'P', // 80
173 CMD_SYMLINK = 'Q', // 81
174 CMD_SUBURL = 'R', // 82 Inform the slave about the url it is streaming on.
175 CMD_MESSAGEBOXANSWER = 'S', // 83
176 CMD_RESUMEANSWER = 'T', // 84
177 CMD_CONFIG = 'U', // 85
178 CMD_MULTI_GET = 'V', // 86
179 CMD_SETLINKDEST = 'W', // 87
180 CMD_OPEN = 'X', // 88
181 CMD_CHOWN = 'Y', // 89
182 CMD_READ = 'Z', // 90
183 CMD_WRITE = 91,
184 CMD_SEEK = 92,
185 CMD_CLOSE = 93,
186 CMD_HOST_INFO = 94
187 // Add new ones here once a release is done, to avoid breaking binary compatibility.
188 // Note that protocol-specific commands shouldn't be added here, but should use special.
189 };
190
191 /**
192 * Error codes that can be emitted by KIO.
193 */
194 enum Error {
195 ERR_CANNOT_OPEN_FOR_READING = KJob::UserDefinedError + 1,
196 ERR_CANNOT_OPEN_FOR_WRITING = KJob::UserDefinedError + 2,
197 ERR_CANNOT_LAUNCH_PROCESS = KJob::UserDefinedError + 3,
198 ERR_INTERNAL = KJob::UserDefinedError + 4,
199 ERR_MALFORMED_URL = KJob::UserDefinedError + 5,
200 ERR_UNSUPPORTED_PROTOCOL = KJob::UserDefinedError + 6,
201 ERR_NO_SOURCE_PROTOCOL = KJob::UserDefinedError + 7,
202 ERR_UNSUPPORTED_ACTION = KJob::UserDefinedError + 8,
203 ERR_IS_DIRECTORY = KJob::UserDefinedError + 9, // ... where a file was expected
204 ERR_IS_FILE = KJob::UserDefinedError + 10, // ... where a directory was expected (e.g. listing)
205 ERR_DOES_NOT_EXIST = KJob::UserDefinedError + 11,
206 ERR_FILE_ALREADY_EXIST = KJob::UserDefinedError + 12,
207 ERR_DIR_ALREADY_EXIST = KJob::UserDefinedError + 13,
208 ERR_UNKNOWN_HOST = KJob::UserDefinedError + 14,
209 ERR_ACCESS_DENIED = KJob::UserDefinedError + 15,
210 ERR_WRITE_ACCESS_DENIED = KJob::UserDefinedError + 16,
211 ERR_CANNOT_ENTER_DIRECTORY = KJob::UserDefinedError + 17,
212 ERR_PROTOCOL_IS_NOT_A_FILESYSTEM = KJob::UserDefinedError + 18,
213 ERR_CYCLIC_LINK = KJob::UserDefinedError + 19,
214 ERR_USER_CANCELED = KJob::KilledJobError,
215 ERR_CYCLIC_COPY = KJob::UserDefinedError + 21,
216 ERR_COULD_NOT_CREATE_SOCKET = KJob::UserDefinedError + 22, // KDE4: s/COULD_NOT/CANNOT/ or the other way round
217 ERR_COULD_NOT_CONNECT = KJob::UserDefinedError + 23,
218 ERR_CONNECTION_BROKEN = KJob::UserDefinedError + 24,
219 ERR_NOT_FILTER_PROTOCOL = KJob::UserDefinedError + 25,
220 ERR_COULD_NOT_MOUNT = KJob::UserDefinedError + 26,
221 ERR_COULD_NOT_UNMOUNT = KJob::UserDefinedError + 27,
222 ERR_COULD_NOT_READ = KJob::UserDefinedError + 28,
223 ERR_COULD_NOT_WRITE = KJob::UserDefinedError + 29,
224 ERR_COULD_NOT_BIND = KJob::UserDefinedError + 30,
225 ERR_COULD_NOT_LISTEN = KJob::UserDefinedError + 31,
226 ERR_COULD_NOT_ACCEPT = KJob::UserDefinedError + 32,
227 ERR_COULD_NOT_LOGIN = KJob::UserDefinedError + 33,
228 ERR_COULD_NOT_STAT = KJob::UserDefinedError + 34,
229 ERR_COULD_NOT_CLOSEDIR = KJob::UserDefinedError + 35,
230 ERR_COULD_NOT_MKDIR = KJob::UserDefinedError + 37,
231 ERR_COULD_NOT_RMDIR = KJob::UserDefinedError + 38,
232 ERR_CANNOT_RESUME = KJob::UserDefinedError + 39,
233 ERR_CANNOT_RENAME = KJob::UserDefinedError + 40,
234 ERR_CANNOT_CHMOD = KJob::UserDefinedError + 41,
235 ERR_CANNOT_DELETE = KJob::UserDefinedError + 42,
236 // The text argument is the protocol that the dead slave supported.
237 // This means for example: file, ftp, http, ...
238 ERR_SLAVE_DIED = KJob::UserDefinedError + 43,
239 ERR_OUT_OF_MEMORY = KJob::UserDefinedError + 44,
240 ERR_UNKNOWN_PROXY_HOST = KJob::UserDefinedError + 45,
241 ERR_COULD_NOT_AUTHENTICATE = KJob::UserDefinedError + 46,
242 ERR_ABORTED = KJob::UserDefinedError + 47, // Action got aborted from application side
243 ERR_INTERNAL_SERVER = KJob::UserDefinedError + 48,
244 ERR_SERVER_TIMEOUT = KJob::UserDefinedError + 49,
245 ERR_SERVICE_NOT_AVAILABLE = KJob::UserDefinedError + 50,
246 ERR_UNKNOWN = KJob::UserDefinedError + 51,
247 // (was a warning) ERR_CHECKSUM_MISMATCH = 52,
248 ERR_UNKNOWN_INTERRUPT = KJob::UserDefinedError + 53,
249 ERR_CANNOT_DELETE_ORIGINAL = KJob::UserDefinedError + 54,
250 ERR_CANNOT_DELETE_PARTIAL = KJob::UserDefinedError + 55,
251 ERR_CANNOT_RENAME_ORIGINAL = KJob::UserDefinedError + 56,
252 ERR_CANNOT_RENAME_PARTIAL = KJob::UserDefinedError + 57,
253 ERR_NEED_PASSWD = KJob::UserDefinedError + 58,
254 ERR_CANNOT_SYMLINK = KJob::UserDefinedError + 59,
255 ERR_NO_CONTENT = KJob::UserDefinedError + 60, // Action succeeded but no content will follow.
256 ERR_DISK_FULL = KJob::UserDefinedError + 61,
257 ERR_IDENTICAL_FILES = KJob::UserDefinedError + 62, // src==dest when moving/copying
258 ERR_SLAVE_DEFINED = KJob::UserDefinedError + 63, // for slave specified errors that can be
259 // rich text. Email links will be handled
260 // by the standard email app and all hrefs
261 // will be handled by the standard browser.
262 // <a href="exec:/khelpcenter ?" will be
263 // forked.
264 ERR_UPGRADE_REQUIRED = KJob::UserDefinedError + 64, // A transport upgrade is required to access this
265 // object. For instance, TLS is demanded by
266 // the server in order to continue.
267 ERR_POST_DENIED = KJob::UserDefinedError + 65, // Issued when trying to POST data to a certain Ports
268 // see job.cpp
269 ERR_COULD_NOT_SEEK = KJob::UserDefinedError + 66,
270 ERR_CANNOT_SETTIME = KJob::UserDefinedError + 67, // Emitted by setModificationTime
271 ERR_CANNOT_CHOWN = KJob::UserDefinedError + 68,
272 ERR_POST_NO_SIZE = KJob::UserDefinedError + 69
273 };
274
275 /**
276 * Returns a translated error message for @p errorCode using the
277 * additional error information provided by @p errorText.
278 * @param errorCode the error code
279 * @param errorText the additional error text
280 * @return the created error string
281 */
282 KIO_EXPORT QString buildErrorString(int errorCode, const QString &errorText);
283
284 /**
285 * Returns a translated html error message for @p errorCode using the
286 * additional error information provided by @p errorText , @p reqUrl
287 * (the request URL), and the ioslave @p method .
288 * @param errorCode the error code
289 * @param errorText the additional error text
290 * @param reqUrl the request URL
291 * @param method the ioslave method
292 * @return the created error string
293 */
294 KIO_EXPORT QString buildHTMLErrorString(int errorCode, const QString &errorText,
295 const KUrl *reqUrl = 0L, int method = -1 );
296
297 /**
298 * Returns translated error details for @p errorCode using the
299 * additional error information provided by @p errorText , @p reqUrl
300 * (the request URL), and the ioslave @p method .
301 *
302 * @param errorCode the error code
303 * @param errorText the additional error text
304 * @param reqUrl the request URL
305 * @param method the ioslave method
306 * @return the following data:
307 * @li QString errorName - the name of the error
308 * @li QString techName - if not null, the more technical name of the error
309 * @li QString description - a description of the error
310 * @li QStringList causes - a list of possible causes of the error
311 * @li QStringList solutions - a liso of solutions for the error
312 */
313 KIO_EXPORT QByteArray rawErrorDetail(int errorCode, const QString &errorText,
314 const KUrl *reqUrl = 0L, int method = -1 );
315
316 /**
317 * Returns an appropriate error message if the given command @p cmd
318 * is an unsupported action (ERR_UNSUPPORTED_ACTION).
319 * @param protocol name of the protocol
320 * @param cmd given command
321 * @see enum Command
322 */
323 KIO_EXPORT QString unsupportedActionErrorString(const QString &protocol, int cmd);
324
325 /**
326 * Specifies how to use the cache.
327 * @see parseCacheControl()
328 * @see getCacheControlString()
329 */
330 enum CacheControl
331 {
332 CC_CacheOnly, ///< Fail request if not in cache
333 CC_Cache, ///< Use cached entry if available
334 CC_Verify, ///< Validate cached entry with remote site if expired
335 CC_Refresh, ///< Always validate cached entry with remote site
336 CC_Reload ///< Always fetch from remote site.
337 };
338
339 /**
340 * Parses the string representation of the cache control option.
341 *
342 * @param cacheControl the string representation
343 * @return the cache control value
344 * @see getCacheControlString()
345 */
346 KIO_EXPORT KIO::CacheControl parseCacheControl(const QString &cacheControl);
347
348 /**
349 * Returns a string representation of the given cache control method.
350 *
351 * @param cacheControl the cache control method
352 * @return the string representation
353 * @see parseCacheControl()
354 */
355 KIO_EXPORT QString getCacheControlString(KIO::CacheControl cacheControl);
356
357 /**
358 * Convenience method to find the pixmap for a URL.
359 *
360 * Call this one when you don't know the mimetype.
361 *
362 * @param _url URL for the file.
363 * @param _mode the mode of the file. The mode may modify the icon
364 * with overlays that show special properties of the
365 * icon. Use 0 for default
366 * @param _group The icon group where the icon is going to be used.
367 * @param _force_size Override globally configured icon size.
368 * Use 0 for the default size
369 * @param _state The icon state, one of: KIconLoader::DefaultState,
370 * KIconLoader::ActiveState or KIconLoader::DisabledState.
371 * @param _path Output parameter to get the full path. Seldom needed.
372 * Ignored if 0
373 * @return the pixmap of the URL, can be a default icon if not found
374 */
375 KIO_EXPORT QPixmap pixmapForUrl( const KUrl & _url, mode_t _mode = 0, KIconLoader::Group _group = KIconLoader::Desktop,
376 int _force_size = 0, int _state = 0, QString * _path = 0 );
377
378 KIO_EXPORT KJobTrackerInterface *getJobTracker();
379
380 /**
381 * Converts KIO file permissions from mode_t to QFile::Permissions format.
382 *
383 * This is a convenience function for converting KIO permissions parameter from
384 * mode_t to QFile::Permissions.
385 *
386 * @param permissions KIO file permissions.
387 *
388 * @return -1 if @p permissions is -1, otherwise its OR'ed QFile::Permission equivalent.
389 * @since 4.12
390 */
391 KIO_EXPORT QFile::Permissions convertPermissions(int permissions);
392
393/**
394 * MetaData is a simple map of key/value strings.
395 */
396class KIO_EXPORT MetaData : public QMap<QString, QString>
397{
398public:
399 /**
400 * Creates an empty meta data map.
401 */
402 MetaData() : QMap<QString, QString>() { }
403 /**
404 * Copy constructor.
405 */
406 MetaData(const QMap<QString, QString>&metaData) :
407 QMap<QString, QString>(metaData) { }
408
409 /**
410 * Creates a meta data map from a QVaraint map.
411 * @since 4.3.1
412 */
413 MetaData(const QMap<QString,QVariant> &);
414
415 /**
416 * Adds the given meta data map to this map.
417 * @param metaData the map to add
418 * @return this map
419 */
420 MetaData & operator += ( const QMap<QString,QString> &metaData )
421 {
422 QMap<QString,QString>::ConstIterator it;
423 for(it = metaData.constBegin(); it != metaData.constEnd(); ++it)
424 {
425 insert(it.key(), it.value());
426 }
427 return *this;
428 }
429
430 /**
431 * Same as above except the value in the map is a QVariant.
432 *
433 * This convenience function allows you to easily assign the values
434 * of a QVariant to this meta data class.
435 *
436 * @param metaData the map to add
437 * @return this map
438 * @since 4.3.1
439 */
440 MetaData & operator += ( const QMap<QString,QVariant> &metaData );
441
442 /**
443 * Sets the given meta data map to this map.
444 * @param metaData the map to add
445 * @return this map
446 * @since 4.3.1
447 */
448 MetaData & operator = ( const QMap<QString,QVariant> &metaData );
449
450 /**
451 * Returns the contents of the map as a QVariant.
452 *
453 * @return a QVariant representation of the meta data map.
454 * @since 4.3.1
455 */
456 QVariant toVariant() const;
457};
458
459}
460#endif
461