Miam-Player  0.8.0
A nice music player
TagLib::ID3v2::Frame Class Referenceabstract

ID3v2 frame implementation. More...

#include <id3v2frame.h>

Inheritance diagram for TagLib::ID3v2::Frame:
TagLib::ID3v2::Header TagLib::ID3v2::AttachedPictureFrame TagLib::ID3v2::ChapterFrame TagLib::ID3v2::CommentsFrame TagLib::ID3v2::EventTimingCodesFrame TagLib::ID3v2::GeneralEncapsulatedObjectFrame TagLib::ID3v2::OwnershipFrame TagLib::ID3v2::PodcastFrame TagLib::ID3v2::PopularimeterFrame TagLib::ID3v2::PrivateFrame TagLib::ID3v2::RelativeVolumeFrame TagLib::ID3v2::SynchronizedLyricsFrame TagLib::ID3v2::TableOfContentsFrame TagLib::ID3v2::TextIdentificationFrame TagLib::ID3v2::UniqueFileIdentifierFrame TagLib::ID3v2::UnknownFrame TagLib::ID3v2::UnsynchronizedLyricsFrame TagLib::ID3v2::UrlLinkFrame

Public Member Functions

virtual ~Frame ()
 Destroys this Frame instance. More...
 
ByteVector frameID () const
 Returns the Frame ID (Structure, 4) (Frames, 4) More...
 
unsigned int size () const
 Returns the size of the frame. More...
 
void setData (const ByteVector &data)
 Sets the data that will be used as the frame. More...
 
virtual void setText (const String &text)
 Set the text of frame in the sanest way possible. More...
 
virtual String toString () const =0
 This returns the textual representation of the data in the frame. More...
 
ByteVector render () const
 Render the frame back to its binary format in a ByteVector. More...
 
 Header (const ByteVector &data, bool synchSafeInts)
 Construct a Frame Header based on data. More...
 
 Header (const ByteVector &data, unsigned int version=4)
 Construct a Frame Header based on data. More...
 
virtual ~Header ()
 Destroys this Header instance. More...
 
void setData (const ByteVector &data, bool synchSafeInts)
 Sets the data for the Header. More...
 
void setData (const ByteVector &data, unsigned int version=4)
 Sets the data for the Header. More...
 
ByteVector frameID () const
 Returns the Frame ID (Structure, 4) (Frames, 4) More...
 
void setFrameID (const ByteVector &id)
 Sets the frame's ID to id. More...
 
unsigned int frameSize () const
 Returns the size of the frame data portion, as set when setData() was called or set explicitly via setFrameSize(). More...
 
void setFrameSize (unsigned int size)
 Sets the size of the frame data portion. More...
 
unsigned int version () const
 Returns the ID3v2 version of the header, as passed in from the construction of the header or set via setVersion(). More...
 
void setVersion (unsigned int version)
 Sets the ID3v2 version of the header, changing has impact on the correct parsing/rendering of frame data. More...
 
bool tagAlterPreservation () const
 Returns true if the flag for tag alter preservation is set. More...
 
void setTagAlterPreservation (bool discard)
 Sets the flag for preservation of this frame if the tag is set. More...
 
bool fileAlterPreservation () const
 Returns true if the flag for file alter preservation is set. More...
 
bool readOnly () const
 Returns true if the frame is meant to be read only. More...
 
bool groupingIdentity () const
 Returns true if the flag for the grouping identity is set. More...
 
bool compression () const
 Returns true if compression is enabled for this frame. More...
 
bool encryption () const
 Returns true if encryption is enabled for this frame. More...
 
bool unsycronisation () const
 
bool unsynchronisation () const
 Returns true if unsynchronisation is enabled for this frame. More...
 
bool dataLengthIndicator () const
 Returns true if the flag for a data length indicator is set. More...
 
ByteVector render () const
 Render the Header back to binary format in a ByteVector. More...
 
bool frameAlterPreservation () const
 

Static Public Member Functions

static FramecreateTextualFrame (const String &key, const StringList &values)
 Creates a textual frame which corresponds to a single key in the PropertyMap interface. More...
 
static unsigned int headerSize ()
 Returns the size of the frame header. More...
 
