1/* This file is part of the KDE project
2 Copyright (C) 1999-2006 David Faure <faure@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License as published by the Free Software Foundation; either
7 version 2 of the License, or (at your option) any later version.
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
20#ifndef KFILEITEM_H
21#define KFILEITEM_H
22
23#include <sys/stat.h>
24
25#include <kio/global.h>
26#include <kio/udsentry.h>
27#include <kurl.h>
28
29#include <kacl.h>
30#include <kmimetype.h>
31#include <kfilemetainfo.h>
32#include <kdatetime.h>
33#include <QtCore/QList>
34
35class KFileItemPrivate;
36
37/**
38 * A KFileItem is a generic class to handle a file, local or remote.
39 * In particular, it makes it easier to handle the result of KIO::listDir
40 * (UDSEntry isn't very friendly to use).
41 * It includes many file attributes such as mimetype, icon, text, mode, link...
42 *
43 * KFileItem is implicitly shared, i.e. it can be used as a value and copied around at almost no cost.
44 */
45class KIO_EXPORT KFileItem
46{
47public:
48 enum { Unknown = static_cast<mode_t>(-1) };
49
50 /**
51 * The timestamps associated with a file.
52 * - ModificationTime: the time the file's contents were last modified
53 * - AccessTime: the time the file was last accessed (last read or written to)
54 * - CreationTime: the time the file was created
55 */
56 enum FileTimes {
57 // warning: don't change without looking at the Private class
58 ModificationTime = 0,
59 AccessTime = 1,
60 CreationTime = 2
61 //ChangeTime
62 };
63
64 /**
65 * Null KFileItem. Doesn't represent any file, only exists for convenience.
66 *
67 * NOTE KDE 4.0 when porting from KFileItem* to KFileItem&:
68 * '(KFileItem*)a==0' becomes '(KFileItem)a.isNull()'
69 */
70 KFileItem();
71
72 /**
73 * Creates an item representing a file, from a UDSEntry.
74 * This is the preferred constructor when using KIO::listDir().
75 *
76 * @param entry the KIO entry used to get the file, contains info about it
77 * @param itemOrDirUrl the URL of the item or of the directory containing this item (see urlIsDirectory).
78 * @param delayedMimeTypes specifies if the mimetype of the given
79 * URL should be determined immediately or on demand.
80 * See the bool delayedMimeTypes in the KDirLister constructor.
81 * @param urlIsDirectory specifies if the url is just the directory of the
82 * fileitem and the filename from the UDSEntry should be used.
83 *
84 * When creating KFileItems out of the UDSEntry emitted by a KIO list job,
85 * use KFileItem(entry, listjob->url(), delayedMimeTypes, true);
86 */
87 KFileItem( const KIO::UDSEntry& entry, const KUrl& itemOrDirUrl,
88 bool delayedMimeTypes = false,
89 bool urlIsDirectory = false );
90
91 /**
92 * Creates an item representing a file, from all the necessary info for it.
93 * @param mode the file mode (according to stat() (e.g. S_IFDIR...)
94 * Set to KFileItem::Unknown if unknown. For local files, KFileItem will use stat().
95 * @param permissions the access permissions
96 * If you set both the mode and the permissions, you save a ::stat() for
97 * local files.
98 * Set to KFileItem::Unknown if you don't know the mode or the permission.
99 * @param url the file url
100 *
101 * @param delayedMimeTypes specify if the mimetype of the given URL
102 * should be determined immediately or on demand
103 */
104 KFileItem( mode_t mode, mode_t permissions, const KUrl& url,
105 bool delayedMimeTypes = false );
106
107 /**
108 * Creates an item representing a file, for which the mimetype is already known.
109 * @param url the file url
110 * @param mimeType the name of the file's mimetype
111 * @param mode the mode (S_IFDIR...)
112 */
113 KFileItem( const KUrl &url, const QString &mimeType, mode_t mode );
114
115 /**
116 * Copy constructor
117 */
118 KFileItem(const KFileItem& other);
119 /**
120 * Assignment operator
121 */
122 KFileItem& operator=(const KFileItem& other);
123
124 /**
125 * Destructs the KFileItem. Extra data set via setExtraData()
126 * is not deleted.
127 */
128 ~KFileItem();
129
130 /**
131 * Throw away and re-read (for local files) all information about the file.
132 * This is called when the _file_ changes.
133 */
134 void refresh();
135
136 /**
137 * Re-reads mimetype information.
138 * This is called when the mimetype database changes.
139 */
140 void refreshMimeType();
141
142 /**
143 * Returns the url of the file.
144 * @return the url of the file
145 */
146 KUrl url() const;
147
148 /**
149 * Sets the item's URL. Do not call unless you know what you are doing!
150 * (used for example when an item got renamed).
151 * @param url the item's URL
152 */
153 void setUrl( const KUrl &url );
154
155 /**
156 * Sets the item's name (i.e. the filename).
157 * This is automatically done by setUrl, to set the name from the URL's fileName().
158 * This method is provided for some special cases like relative paths as names (KFindPart)
159 * @param name the item's name
160 */
161 void setName( const QString &name );
162
163 /**
164 * Returns the permissions of the file (stat.st_mode containing only permissions).
165 * @return the permissions of the file
166 */
167 mode_t permissions() const;
168
169 /**
170 * Returns the access permissions for the file as a string.
171 * @return the access persmission as string
172 */
173 QString permissionsString() const;
174
175 /**
176 * Tells if the file has extended access level information ( Posix ACL )
177 * @return true if the file has extend ACL information or false if it hasn't
178 */
179 bool hasExtendedACL() const;
180
181 /**
182 * Returns the access control list for the file.
183 * @return the access control list as a KACL
184 */
185 KACL ACL() const;
186
187 /**
188 * Returns the default access control list for the directory.
189 * @return the default access control list as a KACL
190 */
191 KACL defaultACL() const;
192
193 /**
194 * Returns the file type (stat.st_mode containing only S_IFDIR, S_IFLNK, ...).
195 * @return the file type
196 */
197 mode_t mode() const;
198
199 /**
200 * Returns the owner of the file.
201 * @return the file's owner
202 */
203 QString user() const;
204
205 /**
206 * Returns the group of the file.
207 * @return the file's group
208 */
209 QString group() const;
210
211 /**
212 * Returns true if this item represents a link in the UNIX sense of
213 * a link.
214 * @return true if the file is a link
215 */
216 bool isLink() const;
217
218 /**
219 * Returns true if this item represents a directory.
220 * @return true if the item is a directory
221 */
222 bool isDir() const;
223
224 /**
225 * Returns true if this item represents a file (and not a a directory)
226 * @return true if the item is a file
227 */
228 bool isFile() const;
229
230 /**
231 * Checks whether the file or directory is readable. In some cases
232 * (remote files), we may return true even though it can't be read.
233 * @return true if the file can be read - more precisely,
234 * false if we know for sure it can't
235 */
236 bool isReadable() const;
237
238 /**
239 * Checks whether the file or directory is writable. In some cases
240 * (remote files), we may return true even though it can't be written to.
241 * @return true if the file or directory can be written to - more precisely,
242 * false if we know for sure it can't
243 */
244 bool isWritable() const;
245
246 /**
247 * Checks whether the file is hidden.
248 * @return true if the file is hidden.
249 */
250 bool isHidden() const;
251
252 /**
253 * @return true if the file is a remote URL, or a local file on a network mount.
254 * It will return false only for really-local file systems.
255 * @since 4.7.4
256 */
257 bool isSlow() const;
258
259 /**
260 * Checks whether the file is a readable local .desktop file,
261 * i.e. a file whose path can be given to KDesktopFile
262 * @return true if the file is a desktop file.
263 * @since 4.1
264 */
265 bool isDesktopFile() const;
266
267 /**
268 * Returns the link destination if isLink() == true.
269 * @return the link destination. QString() if the item is not a link
270 */
271 QString linkDest() const;
272
273 /**
274 * Returns the target url of the file, which is the same as url()
275 * in cases where the slave doesn't specify UDS_TARGET_URL
276 * @return the target url.
277 * @since 4.1
278 */
279 KUrl targetUrl() const;
280
281 /**
282 * Returns the resource URI to be used for Nepomuk annotations. In case
283 * the slave does not specify UDS_NEPOMUK_URI an invalid url is
284 * returned.
285 * For local files this is the same as url().
286 * @return The Nepomuk resource URI.
287 * @since 4.4
288 */
289 KUrl nepomukUri() const;
290
291 /**
292 * Returns the local path if isLocalFile() == true or the KIO item has
293 * a UDS_LOCAL_PATH atom.
294 * @return the item local path, or QString() if not known
295 */
296 QString localPath() const;
297
298 /**
299 * Returns the size of the file, if known.
300 * @return the file size, or 0 if not known
301 */
302 KIO::filesize_t size() const;
303
304 /**
305 * Requests the modification, access or creation time, depending on @p which.
306 * @param which the timestamp
307 * @return the time asked for, (time_t)0 if not available
308 * @see timeString()
309 */
310 KDateTime time( FileTimes which ) const;
311#ifndef KDE_NO_DEPRECATED
312 KDE_DEPRECATED time_t time( unsigned int which ) const;
313#endif
314
315 /**
316 * Requests the modification, access or creation time as a string, depending
317 * on @p which.
318 * @param which the timestamp
319 * @returns a formatted string of the requested time.
320 * @see time
321 */
322 QString timeString( FileTimes which = ModificationTime ) const;
323#ifndef KDE_NO_DEPRECATED
324 KDE_DEPRECATED QString timeString( unsigned int which) const;
325#endif
326
327 /**
328 * Returns true if the file is a local file.
329 * @return true if the file is local, false otherwise
330 */
331 bool isLocalFile() const;
332
333 /**
334 * Returns the text of the file item.
335 * It's not exactly the filename since some decoding happens ('%2F'->'/').
336 * @return the text of the file item
337 */
338 QString text() const;
339
340 /**
341 * Return the name of the file item (without a path).
342 * Similar to text(), but unencoded, i.e. the original name.
343 * @param lowerCase if true, the name will be returned in lower case,
344 * which is useful to speed up sorting by name, case insensitively.
345 * @return the file's name
346 */
347 QString name( bool lowerCase = false ) const;
348
349 /**
350 * Returns the mimetype of the file item.
351 * If @p delayedMimeTypes was used in the constructor, this will determine
352 * the mimetype first. Equivalent to determineMimeType()->name()
353 * @return the mime type of the file
354 */
355 QString mimetype() const;
356
357 /**
358 * Returns the mimetype of the file item.
359 * If delayedMimeTypes was used in the constructor, this will determine
360 * the mimetype first.
361 * @return the mime type
362 */
363 KMimeType::Ptr determineMimeType() const;
364
365 /**
366 * Returns the currently known mimetype of the file item.
367 * This will not try to determine the mimetype if unknown.
368 * @return the known mime type
369 */
370 KMimeType::Ptr mimeTypePtr() const;
371
372 /**
373 * @return true if we have determined the final icon of this file already.
374 * @since 4.10.2
375 */
376 bool isFinalIconKnown() const;
377
378 /**
379 * @return true if we have determined the mimetype of this file already,
380 * i.e. if determineMimeType() will be fast. Otherwise it will have to
381 * find what the mimetype is, which is a possibly slow operation; usually
382 * this is delayed until necessary.
383 */
384 bool isMimeTypeKnown() const;
385
386 /**
387 * Returns the user-readable string representing the type of this file,
388 * like "OpenDocument Text File".
389 * @return the type of this KFileItem
390 */
391 QString mimeComment() const;
392
393 /**
394 * Returns the full path name to the icon that represents
395 * this mime type.
396 * @return iconName the name of the file's icon
397 */
398 QString iconName() const;
399
400 /**
401 * Returns a pixmap representing the file.
402 * @param _size Size for the pixmap in pixels. Zero will return the
403 * globally configured default size.
404 * @param _state The state of the icon: KIconLoader::DefaultState,
405 * KIconLoader::ActiveState or KIconLoader::DisabledState.
406 * @return the pixmap
407 */
408 QPixmap pixmap( int _size, int _state=0 ) const;
409
410 /**
411 * Returns the overlays (bitfield of KIconLoader::*Overlay flags) that are used
412 * for this item's pixmap. Overlays are used to show for example, whether
413 * a file can be modified.
414 * @return the overlays of the pixmap
415 */
416 QStringList overlays() const;
417
418 /**
419 * A comment which can contain anything - even rich text. It will
420 * simply be displayed to the user as is.
421 *
422 * @since 4.6
423 */
424 QString comment() const;
425
426 /**
427 * Returns the string to be displayed in the statusbar,
428 * e.g. when the mouse is over this item
429 * @return the status bar information
430 */
431 QString getStatusBarInfo() const;
432
433 /**
434 * Returns the string to be displayed in the tool tip when the mouse
435 * is over this item. This may load a plugin to determine additional
436 * information specific to the mimetype of the file.
437 *
438 * @param maxcount the maximum number of entries shown
439 * @return the tool tip string
440 *
441 * @deprecated File Managers implement more complete tooltips.
442 */
443#ifndef KDE_NO_DEPRECATED
444 KDE_DEPRECATED QString getToolTipText(int maxcount = 6) const;
445#endif
446
447 /**
448 * Returns true if files can be dropped over this item.
449 * Contrary to popular belief, not only dirs will return true :)
450 * Executables, .desktop files, will do so as well.
451 * @return true if you can drop files over the item
452 *
453 * @deprecated This logic is application-dependent, the behavior described above
454 * mostly makes sense for file managers only.
455 * KDirModel has setDropsAllowed for similar (but configurable) logic.
456 */
457#ifndef KDE_NO_DEPRECATED
458 KDE_DEPRECATED bool acceptsDrops() const;
459#endif
460
461 /**
462 * Let's "KRun" this file !
463 * (e.g. when file is clicked or double-clicked or return is pressed)
464 */
465 void run( QWidget* parentWidget = 0 ) const;
466
467 /**
468 * Returns the UDS entry. Used by the tree view to access all details
469 * by position.
470 * @return the UDS entry
471 */
472 KIO::UDSEntry entry() const;
473
474 /**
475 * Used when updating a directory. marked == seen when refreshing.
476 * @return true if the file item is marked
477 */
478 bool isMarked() const;
479 /**
480 * Marks the item.
481 * @see isMarked()
482 */
483 void mark();
484 /**
485 * Unmarks the item.
486 * @see isMarked()
487 */
488 void unmark();
489
490 /**
491 * Return true if this item is a regular file,
492 * false otherwise (directory, link, character/block device, fifo, socket)
493 * @since 4.3
494 */
495 bool isRegularFile() const;
496
497 /**
498 * Somewhat like a comparison operator, but more explicit,
499 * and it can detect that two fileitems differ if any property of the file item
500 * has changed (file size, modification date, etc.). Two items are equal if
501 * all properties are equal. In contrast, operator== only compares URLs.
502 * @param item the item to compare
503 * @return true if all values are equal
504 */
505 bool cmp( const KFileItem & item ) const;
506
507 /**
508 * Returns true if both items share the same URL.
509 */
510 bool operator==(const KFileItem& other) const;
511
512 /**
513 * Returns true if both items do not share the same URL.
514 */
515 bool operator!=(const KFileItem& other) const;
516
517
518 /**
519 * Converts this KFileItem to a QVariant, this allows to use KFileItem
520 * in QVariant() constructor
521 */
522 operator QVariant() const;
523
524 /**
525 * This allows to associate some "extra" data to a KFileItem. As one
526 * KFileItem can be used by several objects (often views) which all need
527 * to add some data, you have to use a key to reference your extra data
528 * within the KFileItem.
529 *
530 * That way a KFileItem can hold and provide access to all those views
531 * separately.
532 *
533 * I.e. a KFileIconView that associates a KFileIconViewItem (an item suitable
534 * for use with QIconView) does
535 *
536 * \code
537 * kfileItem->setExtraData( this, iconViewItem );
538 * \endcode
539 *
540 * and can later access the iconViewItem by doing
541 *
542 * \code
543 * KFileIconViewItem *iconViewItem = static_cast<KFileIconViewItem*>( kfileItem->extraData( this ));
544 * \endcode
545 *
546 * This is usually more efficient then having every view associate data to
547 * items by using a separate QDict or QMap.
548 *
549 * Note: you have to remove and destroy the data you associated yourself
550 * when you don't need it anymore!
551 *
552 * @param key the key of the extra data
553 * @param value the value of the extra data
554 * @see extraData
555 * @see removeExtraData
556 *
557 * @deprecated use model/view (KDirModel) and you won't need this anymore
558 */
559#ifndef KDE_NO_DEPRECATED
560 KDE_DEPRECATED void setExtraData( const void *key, void *value );
561#endif
562
563 /**
564 * Retrieves the extra data with the given @p key.
565 * @param key the key of the extra data
566 * @return the extra data associated to an item with @p key via
567 * setExtraData. 0L if nothing was associated with @p key.
568 * @see extraData
569 *
570 * @deprecated use model/view (KDirModel) and you won't need this anymore
571 */
572#ifndef KDE_NO_DEPRECATED
573 KDE_DEPRECATED const void * extraData( const void *key ) const;
574#endif
575
576 /**
577 * Removes the extra data associated with an item via @p key.
578 * @param key the key of the extra data to remove
579 *
580 * @deprecated use model/view (KDirModel) and you won't need this anymore
581 */
582#ifndef KDE_NO_DEPRECATED
583 KDE_DEPRECATED void removeExtraData( const void *key );
584#endif
585
586 /**
587 * Sets the metainfo of this item to @p info.
588 *
589 * Made const to avoid deep copy.
590 * @param info the new meta info
591 */
592 void setMetaInfo( const KFileMetaInfo & info ) const;
593
594 /**
595 * Returns the metainfo of this item.
596 *
597 * (since 4.4.3) By default it uses the KFileMetaInfo::ContentInfo | KFileMetaInfo::TechnicalInfo.
598 * If you need more information, create your own KFileMetaInfo object and set it using setMetaInfo()
599 * @param autoget if true, the metainfo will automatically be created
600 * @param what how much metainfo you need to retrieve from the file (KFileMetaInfo::WhatFlag)
601 */
602 KFileMetaInfo metaInfo(bool autoget = true,
603 int what = KFileMetaInfo::ContentInfo | KFileMetaInfo::TechnicalInfo) const;
604
605 /**
606 * @deprecated simply use '='
607 */
608#ifndef KDE_NO_DEPRECATED
609 KDE_DEPRECATED void assign( const KFileItem & item );
610#endif
611
612 /**
613 * Reinitialize KFileItem with a new UDSEntry.
614 *
615 * Note: extra-data set with setExtraData() is not changed or deleted, so
616 * be careful what you do!
617 *
618 * KDirListerCache uses it to save new/delete calls by updating existing
619 * items that are otherwise not needed anymore.
620 *
621 * @param entry the UDSEntry to assign to this KFileItem
622 * @param url the file url
623 * @param delayedMimeTypes specifies if the mimetype of the given
624 * URL should be determined immediately or on demand
625 * @param urlIsDirectory specifies if the url is just the directory of the
626 * fileitem and the filename from the UDSEntry should be used.
627 *
628 * @deprecated why not just create another KFileItem and use operator=,
629 * now that it's a value class?
630 */
631#ifndef KDE_NO_DEPRECATED
632 KDE_DEPRECATED void setUDSEntry( const KIO::UDSEntry& entry, const KUrl& url,
633 bool delayedMimeTypes = false,
634 bool urlIsDirectory = false );
635#endif
636
637 /**
638 * Tries to give a local URL for this file item if possible.
639 * The given boolean indicates if the returned url is local or not.
640 */
641 KUrl mostLocalUrl(bool &local) const; // KDE4 TODO: bool* local = 0
642
643 /**
644 * Tries to give a local URL for this file item if possible.
645 *
646 * \since 4.6
647 */
648 KUrl mostLocalUrl() const; // KDE5: merge with above version
649
650 /**
651 * Return true if default-constructed
652 */
653 bool isNull() const;
654
655private:
656 QSharedDataPointer<KFileItemPrivate> d;
657
658private:
659 KIO_EXPORT friend QDataStream & operator<< ( QDataStream & s, const KFileItem & a );
660 KIO_EXPORT friend QDataStream & operator>> ( QDataStream & s, KFileItem & a );
661
662 friend class KFileItemTest;
663};
664
665Q_DECLARE_METATYPE(KFileItem)
666
667Q_CORE_EXPORT uint qHash(const QString &key);
668inline uint qHash(const KFileItem& item){ return qHash(item.url().url()); }
669
670/**
671 * List of KFileItems, which adds a few helper
672 * methods to QList<KFileItem>.
673 */
674class KIO_EXPORT KFileItemList : public QList<KFileItem>
675{
676public:
677 /// Creates an empty list of file items.
678 KFileItemList();
679
680 /// Creates a new KFileItemList from a QList of file @p items.
681 KFileItemList( const QList<KFileItem> &items );
682
683 /**
684 * Find a KFileItem by name and return it.
685 * @return the item with the given name, or a null-item if none was found
686 * (see KFileItem::isNull())
687 */
688 KFileItem findByName( const QString& fileName ) const;
689
690 /**
691 * Find a KFileItem by URL and return it.
692 * @return the item with the given URL, or a null-item if none was found
693 * (see KFileItem::isNull())
694 */
695 KFileItem findByUrl( const KUrl& url ) const;
696
697 /// @return the list of URLs that those items represent
698 KUrl::List urlList() const;
699
700 /// @return the list of target URLs that those items represent
701 /// @since 4.2
702 KUrl::List targetUrlList() const;
703
704 // TODO KDE-5 add d pointer here so that we can merge KFileItemListProperties into KFileItemList
705};
706
707KIO_EXPORT QDataStream & operator<< ( QDataStream & s, const KFileItem & a );
708KIO_EXPORT QDataStream & operator>> ( QDataStream & s, KFileItem & a );
709
710/**
711 * Support for qDebug() << aFileItem
712 * \since 4.4
713 */
714KIO_EXPORT QDebug operator<<(QDebug stream, const KFileItem& item);
715
716#endif
717