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 |
40 | template class KDE_EXPORT QMap<QString, QString>; |
41 | #endif |
42 | |
43 | class KUrl; |
44 | class KJobTrackerInterface; |
45 | |
46 | class QTime; |
47 | |
48 | /** |
49 | * @short A namespace for KIO globals |
50 | * |
51 | */ |
52 | namespace 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 | */ |
396 | class KIO_EXPORT MetaData : public QMap<QString, QString> |
397 | { |
398 | public: |
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 | |