static unsigned int headerSize (unsigned int version)
 Returns the size of the frame header for the given ID3v2 version. More...
 
static ByteVector textDelimiter (String::Type t)
 Returns the text delimiter that is used between fields for the string type t. More...
 
static unsigned int size ()
 Returns the size of the frame header in bytes. More...
 
static unsigned int size (unsigned int version)
 Returns the size of the frame header in bytes for the ID3v2 version that's given. More...
 

Static Public Attributes

static const String instrumentPrefix
 The string with which an instrument name is prefixed to build a key in a PropertyMap; used to translate PropertyMaps to TMCL frames. More...
 
static const String commentPrefix
 The PropertyMap key prefix which triggers the use of a COMM frame instead of a TXXX frame for a non-standard key. More...
 
static const String lyricsPrefix
 The PropertyMap key prefix which triggers the use of a USLT frame instead of a TXXX frame for a non-standard key. More...
 
static const String urlPrefix
 The PropertyMap key prefix which triggers the use of a WXXX frame instead of a TXX frame for a non-standard key. More...
 

Protected Member Functions

 Frame (const ByteVector &data)
 Constructs an ID3v2 frame using data to read the header information. More...
 
 Frame (Header *h)
 This creates an Frame using the header h. More...
 
Headerheader () const
 Returns a pointer to the frame header. More...
 
void setHeader (Header *h, bool deleteCurrent=true)
 Sets the header to h. More...
 
void parse (const ByteVector &data)
 Called by setData() to parse the frame data. More...
 
virtual void parseFields (const ByteVector &data)=0
 Called by parse() to parse the field data. More...
 
virtual ByteVector renderFields () const =0
 Render the field data back to a binary format in a ByteVector. More...
 
ByteVector fieldData (const ByteVector &frameData) const
 Returns a ByteVector containing the field data given the frame data. More...
 
String readStringField (const ByteVector &data, String::Type encoding, int *positon=0)
 Reads a String of type encoding from the ByteVector data. More...
 
String::Type checkTextEncoding (const StringList &fields, String::Type encoding) const
 Checks a the list of string values to see if they can be used with the specified encoding and returns the recommended encoding. More...
 
PropertyMap asProperties () const
 Parses the contents of this frame as PropertyMap. More...
 

Static Protected Member Functions

static String::Type checkEncoding (const StringList &fields, String::Type encoding)
 Checks a the list of string values to see if they can be used with the specified encoding and returns the recommended encoding. More...
 
static String::Type checkEncoding (const StringList &fields, String::Type encoding, unsigned int version)
 Checks a the list of string values to see if they can be used with the specified encoding and returns the recommended encoding. More...
 
static ByteVector keyToFrameID (const String &)
 Returns an appropriate ID3 frame ID for the given free-form tag key. More...
 
static String frameIDToKey (const ByteVector &)
 Returns a free-form tag name for the given ID3 frame ID. More...
 
static String keyToTXXX (const String &)
 Returns an appropriate TXXX frame description for the given free-form tag key. More...
 
static String txxxToKey (const String &)
 Returns a free-form tag name for the given ID3 frame description. More...
 
static void splitProperties (const PropertyMap &original, PropertyMap &singleFrameProperties, PropertyMap &tiplProperties, PropertyMap &tmclProperties)
 This helper function splits the PropertyMap original into three ProperytMaps singleFrameProperties, tiplProperties, and tmclProperties, such that: More...
 

Friends

class Tag
 
class FrameFactory
 
class FramePrivate
 

Detailed Description

ID3v2 frame implementation.

ID3v2 frame header implementation.

