TagLib  1.13.1
TagLib::ID3v2::Frame Class Referenceabstract

ID3v2 frame implementation. More...

#include <id3v2frame.h>

Inheritance diagram for TagLib::ID3v2::Frame:
[legend]
Collaboration diagram for TagLib::ID3v2::Frame:
[legend]

Classes

class  Header
 ID3v2 frame header implementation. More...
 

Public Member Functions

virtual ~Frame ()
 
ByteVector frameID () const
 
unsigned int size () const
 
void setData (const ByteVector &data)
 
virtual void setText (const String &text)
 
virtual String toString () const =0
 
ByteVector render () const
 

Static Public Member Functions

static FramecreateTextualFrame (const String &key, const StringList &values)
 
static unsigned int headerSize ()
 
static unsigned int headerSize (unsigned int version)
 
static ByteVector textDelimiter (String::Type t)
 

Static Public Attributes

static const String instrumentPrefix
 
static const String commentPrefix
 
static const String lyricsPrefix
 
static const String urlPrefix
 

Protected Member Functions

 Frame (const ByteVector &data)
 
 Frame (Header *h)
 
Headerheader () const
 
void setHeader (Header *h, bool deleteCurrent=true)
 
void parse (const ByteVector &data)
 
virtual void parseFields (const ByteVector &data)=0
 
virtual ByteVector renderFields () const =0
 
ByteVector fieldData (const ByteVector &frameData) const
 
String readStringField (const ByteVector &data, String::Type encoding, int *position=0)
 
String::Type checkTextEncoding (const StringList &fields, String::Type encoding) const
 
PropertyMap asProperties () const
 

Static Protected Member Functions

static String::Type checkEncoding (const StringList &fields, String::Type encoding)
 
static String::Type checkEncoding (const StringList &fields, String::Type encoding, unsigned int version)
 
static ByteVector keyToFrameID (const String &)
 
static String frameIDToKey (const ByteVector &)
 
static String keyToTXXX (const String &)
 
static String txxxToKey (const String &)
 
static void splitProperties (const PropertyMap &original, PropertyMap &singleFrameProperties, PropertyMap &tiplProperties, PropertyMap &tmclProperties)
 

Friends

class Tag
 
class FrameFactory
 
class TableOfContentsFrame
 
class ChapterFrame
 
class FramePrivate
 

Detailed Description

ID3v2 frame 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. Functionality specific to a given frame type is handed in one of the many subclasses.

Constructor & Destructor Documentation

◆ ~Frame()

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

Destroys this Frame instance.

◆ Frame() [1/2]

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.

Referenced by TagLib::ID3v2::ChapterFrame::addEmbeddedFrame(), TagLib::ID3v2::TableOfContentsFrame::addEmbeddedFrame(), createTextualFrame(), TagLib::ID3v2::ChapterFrame::removeEmbeddedFrame(), TagLib::ID3v2::TableOfContentsFrame::removeEmbeddedFrame(), and splitProperties().

◆ Frame() [2/2]

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.

Member Function Documentation

◆ asProperties()

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

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

◆ checkEncoding() [1/2]

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.

◆ checkEncoding() [2/2]

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.

◆ checkTextEncoding()

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.

◆ createTextualFrame()

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.

References Frame().

◆ fieldData()

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.

◆ frameID()

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

◆ frameIDToKey()

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.

◆ header()

Header * TagLib::ID3v2::Frame::header ( ) const
protected

Returns a pointer to the frame header.

◆ headerSize() [1/2]

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.

◆ headerSize() [2/2]

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.

◆ keyToFrameID()

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.

◆ keyToTXXX()

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

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

◆ parse()

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.

◆ parseFields()

◆ readStringField()

String TagLib::ID3v2::Frame::readStringField ( const ByteVector & data,
String::Type encoding,
int * position = 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.

◆ render()

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

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

◆ renderFields()

◆ setData()

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

◆ setHeader()

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.

◆ setText()

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::CommentsFrame, TagLib::ID3v2::TextIdentificationFrame, TagLib::ID3v2::UnsynchronizedLyricsFrame, TagLib::ID3v2::UrlLinkFrame, and TagLib::ID3v2::UserTextIdentificationFrame.

◆ size()

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

Returns the size of the frame.

◆ splitProperties()

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

References Frame(), and FramePrivate.

◆ textDelimiter()

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

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

◆ toString()

◆ txxxToKey()

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

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

Friends And Related Symbol Documentation

◆ ChapterFrame

friend class ChapterFrame
friend

References ChapterFrame.

Referenced by ChapterFrame.

◆ FrameFactory

friend class FrameFactory
friend

References FrameFactory.

Referenced by FrameFactory.

◆ FramePrivate

friend class FramePrivate
friend

References FramePrivate.

Referenced by FramePrivate, and splitProperties().

◆ TableOfContentsFrame

friend class TableOfContentsFrame
friend

References TableOfContentsFrame.

Referenced by TableOfContentsFrame.

◆ Tag

Member Data Documentation

◆ commentPrefix

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:".

◆ instrumentPrefix

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:".

◆ lyricsPrefix

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:".

◆ urlPrefix

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: