1/* This file is part of the KDE libraries
2 Copyright (C) 2000-2005 David Faure <faure@kde.org>
3 Copyright (C) 2007 Norbert Frese <nf2@scheinwelt.at>
4 Copyright (C) 2007 Thiago Macieira <thiago@kde.org>
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public
8 License version 2 as published by the Free Software Foundation.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20
21
22#ifndef UDSENTRY_H
23#define UDSENTRY_H
24
25#include <QtCore/QString>
26#include <QtCore/QList>
27#include <QtCore/QSharedData>
28
29#include <kio/kio_export.h>
30
31namespace KIO
32{
33 class UDSEntryPrivate;
34 /**
35 * Universal Directory Service
36 *
37 * UDS entry is the data structure representing all the fields about a given URL
38 * (file or directory).
39 *
40 * The KIO::listDir() and KIO:stat() operations use this data structure.
41 *
42 * KIO defines a number of standard fields, see the UDS_XXX enums (see StandardFieldTypes).
43 * at the moment UDSEntry only provides fields with numeric indexes,
44 * but there might be named fields with string indexes in the future.
45 *
46 * For instance, to retrieve the name of the entry, use:
47 * \code
48 * QString displayName = entry.stringValue( KIO::UDSEntry::UDS_NAME );
49 * \endcode
50 *
51 * To know the modification time of the file/url:
52 * \code
53 * time_t mtime = entry.numberValue( KIO::UDSEntry::UDS_MODIFICATION_TIME, -1 );
54 * if ( mtime != -1 )
55 * ...
56 * \endcode
57 */
58 class KIO_EXPORT UDSEntry
59 {
60 public:
61
62 UDSEntry();
63 UDSEntry(const UDSEntry &other);
64 ~UDSEntry();
65 UDSEntry &operator=(const UDSEntry &other);
66
67 /**
68 * @return value of a textual field
69 */
70 QString stringValue( uint field ) const;
71
72 /**
73 * @return value of a numeric field
74 */
75 long long numberValue( uint field, long long defaultValue = 0 ) const;
76
77 // Convenience methods.
78 // Let's not add one method per field, only methods that have some more logic
79 // than just calling stringValue(field) or numberValue(field).
80
81 /// @return true if this entry is a directory (or a link to a directory)
82 bool isDir() const;
83 /// @return true if this entry is a link
84 bool isLink() const;
85
86 /**
87 * insert field with numeric value
88 * @param field numeric field id
89 * @param value
90 */
91 void insert(uint field, const QString& value);
92
93 /**
94 * insert field with string value
95 * @param field numeric tield id
96 * @param l value to set
97 */
98 void insert(uint field, long long l);
99
100 /**
101 * count fields
102 * @return the number of fields
103 */
104 int count() const;
105
106 /**
107 * check existence of a field
108 * @param field
109 */
110 bool contains(uint field) const;
111
112 /**
113 * remove a field with a certain numeric id
114 * @param field numeric type id
115 */
116 bool remove(uint field);
117
118 /**
119 * lists all fields
120 */
121 QList<uint> listFields() const;
122
123 /**
124 * remove all fields
125 */
126 void clear();
127
128 /**
129 * Constants used to specify the type of a UDSField.
130 */
131 enum StandardFieldTypes {
132 // First let's define the item types: bit field
133
134 /// Indicates that the field is a QString
135 UDS_STRING = 0x01000000,
136 /// Indicates that the field is a number (long long)
137 UDS_NUMBER = 0x02000000,
138 /// Indicates that the field represents a time, which is modelled by a long long
139 UDS_TIME = 0x04000000 | UDS_NUMBER,
140
141 // The rest isn't a bit field
142
143 /// Size of the file
144 UDS_SIZE = 1 | UDS_NUMBER,
145 /// @internal
146 UDS_SIZE_LARGE = 2 | UDS_NUMBER,
147 /// User ID of the file owner
148 UDS_USER = 3 | UDS_STRING,
149 /// Name of the icon, that should be used for displaying.
150 /// It overrides all other detection mechanisms
151 UDS_ICON_NAME = 4 | UDS_STRING,
152 /// Group ID of the file owner
153 UDS_GROUP = 5 | UDS_STRING,
154 /// Filename - as displayed in directory listings etc.
155 /// "." has the usual special meaning of "current directory"
156 /// UDS_NAME must always be set and never be empty, neither contain '/'.
157 ///
158 /// Note that KIO will append the UDS_NAME to the url of their
159 /// parent directory, so all kioslaves must use that naming scheme
160 /// ("url_of_parent/filename" will be the full url of that file).
161 /// To customize the appearance of files without changing the url
162 /// of the items, use UDS_DISPLAY_NAME.
163 UDS_NAME = 6 | UDS_STRING,
164 /// A local file path if the ioslave display files sitting
165 /// on the local filesystem (but in another hierarchy, e.g. settings:/ or remote:/)
166 UDS_LOCAL_PATH = 7 | UDS_STRING,
167 /// Treat the file as a hidden file (if set to 1) or as a normal file (if set to 0).
168 /// This field overrides the default behavior (the check for a leading dot in the filename).
169 UDS_HIDDEN = 8 | UDS_NUMBER,
170 /// Access permissions (part of the mode returned by stat)
171 UDS_ACCESS = 9 | UDS_NUMBER,
172 /// The last time the file was modified
173 UDS_MODIFICATION_TIME = 10 | UDS_TIME,
174 /// The last time the file was opened
175 UDS_ACCESS_TIME = 11 | UDS_TIME,
176 /// The time the file was created
177 UDS_CREATION_TIME = 12 | UDS_TIME,
178 /// File type, part of the mode returned by stat
179 /// (for a link, this returns the file type of the pointed item)
180 /// check UDS_LINK_DEST to know if this is a link
181 UDS_FILE_TYPE = 13 | UDS_NUMBER,
182 /// Name of the file where the link points to
183 /// Allows to check for a symlink (don't use S_ISLNK !)
184 UDS_LINK_DEST = 14 | UDS_STRING,
185 /// An alternative URL (If different from the caption).
186 /// Can be used to mix different hierarchies.
187 ///
188 /// Use UDS_DISPLAY_NAME if you simply want to customize the user-visible filenames, or use
189 /// UDS_TARGET_URL if you want "links" to unrelated urls.
190 UDS_URL = 15 | UDS_STRING,
191 /// A mime type; the slave should set it if it's known.
192 UDS_MIME_TYPE = 16 | UDS_STRING,
193 /// A mime type to be used for displaying only.
194 /// But when 'running' the file, the mimetype is re-determined
195 /// This is for special cases like symlinks in FTP; you probably don't want to use this one.
196 UDS_GUESSED_MIME_TYPE = 17 | UDS_STRING,
197 /// XML properties, e.g. for WebDAV
198 UDS_XML_PROPERTIES = 18 | UDS_STRING,
199
200 /// Indicates that the entry has extended ACL entries
201 UDS_EXTENDED_ACL = 19 | UDS_NUMBER,
202 /// The access control list serialized into a single string.
203 UDS_ACL_STRING = 20 | UDS_STRING,
204 /// The default access control list serialized into a single string.
205 /// Only available for directories.
206 UDS_DEFAULT_ACL_STRING = 21 | UDS_STRING,
207
208 /// If set, contains the label to display instead of
209 /// the 'real name' in UDS_NAME
210 /// @since 4.1
211 UDS_DISPLAY_NAME = 22 | UDS_STRING,
212 /// This file is a shortcut or mount, pointing to an
213 /// URL in a different hierarchy
214 /// @since 4.1
215 UDS_TARGET_URL = 23 | UDS_STRING,
216
217 /// User-readable type of file (if not specified,
218 /// the mimetype's description is used)
219 /// @since 4.4
220 UDS_DISPLAY_TYPE = 24 | UDS_STRING,
221
222 /// The URI of the corresponding Nepomuk resource.
223 /// KIO slaves can use this optional entry to provide
224 /// client applications with a Nepomuk resource to be used
225 /// for annotations like tags or ratings. A typical example
226 /// is to provide the URI of the Nepomuk resource corresponding
227 /// to a file in a search result
228 /// Client applications should only provide annotations for
229 /// entries that provide this URI
230 ///
231 /// URIs need to be encoded using KUrl::url()
232 ///
233 /// @since 4.4
234 UDS_NEPOMUK_URI = 25 | UDS_STRING,
235
236 /// A comma-separated list of supplementary icon overlays
237 /// which will be added to the list of overlays created
238 /// by KFileItem.
239 ///
240 /// @since 4.5
241 UDS_ICON_OVERLAY_NAMES = 26 | UDS_STRING,
242
243 /// A serialized Nepomuk::Query::Query which lists the contents of
244 /// the folder this UDSEntry describes. This can be used to enable
245 /// faceted browsing via any local KIO slave.
246 ///
247 /// @since 4.6
248 UDS_NEPOMUK_QUERY = 27 | UDS_STRING,
249
250 /// A comment which will be displayed as is to the user. The string
251 /// value may contain plain text or Qt-style rich-text extensions.
252 ///
253 /// @since 4.6
254 UDS_COMMENT = 28 | UDS_STRING,
255
256 /// Device number for this file, used to detect hardlinks
257 /// @since 4.7.3
258 UDS_DEVICE_ID = 29 | UDS_NUMBER,
259 /// Inode number for this file, used to detect hardlinks
260 /// @since 4.7.3
261 UDS_INODE = 30 | UDS_NUMBER,
262
263 /// Extra data (used only if you specified Columns/ColumnsTypes)
264 /// KDE 4.0 change: you cannot repeat this entry anymore, use UDS_EXTRA + i
265 /// until UDS_EXTRA_END.
266 UDS_EXTRA = 100 | UDS_STRING,
267 /// Extra data (used only if you specified Columns/ColumnsTypes)
268 /// KDE 4.0 change: you cannot repeat this entry anymore, use UDS_EXTRA + i
269 /// until UDS_EXTRA_END.
270 UDS_EXTRA_END = 140 | UDS_STRING
271 };
272
273 private:
274 friend class UDSEntryPrivate;
275 QSharedDataPointer<UDSEntryPrivate> d;
276 };
277
278 /**
279 * A directory listing is a list of UDSEntry instances.
280 *
281 * To list the name and size of all the files in a directory listing you would do:
282 * \code
283 * KIO::UDSEntryList::ConstIterator it = entries.begin();
284 * const KIO::UDSEntryList::ConstIterator end = entries.end();
285 * for (; it != end; ++it) {
286 * const KIO::UDSEntry& entry = *it;
287 * QString name = entry.stringValue( KIO::UDSEntry::UDS_NAME );
288 * bool isDir = entry.isDir();
289 * KIO::filesize_t size = entry.numberValue( KIO::UDSEntry::UDS_SIZE, -1 );
290 * ...
291 * }
292 * \endcode
293 */
294 typedef QList<UDSEntry> UDSEntryList;
295} // end namespace
296
297KIO_EXPORT QDataStream & operator<< ( QDataStream & s, const KIO::UDSEntry & a );
298KIO_EXPORT QDataStream & operator>> ( QDataStream & s, KIO::UDSEntry & a );
299
300#endif /*UDSENTRY_H*/
301