This class is the main ID3v2 frame implementation. In ID3v2, a tag is split between a collection of frames (which are in turn split into fields (Structure, 4) (Frames). This class provides an API for gathering information about and modifying ID3v2 frames. Funtionallity specific to a given frame type is handed in one of the many subclasses.

The ID3v2 Frame Header (Structure, 4)

Every ID3v2::Frame has an associated header that gives some general properties of the frame and also makes it possible to identify the frame type.

As such when reading an ID3v2 tag ID3v2::FrameFactory first creates the frame headers and then creates the appropriate Frame subclass based on the type and attaches the header.

Constructor & Destructor Documentation

virtual TagLib::ID3v2::Frame::~Frame ( )
virtual

Destroys this Frame instance.

TagLib::ID3v2::Frame::Frame ( const ByteVector data)
explicitprotected

Constructs an ID3v2 frame using data to read the header information.

All other processing of data should be handled in a subclass.

Note
This need not contain anything more than a frame ID, but must contain at least that.
TagLib::ID3v2::Frame::Frame ( Header h)
protected

This creates an Frame using the header h.

The ownership of this header will be assigned to the frame and the header will be deleted when the frame is destroyed.

virtual TagLib::ID3v2::Frame::~Header ( )
virtual

Destroys this Header instance.

Reimplemented from TagLib::ID3v2::Header.

Member Function Documentation

PropertyMap TagLib::ID3v2::Frame::asProperties ( ) const
protected

Parses the contents of this frame as PropertyMap.

If that fails, the returend PropertyMap will be empty, and its unsupportedData() will contain this frame's ID. BIC: Will be a virtual function in future releases.

static String::Type TagLib::ID3v2::Frame::checkEncoding ( const StringList fields,
String::Type  encoding 
)
staticprotected

Checks a the list of string values to see if they can be used with the specified encoding and returns the recommended encoding.

static String::Type TagLib::ID3v2::Frame::checkEncoding ( const StringList fields,
String::Type  encoding,
unsigned int  version 
)
staticprotected

Checks a the list of string values to see if they can be used with the specified encoding and returns the recommended encoding.

This method also checks the ID3v2 version and makes sure the encoding can be used in the specified version.

String::Type TagLib::ID3v2::Frame::checkTextEncoding ( const StringList fields,
String::Type  encoding 
) const
protected

Checks a the list of string values to see if they can be used with the specified encoding and returns the recommended encoding.

This method also checks the ID3v2 version and makes sure the encoding can be used in the version specified by the frame's header.

bool TagLib::ID3v2::Frame::compression ( ) const

Returns true if compression is enabled for this frame.

Note
This flag is currently ignored internally in TagLib.
static Frame* TagLib::ID3v2::Frame::createTextualFrame ( const String key,
const StringList values 
)
static

Creates a textual frame which corresponds to a single key in the PropertyMap interface.

These are all (User)TextIdentificationFrames except TIPL and TMCL, all (User)URLLinkFrames, CommentsFrames, and UnsynchronizedLyricsFrame.

bool TagLib::ID3v2::Frame::dataLengthIndicator ( ) const

Returns true if the flag for a data length indicator is set.

bool TagLib::ID3v2::Frame::encryption ( ) const

Returns true if encryption is enabled for this frame.

Note
This flag is currently ignored internally in TagLib.
ByteVector TagLib::ID3v2::Frame::fieldData ( const ByteVector frameData) const
protected

Returns a ByteVector containing the field data given the frame data.

This correctly adjusts for the header size plus any additional frame data that's specified in the frame header flags.

bool TagLib::ID3v2::Frame::fileAlterPreservation ( ) const

Returns true if the flag for file alter preservation is set.

Note
This flag is currently ignored internally in TagLib.
bool TagLib::ID3v2::Frame::frameAlterPreservation ( ) const
ByteVector TagLib::ID3v2::Frame::frameID ( ) const

Returns the Frame ID (Structure, 4) (Frames, 4)

ByteVector TagLib::ID3v2::Frame::frameID ( ) const

Returns the Frame ID (Structure, 4) (Frames, 4)

static String TagLib::ID3v2::Frame::frameIDToKey ( const ByteVector )
staticprotected

Returns a free-form tag name for the given ID3 frame ID.

Note that this does not work for general frame IDs such as TXXX or WXXX; in such a case an empty string is returned.

unsigned int TagLib::ID3v2::Frame::frameSize ( ) const

Returns the size of the frame data portion, as set when setData() was called or set explicitly via setFrameSize().

bool TagLib::ID3v2::Frame::groupingIdentity ( ) const

Returns true if the flag for the grouping identity is set.

Note
This flag is currently ignored internally in TagLib.
Header* TagLib::ID3v2::Frame::header ( ) const
protected

Returns a pointer to the frame header.

TagLib::ID3v2::Frame::Header ( const ByteVector data,
bool  synchSafeInts 
)

Construct a Frame Header based on data.

data must at least contain a 4 byte frame ID, and optionally can contain flag data and the frame size. i.e. Just the frame id – "TALB" – is a valid value.

Deprecated:
Please use the constructor below that accepts a version number.
TagLib::ID3v2::Frame::Header ( const ByteVector data,
unsigned int  version = 4 
)
explicit

Construct a Frame Header based on data.

data must at least contain a 4 byte frame ID, and optionally can contain flag data and the frame size. i.e. Just the frame id – "TALB" – is a valid value.

version should be the ID3v2 version of the tag.

static unsigned int TagLib::ID3v2::Frame::headerSize ( )
static

Returns the size of the frame header.

Deprecated:
This is only accurate for ID3v2.3 or ID3v2.4. Please use the call below which accepts an ID3v2 version number. In the next non-binary compatible release this will be made into a non-static member that checks the internal ID3v2 version.
static unsigned int TagLib::ID3v2::Frame::headerSize ( unsigned int  version)
static

Returns the size of the frame header for the given ID3v2 version.

Deprecated:
Please see the explanation above.
static ByteVector TagLib::ID3v2::Frame::keyToFrameID ( const String )
staticprotected

Returns an appropriate ID3 frame ID for the given free-form tag key.

This method will return an empty ByteVector if no specialized translation is found.

static String TagLib::ID3v2::Frame::keyToTXXX ( const String )
staticprotected

Returns an appropriate TXXX frame description for the given free-form tag key.

void TagLib::ID3v2::Frame::parse ( const ByteVector data)
protected

Called by setData() to parse the frame data.

It makes this information available through the public API.

bool TagLib::ID3v2::Frame::readOnly ( ) const

Returns true if the frame is meant to be read only.

Note
This flag is currently ignored internally in TagLib.
String TagLib::ID3v2::Frame::readStringField ( const ByteVector data,
String::Type  encoding,
int *  positon = 0 
)
protected

Reads a String of type encoding from the ByteVector data.

If position is passed in it is used both as the starting point and is updated to return the position just after the string that has been read. This is useful for reading strings sequentially.

ByteVector TagLib::ID3v2::Frame::render ( ) const

Render the frame back to its binary format in a ByteVector.

ByteVector TagLib::ID3v2::Frame::render ( ) const

Render the Header back to binary format in a ByteVector.

void TagLib::ID3v2::Frame::setData ( const ByteVector data)

Sets the data that will be used as the frame.

Since the length is not known before the frame has been parsed, this should just be a pointer to the first byte of the frame. It will determine the length internally and make that available through size().

void TagLib::ID3v2::Frame::setData ( const ByteVector data,
bool  synchSafeInts 
)

Sets the data for the Header.

Deprecated:
Please use the version below that accepts an ID3v2 version number.
void TagLib::ID3v2::Frame::setData ( const ByteVector data,
unsigned int  version = 4 
)

Sets the data for the Header.

version should indicate the ID3v2 version number of the tag that this frame is contained in.

void TagLib::ID3v2::Frame::setFrameID ( const ByteVector id)

Sets the frame's ID to id.

Only the first four bytes of id will be used.

Warning
This method should in general be avoided. It exists simply to provide a mechanism for transforming frames from a deprecated frame type to a newer one – i.e. TYER to TDRC from ID3v2.3 to ID3v2.4.
void TagLib::ID3v2::Frame::setFrameSize ( unsigned int  size)

Sets the size of the frame data portion.

void TagLib::ID3v2::Frame::setHeader ( Header h,
bool  deleteCurrent = true 
)
protected

Sets the header to h.

If deleteCurrent is true, this will free the memory of the current header.

The ownership of this header will be assigned to the frame and the header will be deleted when the frame is destroyed.

void TagLib::ID3v2::Frame::setTagAlterPreservation ( bool  discard)

Sets the flag for preservation of this frame if the tag is set.

If this is set to true the frame will not be written when the tag is saved.

The semantics are a little backwards from what would seem natural (setting the preservation flag to throw away the frame), but this follows the ID3v2 standard.

See also
tagAlterPreservation()
virtual void TagLib::ID3v2::Frame::setText ( const String text)
virtual

Set the text of frame in the sanest way possible.

This should only be reimplemented in frames where there is some logical mapping to text.

Note
If the frame type supports multiple text encodings, this will not change the text encoding of the frame; the string will be converted to that frame's encoding. Please use the specific APIs of the frame types to set the encoding if that is desired.

Reimplemented in TagLib::ID3v2::UserTextIdentificationFrame, TagLib::ID3v2::TextIdentificationFrame, TagLib::ID3v2::CommentsFrame, TagLib::ID3v2::UnsynchronizedLyricsFrame, and TagLib::ID3v2::UrlLinkFrame.

void TagLib::ID3v2::Frame::setVersion ( unsigned int  version)

Sets the ID3v2 version of the header, changing has impact on the correct parsing/rendering of frame data.

unsigned int TagLib::ID3v2::Frame::size ( ) const

Returns the size of the frame.

static unsigned int TagLib::ID3v2::Frame::size ( )
static

Returns the size of the frame header in bytes.

Deprecated:
Please use the version of this method that accepts a version. This is only accurate for ID3v2.3 and ID3v2.4. This will be removed in the next binary incompatible release (2.0) and will be replaced with a non-static method that checks the frame version.
static unsigned int TagLib::ID3v2::Frame::size ( unsigned int  version)
static

Returns the size of the frame header in bytes for the ID3v2 version that's given.

Deprecated:
Please see the explanation in the version above.
static void TagLib::ID3v2::Frame::splitProperties ( const PropertyMap original,
PropertyMap singleFrameProperties,
PropertyMap tiplProperties,
PropertyMap tmclProperties 
)
staticprotected

This helper function splits the PropertyMap original into three ProperytMaps singleFrameProperties, tiplProperties, and tmclProperties, such that:

  • singleFrameProperties contains only of keys which can be represented with exactly one ID3 frame per key. In the current implementation this is everything except for the fixed "involved people" keys and keys of the form "TextIdentificationFrame::instrumentPrefix" + "instrument", which are mapped to a TMCL frame.
  • tiplProperties will consist of those keys that are present in TextIdentificationFrame::involvedPeopleMap()
  • tmclProperties contains the "musician credits" keys which should be mapped to a TMCL frame
bool TagLib::ID3v2::Frame::tagAlterPreservation ( ) const

Returns true if the flag for tag alter preservation is set.

The semantics are a little backwards from what would seem natural (setting the preservation flag to throw away the frame), but this follows the ID3v2 standard.

See also
setTagAlterPreservation()
static ByteVector TagLib::ID3v2::Frame::textDelimiter ( String::Type  t)
static

Returns the text delimiter that is used between fields for the string type t.

static String TagLib::ID3v2::Frame::txxxToKey ( const String )
staticprotected

Returns a free-form tag name for the given ID3 frame description.

bool TagLib::ID3v2::Frame::unsycronisation ( ) const
bool TagLib::ID3v2::Frame::unsynchronisation ( ) const

Returns true if unsynchronisation is enabled for this frame.

unsigned int TagLib::ID3v2::Frame::version ( ) const

Returns the ID3v2 version of the header, as passed in from the construction of the header or set via setVersion().

Friends And Related Function Documentation

friend class FrameFactory
friend
friend class FramePrivate
friend
friend class Tag
friend

Member Data Documentation

const String TagLib::ID3v2::Frame::commentPrefix
static

The PropertyMap key prefix which triggers the use of a COMM frame instead of a TXXX frame for a non-standard key.

In the current implementation, this is "COMMENT:".

const String TagLib::ID3v2::Frame::instrumentPrefix
static

The string with which an instrument name is prefixed to build a key in a PropertyMap; used to translate PropertyMaps to TMCL frames.

In the current implementation, this is "PERFORMER:".

const String TagLib::ID3v2::Frame::lyricsPrefix
static

The PropertyMap key prefix which triggers the use of a USLT frame instead of a TXXX frame for a non-standard key.

In the current implementation, this is "LYRICS:".

const String TagLib::ID3v2::Frame::urlPrefix
static

The PropertyMap key prefix which triggers the use of a WXXX frame instead of a TXX frame for a non-standard key.

In the current implementation, this is "URL:".


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