1/*
2 This file is part of the KDE project
3 SPDX-FileCopyrightText: 1999-2006 David Faure <faure@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KFILEITEM_H
9#define KFILEITEM_H
10
11#include "kiocore_export.h"
12#include <QDateTime>
13#include <QFile>
14#include <QUrl>
15#include <kacl.h>
16#include <kio/global.h>
17#include <kio/udsentry.h>
18
19#include <QList>
20#include <QMimeType>
21#include <qplatformdefs.h>
22
23class KFileItemPrivate;
24
25/*!
26 * \class KFileItem
27 * \inmodule KIOCore
28 *
29 * \brief A KFileItem is a generic class to handle a file, local or remote.
30 *
31 * In particular, it makes it easier to handle the result of KIO::listDir
32 * (UDSEntry isn't very friendly to use).
33 * It includes many file attributes such as MIME type, icon, text, mode, link...
34 *
35 * KFileItem is implicitly shared, i.e. it can be used as a value and copied around at almost no cost.
36 */
37class KIOCORE_EXPORT KFileItem
38{
39 Q_GADGET
40
41 /*!
42 * \property KFileItem::url
43 */
44 Q_PROPERTY(QUrl url READ url WRITE setUrl)
45
46 /*!
47 * \property KFileItem::user
48 */
49 Q_PROPERTY(QString user READ user)
50
51 /*!
52 * \property KFileItem::group
53 */
54 Q_PROPERTY(QString group READ group)
55
56 /*!
57 * \property KFileItem::isLink
58 */
59 Q_PROPERTY(bool isLink READ isLink)
60
61 /*!
62 * \property KFileItem::isDir
63 */
64 Q_PROPERTY(bool isDir READ isDir)
65
66 /*!
67 * \property KFileItem::isFile
68 */
69 Q_PROPERTY(bool isFile READ isFile)
70
71 /*!
72 * \property KFileItem::isReadable
73 */
74 Q_PROPERTY(bool isReadable READ isReadable)
75
76 /*!
77 * \property KFileItem::isWritable
78 */
79 Q_PROPERTY(bool isWritable READ isWritable)
80
81 /*!
82 * \property KFileItem::isHidden
83 */
84 Q_PROPERTY(bool isHidden READ isHidden)
85
86 /*!
87 * \property KFileItem::isSlow
88 */
89 Q_PROPERTY(bool isSlow READ isSlow)
90
91 /*!
92 * \property KFileItem::isDesktopFile
93 */
94 Q_PROPERTY(bool isDesktopFile READ isDesktopFile)
95
96 /*!
97 * \property KFileItem::linkDest
98 */
99 Q_PROPERTY(QString linkDest READ linkDest)
100
101 /*!
102 * \property KFileItem::targetUrl
103 */
104 Q_PROPERTY(QUrl targetUrl READ targetUrl)
105
106 /*!
107 * \property KFileItem::localPath
108 */
109 Q_PROPERTY(QString localPath READ localPath WRITE setLocalPath)
110
111 /*!
112 * \property KFileItem::isLocalFile
113 */
114 Q_PROPERTY(bool isLocalFile READ isLocalFile)
115
116 /*!
117 * \property KFileItem::text
118 */
119 Q_PROPERTY(QString text READ text)
120
121 /*!
122 * \property KFileItem::name
123 */
124 Q_PROPERTY(QString name READ name WRITE setName)
125
126 /*!
127 * \property KFileItem::mimetype
128 */
129 Q_PROPERTY(QString mimetype READ mimetype)
130
131 /*!
132 * \property KFileItem::determineMimeType
133 */
134 Q_PROPERTY(QMimeType determineMimeType READ determineMimeType)
135
136 /*!
137 * \property KFileItem::currentMimeType
138 */
139 Q_PROPERTY(QMimeType currentMimeType READ currentMimeType)
140
141 /*!
142 * \property KFileItem::isFinalIconKnown
143 */
144 Q_PROPERTY(bool isFinalIconKnown READ isFinalIconKnown)
145
146 /*!
147 * \property KFileItem::isMimeTypeKnown
148 */
149 Q_PROPERTY(bool isMimeTypeKnown READ isMimeTypeKnown)
150
151 /*!
152 * \property KFileItem::mimeComment
153 */
154 Q_PROPERTY(QString mimeComment READ mimeComment)
155
156 /*!
157 * \property KFileItem::iconName
158 */
159 Q_PROPERTY(QString iconName READ iconName)
160
161 /*!
162 * \property KFileItem::overlays
163 */
164 Q_PROPERTY(QStringList overlays READ overlays)
165
166 /*!
167 * \property KFileItem::comment
168 */
169 Q_PROPERTY(QString comment READ comment)
170
171 /*!
172 * \property KFileItem::getStatusBarInfo
173 */
174 Q_PROPERTY(QString getStatusBarInfo READ getStatusBarInfo)
175
176 /*!
177 * \property KFileItem::isRegularFile
178 */
179 Q_PROPERTY(bool isRegularFile READ isRegularFile)
180
181public:
182 enum {
183 Unknown = static_cast<mode_t>(-1)
184 };
185
186 /*!
187 * The timestamps associated with a file.
188 *
189 * \value ModificationTime The time the file's contents were last modified
190 * \value AccessTime The time the file was last accessed (last read or written to)
191 * \value CreationTime The time the file was created
192 */
193 enum FileTimes {
194 // warning: don't change without looking at the Private class
195 ModificationTime = 0,
196 AccessTime = 1,
197 CreationTime = 2,
198 // ChangeTime
199 };
200 Q_ENUM(FileTimes)
201
202 /*!
203 * \value NormalMimeTypeDetermination
204 * \value SkipMimeTypeFromContent
205 */
206 enum MimeTypeDetermination {
207 NormalMimeTypeDetermination = 0,
208 SkipMimeTypeFromContent,
209 };
210 Q_ENUM(MimeTypeDetermination)
211
212 /*!
213 * Null KFileItem. Doesn't represent any file, only exists for convenience.
214 */
215 KFileItem();
216
217 /*!
218 * Creates an item representing a file, from a UDSEntry.
219 * This is the preferred constructor when using KIO::listDir().
220 *
221 * \a entry the KIO entry used to get the file, contains info about it
222 *
223 * \a itemOrDirUrl the URL of the item or of the directory containing this item (see urlIsDirectory).
224 *
225 * \a delayedMimeTypes specifies if the MIME type of the given
226 * URL should be determined immediately or on demand.
227 * See the bool delayedMimeTypes in the KDirLister constructor.
228 *
229 * \a urlIsDirectory specifies if the url is just the directory of the
230 * fileitem and the filename from the UDSEntry should be used.
231 *
232 * When creating KFileItems out of the UDSEntry emitted by a KIO list job,
233 * use KFileItem(entry, listjob->url(), delayedMimeTypes, true);
234 */
235 KFileItem(const KIO::UDSEntry &entry, const QUrl &itemOrDirUrl, bool delayedMimeTypes = false, bool urlIsDirectory = false);
236
237 /*!
238 * Creates an item representing a file, for which the MIME type is already known.
239 *
240 * \a url the file url
241 *
242 * \a mimeType the name of the file's MIME type
243 *
244 * \a mode the mode (S_IFDIR...)
245 */
246 explicit KFileItem(const QUrl &url, const QString &mimeType = QString(), mode_t mode = KFileItem::Unknown);
247
248 /*!
249 * Creates an item representing a file, with the option of skipping MIME type determination.
250 *
251 * \a url the file url
252 *
253 * \a mimeTypeDetermination the mode of determining the MIME type:
254 * \list
255 * \li NormalMimeTypeDetermination: By content if local file, i.e. access the file,
256 * open and read part of it;
257 * by QMimeDatabase::MatchMode::MatchExtension if not local.
258 * \li SkipMimeTypeFromContent: Always by QMimeDatabase::MatchMode::MatchExtension,
259 * i.e. won't access the file by stat() or opening it;
260 * only suitable for files, directories won't be recognized.
261 * \endlist
262 * \since 5.57
263 */
264 KFileItem(const QUrl &url, KFileItem::MimeTypeDetermination mimeTypeDetermination);
265
266 /*!
267 * Copy constructor
268 */
269 KFileItem(const KFileItem &);
270
271 ~KFileItem();
272
273 KFileItem(KFileItem &&);
274
275 KFileItem &operator=(const KFileItem &);
276
277 KFileItem &operator=(KFileItem &&);
278
279 /*!
280 * Throw away and re-read (for local files) all information about the file.
281 * This is called when the _file_ changes.
282 */
283 void refresh();
284
285 /*!
286 * Re-reads MIME type information.
287 * This is called when the MIME type database changes.
288 */
289 void refreshMimeType();
290
291 /*!
292 * Sets MIME type determination to be immediate or on demand.
293 * Call this after the constructor, and before using any MIME-type-related method.
294 * 5.0
295 */
296 void setDelayedMimeTypes(bool b);
297
298 /*!
299 * Returns the url of the file.
300 */
301 QUrl url() const;
302
303 /*!
304 * Sets the item's URL. Do not call unless you know what you are doing!
305 * (used for example when an item got renamed).
306 *
307 * \a url the item's URL
308 */
309 void setUrl(const QUrl &url);
310
311 /*!
312 * Sets the item's local path (UDS_LOCAL_PATH). Do not call unless you know what you are doing!
313 * This won't change the item's name or URL.
314 * (used for example when an item got renamed).
315 *
316 * \a path the item's local path
317 * \since 5.20
318 */
319 void setLocalPath(const QString &path);
320
321 /*!
322 * Sets the item's name (i.e.\ the filename).
323 * This is automatically done by setUrl, to set the name from the URL's fileName().
324 * This method is provided for some special cases like relative paths as names (KFindPart)
325 *
326 * \a name the item's name
327 */
328 void setName(const QString &name);
329
330 /*!
331 * Returns the permissions of the file (stat.st_mode containing only permissions).
332 */
333 mode_t permissions() const;
334
335 /*!
336 * Returns the access permissions for the file as a string.
337 */
338 QString permissionsString() const;
339
340 /*!
341 * Tells if the file has extended access level information ( Posix ACL )
342 */
343 bool hasExtendedACL() const;
344
345 /*!
346 * Returns the access control list for the file.
347 */
348 KACL ACL() const;
349
350 /*!
351 * Returns the default access control list for the directory.
352 */
353 KACL defaultACL() const;
354
355 /*!
356 * Returns the file type (stat.st_mode containing only S_IFDIR, S_IFLNK, ...).
357 */
358 mode_t mode() const;
359
360 /*!
361 * Returns the file's owner's user id.
362 * Available only on supported protocols.
363 * \since 6.0
364 */
365 int userId() const;
366
367 /*!
368 * Returns the file's owner's group id.
369 * Available only on supported protocols.
370 * \since 6.0
371 */
372 int groupId() const;
373
374 /*!
375 * Returns the owner of the file.
376 */
377 QString user() const;
378
379 /*!
380 * Returns the group of the file.
381 */
382 QString group() const;
383
384 /*!
385 * Returns \c true if this item represents a link in the UNIX sense of
386 * a link.
387 */
388 bool isLink() const;
389
390 /*!
391 * Returns \c true if this item represents a directory.
392 */
393 bool isDir() const;
394
395 /*!
396 * Returns \c true if this item represents a file (and not a directory)
397 */
398 bool isFile() const;
399
400 /*!
401 * Checks whether the file or directory is readable. In some cases
402 * (remote files), we may return \c true even though it can't be read.
403 *
404 * Returns \c true if the file can be read - more precisely,
405 * false if we know for sure it can't
406 */
407 bool isReadable() const;
408
409 /*!
410 * Checks whether the file or directory is writable. In some cases
411 * (remote files), we may return \c true even though it can't be written to.
412 *
413 * Returns \c true if the file or directory can be written to - more precisely,
414 * false if we know for sure it can't
415 */
416 bool isWritable() const;
417
418 /*!
419 * Checks whether the file is hidden.
420 *
421 * Returns \c true if the file is hidden.
422 */
423 bool isHidden() const;
424
425 /*!
426 * Returns \c true if the file is a remote URL, or a local file on a network mount.
427 * It will return \c false only for really-local file systems.
428 * \since 4.7.4
429 */
430 bool isSlow() const;
431
432 /*!
433 * Checks whether the file is a readable local .desktop file,
434 * i.e. a file whose path can be given to KDesktopFile
435 *
436 * Returns \c true if the file is a desktop file.
437 */
438 bool isDesktopFile() const;
439
440 /*!
441 * Returns the link destination if isLink() == true, or QString() if the item is not a link
442 */
443 QString linkDest() const;
444
445 /*!
446 * Returns the target url of the file, which is the same as url()
447 * in cases where the worker doesn't specify UDS_TARGET_URL
448 */
449 QUrl targetUrl() const;
450
451 /*!
452 * Returns the local path if isLocalFile() == true or the KIO item has
453 * a UDS_LOCAL_PATH atom.
454 *
455 * Treat it as a readonly path to open/list contents, use original url to move/delete files.
456 *
457 * Returns the item local path, or QString() if not known
458 */
459 QString localPath() const;
460
461 /*!
462 * Returns the size of the file, if known.
463 *
464 * Returns 0 otherwise.
465 */
466 KIO::filesize_t size() const;
467
468 /*!
469 * For folders, returns its recursive size: the size of its files plus the recursiveSize of its folder
470 *
471 * Initially only implemented for trash:/
472 *
473 * \since 5.70
474 */
475 KIO::filesize_t recursiveSize() const;
476
477 /*!
478 * Requests the modification, access or creation time, depending on \a which.
479 *
480 * \a which the timestamp
481 *
482 * Returns the time asked for, QDateTime() if not available
483 *
484 * \sa timeString()
485 */
486 Q_INVOKABLE QDateTime time(KFileItem::FileTimes which) const;
487
488 /*!
489 * Requests the modification, access or creation time as a string, depending
490 * on \a which.
491 *
492 * \a which the timestamp
493 *
494 * Returns a formatted string of the requested time.
495 *
496 * \sa time()
497 */
498 Q_INVOKABLE QString timeString(KFileItem::FileTimes which = ModificationTime) const;
499
500 /*!
501 * Returns \c true if the file is a local file.
502 */
503 bool isLocalFile() const;
504
505 /*!
506 * Returns the text of the file item.
507 *
508 * It's not exactly the filename since some decoding happens ('%2F'->'/').
509 */
510 QString text() const;
511
512 /*!
513 * Return the name of the file item (without a path).
514 *
515 * Similar to text(), but unencoded, i.e. the original name.
516 *
517 * \a lowerCase if true, the name will be returned in lower case,
518 * which is useful to speed up sorting by name, case insensitively.
519 *
520 * Returns the file's name
521 */
522 QString name(bool lowerCase = false) const;
523
524 /*!
525 * Returns the MIME type of the file item.
526 *
527 * If \c delayedMimeTypes was used in the constructor, this will determine
528 * the MIME type first. Equivalent to determineMimeType()->name()
529 */
530 QString mimetype() const;
531
532 /*!
533 * Returns the MIME type of the file item.
534 *
535 * If delayedMimeTypes was used in the constructor, this will determine
536 * the MIME type first.
537 */
538 QMimeType determineMimeType() const;
539
540 /*!
541 * Returns the currently known MIME type of the file item.
542 * This will not try to determine the MIME type if unknown.
543 */
544 QMimeType currentMimeType() const;
545
546 /*!
547 * Returns \c true if we have determined the final icon of this file already.
548 * \since 4.10.2
549 */
550 bool isFinalIconKnown() const;
551
552 /*!
553 * Returns \c true if we have determined the MIME type of this file already,
554 * i.e. if determineMimeType() will be fast. Otherwise it will have to
555 * find what the MIME type is, which is a possibly slow operation; usually
556 * this is delayed until necessary.
557 */
558 bool isMimeTypeKnown() const;
559
560 /*!
561 * Returns the user-readable string representing the type of this file,
562 * like "OpenDocument Text File".
563 */
564 QString mimeComment() const;
565
566 /*!
567 * Returns the full path name to the icon that represents
568 * this MIME type.
569 */
570 QString iconName() const;
571
572 /*!
573 * Returns the overlays (bitfield of KIconLoader::*Overlay flags) that are used
574 * for this item's pixmap. Overlays are used to show for example, whether
575 * a file can be modified.
576 */
577 QStringList overlays() const;
578
579 /*!
580 * A comment which can contain anything - even rich text. It will
581 * simply be displayed to the user as is.
582 */
583 QString comment() const;
584
585 /*!
586 * Returns the string to be displayed in the statusbar,
587 * e.g.\ when the mouse is over this item.
588 */
589 QString getStatusBarInfo() const;
590
591 /*!
592 * Returns the UDS entry. Used by the tree view to access all details
593 * by position.
594 */
595 KIO::UDSEntry entry() const;
596
597 /*!
598 * Return \c true if this item is a regular file,
599 * \c false otherwise (directory, link, character/block device, fifo, socket)
600 */
601 bool isRegularFile() const;
602
603 /*!
604 * Returns the file extension
605 *
606 * Similar to QFileInfo::suffix except it takes into account UDS_DISPLAY_NAME and saves a stat call
607 * \since 6.0
608 */
609 QString suffix() const;
610
611 /*!
612 * Somewhat like a comparison operator, but more explicit,
613 * and it can detect that two fileitems differ if any property of the file item
614 * has changed (file size, modification date, etc.). Two items are equal if
615 * all properties are equal. In contrast, operator== only compares URLs.
616 *
617 * \a item the item to compare
618 *
619 * Returns \c true if all values are equal
620 */
621 bool cmp(const KFileItem &item) const;
622
623 /*!
624 * Returns \c true if both items share the same URL.
625 */
626 bool operator==(const KFileItem &other) const;
627
628 /*!
629 * Returns \c true if both items do not share the same URL.
630 */
631 bool operator!=(const KFileItem &other) const;
632
633 /*!
634 * Returns \c true if this item's URL is lexically less than other's URL; otherwise returns \c false
635 * \since 5.48
636 */
637 bool operator<(const KFileItem &other) const;
638
639 /*!
640 * Returns \c true if this item's URL is lexically less than url other; otherwise returns \c false
641 * \since 5.48
642 */
643 bool operator<(const QUrl &other) const;
644
645 /*!
646 * Converts this KFileItem to a QVariant, this allows to use KFileItem
647 * in QVariant() constructor
648 */
649 operator QVariant() const;
650
651 /*!
652 * Tries to return a local URL for this file item if possible.
653 *
654 * If \a local is not null, it will be set to \c true if the returned url is local,
655 * \c false otherwise.
656 *
657 * Example:
658 * \code
659 * bool isLocal = false;
660 * KFileItem item;
661 * const QUrl url = item.mostLocalUrl(&isLocal);
662 * if (isLocal) {
663 * // Use url
664 * }
665 * \endcode
666 *
667 */
668 QUrl mostLocalUrl(bool *local = nullptr) const;
669
670 // TODO qdoc?
671 struct MostLocalUrlResult {
672 QUrl url;
673 bool local;
674 };
675
676 /*!
677 * Returns a MostLocalUrlResult, with the local Url for this item if possible
678 * (otherwise the item url), and a bool that is set to \c true if this Url
679 * does represent a local file otherwise \c false.
680 *
681 * Basically this is an alternative to mostLocalUrl(bool*), that does not use an
682 * output parameter.
683 *
684 * Example:
685 * \code
686 * KFileItem item;
687 * const MostLocalUrlResult result = item.isMostLocalUrl();
688 * if (result.local) { // A local file
689 * // Use result.url
690 * }
691 * \endcode
692 * \since 5.84
693 */
694 MostLocalUrlResult isMostLocalUrl() const;
695
696 /*!
697 * Returns \c true if default-constructed
698 */
699 bool isNull() const;
700
701 /*!
702 * Returns whether the KFileItem exists on-disk
703 *
704 * Call only after initialization (i.e `KIO::stat` or `refresh()` for local files)
705 * \since 6.0
706 */
707 bool exists() const;
708
709 /*!
710 * Returns \c true if the file has executable permission
711 * \since 6.0
712 */
713 bool isExecutable() const;
714
715private:
716 QSharedDataPointer<KFileItemPrivate> d;
717
718 /*!
719 * Hides the file.
720 * \internal
721 */
722 KIOCORE_NO_EXPORT void setHidden();
723
724private:
725 KIOCORE_EXPORT friend QDataStream &operator<<(QDataStream &s, const KFileItem &a);
726 KIOCORE_EXPORT friend QDataStream &operator>>(QDataStream &s, KFileItem &a);
727
728 friend class KFileItemTest;
729 friend class KCoreDirListerCache;
730};
731
732Q_DECLARE_METATYPE(KFileItem)
733Q_DECLARE_TYPEINFO(KFileItem, Q_RELOCATABLE_TYPE);
734
735inline size_t qHash(const KFileItem &item, size_t seed = 0)
736{
737 return qHash(url: item.url(), seed);
738}
739
740/*!
741 * \class KFileItemList
742 * \inheaderfile KFileItem
743 * \inmodule KIOCore
744 *
745 * List of KFileItem, which adds a few helper
746 * methods to QList<KFileItem>.
747 */
748class KIOCORE_EXPORT KFileItemList : public QList<KFileItem>
749{
750public:
751 /*!
752 * Creates an empty list of file items.
753 */
754 KFileItemList();
755
756 /*!
757 * Creates a new KFileItemList from a QList of file \a items.
758 */
759 KFileItemList(const QList<KFileItem> &items);
760
761 /*!
762 * Creates a new KFileItemList from an initializer_list of file \a items.
763 * \since 5.76
764 */
765 KFileItemList(std::initializer_list<KFileItem> items);
766
767 /*!
768 * Find a KFileItem by name and return it.
769 *
770 * Returns the item with the given name, or a null-item if none was found
771 * (see KFileItem::isNull())
772 */
773 KFileItem findByName(const QString &fileName) const;
774
775 /*!
776 * Find a KFileItem by URL and return it.
777 *
778 * Returns the item with the given URL, or a null-item if none was found
779 * (see KFileItem::isNull())
780 */
781 KFileItem findByUrl(const QUrl &url) const;
782
783 /*!
784 * Returns the list of URLs that those items represent
785 */
786 QList<QUrl> urlList() const;
787
788 /*!
789 * Returns the list of target URLs that those items represent
790 * \since 4.2
791 */
792 QList<QUrl> targetUrlList() const;
793
794 // TODO KDE-5 add d pointer here so that we can merge KFileItemListProperties into KFileItemList
795};
796
797KIOCORE_EXPORT QDataStream &operator<<(QDataStream &s, const KFileItem &a);
798KIOCORE_EXPORT QDataStream &operator>>(QDataStream &s, KFileItem &a);
799
800KIOCORE_EXPORT QDebug operator<<(QDebug stream, const KFileItem &item);
801
802#endif
803

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