TagLib API Documentation

TagLib::File Class Reference

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

#include <tfile.h>

Inheritance diagram for TagLib::File:

TagLib::FLAC::File TagLib::MPEG::File TagLib::Ogg::File TagLib::Vorbis::File List of all members.

Public Types

enum  Position { Beginning, Current, End }

Public Member Functions

virtual ~File ()
const char * name () const
virtual Tagtag () const =0
virtual AudioPropertiesaudioProperties () const =0
virtual void 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

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

Protected Member Functions

 File (const char *file)
void setValid (bool valid)
void truncate (long length)

Static Protected Member Functions

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.

Definition at line 42 of file tfile.h.


Member Enumeration Documentation

enum TagLib::File::Position
 

Position in the file used for seeking.

Enumeration values:
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.

Definition at line 48 of file tfile.h.


Constructor & Destructor Documentation

virtual TagLib::File::~File  )  [virtual]
 

Destroys this File instance.

Reimplemented in TagLib::FLAC::File, TagLib::MPEG::File, TagLib::Ogg::File, and TagLib::Vorbis::File.

TagLib::File::File const char *  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.


Member Function Documentation

const char* TagLib::File::name  )  const
 

Returns the file name in the local file system encoding.

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::FLAC::File, TagLib::MPEG::File, and TagLib::Vorbis::File.

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::FLAC::File, TagLib::MPEG::File, and TagLib::Vorbis::File.

virtual void TagLib::File::save  )  [pure virtual]
 

Save the file and its associated tags. This should be reimplemented in the concrete subclasses.

Implemented in TagLib::FLAC::File, TagLib::MPEG::File, TagLib::Ogg::File, and TagLib::Vorbis::File.

ByteVector TagLib::File::readBlock ulong  length  ) 
 

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

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[].

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.

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.

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.

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.

bool TagLib::File::readOnly  )  const
 

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

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.

bool TagLib::File::isValid  )  const
 

Returns true if the file is open and readble and valid information for the Tag and / or AudioProperties was found.

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

void TagLib::File::clear  ) 
 

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

long TagLib::File::tell  )  const
 

Returns the current offset withing the file.

long TagLib::File::length  ) 
 

Returns the length of the file.

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::isWritable const char *  name  )  [static]
 

Returns true if file can be opened for writing.

void TagLib::File::setValid bool  valid  )  [protected]
 

Marks the file as valid or invalid.

See also:
isValid()

void TagLib::File::truncate long  length  )  [protected]
 

Truncates the file to a length.

uint TagLib::File::bufferSize  )  [static, protected]
 

Returns the buffer size that is used for internal buffering.


The documentation for this class was generated from the following file:
KDE Logo
This file is part of the documentation for TagLib Version 1.0.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Thu Jan 22 05:44:22 2004 by doxygen 1.3.4 written by Dimitri van Heesch, © 1997-2003