TagLib::File Class Referenceabstract

A file class with some useful methods for tag manipulation. More...

`#include <tfile.h>`

Inheritance diagram for TagLib::File:
[legend]

## Public Types

enum | Position { Beginning , Current , End }
enum | StripTags { StripNone , StripOthers }
enum | DuplicateTags { Duplicate , DoNotDuplicate }

## Public Member Functions

virtual | ~File ()
| File (const File &)=delete
File & | operator= (const File &)=delete
FileName | name () const
virtual Tag * | tag () const =0
virtual PropertyMap | properties () const
virtual void | removeUnsupportedProperties (const StringList &properties)
virtual PropertyMap | setProperties (const PropertyMap &properties)
virtual StringList | complexPropertyKeys () const
virtual List< VariantMap > | complexProperties (const String &key) const
virtual bool | setComplexProperties (const String &key, const List< VariantMap > &value)
virtual AudioProperties * | audioProperties () const =0
virtual bool | save ()=0
ByteVector | readBlock (size_t length)
void | writeBlock (const ByteVector &data)
offset_t | find (const ByteVector &pattern, offset_t fromOffset=0, const ByteVector &before=ByteVector())
offset_t | rfind (const ByteVector &pattern, offset_t fromOffset=0, const ByteVector &before=ByteVector())
void | insert (const ByteVector &data, offset_t start=0, size_t replace=0)
void | removeBlock (offset_t start=0, size_t length=0)
bool | readOnly () const
bool | isOpen () const
bool | isValid () const
void | seek (offset_t offset, Position p=Beginning)
void | clear ()
offset_t | tell () const
offset_t | length ()

## Protected Member Functions

| File (FileName fileName)
| File (IOStream *stream)
void | setValid (bool valid)
void | truncate (offset_t length)

## Static Protected Member Functions

static unsigned int | bufferSize ()

## Detailed Description

A file class with some useful methods for tag manipulation.

This class is a basic file class with some methods that are particularly useful for tag editors. It has methods to take advantage of ByteVector and a binary search method for finding patterns in a file.

## Member Enumeration Documentation

## DuplicateTags

enum TagLib::File::DuplicateTags

Used to specify if when saving files, if values between different tag types should be synchronized.

Enumerator
Duplicate | Synchronize values between different tag types.
DoNotDuplicate | Do not synchronize values between different tag types.

## Position

enum TagLib::File::Position

Position in the file used for seeking.

Enumerator
Beginning | Seek from the beginning of the file.
Current | Seek from the current position in the file.
End | Seek from the end of the file.

## StripTags

enum TagLib::File::StripTags

Specify which tags to strip either explicitly, or on save.

Enumerator
StripNone | Don't strip any tags.
StripOthers | Strip all tags not explicitly referenced in method call.

## Constructor & Destructor Documentation

## ~File()

virtual TagLib::File::~File | ( |  | ) |

virtual

Destroys this File instance.

Reimplemented in TagLib::APE::File, TagLib::ASF::File, TagLib::DSDIFF::File, TagLib::DSF::File, TagLib::FLAC::File, TagLib::IT::File, TagLib::Matroska::File, TagLib::Mod::File, TagLib::MP4::File, TagLib::MPC::File, TagLib::MPEG::File, TagLib::Ogg::File, TagLib::Ogg::FLAC::File, TagLib::Ogg::Opus::File, TagLib::Ogg::Speex::File, TagLib::Ogg::Vorbis::File, TagLib::RIFF::AIFF::File, TagLib::RIFF::File, TagLib::RIFF::WAV::File, TagLib::S3M::File, TagLib::Shorten::File, TagLib::TrueAudio::File, TagLib::WavPack::File, and TagLib::XM::File.

## File() [1/3]

TagLib::File::File | ( | const File & |  | ) |

delete

References File().

Referenced by File(), and operator=().

## File() [2/3]

TagLib::File::File | ( | FileName | fileName | ) |

protected

Construct a File object and open the fileName. fileName should be a C-string in the local file system encoding.

Note
  Constructor is protected since this class should only be instantiated through subclasses.

## File() [3/3]

TagLib::File::File | ( | IOStream * | stream | ) |

protected

Construct a File object and use the stream instance.

Note
  TagLib will not take ownership of the stream, the caller is responsible for deleting it after the File object.
  Constructor is protected since this class should only be instantiated through subclasses.

## Member Function Documentation

## audioProperties()

virtual AudioProperties * TagLib::File::audioProperties | ( |  | ) | const

pure virtual

Returns a pointer to this file's audio properties. This should be reimplemented in the concrete subclasses. If no audio properties were read then this will return a null pointer.

Implemented in TagLib::APE::File, TagLib::ASF::File, TagLib::DSDIFF::File, TagLib::DSF::File, TagLib::FLAC::File, TagLib::IT::File, TagLib::Matroska::File, TagLib::Mod::File, TagLib::MP4::File, TagLib::MPC::File, TagLib::MPEG::File, TagLib::Ogg::FLAC::File, TagLib::Ogg::Opus::File, TagLib::Ogg::Speex::File, TagLib::Ogg::Vorbis::File, TagLib::RIFF::AIFF::File, TagLib::RIFF::WAV::File, TagLib::S3M::File, TagLib::Shorten::File, TagLib::TrueAudio::File, TagLib::WavPack::File, and TagLib::XM::File.

## bufferSize()

unsigned int TagLib::File::bufferSize | ( |  | ) |

static protected

Returns the buffer size that is used for internal buffering.

References TAGLIB_MSVC_SUPPRESS_WARNING_NEEDS_TO_HAVE_DLL_INTERFACE.

## clear()

void TagLib::File::clear | ( |  | ) |

Reset the end-of-file and error flags on the file.

## complexProperties()

virtual List< VariantMap > TagLib::File::complexProperties | ( | const String & | key | ) | const

virtual

Get the complex properties for a given key. The default implementation calls Tag::complexProperties().

See also
  Tag::complexProperties()

Reimplemented in TagLib::FLAC::File, and TagLib::Matroska::File.

## complexPropertyKeys()

virtual StringList TagLib::File::complexPropertyKeys | ( |  | ) | const

virtual

Get the keys of complex properties, i.e. properties which cannot be represented simply by a string. The default implementation calls Tag::complexPropertyKeys().

See also
  Tag::complexPropertyKeys()

Reimplemented in TagLib::FLAC::File, and TagLib::Matroska::File.

## find()

offset_t TagLib::File::find | ( | const ByteVector & | pattern,
|  | offset_t | fromOffset = 0,
|  | const ByteVector & | before = ByteVector() )

Returns the offset in the file that pattern occurs at or -1 if it can not be found. If before is set, the search will only continue until the pattern before is found. This is useful for tagging purposes to search for a tag before the sync frame.

Searching starts at fromOffset, which defaults to the beginning of the file.

Note
  This has the practical limitation that pattern can not be longer than the buffer size used by readBlock(). Currently this is 1024 bytes.

## insert()

void TagLib::File::insert | ( | const ByteVector & | data,
|  | offset_t | start = 0,
|  | size_t | replace = 0 )

Insert data at position start in the file overwriting replace bytes of the original content.

Note
  This method is slow since it requires rewriting all of the file after the insertion point.

## isOpen()

bool TagLib::File::isOpen | ( |  | ) | const

Since the file can currently only be opened as an argument to the constructor (sort-of by design), this returns if that open succeeded.

## isValid()

bool TagLib::File::isValid | ( |  | ) | const

Returns `true` if the file is open and readable.

## length()

offset_t TagLib::File::length | ( |  | ) |

Returns the length of the file.

Referenced by readBlock(), removeBlock(), and truncate().

## name()

FileName TagLib::File::name | ( |  | ) | const

Returns the file name in the local file system encoding.

Referenced by TagLib::RIFF::File::removeChunk(), TagLib::RIFF::File::setChunkData(), and TagLib::RIFF::File::setChunkData().

## operator=()

File & TagLib::File::operator= | ( | const File & |  | ) |

delete

References File().

## properties()

virtual PropertyMap TagLib::File::properties | ( |  | ) | const

virtual

Exports the tags of the file as dictionary mapping (human readable) tag names (uppercase Strings) to StringLists of tag values. Calls the according specialization in the File subclasses. 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).

Reimplemented in TagLib::APE::File, TagLib::ASF::File, TagLib::DSDIFF::File, TagLib::DSF::File, TagLib::FLAC::File, TagLib::Matroska::File, TagLib::Mod::File, TagLib::MP4::File, TagLib::MPC::File, TagLib::MPEG::File, TagLib::Ogg::FLAC::File, TagLib::Ogg::Opus::File, TagLib::Ogg::Speex::File, TagLib::Ogg::Vorbis::File, TagLib::RIFF::AIFF::File, TagLib::RIFF::WAV::File, TagLib::S3M::File, TagLib::Shorten::File, TagLib::TrueAudio::File, TagLib::WavPack::File, and TagLib::XM::File.

Referenced by removeUnsupportedProperties(), and setProperties().

## readBlock()

ByteVector TagLib::File::readBlock | ( | size_t | length | ) |

Reads a block of size length at the current get pointer.

References length().

## readOnly()

bool TagLib::File::readOnly | ( |  | ) | const

Returns `true` if the file is read only (or if the file can not be opened).

## removeBlock()

void TagLib::File::removeBlock | ( | offset_t | start = 0,
|  | size_t | length = 0 )

Removes a block of the file starting a start and continuing for length bytes.

Note
  This method is slow since it involves rewriting all of the file after the removed portion.

References length().

## removeUnsupportedProperties()

virtual void TagLib::File::removeUnsupportedProperties | ( | const StringList & | properties | ) |

virtual

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

Reimplemented in TagLib::APE::File, TagLib::ASF::File, TagLib::DSDIFF::File, TagLib::FLAC::File, TagLib::Matroska::File, TagLib::MP4::File, TagLib::MPC::File, TagLib::MPEG::File, TagLib::RIFF::AIFF::File, TagLib::RIFF::WAV::File, TagLib::TrueAudio::File, and TagLib::WavPack::File.

References properties().

## rfind()

offset_t TagLib::File::rfind | ( | const ByteVector & | pattern,
|  | offset_t | fromOffset = 0,
|  | const ByteVector & | before = ByteVector() )

Returns the offset in the file that pattern occurs at or -1 if it can not be found. If before is set, the search will only continue until the pattern before is found. This is useful for tagging purposes to search for a tag before the sync frame.

Searching starts at fromOffset and proceeds from the that point to the beginning of the file and defaults to the end of the file.

Note
  This has the practical limitation that pattern can not be longer than the buffer size used by readBlock(). Currently this is 1024 bytes.

## save()

virtual bool TagLib::File::save | ( |  | ) |

pure virtual

Save the file and its associated tags. This should be reimplemented in the concrete subclasses. Returns `true` if the save succeeds.

Warning
  On UNIX multiple processes are able to write to the same file at the same time. This can result in serious file corruption. If you are developing a program that makes use of TagLib from multiple processes you must insure that you are only doing writes to a particular file from one of them.

Implemented in TagLib::APE::File, TagLib::ASF::File, TagLib::DSDIFF::File, TagLib::DSF::File, TagLib::FLAC::File, TagLib::IT::File, TagLib::Matroska::File, TagLib::Mod::File, TagLib::MP4::File, TagLib::MPC::File, TagLib::MPEG::File, TagLib::Ogg::File, TagLib::Ogg::FLAC::File, TagLib::Ogg::Opus::File, TagLib::Ogg::Speex::File, TagLib::Ogg::Vorbis::File, TagLib::RIFF::AIFF::File, TagLib::RIFF::WAV::File, TagLib::S3M::File, TagLib::Shorten::File, TagLib::TrueAudio::File, TagLib::WavPack::File, and TagLib::XM::File.

## seek()

void TagLib::File::seek | ( | offset_t | offset,
|  | Position | p = Beginning )

Move the I/O pointer to offset in the file from position p. This defaults to seeking from the beginning of the file.

See also
  Position

References Beginning.

## setComplexProperties()

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

virtual

Set all complex properties for key using the variant maps value. The default implementation calls Tag::setComplexProperties().

See also
  Tag::setComplexProperties()

Reimplemented in TagLib::FLAC::File, and TagLib::Matroska::File.

## setProperties()

virtual PropertyMap TagLib::File::setProperties | ( | const PropertyMap & | properties | ) |

virtual

Sets the tags of this File to those specified in properties. Calls the according specialization method in the subclasses of File to do the translation into the format-specific details. 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.

Reimplemented in TagLib::APE::File, TagLib::ASF::File, TagLib::DSDIFF::File, TagLib::DSF::File, TagLib::FLAC::File, TagLib::Matroska::File, TagLib::Mod::File, TagLib::MP4::File, TagLib::MPC::File, TagLib::MPEG::File, TagLib::Ogg::FLAC::File, TagLib::Ogg::Opus::File, TagLib::Ogg::Speex::File, TagLib::Ogg::Vorbis::File, TagLib::RIFF::AIFF::File, TagLib::RIFF::WAV::File, TagLib::S3M::File, TagLib::Shorten::File, TagLib::TrueAudio::File, TagLib::WavPack::File, and TagLib::XM::File.

References properties().

## setValid()

void TagLib::File::setValid | ( | bool | valid | ) |

protected

Marks the file as valid or invalid.

See also
  isValid()

## tag()

virtual Tag * TagLib::File::tag | ( |  | ) | const

pure virtual

Returns a pointer to this file's tag. This should be reimplemented in the concrete subclasses.

Implemented in TagLib::APE::File, TagLib::ASF::File, TagLib::DSDIFF::File, TagLib::DSF::File, TagLib::FLAC::File, TagLib::IT::File, TagLib::Matroska::File, TagLib::Mod::File, TagLib::MP4::File, TagLib::MPC::File, TagLib::MPEG::File, TagLib::Ogg::FLAC::File, TagLib::Ogg::Opus::File, TagLib::Ogg::Speex::File, TagLib::Ogg::Vorbis::File, TagLib::RIFF::AIFF::File, TagLib::RIFF::WAV::File, TagLib::S3M::File, TagLib::Shorten::File, TagLib::TrueAudio::File, TagLib::WavPack::File, and TagLib::XM::File.

## tell()

offset_t TagLib::File::tell | ( |  | ) | const

Returns the current offset within the file.

## truncate()

void TagLib::File::truncate | ( | offset_t | length | ) |

protected

Truncates the file to a length.

References length().

## writeBlock()

void TagLib::File::writeBlock | ( | const ByteVector & | data | ) |

Attempts to write the block data at the current get pointer. If the file is currently only opened read only – i.e. readOnly() returns `true` – this attempts to reopen the file in read/write mode.

Note
  This should be used instead of using the streaming output operator for a ByteVector. And even this function is significantly slower than doing output with a char[].

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

- tfile.h