KIO

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

KDE's Doxygen guidelines are available online.