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 | |
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 | KIOCORE_EXPORT QDebug operator<<(QDebug stream, const KIO::UDSEntry &entry); |
31 | |
32 | namespace KIO |
33 | { |
34 | class UDSEntryPrivate; |
35 | |
36 | // TODO qdoc |
37 | /*! |
38 | * Returns true if the entry contains the same data as the other |
39 | * \since 5.63 |
40 | */ |
41 | KIOCORE_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 | */ |
47 | KIOCORE_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 | */ |
76 | class KIOCORE_EXPORT UDSEntry |
77 | { |
78 | public: |
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 | = 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 | = 100 | UDS_STRING, |
285 | = 140 | UDS_STRING, |
286 | }; |
287 | |
288 | private: |
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 | |
294 | public: |
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 |
319 | inline constexpr UDSEntry::StandardFieldTypes operator|(UDSEntry::StandardFieldTypes fieldType, UDSEntry::ItemTypes type) |
320 | { |
321 | return static_cast<UDSEntry::StandardFieldTypes>((char)fieldType | (char)type); |
322 | } |
323 | inline constexpr UDSEntry::StandardFieldTypes operator^(UDSEntry::StandardFieldTypes fieldType, UDSEntry::ItemTypes type) |
324 | { |
325 | return static_cast<UDSEntry::StandardFieldTypes>((char)fieldType ^ (char)type); |
326 | } |
327 | } |
328 | |
329 | Q_DECLARE_TYPEINFO(KIO::UDSEntry, Q_RELOCATABLE_TYPE); |
330 | |
331 | namespace 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 | */ |
353 | typedef QList<UDSEntry> UDSEntryList; |
354 | } // end namespace |
355 | |
356 | Q_DECLARE_METATYPE(KIO::UDSEntry) |
357 | |
358 | #endif /*UDSENTRY_H*/ |
359 | |