TagLib::File Class Reference

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

#include <tfile.h>

Inheritance diagram for TagLib::File:

List of all members.

Public Types

enum  Position { Beginning, Current, End }

Public Member Functions

virtual ~File ()
FileName name () const
virtual Tagtag () const =0
PropertyMap properties () const
void removeUnsupportedProperties (const StringList &properties)
PropertyMap setProperties (const PropertyMap &properties)
virtual AudioPropertiesaudioProperties () const =0
virtual bool save ()=0
ByteVector readBlock (ulong length)
void writeBlock (const ByteVector &data)
long find (const ByteVector &pattern, long fromOffset=0, const ByteVector &before=ByteVector::null)
long rfind (const ByteVector &pattern, long fromOffset=0, const ByteVector &before=ByteVector::null)
void insert (const ByteVector &data, ulong start=0, ulong replace=0)
void removeBlock (ulong start=0, ulong length=0)
bool readOnly () const
bool isOpen () const
bool isValid () const
void seek (long offset, Position p=Beginning)
void clear ()
long tell () const
long length ()

Static Public Member Functions

static bool isReadable (const char *file)
static bool isWritable (const char *name)

Protected Member Functions

 File (FileName file)
 File (IOStream *stream)
void setValid (bool valid)
void truncate (long length)

Static Protected Member Functions

static uint 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

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.


Constructor & Destructor Documentation

TagLib::File::File ( FileName  file)
protected

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

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

Reimplemented in TagLib::Ogg::File.

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.

Reimplemented in TagLib::Ogg::File.


Member Function Documentation

virtual AudioProperties* TagLib::File::audioProperties ( ) const
pure virtual
static uint TagLib::File::bufferSize ( )
staticprotected

Returns the buffer size that is used for internal buffering.

void TagLib::File::clear ( )

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

long TagLib::File::find ( const ByteVector pattern,
long  fromOffset = 0,
const ByteVector before = ByteVector::null 
)

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 synch frame.

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

Note:
This has the practial limitation that pattern can not be longer than the buffer size used by readBlock(). Currently this is 1024 bytes.
void TagLib::File::insert ( const ByteVector data,
ulong  start = 0,
ulong  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.
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.

static bool TagLib::File::isReadable ( const char *  file)
static

Returns true if file can be opened for reading. If the file does not exist, this will return false.

bool TagLib::File::isValid ( ) const

Returns true if the file is open and readble.

static bool TagLib::File::isWritable ( const char *  name)
static

Returns true if file can be opened for writing.

long TagLib::File::length ( )

Returns the length of the file.

FileName TagLib::File::name ( ) const

Returns the file name in the local file system encoding.

PropertyMap TagLib::File::properties ( ) const

Exports the tags of the file as dictionary mapping (human readable) tag names (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 returend 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. BIC: Will be made virtual in future releases.

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

ByteVector TagLib::File::readBlock ( ulong  length)

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

bool TagLib::File::readOnly ( ) const

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

void TagLib::File::removeBlock ( ulong  start = 0,
ulong  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.
void TagLib::File::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(). BIC: Will be mad virtual in future releases.

Reimplemented in TagLib::MPEG::File, TagLib::FLAC::File, TagLib::APE::File, TagLib::MPC::File, TagLib::ASF::File, and TagLib::MP4::File.

long TagLib::File::rfind ( const ByteVector pattern,
long  fromOffset = 0,
const ByteVector before = ByteVector::null 
)

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 synch 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 practial limitation that pattern can not be longer than the buffer size used by readBlock(). Currently this is 1024 bytes.
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::MPEG::File, TagLib::TrueAudio::File, TagLib::FLAC::File, TagLib::APE::File, TagLib::MPC::File, TagLib::RIFF::WAV::File, TagLib::WavPack::File, TagLib::ASF::File, TagLib::MP4::File, TagLib::Ogg::Vorbis::File, TagLib::RIFF::AIFF::File, TagLib::Ogg::FLAC::File, TagLib::Ogg::Opus::File, TagLib::Ogg::Speex::File, TagLib::IT::File, TagLib::Mod::File, TagLib::S3M::File, TagLib::XM::File, and TagLib::Ogg::File.

void TagLib::File::seek ( long  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
PropertyMap TagLib::File::setProperties ( const PropertyMap properties)

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 imported to the specific metadata format, the returned PropertyMap will contain those value(s). Otherwise it will be empty, indicating that no problems occured. BIC: will become pure virtual in the future

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

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

Marks the file as valid or invalid.

See also:
isValid()
long TagLib::File::tell ( ) const

Returns the current offset within the file.

void TagLib::File::truncate ( long  length)
protected

Truncates the file to a length.

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: