TagLib::FileRef Class Reference

This class provides a simple abstraction for creating and handling files. More...

#include <fileref.h>

Classes
class	FileTypeResolver
	A class for pluggable file type resolution. More...
class	StreamTypeResolver
	A class for pluggable stream type resolution. More...

Public Member Functions
	FileRef ()
	FileRef (FileName fileName, bool readAudioProperties=true, AudioProperties::ReadStyle audioPropertiesStyle=AudioProperties::Average)
	FileRef (IOStream *stream, bool readAudioProperties=true, AudioProperties::ReadStyle audioPropertiesStyle=AudioProperties::Average)
	FileRef (File *file)
	FileRef (const FileRef &ref)
	~FileRef ()
Tag *	tag () const
PropertyMap	properties () const
void	removeUnsupportedProperties (const StringList &properties)
PropertyMap	setProperties (const PropertyMap &properties)
StringList	complexPropertyKeys () const
List< VariantMap >	complexProperties (const String &key) const
bool	setComplexProperties (const String &key, const List< VariantMap > &value)
AudioProperties *	audioProperties () const
File *	file () const
bool	save ()
bool	isNull () const
FileRef &	operator= (const FileRef &ref)
void	swap (FileRef &ref) noexcept
bool	operator== (const FileRef &ref) const
bool	operator!= (const FileRef &ref) const

Static Public Member Functions
static const FileTypeResolver *	addFileTypeResolver (const FileTypeResolver *resolver)
static void	clearFileTypeResolvers ()
static StringList	defaultFileExtensions ()

Detailed Description

This class provides a simple abstraction for creating and handling files.

FileRef exists to provide a minimal, generic and value-based wrapper around a File. It is lightweight and implicitly shared, and as such suitable for pass-by-value use. This hides some of the uglier details of TagLib::File and the non-generic portions of the concrete file implementations.

This class is useful in a "simple usage" situation where it is desirable to be able to get and set some of the tag information that is similar across file types.

Also note that it is probably a good idea to plug this into your mime type system rather than using the constructor that accepts a file name using the FileTypeResolver.

See also

FileTypeResolver

addFileTypeResolver()

Constructor & Destructor Documentation

FileRef() [1/5]

TagLib::FileRef::FileRef

(

)

Creates a null FileRef.

FileRef() [2/5]

TagLib::FileRef::FileRef ( FileName  fileName, bool  readAudioProperties = true, AudioProperties::ReadStyle  audioPropertiesStyle = AudioProperties::Average  )

explicit

Create a FileRef from fileName. If readAudioProperties is true then the audio properties will be read using audioPropertiesStyle. If readAudioProperties is false then audioPropertiesStyle will be ignored.

Also see the note in the class documentation about why you may not want to use this method in your application.

FileRef() [3/5]

TagLib::FileRef::FileRef ( IOStream *  stream, bool  readAudioProperties = true, AudioProperties::ReadStyle  audioPropertiesStyle = AudioProperties::Average  )

explicit

Construct a FileRef from an opened IOStream. If readAudioProperties is true then the audio properties will be read using audioPropertiesStyle. If readAudioProperties is false then audioPropertiesStyle will be ignored.

Also see the note in the class documentation about why you may not want to use this method in your application.

Note

TagLib will not take ownership of the stream, the caller is responsible for deleting it after the File object.

FileRef() [4/5]

TagLib::FileRef::FileRef ( File *  file )

explicit

Construct a FileRef using file. The FileRef now takes ownership of the pointer and will delete the File when it passes out of scope.

FileRef() [5/5]

TagLib::FileRef::FileRef

(

const FileRef &

ref

)

Make a copy of ref.

~FileRef()

TagLib::FileRef::~FileRef

(

)

Destroys this FileRef instance.

Member Function Documentation

addFileTypeResolver()

static const FileTypeResolver * TagLib::FileRef::addFileTypeResolver ( const FileTypeResolver *  resolver )

static

Adds a FileTypeResolver to the list of those used by TagLib. Each additional FileTypeResolver is added to the front of a list of resolvers that are tried. If the FileTypeResolver returns zero the next resolver is tried.

