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.

Referenced by FileRef(), operator!=(), operator=(), operator==(), and swap().

## 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.

References TagLib::AudioProperties::Average.

## 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.

References TagLib::AudioProperties::Average.

## 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.

References file().

## FileRef() [5/5]

TagLib::FileRef::FileRef | ( | const FileRef & | ref | ) |

Make a copy of ref.

References FileRef().

## ~FileRef()

TagLib::FileRef::~FileRef | ( |  | ) |

Destroys this FileRef instance.

## Member Function Documentation

## addFileTypeResolver()

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()

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()

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.

Referenced by FileRef().

## 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.

References FileRef(), and TAGLIB_MSVC_SUPPRESS_WARNING_NEEDS_TO_HAVE_DLL_INTERFACE.

## operator=()

FileRef & TagLib::FileRef::operator= | ( | const FileRef & | ref | ) |

Assign the file pointed to by ref to this FileRef.

References FileRef().

## operator==()

bool TagLib::FileRef::operator== | ( | const FileRef & | ref | ) | const

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

References FileRef().

## 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).

Referenced by removeUnsupportedProperties(), and setProperties().

## 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().

References properties().

## 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.

References properties().

## swap()

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

noexcept

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

References FileRef().

## 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