KFileMetaInfo Class Reference

Meta Information about a file. More...

#include <kfilemetainfo.h>

List of all members.

Public Types
typedef KFileMimeTypeInfo::Attributes	Attributes
typedef KFileMimeTypeInfo::Hint	Hint
typedef KFileMimeTypeInfo::Unit	Unit
enum	What {   Fastest = 0x1, DontCare = 0x2, TechnicalInfo = 0x4, ContentInfo = 0x8,   ExtenedAttr = 0x10, Thumbnail = 0x20, Preferred = 0x40, Everything = 0xffff }
Public Member Functions
bool	addGroup (const QString &name)
bool	applyChanges (const QString &path)
bool	applyChanges ()
bool	contains (const QString &key) const
bool	containsGroup (const QString &key) const
QStringList	editableGroups () const
KFileMetaInfoGroup	group (const QString &key) const
QStringList	groups () const
bool	isEmpty () const
bool	isValid () const
KFileMetaInfoItem	item (const KFileMetaInfoItem::Hint hint) const
KFileMetaInfoItem	item (const QString &key) const
	KFileMetaInfo (const KFileMetaInfo &original)
	KFileMetaInfo ()
	KFileMetaInfo (const KURL &url, const QString &mimeType=QString::null, uint what=Fastest)
	KFileMetaInfo (const QString &path, const QString &mimeType=QString::null, uint what=Fastest)
QString	mimeType () const
const KFileMetaInfo &	operator= (const KFileMetaInfo &info)
KFileMetaInfoGroup	operator[] (const QString &key) const
QString	path () const
QStringList	preferredGroups () const
QStringList	preferredKeys () const
QStringList	removedGroups ()
bool	removeGroup (const QString &name)
KFileMetaInfoItem	saveItem (const QString &key, const QString &preferredGroup=QString::null, bool createGroup=true)
QStringList	supportedGroups () const
QStringList	supportedKeys () const
KURL	url () const
const QVariant	value (const QString &key) const
	~KFileMetaInfo ()
Protected Member Functions
KFileMetaInfoGroup	appendGroup (const QString &name)
void	deref ()
KFilePlugin *const	plugin () const
void	ref ()
Protected Attributes
Data *	d
Friends
KIO_EXPORT friend QDataStream &	operator<< (QDataStream &s, const KFileMetaInfo &)
KIO_EXPORT friend QDataStream &	operator>> (QDataStream &s, KFileMetaInfo &)

---

Detailed Description

Meta Information about a file.

This is the class for objects that hold meta information about a file. The information is kept in form of a system of key/value pairs. See also KFileMetaInfoItem. This information is retrieved from the file through a plugin system, and this class is the main interface to it. If you want to write your own plugin, have a look at KFilePlugin. There are basically two different kinds of meta information: Fixed ones that the plugin knows about (e.g. an mp3 id3v1 tag has a well defined fixed list of fields), and variable keys that exist in mimetypes that support their own key/value system (comments in png files are of this type). Almost every file has fixed keys, but some also have variable keys.

The groups and the What enum are not yet supported, but already added to the interface so that adding support doesn't break compatibility.

Definition at line 926 of file kfilemetainfo.h.

---

Member Typedef Documentation

typedef KFileMimeTypeInfo::Attributes KFileMetaInfo::Attributes

Definition at line 931 of file kfilemetainfo.h.

typedef KFileMimeTypeInfo::Hint KFileMetaInfo::Hint

Definition at line 929 of file kfilemetainfo.h.

typedef KFileMimeTypeInfo::Unit KFileMetaInfo::Unit

Definition at line 930 of file kfilemetainfo.h.

---

Member Enumeration Documentation

enum KFileMetaInfo::What

This is used to specify what a KFileMetaInfo object should read, so you can specify if you want to read "expensive" items or not.

Enumerator:

Fastest	do the fastest possible read and omit all items that might need a significantly longer time than the others
DontCare	let the plugin decide what to read
TechnicalInfo	extract technical details about the file, like e.g. play time, resolution or a compressioni type
ContentInfo	read information about the content of the file, like comments or id3 tags
ExtenedAttr	read filesystem based extended attributes if they are supported for the filesystem
Thumbnail	only read the file's thumbnail, if it contains one
Preferred	get at least the preferred items
Everything	read everything, even if it might take a while

Definition at line 938 of file kfilemetainfo.h.

---

Constructor & Destructor Documentation

KFileMetaInfo::KFileMetaInfo	(	const QString &	path,
		const QString &	mimeType = QString::null,
		uint	what = Fastest
	)

The constructor.

creating a KFileMetaInfo item through this will autoload the plugin belonging to the mimetype and try to get meta information about the specified file.

