KIO

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

KDE's Doxygen guidelines are available online.