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

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