Returns a pointer to the added resolver (the same one that's passed in – this is mostly so that static initializers have something to use for assignment).

See also

FileTypeResolver

audioProperties()

AudioProperties * TagLib::FileRef::audioProperties

(

)

const

Returns the audio properties for this FileRef. If no audio properties were read then this will return a null pointer.

clearFileTypeResolvers()

static void TagLib::FileRef::clearFileTypeResolvers ( )

static

Remove all resolvers added by addFileTypeResolver().

complexProperties()

List< VariantMap > TagLib::FileRef::complexProperties

(

const String &

key

)

const

Get the complex properties for a given key. In order to be flexible for different metadata formats, the properties are represented as variant maps. Despite this dynamic nature, some degree of standardization should be achieved between formats:

• PICTURE
  • data: ByteVector with picture data
  • description: String with description
  • pictureType: String with type as specified for ID3v2, e.g. "Front Cover", "Back Cover", "Band"
  • mimeType: String with image format, e.g. "image/jpeg"
  • optionally more information found in the tag, such as "width", "height", "numColors", "colorDepth" int values in FLAC pictures
• GENERALOBJECT
  • data: ByteVector with object data
  • description: String with description
  • fileName: String with file name
  • mimeType: String with MIME type
  • this is currently only implemented for ID3v2 GEOB frames

Calls the method on the wrapped File, which gets the properties from one or more of its tags.

complexPropertyKeys()

StringList TagLib::FileRef::complexPropertyKeys

(

)

const

Get the keys of complex properties, i.e. properties which cannot be represented simply by a string. Because such properties might be expensive to fetch, there are separate operations to get the available keys - which is expected to be cheap - and getting and setting the property values. Calls the method on the wrapped File, which collects the keys from one or more of its tags.

defaultFileExtensions()

static StringList TagLib::FileRef::defaultFileExtensions ( )

static

As is mentioned elsewhere in this class's documentation, the default file type resolution code provided by TagLib only works by comparing file extensions.

This method returns the list of file extensions that are used by default.

The extensions are all returned in lowercase, though the comparison used by TagLib for resolution is case-insensitive.

Note

This does not account for any additional file type resolvers that are plugged in. Also note that this is not intended to replace a proper mime-type resolution system, but is just here for reference.

See also

FileTypeResolver

file()

File * TagLib::FileRef::file

(

)

const

Returns a pointer to the file represented by this handler class.

As a general rule this call should be avoided since if you need to work with file objects directly, you are probably better served instantiating the File subclasses (i.e. MPEG::File) manually and working with their APIs.

This handle exists to provide a minimal, generic and value-based wrapper around a File. Accessing the file directly generally indicates a moving away from this simplicity (and into things beyond the scope of FileRef).

Warning

This pointer will become invalid when this FileRef and all copies pass out of scope.

isNull()

bool TagLib::FileRef::isNull

(

)

const

Returns true if the file (and as such other pointers) are null.

operator!=()

bool TagLib::FileRef::operator!=

(

const FileRef &

ref

)

const

Returns true if this FileRef and ref do not point to the same File object.

operator=()

FileRef & TagLib::FileRef::operator=

(

const FileRef &

ref

)

Assign the file pointed to by ref to this FileRef.

operator==()

bool TagLib::FileRef::operator==

(

const FileRef &

ref

)

const

Returns true if this FileRef and ref point to the same File object.

properties()

PropertyMap TagLib::FileRef::properties

(

)

const

Exports the tags of the file as dictionary mapping (human readable) tag names (uppercase Strings) to StringLists of tag values. Calls this method on the wrapped File instance. For each metadata object of the file that could not be parsed into the PropertyMap format, the returned map's unsupportedData() list will contain one entry identifying that object (e.g. the frame type for ID3v2 tags). Use removeUnsupportedProperties() to remove (a subset of) them. For files that contain more than one tag (e.g. an MP3 with both an ID3v1 and an ID3v2 tag) only the most "modern" one will be exported (ID3v2 in this case).

removeUnsupportedProperties()

void TagLib::FileRef::removeUnsupportedProperties

(

const StringList &

properties

)

Removes unsupported properties, or a subset of them, from the file's metadata. The parameter properties must contain only entries from properties().unsupportedData().

save()

bool TagLib::FileRef::save

(

)

Saves the file. Returns true on success.

setComplexProperties()

bool TagLib::FileRef::setComplexProperties	(	const String &	key,
		const List< VariantMap > &	value
	)

Set all complex properties for a given key using variant maps as value with the same format as returned by complexProperties(). An empty list as value removes all complex properties for key.

setProperties()

PropertyMap TagLib::FileRef::setProperties

(

const PropertyMap &

properties

)

Sets the tags of the wrapped File to those specified in properties. If some value(s) could not be written to the specific metadata format, the returned PropertyMap will contain those value(s). Otherwise it will be empty, indicating that no problems occurred. With file types that support several tag formats (for instance, MP3 files can have ID3v1, ID3v2, and APEv2 tags), this function will create the most appropriate one (ID3v2 for MP3 files). Older formats will be updated as well, if they exist, but won't be taken into account for the return value of this function. See the documentation of the subclass implementations for detailed descriptions.

swap()

void TagLib::FileRef::swap ( FileRef &  ref )

noexcept

Exchanges the content of the FileRef with the content of ref.

tag()

Tag * TagLib::FileRef::tag

(

)

const

Returns a pointer to the represented file's tag.

Warning

This pointer will become invalid when this FileRef and all copies pass out of scope.

Do not cast it to any subclasses of Tag. Use tag returning methods of appropriate subclasses of File instead.

See also

File::tag()

---

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

• fileref.h