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 | |
31 | namespace 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 | |
297 | KIO_EXPORT QDataStream & operator<< ( QDataStream & s, const KIO::UDSEntry & a ); |
298 | KIO_EXPORT QDataStream & operator>> ( QDataStream & s, KIO::UDSEntry & a ); |
299 | |
300 | #endif /*UDSENTRY_H*/ |
301 | |