File indexing completed on 2023-09-24 04:08:45
0001 /* 0002 This file is part of the KDE libraries 0003 SPDX-FileCopyrightText: 2000-2005 David Faure <faure@kde.org> 0004 SPDX-FileCopyrightText: 2007 Norbert Frese <nf2@scheinwelt.at> 0005 SPDX-FileCopyrightText: 2007 Thiago Macieira <thiago@kde.org> 0006 0007 SPDX-License-Identifier: LGPL-2.0-only 0008 */ 0009 0010 #ifndef UDSENTRY_H 0011 #define UDSENTRY_H 0012 0013 #include <QList> 0014 #include <QMetaType> 0015 #include <QSharedData> 0016 #include <QString> 0017 #include <QtGlobal> 0018 #include <qplatformdefs.h> 0019 0020 #include "kiocore_export.h" 0021 0022 namespace KIO 0023 { 0024 class UDSEntry; 0025 } 0026 0027 KIOCORE_EXPORT QDataStream &operator<<(QDataStream &s, const KIO::UDSEntry &a); 0028 KIOCORE_EXPORT QDataStream &operator>>(QDataStream &s, KIO::UDSEntry &a); 0029 0030 /** 0031 * Support for qDebug() << aUDSEntry 0032 * \since 5.22 0033 */ 0034 KIOCORE_EXPORT QDebug operator<<(QDebug stream, const KIO::UDSEntry &entry); 0035 0036 /** 0037 * Returns true if the entry contains the same data as the other 0038 * @since 5.63 0039 */ 0040 KIOCORE_EXPORT bool operator==(const KIO::UDSEntry &entry, const KIO::UDSEntry &other); 0041 0042 /** 0043 * Returns true if the entry does not contain the same data as the other 0044 * @since 5.63 0045 */ 0046 KIOCORE_EXPORT bool operator!=(const KIO::UDSEntry &entry, const KIO::UDSEntry &other); 0047 0048 namespace KIO 0049 { 0050 class UDSEntryPrivate; 0051 /** 0052 * @class KIO::UDSEntry udsentry.h <KIO/UDSEntry> 0053 * 0054 * Universal Directory Service 0055 * 0056 * UDS entry is the data structure representing all the fields about a given URL 0057 * (file or directory). 0058 * 0059 * The KIO::listDir() and KIO:stat() operations use this data structure. 0060 * 0061 * KIO defines a number of standard fields, see the UDS_XXX enums (see StandardFieldTypes). 0062 * at the moment UDSEntry only provides fields with numeric indexes, 0063 * but there might be named fields with string indexes in the future. 0064 * 0065 * For instance, to retrieve the name of the entry, use: 0066 * \code 0067 * QString displayName = entry.stringValue( KIO::UDSEntry::UDS_NAME ); 0068 * \endcode 0069 * 0070 * To know the modification time of the file/url: 0071 * \code 0072 * QDateTime mtime = QDateTime::fromSecsSinceEpoch(entry.numberValue(KIO::UDSEntry::UDS_MODIFICATION_TIME, 0)); 0073 * if (mtime.isValid()) 0074 * ... 0075 * \endcode 0076 */ 0077 class KIOCORE_EXPORT UDSEntry 0078 { 0079 public: 0080 UDSEntry(); 0081 0082 /** 0083 * Create a UDSEntry by QT_STATBUF 0084 * @param buff QT_STATBUF object 0085 * @param name filename 0086 * @since 5.0 0087 */ 0088 UDSEntry(const QT_STATBUF &buff, const QString &name = QString()); 0089 0090 /** 0091 * Copy constructor 0092 */ 0093 UDSEntry(const UDSEntry &); 0094 0095 /** 0096 * Destructor 0097 */ 0098 ~UDSEntry(); 0099 0100 /** 0101 * Move constructor 0102 * @since 5.44 0103 */ 0104 UDSEntry(UDSEntry &&); 0105 0106 /** 0107 * Copy assignment 0108 */ 0109 UDSEntry &operator=(const UDSEntry &); 0110 0111 /** 0112 * Move assignment 0113 * @since 5.44 0114 */ 0115 UDSEntry &operator=(UDSEntry &&); 0116 0117 /** 0118 * @return value of a textual field 0119 */ 0120 QString stringValue(uint field) const; 0121 0122 /** 0123 * @return value of a numeric field 0124 */ 0125 long long numberValue(uint field, long long defaultValue = 0) const; 0126 0127 // Convenience methods. 0128 // Let's not add one method per field, only methods that have some more logic 0129 // than just calling stringValue(field) or numberValue(field). 0130 0131 /// @return true if this entry is a directory (or a link to a directory) 0132 bool isDir() const; 0133 /// @return true if this entry is a link 0134 bool isLink() const; 0135 0136 /** 0137 * Calling this function before inserting items into an empty UDSEntry may save time and memory. 0138 * @param size number of items for which memory will be pre-allocated 0139 */ 0140 void reserve(int size); 0141 0142 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 48) 0143 /** 0144 * insert field with string value 0145 * @param field numeric field id 0146 * @param value to set 0147 * @deprecated since 5.48 in favor of fastInsert or replace 0148 */ 0149 KIOCORE_DEPRECATED_VERSION(5, 48, "Use UDSEntry::fastInsert(uint, const QString &) or UDSEntry::replace(uint, const QString &)") 0150 void insert(uint field, const QString &value); 0151 #endif 0152 0153 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 48) 0154 /** 0155 * insert field with numeric value 0156 * @param field numeric field id 0157 * @param l value to set 0158 * @deprecated since 5.48 in favor of fastInsert or replace 0159 */ 0160 KIOCORE_DEPRECATED_VERSION(5, 48, "Use UDSEntry::fastInsert(uint, long long) or UDSEntry::replace(uint, long long)") 0161 void insert(uint field, long long l); 0162 #endif 0163 0164 /** 0165 * insert field with string value, it will assert if the field is already inserted. In that case, use replace() instead. 0166 * @param field numeric field id 0167 * @param value to set 0168 * @since 5.48 0169 */ 0170 void fastInsert(uint field, const QString &value); 0171 0172 /** 0173 * insert field with numeric value, it will assert if the field is already inserted. In that case, use replace() instead. 0174 * @param field numeric field id 0175 * @param l value to set 0176 * @since 5.48 0177 */ 0178 void fastInsert(uint field, long long l); 0179 0180 /** 0181 * count fields 0182 * @return the number of fields 0183 */ 0184 int count() const; 0185 0186 /** 0187 * check existence of a field 0188 * @param field numeric field id 0189 */ 0190 bool contains(uint field) const; 0191 0192 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 8) 0193 /** 0194 * List all fields. 0195 * @return all fields. 0196 * @deprecated since 5.8. Use fields() instead. 0197 */ 0198 KIOCORE_DEPRECATED_VERSION(5, 8, "Use UDSEntry::fields()") 0199 QList<uint> listFields() const; 0200 #endif 0201 0202 /** 0203 * A vector of fields being present for the current entry. 0204 * @return all fields for the current entry. 0205 * @since 5.8 0206 */ 0207 QVector<uint> fields() const; 0208 0209 /** 0210 * remove all fields 0211 */ 0212 void clear(); 0213 0214 /** 0215 * Constants used to specify the type of a UDSField. 0216 */ 0217 enum StandardFieldTypes { 0218 // First let's define the item types: bit field 0219 0220 /// Indicates that the field is a QString 0221 UDS_STRING = 0x01000000, 0222 /// Indicates that the field is a number (long long) 0223 UDS_NUMBER = 0x02000000, 0224 /// Indicates that the field represents a time, which is modelled by a long long 0225 UDS_TIME = 0x04000000 | UDS_NUMBER, 0226 0227 // The rest isn't a bit field 0228 0229 /// Size of the file 0230 UDS_SIZE = 1 | UDS_NUMBER, 0231 /// @internal 0232 UDS_SIZE_LARGE = 2 | UDS_NUMBER, 0233 /// User ID of the file owner 0234 UDS_USER = 3 | UDS_STRING, 0235 /// Name of the icon, that should be used for displaying. 0236 /// It overrides all other detection mechanisms 0237 UDS_ICON_NAME = 4 | UDS_STRING, 0238 /// Group ID of the file owner 0239 UDS_GROUP = 5 | UDS_STRING, 0240 /// Filename - as displayed in directory listings etc. 0241 /// "." has the usual special meaning of "current directory" 0242 /// UDS_NAME must always be set and never be empty, neither contain '/'. 0243 /// 0244 /// Note that KIO will append the UDS_NAME to the url of their 0245 /// parent directory, so all KIO workers must use that naming scheme 0246 /// ("url_of_parent/filename" will be the full url of that file). 0247 /// To customize the appearance of files without changing the url 0248 /// of the items, use UDS_DISPLAY_NAME. 0249 UDS_NAME = 6 | UDS_STRING, 0250 /// A local file path if the KIO worker display files sitting 0251 /// on the local filesystem (but in another hierarchy, e.g.\ settings:/ or remote:/) 0252 UDS_LOCAL_PATH = 7 | UDS_STRING, 0253 /// Treat the file as a hidden file (if set to 1) or as a normal file (if set to 0). 0254 /// This field overrides the default behavior (the check for a leading dot in the filename). 0255 UDS_HIDDEN = 8 | UDS_NUMBER, 0256 /// Access permissions (part of the mode returned by stat) 0257 UDS_ACCESS = 9 | UDS_NUMBER, 0258 /// The last time the file was modified. Required time format: seconds since UNIX epoch. 0259 UDS_MODIFICATION_TIME = 10 | UDS_TIME, 0260 /// The last time the file was opened. Required time format: seconds since UNIX epoch. 0261 UDS_ACCESS_TIME = 11 | UDS_TIME, 0262 /// The time the file was created. Required time format: seconds since UNIX epoch. 0263 UDS_CREATION_TIME = 12 | UDS_TIME, 0264 /// File type, part of the mode returned by stat 0265 /// (for a link, this returns the file type of the pointed item) 0266 /// check UDS_LINK_DEST to know if this is a link 0267 UDS_FILE_TYPE = 13 | UDS_NUMBER, 0268 /// Name of the file where the link points to 0269 /// Allows to check for a symlink (don't use S_ISLNK !) 0270 UDS_LINK_DEST = 14 | UDS_STRING, 0271 /// An alternative URL (If different from the caption). 0272 /// Can be used to mix different hierarchies. 0273 /// 0274 /// Use UDS_DISPLAY_NAME if you simply want to customize the user-visible filenames, or use 0275 /// UDS_TARGET_URL if you want "links" to unrelated urls. 0276 UDS_URL = 15 | UDS_STRING, 0277 /// A MIME type; the KIO worker should set it if it's known. 0278 UDS_MIME_TYPE = 16 | UDS_STRING, 0279 /// A MIME type to be used for displaying only. 0280 /// But when 'running' the file, the MIME type is re-determined 0281 /// This is for special cases like symlinks in FTP; you probably don't want to use this one. 0282 UDS_GUESSED_MIME_TYPE = 17 | UDS_STRING, 0283 /// XML properties, e.g.\ for WebDAV 0284 UDS_XML_PROPERTIES = 18 | UDS_STRING, 0285 0286 /// Indicates that the entry has extended ACL entries 0287 UDS_EXTENDED_ACL = 19 | UDS_NUMBER, 0288 /// The access control list serialized into a single string. 0289 UDS_ACL_STRING = 20 | UDS_STRING, 0290 /// The default access control list serialized into a single string. 0291 /// Only available for directories. 0292 UDS_DEFAULT_ACL_STRING = 21 | UDS_STRING, 0293 0294 /// If set, contains the label to display instead of 0295 /// the 'real name' in UDS_NAME 0296 /// @since 4.1 0297 UDS_DISPLAY_NAME = 22 | UDS_STRING, 0298 /// This file is a shortcut or mount, pointing to an 0299 /// URL in a different hierarchy 0300 /// @since 4.1 0301 UDS_TARGET_URL = 23 | UDS_STRING, 0302 0303 /// User-readable type of file (if not specified, 0304 /// the MIME type's description is used) 0305 /// @since 4.4 0306 UDS_DISPLAY_TYPE = 24 | UDS_STRING, 0307 0308 /// 25 was used by the now removed UDS_NEPOMUK_URI 0309 0310 /// A comma-separated list of supplementary icon overlays 0311 /// which will be added to the list of overlays created 0312 /// by KFileItem. 0313 /// 0314 /// @since 4.5 0315 UDS_ICON_OVERLAY_NAMES = 26 | UDS_STRING, 0316 0317 /// 27 was used by the now removed UDS_NEPOMUK_QUERY 0318 0319 /// A comment which will be displayed as is to the user. The string 0320 /// value may contain plain text or Qt-style rich-text extensions. 0321 /// 0322 /// @since 4.6 0323 UDS_COMMENT = 28 | UDS_STRING, 0324 0325 /// Device number for this file, used to detect hardlinks 0326 /// @since 4.7.3 0327 UDS_DEVICE_ID = 29 | UDS_NUMBER, 0328 /// Inode number for this file, used to detect hardlinks 0329 /// @since 4.7.3 0330 UDS_INODE = 30 | UDS_NUMBER, 0331 0332 /// For folders, the recursize size of its content 0333 /// @since 5.70 0334 UDS_RECURSIVE_SIZE = 31 | UDS_NUMBER, 0335 0336 /// Extra data (used only if you specified Columns/ColumnsTypes) 0337 /// NB: you cannot repeat this entry; use UDS_EXTRA + i 0338 /// until UDS_EXTRA_END. 0339 UDS_EXTRA = 100 | UDS_STRING, 0340 /// Extra data (used only if you specified Columns/ColumnsTypes) 0341 /// NB: you cannot repeat this entry; use UDS_EXTRA + i 0342 /// until UDS_EXTRA_END. 0343 UDS_EXTRA_END = 140 | UDS_STRING, 0344 }; 0345 0346 private: 0347 QSharedDataPointer<UDSEntryPrivate> d; 0348 friend KIOCORE_EXPORT QDataStream & ::operator<<(QDataStream &s, const KIO::UDSEntry &a); 0349 friend KIOCORE_EXPORT QDataStream & ::operator>>(QDataStream &s, KIO::UDSEntry &a); 0350 friend KIOCORE_EXPORT QDebug(::operator<<)(QDebug stream, const KIO::UDSEntry &entry); 0351 0352 public: 0353 /** 0354 * Replace or insert field with string value 0355 * @param field numeric field id 0356 * @param value to set 0357 * @since 5.47 0358 */ 0359 void replace(uint field, const QString &value); 0360 0361 /** 0362 * Replace or insert field with numeric value 0363 * @param field numeric field id 0364 * @param l value to set 0365 * @since 5.47 0366 */ 0367 void replace(uint field, long long l); 0368 }; 0369 0370 } 0371 0372 Q_DECLARE_TYPEINFO(KIO::UDSEntry, Q_MOVABLE_TYPE); 0373 0374 namespace KIO 0375 { 0376 /** 0377 * A directory listing is a list of UDSEntry instances. 0378 * 0379 * To list the name and size of all the files in a directory listing you would do: 0380 * \code 0381 * KIO::UDSEntryList::ConstIterator it = entries.begin(); 0382 * const KIO::UDSEntryList::ConstIterator end = entries.end(); 0383 * for (; it != end; ++it) { 0384 * const KIO::UDSEntry& entry = *it; 0385 * QString name = entry.stringValue( KIO::UDSEntry::UDS_NAME ); 0386 * bool isDir = entry.isDir(); 0387 * KIO::filesize_t size = entry.numberValue( KIO::UDSEntry::UDS_SIZE, -1 ); 0388 * ... 0389 * } 0390 * \endcode 0391 */ 0392 typedef QList<UDSEntry> UDSEntryList; 0393 } // end namespace 0394 0395 Q_DECLARE_METATYPE(KIO::UDSEntry) 0396 0397 #endif /*UDSENTRY_H*/