KIO

udsentry.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2000-2005 David Faure <[email protected]>
4  SPDX-FileCopyrightText: 2007 Norbert Frese <[email protected]>
5  SPDX-FileCopyrightText: 2007 Thiago Macieira <[email protected]>
6 
7  SPDX-License-Identifier: LGPL-2.0-only
8 */
9 
10 #ifndef UDSENTRY_H
11 #define UDSENTRY_H
12 
13 #include <QList>
14 #include <QMetaType>
15 #include <QSharedData>
16 #include <QString>
17 #include <QtGlobal>
18 #include <qplatformdefs.h>
19 
20 #include "kiocore_export.h"
21 
22 namespace KIO
23 {
24 class UDSEntry;
25 }
26 
27 KIOCORE_EXPORT QDataStream &operator<<(QDataStream &s, const KIO::UDSEntry &a);
28 KIOCORE_EXPORT QDataStream &operator>>(QDataStream &s, KIO::UDSEntry &a);
29 
30 /**
31  * Support for qDebug() << aUDSEntry
32  * \since 5.22
33  */
34 KIOCORE_EXPORT QDebug operator<<(QDebug stream, const KIO::UDSEntry &entry);
35 
36 /**
37  * Returns true if the entry contains the same data as the other
38  * @since 5.63
39  */
40 KIOCORE_EXPORT bool operator==(const KIO::UDSEntry &entry, const KIO::UDSEntry &other);
41 
42 /**
43  * Returns true if the entry does not contain the same data as the other
44  * @since 5.63
45  */
46 KIOCORE_EXPORT bool operator!=(const KIO::UDSEntry &entry, const KIO::UDSEntry &other);
47 
48 namespace KIO
49 {
50 class UDSEntryPrivate;
51 /**
52  * @class KIO::UDSEntry udsentry.h <KIO/UDSEntry>
53  *
54  * Universal Directory Service
55  *
56  * UDS entry is the data structure representing all the fields about a given URL
57  * (file or directory).
58  *
59  * The KIO::listDir() and KIO:stat() operations use this data structure.
60  *
61  * KIO defines a number of standard fields, see the UDS_XXX enums (see StandardFieldTypes).
62  * at the moment UDSEntry only provides fields with numeric indexes,
63  * but there might be named fields with string indexes in the future.
64  *
65  * For instance, to retrieve the name of the entry, use:
66  * \code
67  * QString displayName = entry.stringValue( KIO::UDSEntry::UDS_NAME );
68  * \endcode
69  *
70  * To know the modification time of the file/url:
71  * \code
72  * QDateTime mtime = QDateTime::fromSecsSinceEpoch(entry.numberValue(KIO::UDSEntry::UDS_MODIFICATION_TIME, 0));
73  * if (mtime.isValid())
74  * ...
75  * \endcode
76  */
77 class KIOCORE_EXPORT UDSEntry
78 {
79 public:
80  UDSEntry();
81 
82  /**
83  * Create a UDSEntry by QT_STATBUF
84  * @param buff QT_STATBUF object
85  * @param name filename
86  * @since 5.0
87  */
88  UDSEntry(const QT_STATBUF &buff, const QString &name = QString());
89 
90  /**
91  * Copy constructor
92  */
93  UDSEntry(const UDSEntry &);
94 
95  /**
96  * Destructor
97  */
98  ~UDSEntry();
99 
100  /**
101  * Move constructor
102  * @since 5.44
103  */
104  UDSEntry(UDSEntry &&);
105 
106  /**
107  * Copy assignment
108  */
109  UDSEntry &operator=(const UDSEntry &);
110 
111  /**
112  * Move assignment
113  * @since 5.44
114  */
115  UDSEntry &operator=(UDSEntry &&);
116 
117  /**
118  * @return value of a textual field
119  */
120  QString stringValue(uint field) const;
121 
122  /**
123  * @return value of a numeric field
124  */
125  long long numberValue(uint field, long long defaultValue = 0) const;
126 
127  // Convenience methods.
128  // Let's not add one method per field, only methods that have some more logic
129  // than just calling stringValue(field) or numberValue(field).
130 
131  /// @return true if this entry is a directory (or a link to a directory)
132  bool isDir() const;
133  /// @return true if this entry is a link
134  bool isLink() const;
135 
136  /**
137  * Calling this function before inserting items into an empty UDSEntry may save time and memory.
138  * @param size number of items for which memory will be pre-allocated
139  */
140  void reserve(int size);
141 
142 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 48)
143  /**
144  * insert field with string value
145  * @param field numeric field id
146  * @param value to set
147  * @deprecated since 5.48 in favor of fastInsert or replace
148  */
149  KIOCORE_DEPRECATED_VERSION(5, 48, "Use UDSEntry::fastInsert(uint, const QString &) or UDSEntry::replace(uint, const QString &)")
150  void insert(uint field, const QString &value);
151 #endif
152 
153 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 48)
154  /**
155  * insert field with numeric value
156  * @param field numeric field id
157  * @param l value to set
158  * @deprecated since 5.48 in favor of fastInsert or replace
159  */
160  KIOCORE_DEPRECATED_VERSION(5, 48, "Use UDSEntry::fastInsert(uint, long long) or UDSEntry::replace(uint, long long)")
161  void insert(uint field, long long l);
162 #endif
163 
164  /**
165  * insert field with string value, it will assert if the field is already inserted. In that case, use replace() instead.
166  * @param field numeric field id
167  * @param value to set
168  * @since 5.48
169  */
170  void fastInsert(uint field, const QString &value);
171 
172  /**
173  * insert field with numeric value, it will assert if the field is already inserted. In that case, use replace() instead.
174  * @param field numeric field id
175  * @param l value to set
176  * @since 5.48
177  */
178  void fastInsert(uint field, long long l);
179 
180  /**
181  * count fields
182  * @return the number of fields
183  */
184  int count() const;
185 
186  /**
187  * check existence of a field
188  * @param field numeric field id
189  */
190  bool contains(uint field) const;
191 
192 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 8)
193  /**
194  * List all fields.
195  * @return all fields.
196  * @deprecated since 5.8. Use fields() instead.
197  */
198  KIOCORE_DEPRECATED_VERSION(5, 8, "Use UDSEntry::fields()")
199  QList<uint> listFields() const;
200 #endif
201 
202  /**
203  * A vector of fields being present for the current entry.
204  * @return all fields for the current entry.
205  * @since 5.8
206  */
207  QVector<uint> fields() const;
208 
209  /**
210  * remove all fields
211  */
212  void clear();
213 
214  /**
215  * Constants used to specify the type of a UDSField.
216  */
218  // First let's define the item types: bit field
219 
220  /// Indicates that the field is a QString
221  UDS_STRING = 0x01000000,
222  /// Indicates that the field is a number (long long)
223  UDS_NUMBER = 0x02000000,
224  /// Indicates that the field represents a time, which is modelled by a long long
225  UDS_TIME = 0x04000000 | UDS_NUMBER,
226 
227  // The rest isn't a bit field
228 
229  /// Size of the file
230  UDS_SIZE = 1 | UDS_NUMBER,
231  /// @internal
232  UDS_SIZE_LARGE = 2 | UDS_NUMBER,
233  /// User ID of the file owner
234  UDS_USER = 3 | UDS_STRING,
235  /// Name of the icon, that should be used for displaying.
236  /// It overrides all other detection mechanisms
237  UDS_ICON_NAME = 4 | UDS_STRING,
238  /// Group ID of the file owner
239  UDS_GROUP = 5 | UDS_STRING,
240  /// Filename - as displayed in directory listings etc.
241  /// "." has the usual special meaning of "current directory"
242  /// UDS_NAME must always be set and never be empty, neither contain '/'.
243  ///
244  /// Note that KIO will append the UDS_NAME to the url of their
245  /// parent directory, so all KIO workers must use that naming scheme
246  /// ("url_of_parent/filename" will be the full url of that file).
247  /// To customize the appearance of files without changing the url
248  /// of the items, use UDS_DISPLAY_NAME.
249  UDS_NAME = 6 | UDS_STRING,
250  /// A local file path if the KIO worker display files sitting
251  /// on the local filesystem (but in another hierarchy, e.g.\ settings:/ or remote:/)
252  UDS_LOCAL_PATH = 7 | UDS_STRING,
253  /// Treat the file as a hidden file (if set to 1) or as a normal file (if set to 0).
254  /// This field overrides the default behavior (the check for a leading dot in the filename).
255  UDS_HIDDEN = 8 | UDS_NUMBER,
256  /// Access permissions (part of the mode returned by stat)
257  UDS_ACCESS = 9 | UDS_NUMBER,
258  /// The last time the file was modified. Required time format: seconds since UNIX epoch.
259  UDS_MODIFICATION_TIME = 10 | UDS_TIME,
260  /// The last time the file was opened. Required time format: seconds since UNIX epoch.
261  UDS_ACCESS_TIME = 11 | UDS_TIME,
262  /// The time the file was created. Required time format: seconds since UNIX epoch.
263  UDS_CREATION_TIME = 12 | UDS_TIME,
264  /// File type, part of the mode returned by stat
265  /// (for a link, this returns the file type of the pointed item)
266  /// check UDS_LINK_DEST to know if this is a link
267  UDS_FILE_TYPE = 13 | UDS_NUMBER,
268  /// Name of the file where the link points to
269  /// Allows to check for a symlink (don't use S_ISLNK !)
270  UDS_LINK_DEST = 14 | UDS_STRING,
271  /// An alternative URL (If different from the caption).
272  /// Can be used to mix different hierarchies.
273  ///
274  /// Use UDS_DISPLAY_NAME if you simply want to customize the user-visible filenames, or use
275  /// UDS_TARGET_URL if you want "links" to unrelated urls.
276  UDS_URL = 15 | UDS_STRING,
277  /// A MIME type; the KIO worker should set it if it's known.
278  UDS_MIME_TYPE = 16 | UDS_STRING,
279  /// A MIME type to be used for displaying only.
280  /// But when 'running' the file, the MIME type is re-determined
281  /// This is for special cases like symlinks in FTP; you probably don't want to use this one.
282  UDS_GUESSED_MIME_TYPE = 17 | UDS_STRING,
283  /// XML properties, e.g.\ for WebDAV
284  UDS_XML_PROPERTIES = 18 | UDS_STRING,
285 
286  /// Indicates that the entry has extended ACL entries
287  UDS_EXTENDED_ACL = 19 | UDS_NUMBER,
288  /// The access control list serialized into a single string.
289  UDS_ACL_STRING = 20 | UDS_STRING,
290  /// The default access control list serialized into a single string.
291  /// Only available for directories.
292  UDS_DEFAULT_ACL_STRING = 21 | UDS_STRING,
293 
294  /// If set, contains the label to display instead of
295  /// the 'real name' in UDS_NAME
296  /// @since 4.1
297  UDS_DISPLAY_NAME = 22 | UDS_STRING,
298  /// This file is a shortcut or mount, pointing to an
299  /// URL in a different hierarchy
300  /// @since 4.1
301  UDS_TARGET_URL = 23 | UDS_STRING,
302 
303  /// User-readable type of file (if not specified,
304  /// the MIME type's description is used)
305  /// @since 4.4
306  UDS_DISPLAY_TYPE = 24 | UDS_STRING,
307 
308  /// 25 was used by the now removed UDS_NEPOMUK_URI
309 
310  /// A comma-separated list of supplementary icon overlays
311  /// which will be added to the list of overlays created
312  /// by KFileItem.
313  ///
314  /// @since 4.5
315  UDS_ICON_OVERLAY_NAMES = 26 | UDS_STRING,
316 
317  /// 27 was used by the now removed UDS_NEPOMUK_QUERY
318 
319  /// A comment which will be displayed as is to the user. The string
320  /// value may contain plain text or Qt-style rich-text extensions.
321  ///
322  /// @since 4.6
323  UDS_COMMENT = 28 | UDS_STRING,
324 
325  /// Device number for this file, used to detect hardlinks
326  /// @since 4.7.3
327  UDS_DEVICE_ID = 29 | UDS_NUMBER,
328  /// Inode number for this file, used to detect hardlinks
329  /// @since 4.7.3
330  UDS_INODE = 30 | UDS_NUMBER,
331 
332  /// For folders, the recursize size of its content
333  /// @since 5.70
334  UDS_RECURSIVE_SIZE = 31 | UDS_NUMBER,
335 
336  /// Extra data (used only if you specified Columns/ColumnsTypes)
337  /// NB: you cannot repeat this entry; use UDS_EXTRA + i
338  /// until UDS_EXTRA_END.
339  UDS_EXTRA = 100 | UDS_STRING,
340  /// Extra data (used only if you specified Columns/ColumnsTypes)
341  /// NB: you cannot repeat this entry; use UDS_EXTRA + i
342  /// until UDS_EXTRA_END.
343  UDS_EXTRA_END = 140 | UDS_STRING,
344  };
345 
346 private:
348  friend KIOCORE_EXPORT QDataStream & ::operator<<(QDataStream &s, const KIO::UDSEntry &a);
349  friend KIOCORE_EXPORT QDataStream & ::operator>>(QDataStream &s, KIO::UDSEntry &a);
350  friend KIOCORE_EXPORT QDebug(::operator<<)(QDebug stream, const KIO::UDSEntry &entry);
351 
352 public:
353  /**
354  * Replace or insert field with string value
355  * @param field numeric field id
356  * @param value to set
357  * @since 5.47
358  */
359  void replace(uint field, const QString &value);
360 
361  /**
362  * Replace or insert field with numeric value
363  * @param field numeric field id
364  * @param l value to set
365  * @since 5.47
366  */
367  void replace(uint field, long long l);
368 };
369 
370 }
371 
372 Q_DECLARE_TYPEINFO(KIO::UDSEntry, Q_MOVABLE_TYPE);
373 
374 namespace KIO
375 {
376 /**
377  * A directory listing is a list of UDSEntry instances.
378  *
379  * To list the name and size of all the files in a directory listing you would do:
380  * \code
381  * KIO::UDSEntryList::ConstIterator it = entries.begin();
382  * const KIO::UDSEntryList::ConstIterator end = entries.end();
383  * for (; it != end; ++it) {
384  * const KIO::UDSEntry& entry = *it;
385  * QString name = entry.stringValue( KIO::UDSEntry::UDS_NAME );
386  * bool isDir = entry.isDir();
387  * KIO::filesize_t size = entry.numberValue( KIO::UDSEntry::UDS_SIZE, -1 );
388  * ...
389  * }
390  * \endcode
391  */
393 } // end namespace
394 
395 Q_DECLARE_METATYPE(KIO::UDSEntry)
396 
397 #endif /*UDSENTRY_H*/
StandardFieldTypes
Constants used to specify the type of a UDSField.
Definition: udsentry.h:217
KCALENDARCORE_EXPORT QDataStream & operator<<(QDataStream &out, const KCalendarCore::Alarm::Ptr &)
KCALENDARCORE_EXPORT QDataStream & operator>>(QDataStream &in, const KCalendarCore::Alarm::Ptr &)
bool operator==(const Qt3DRender::QGraphicsApiFilter &reference, const Qt3DRender::QGraphicsApiFilter &sample)
bool operator!=(const Qt3DRender::QGraphicsApiFilter &reference, const Qt3DRender::QGraphicsApiFilter &sample)
A namespace for KIO globals.
QList< UDSEntry > UDSEntryList
A directory listing is a list of UDSEntry instances.
Definition: udsentry.h:392
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Thu Nov 30 2023 03:52:32 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.