KIO::UDSEntry Class

class KIO::UDSEntry

Universal Directory Service. More...

Header: #include <KIO/UDSEntry>
CMake: find_package(KF6 REQUIRED COMPONENTS KIO)
target_link_libraries(mytarget PRIVATE KF6::KIOCore)

Public Types

enum ItemTypes { UDS_STRING, UDS_NUMBER, UDS_TIME }
enum StandardFieldTypes { UDS_SIZE, UDS_USER, UDS_ICON_NAME, UDS_GROUP, UDS_NAME, …, UDS_EXTRA_END }

Public Functions

UDSEntry()
(since 5.0) UDSEntry(const struct stat64 &buff, const QString &name = QString())
UDSEntry(const KIO::UDSEntry &)
void clear()
bool contains(uint field) const
int count() const
(since 5.48) void fastInsert(uint field, const QString &value)
(since 5.48) void fastInsert(uint field, long long l)
(since 5.8) QList<uint> fields() const
bool isDir() const
bool isLink() const
long long numberValue(uint field, long long defaultValue = 0) const
(since 5.47) void replace(uint field, const QString &value)
(since 5.47) void replace(uint field, long long l)
void reserve(int size)
QString stringValue(uint field) const

Detailed Description

UDS entry is the data structure representing all the fields about a given URL (file or directory).

The KIO::listDir() and KIO:stat() operations use this data structure.

KIO defines a number of standard fields, see the UDS_XXX enums (see StandardFieldTypes). at the moment UDSEntry only provides fields with numeric indexes, but there might be named fields with string indexes in the future.

For instance, to retrieve the name of the entry, use:

QString displayName = entry.stringValue( KIO::UDSEntry::UDS_NAME );

To know the modification time of the file/url:

QDateTime mtime = QDateTime::fromSecsSinceEpoch(entry.numberValue(KIO::UDSEntry::UDS_MODIFICATION_TIME, 0));
if (mtime.isValid())
    ...

Member Type Documentation

enum UDSEntry::ItemTypes

Bit field used to specify the item type of a StandardFieldTypes.

ConstantValueDescription
KIO::UDSEntry::UDS_STRING0x01000000Indicates that the field is a QString
KIO::UDSEntry::UDS_NUMBER0x02000000Indicates that the field is a number (long long)
KIO::UDSEntry::UDS_TIME0x04000000 | UDS_NUMBERIndicates that the field represents a time, which is modelled by a long long

enum UDSEntry::StandardFieldTypes

Constants used to specify the type of a UDSEntry’s field.