If no info is available, you'll get an empty (not invalid) object. You can test for it with the isEmpty() method.

Parameters:

	path	The file name. This must be the path to a local file.
	mimeType	The name of the file's mimetype. If ommited, the mimetype is autodetected
	what	one or more of the What enum values. It gives some hint to the plugin what information is desired. The plugin may still return more items.

Note:

This version will only work for local (file:/) files.

Definition at line 297 of file kfilemetainfo.cpp.

KFileMetaInfo::KFileMetaInfo	(	const KURL &	url,
		const QString &	mimeType = QString::null,
		uint	what = Fastest
	)

Another constructor.

Similar to the above, but takes a URL so that meta-data may be retrieved over other protocols (ftp, etc.)

Definition at line 306 of file kfilemetainfo.cpp.

KFileMetaInfo::KFileMetaInfo

(

)

Default constructor.

This will create an invalid object (see isValid().

Definition at line 355 of file kfilemetainfo.cpp.

KFileMetaInfo::KFileMetaInfo

(

const KFileMetaInfo &

original

)

Copy constructor.

This creates a copy of the original object, but that copy will point to the same data, so if you change the original, the copy will be changed, too. After all, they are referring to the same file.

Definition at line 348 of file kfilemetainfo.cpp.

KFileMetaInfo::~KFileMetaInfo

(

)

Definition at line 360 of file kfilemetainfo.cpp.

---

Member Function Documentation

bool KFileMetaInfo::addGroup

(

const QString &

name

)

Try to add the specified group.

This will only succeed if it is in the list of editableGroups().

Note:

that all non-variable items that belong to this group are automatically added as empty item.

Parameters:

name

the name of the group to add

Returns:

true if successful, false if not

Definition at line 450 of file kfilemetainfo.cpp.

KFileMetaInfoGroup KFileMetaInfo::appendGroup

(

const QString &

name

)

[protected]

Definition at line 717 of file kfilemetainfo.cpp.

bool KFileMetaInfo::applyChanges

(

const QString &

path

)

This method writes all pending changes of the meta info to the file path.

If any items are marked as removed, they are really removed from the list. The info object as well as all items are updated.

Returns:

true if successful, false if not

Definition at line 537 of file kfilemetainfo.cpp.

bool KFileMetaInfo::applyChanges

(

)

This method writes all pending changes of the meta info back to the file.

If any items are marked as removed, they are really removed from the list. The info object as well as all items are updated.

Returns:

true if successful, false if not

Definition at line 532 of file kfilemetainfo.cpp.

bool KFileMetaInfo::contains

(

const QString &

key

)

const

Checks whether an item with the given key exists.

Parameters:

key

the key to check

Returns:

whether an item for this key exists.

Definition at line 598 of file kfilemetainfo.cpp.

bool KFileMetaInfo::containsGroup

(

const QString &

key

)

const

Checks whether a group with the given key exists.

Parameters:

key

the key to check

Returns:

whether a group with this name exists.

Definition at line 609 of file kfilemetainfo.cpp.

void KFileMetaInfo::deref

(

)

[protected]

Definition at line 750 of file kfilemetainfo.cpp.

QStringList KFileMetaInfo::editableGroups

(

)

const

Returns the list of groups that you can add or remove from the file.

Returns:

the groups can be added or removed

Definition at line 387 of file kfilemetainfo.cpp.

KFileMetaInfoGroup KFileMetaInfo::group

(

const QString &

key

)

const

Returns the KFileMetaInfoGroup with the given key.

Parameters:

key

the key of the item

Returns:

the group. Invalid if there is no group with the given key.

Definition at line 441 of file kfilemetainfo.cpp.

QStringList KFileMetaInfo::groups

(

)

const

Returns a list of all groups.

Returns:

the keys of the groups that the file has.

Definition at line 377 of file kfilemetainfo.cpp.

bool KFileMetaInfo::isEmpty

(

)

const

Returns false if the object contains data, true if it's empty.

You'll get an empty object if no plugin for the file could be found.

Returns:

true if empty, false otherwise

Definition at line 523 of file kfilemetainfo.cpp.

bool KFileMetaInfo::isValid

(

)

const

Returns true if the item is valid, i.e.

if actually represents the info about a file, false if the object is uninitialized.

Returns:

true if valid, false otherwise

Definition at line 517 of file kfilemetainfo.cpp.

KFileMetaInfoItem KFileMetaInfo::item

(

const KFileMetaInfoItem::Hint

hint

)

const

Returns the KFileMetaInfoItem with the given hint.

Parameters:

hint

the hint of the item

Returns:

the item. Invalid if there is no item with the given hint.

Definition at line 625 of file kfilemetainfo.cpp.

KFileMetaInfoItem KFileMetaInfo::item

(

const QString &

key

)

const

Returns the KFileMetaInfoItem with the given key.

Parameters:

key

the key of the item

Returns:

the item. Invalid if there is no item with the given key.

Definition at line 614 of file kfilemetainfo.cpp.

QString KFileMetaInfo::mimeType

(

)

const

Returns the mime type of file.

Returns:

the file's mime type

Definition at line 592 of file kfilemetainfo.cpp.

const KFileMetaInfo & KFileMetaInfo::operator=

(

const KFileMetaInfo &

info

)

The assignment operator, so you can do e.g.

:

    KFileMetaInfo info;
    if (something) info = KFileMetaInfo("/the/file");

This will create a shared copy of the object. The actual data is automatically deleted if all copies go out of scope.

Definition at line 504 of file kfilemetainfo.cpp.

KFileMetaInfoGroup KFileMetaInfo::operator[]

(

const QString &

key

)

const [inline]

Returns the KFileMetaInfoGroup with the given key.

Parameters:

key

the key of the item

Returns:

the group. Invalid if there is no group with the given key.

Definition at line 1108 of file kfilemetainfo.h.

QString KFileMetaInfo::path

(

)

const

Returns the path of file - or QString::null if file is non-local.

Returns:

the file's path - or QString::null if file is non-local

Definition at line 734 of file kfilemetainfo.cpp.

KFilePlugin *const KFileMetaInfo::plugin

(

)

const [protected]

Returns:

a pointer to the plugin that belogs to this object's mimetype. It will be auto-loaded if it's currently not loaded

Definition at line 585 of file kfilemetainfo.cpp.

QStringList KFileMetaInfo::preferredGroups

(

)

const

Returns a list of the preferred groups.

Returns:

the keys of the preferred groups that the file has.

Definition at line 402 of file kfilemetainfo.cpp.

QStringList KFileMetaInfo::preferredKeys

(

)

const

Returns a list of all preferred keys.

Returns:

a list of all preferred keys.

Definition at line 428 of file kfilemetainfo.cpp.

void KFileMetaInfo::ref

(

)

[protected]

Definition at line 744 of file kfilemetainfo.cpp.

QStringList KFileMetaInfo::removedGroups

(

)

Returns a list of removed groups.

Returns:

a list of removed groups.

Definition at line 499 of file kfilemetainfo.cpp.

bool KFileMetaInfo::removeGroup

(

const QString &

name

)

Remove the specified group.

This will only succeed if it is in the list of editableGroups(). Beware that this also removes all the items in that group, so always ask the user before removing it!

Parameters:

name

the name of the group to remove

Returns:

true if successful, false if not

Definition at line 487 of file kfilemetainfo.cpp.

KFileMetaInfoItem KFileMetaInfo::saveItem	(	const QString &	key,
		const QString &	preferredGroup = QString::null,
		bool	createGroup = true
	)

Saves the item with the given key.

Parameters:

	key	the key of the item
	preferredGroup	the preferred group, or QString::null
	createGroup	true to create the group if necessary

Returns:

the saved item

Definition at line 637 of file kfilemetainfo.cpp.

QStringList KFileMetaInfo::supportedGroups

(

)

const

Returns a list of all supported groups.

Returns:

the supported keys of the groups that the file has.

Definition at line 365 of file kfilemetainfo.cpp.

QStringList KFileMetaInfo::supportedKeys

(

)

const

Returns a list of supported keys.

Returns:

a list of supported keys

Definition at line 371 of file kfilemetainfo.cpp.

KURL KFileMetaInfo::url

(

)

const

Returns the url of file.

Returns:

the file's url

Definition at line 739 of file kfilemetainfo.cpp.

const QVariant KFileMetaInfo::value

(

const QString &

key

)

const [inline]

Returns the value with the given key.

Parameters:

key

the key to retrieve

Returns:

the value. Invalid if it does not exist

Definition at line 1183 of file kfilemetainfo.h.

---

Friends And Related Function Documentation

KIO_EXPORT friend QDataStream& operator<<	(	QDataStream &	s,
		const KFileMetaInfo &
	)			[friend]

Definition at line 1815 of file kfilemetainfo.cpp.

KIO_EXPORT friend QDataStream& operator>>	(	QDataStream &	s,
		KFileMetaInfo &
	)			[friend]

Definition at line 1833 of file kfilemetainfo.cpp.

---

Member Data Documentation

Data* KFileMetaInfo::d [protected]

Definition at line 1242 of file kfilemetainfo.h.

---

The documentation for this class was generated from the following files:

• kfilemetainfo.h
• kfilemetainfo.cpp