ConstantValueDescription
KIO::UDSEntry::UDS_SIZE1 | UDS_NUMBERSize of the file
KIO::UDSEntry::UDS_USER3 | UDS_STRINGUser Name of the file owner. Not present on local fs, use UDS_LOCAL_USER_ID
KIO::UDSEntry::UDS_ICON_NAME4 | UDS_STRINGName of the icon, that should be used for displaying. It overrides all other detection mechanisms
KIO::UDSEntry::UDS_GROUP5 | UDS_STRINGGroup Name of the file owner. Not present on local fs, use UDS_LOCAL_GROUP_ID
KIO::UDSEntry::UDS_NAME6 | UDS_STRINGFilename - as displayed in directory listings etc. "." has the usual special meaning of "current directory" UDS_NAME must always be set and never be empty, neither contain '/'. Note that KIO will append the UDS_NAME to the url of their parent directory, so all KIO workers must use that naming scheme ("url_of_parent/filename" will be the full url of that file). To customize the appearance of files without changing the url of the items, use UDS_DISPLAY_NAME.
KIO::UDSEntry::UDS_LOCAL_PATH7 | UDS_STRINGA local file path if the KIO worker display files sitting on the local filesystem (but in another hierarchy, e.g. settings:/ or remote:/)
KIO::UDSEntry::UDS_HIDDEN8 | UDS_NUMBERTreat 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 for a leading dot in the filename).
KIO::UDSEntry::UDS_ACCESS9 | UDS_NUMBERAccess permissions (part of the mode returned by stat)
KIO::UDSEntry::UDS_MODIFICATION_TIME10 | UDS_TIMEThe last time the file was modified. Required time format: seconds since UNIX epoch.
KIO::UDSEntry::UDS_ACCESS_TIME11 | UDS_TIMEThe last time the file was opened. Required time format: seconds since UNIX epoch.
KIO::UDSEntry::UDS_CREATION_TIME12 | UDS_TIMEThe time the file was created. Required time format: seconds since UNIX epoch.
KIO::UDSEntry::UDS_FILE_TYPE13 | UDS_NUMBERFile 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 know if this is a link
KIO::UDSEntry::UDS_LINK_DEST14 | UDS_STRINGName of the file where the link points to. Allows to check for a symlink (don't use S_ISLNK !)
KIO::UDSEntry::UDS_URL15 | UDS_STRINGAn alternative URL (If different from the caption). Can be used to mix different hierarchies. Use UDS_DISPLAY_NAME if you simply want to customize the user-visible filenames, or use UDS_TARGET_URL if you want "links" to unrelated urls.
KIO::UDSEntry::UDS_MIME_TYPE16 | UDS_STRINGA MIME type; the KIO worker should set it if it's known.
KIO::UDSEntry::UDS_GUESSED_MIME_TYPE17 | UDS_STRINGA MIME type to be used for displaying only. But when 'running' the file, the MIME type is re-determined. This is for special cases like symlinks in FTP; you probably don't want to use this one
KIO::UDSEntry::UDS_XML_PROPERTIES18 | UDS_STRINGXML properties, e.g. for WebDAV
KIO::UDSEntry::UDS_EXTENDED_ACL19 | UDS_NUMBERIndicates that the entry has extended ACL entries
KIO::UDSEntry::UDS_ACL_STRING20 | UDS_STRINGThe access control list serialized into a single string
KIO::UDSEntry::UDS_DEFAULT_ACL_STRING21 | UDS_STRINGThe default access control list serialized into a single string. Only available for directories
KIO::UDSEntry::UDS_DISPLAY_NAME (since Qt 4.1)22 | UDS_STRINGIf set, contains the label to display instead of the 'real name' in UDS_NAME
KIO::UDSEntry::UDS_TARGET_URL (since Qt 4.1)23 | UDS_STRINGThis file is a shortcut or mount, pointing to an URL in a different hierarchy
KIO::UDSEntry::UDS_DISPLAY_TYPE (since Qt 4.4)24 | UDS_STRINGUser-readable type of file (if not specified, the MIME type's description is used)
KIO::UDSEntry::UDS_ICON_OVERLAY_NAMES (since Qt 4.5)25 | UDS_STRINGA comma-separated list of supplementary icon overlays which will be added to the list of overlays created by KFileItem.
KIO::UDSEntry::UDS_COMMENT (since Qt 4.6)26 | UDS_STRINGA comment which will be displayed as is to the user. The string value may contain plain text or Qt-style rich-text extensions.
KIO::UDSEntry::UDS_DEVICE_ID (since Qt 4.7.3)27 | UDS_NUMBERDevice number for this file, used to detect hardlinks
KIO::UDSEntry::UDS_INODE (since Qt 4.7.3)28 | UDS_NUMBERInode number for this file, used to detect hardlinks
KIO::UDSEntry::UDS_RECURSIVE_SIZE (since Qt 5.70)29 | UDS_NUMBERFor folders, the recursize size of its content
KIO::UDSEntry::UDS_LOCAL_USER_ID (since Qt 6.0)30 | UDS_NUMBERUser ID of the file owner
KIO::UDSEntry::UDS_LOCAL_GROUP_ID (since Qt 6.0)31 | UDS_NUMBERGroup ID of the file owner
KIO::UDSEntry::UDS_EXTRA100 | UDS_STRINGExtra data (used only if you specified Columns/ColumnsTypes). NB: you cannot repeat this entry; use UDS_EXTRA + i until UDS_EXTRA_END
KIO::UDSEntry::UDS_EXTRA_END140 | UDS_STRING 

Member Function Documentation

UDSEntry::UDSEntry()

[since 5.0] UDSEntry::UDSEntry(const struct stat64 &buff, const QString &name = QString())

Create a UDSEntry by QT_STATBUF

buff QT_STATBUF object

name filename

This function was introduced in 5.0.

UDSEntry::UDSEntry(const KIO::UDSEntry &)

Copy constructor

void UDSEntry::clear()

remove all fields

bool UDSEntry::contains(uint field) const

check existence of a field

field numeric field id

int UDSEntry::count() const

Returns the number of fields

[since 5.48] void UDSEntry::fastInsert(uint field, const QString &value)

insert field with string value, it will assert if the field is already inserted. In that case, use replace() instead.

field numeric field id

value to set

This function was introduced in 5.48.

[since 5.48] void UDSEntry::fastInsert(uint field, long long l)

insert field with numeric value, it will assert if the field is already inserted. In that case, use replace() instead.

field numeric field id

l value to set

This function was introduced in 5.48.

[since 5.8] QList<uint> UDSEntry::fields() const

A vector of fields being present for the current entry.

Returns all fields for the current entry.

This function was introduced in 5.8.

bool UDSEntry::isDir() const

Returns true if this entry is a directory (or a link to a directory)

Returns true if this entry is a link

long long UDSEntry::numberValue(uint field, long long defaultValue = 0) const

Returns value of a numeric field

[since 5.47] void UDSEntry::replace(uint field, const QString &value)

Replace or insert field with string value

field numeric field id

value to set

This function was introduced in 5.47.

[since 5.47] void UDSEntry::replace(uint field, long long l)

Replace or insert field with numeric value

field numeric field id

l value to set

This function was introduced in 5.47.

void UDSEntry::reserve(int size)

Calling this function before inserting items into an empty UDSEntry may save time and memory.

size number of items for which memory will be pre-allocated

QString UDSEntry::stringValue(uint field) const

Returns value of a textual field

Related Non-Members

UDSEntryList

A directory listing is a list of UDSEntry instances.

To list the name and size of all the files in a directory listing you would do:

KIO::UDSEntryList::ConstIterator it = entries.begin();
const KIO::UDSEntryList::ConstIterator end = entries.end();
for (; it != end; ++it) {
  const KIO::UDSEntry& entry = *it;
  QString name = entry.stringValue( KIO::UDSEntry::UDS_NAME );
  bool isDir = entry.isDir();
  KIO::filesize_t size = entry.numberValue( KIO::UDSEntry::UDS_SIZE, -1 );
  ...
}