ID3v2 frame implementation. More...

#include <id3v2frame.h>

Inheritance diagram for TagLib::ID3v2::Frame:

Collaboration diagram for TagLib::ID3v2::Frame:

Public Member Functions
virtual	~Frame ()

	Frame (const Frame &)=delete

Frame &	operator= (const Frame &)=delete

ByteVector	frameID () const

unsigned int	size () const

unsigned int	headerSize () const

void	setData (const ByteVector &data)

virtual void	setText (const String &text)

virtual String	toString () const =0

virtual StringList	toStringList () const

ByteVector	render () const

Header *	header () const

	Header (const ByteVector &data, unsigned int version=4)

virtual	~Header ()

	Header (const Header &)=delete

Header &	operator= (const Header &)=delete

void	setData (const ByteVector &data, unsigned int version=4)

ByteVector	frameID () const

void	setFrameID (const ByteVector &id)

unsigned int	frameSize () const

void	setFrameSize (unsigned int size)

unsigned int	version () const

void	setVersion (unsigned int version)

unsigned int	size () const

bool	tagAlterPreservation () const

void	setTagAlterPreservation (bool preserve)

bool	fileAlterPreservation () const

bool	readOnly () const

bool	groupingIdentity () const

bool	compression () const

bool	encryption () const

bool	unsynchronisation () const

bool	dataLengthIndicator () const

ByteVector	render () const

Static Public Member Functions
static ByteVector	textDelimiter (String::Type t)

static ByteVector	keyToFrameID (const String &)

static String	frameIDToKey (const ByteVector &)

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)

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=nullptr)

String::Type	checkTextEncoding (const StringList &fields, String::Type encoding) const

virtual PropertyMap	asProperties () const

Static Protected Member Functions
static void	splitProperties (const PropertyMap &original, PropertyMap &singleFrameProperties, PropertyMap &tiplProperties, PropertyMap &tmclProperties)

Friends
class	Tag

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 (id3v2.4.0-structure.txt, 4) (id3v2.4.0-frames.txt). This class provides an API for gathering information about and modifying ID3v2 frames. Functionality specific to a given frame type is handled in one of the many subclasses.

The ID3v2 Frame Header (id3v2.4.0-structure.txt, 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

◆ ~Frame()

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

virtual

Destroys this Frame instance.

◆ Frame() [1/3]

TagLib::ID3v2::Frame::Frame ( const Frame & )

delete

◆ Frame() [2/3]

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.

◆ Frame() [3/3]

TagLib::ID3v2::Frame::Frame ( Header * h )

protected

This creates a 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.

◆ ~Header()

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

virtual

Destroys this Header instance.

Member Function Documentation

◆ asProperties()

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

protectedvirtual

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.

Reimplemented in TagLib::ID3v2::ChapterFrame, TagLib::ID3v2::CommentsFrame, TagLib::ID3v2::PodcastFrame, TagLib::ID3v2::TableOfContentsFrame, TagLib::ID3v2::TextIdentificationFrame, TagLib::ID3v2::UserTextIdentificationFrame, TagLib::ID3v2::UniqueFileIdentifierFrame, TagLib::ID3v2::UnsynchronizedLyricsFrame, TagLib::ID3v2::UrlLinkFrame, and TagLib::ID3v2::UserUrlLinkFrame.

◆ checkTextEncoding()

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

protected

Checks 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.

◆ compression()

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

Returns true if compression is enabled for this frame.

Note: This flag is currently ignored internally in TagLib.

◆ dataLengthIndicator()

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

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

◆ encryption()

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

Returns true if encryption is enabled for this frame.

Note: This flag is currently ignored internally in TagLib.

◆ 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.

◆ fileAlterPreservation()

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.

◆ frameID() [1/2]

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

Returns the Frame ID (id3v2.4.0-structure.txt, 4) (id3v2.4.0-frames.txt, 4)

◆ frameID() [2/2]

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

Returns the Frame ID (id3v2.4.0-structure.txt, 4) (id3v2.4.0-frames.txt, 4)

◆ frameIDToKey()

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

static

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.

◆ frameSize()

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

◆ groupingIdentity()

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

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

Returns a pointer to the frame header.

◆ Header() [1/2]

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.

◆ Header() [2/2]

TagLib::ID3v2::Frame::Header ( const Header & )

delete

◆ headerSize()

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

Returns the size of the frame header

◆ keyToFrameID()

static ByteVector TagLib::ID3v2::Frame::keyToFrameID ( const String & )

static

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.

◆ operator=() [1/2]

Frame & TagLib::ID3v2::Frame::operator= ( const Frame & )

delete

◆ operator=() [2/2]

Header & TagLib::ID3v2::Frame::operator= ( const Header & )

delete

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

virtual void TagLib::ID3v2::Frame::parseFields ( const ByteVector & data )

protectedpure virtual

Called by parse() to parse the field data. It makes this information available through the public API. This must be overridden by the subclasses.

◆ readOnly()

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.

◆ readStringField()

String TagLib::ID3v2::Frame::readStringField	(	const ByteVector &	data,
		String::Type	encoding,
		int *	position = `nullptr`
	)

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() [1/2]

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

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

◆ render() [2/2]

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

Render the Header back to binary format in a ByteVector.

◆ renderFields()

virtual ByteVector TagLib::ID3v2::Frame::renderFields ( ) const

protectedpure virtual

Render the field data back to a binary format in a ByteVector. This must be overridden by subclasses.

◆ setData() [1/2]

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

◆ setData() [2/2]

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.

◆ setFrameID()

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.

◆ setFrameSize()

void TagLib::ID3v2::Frame::setFrameSize ( unsigned int size )

Sets the size of the frame data portion.

◆ 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.

◆ setTagAlterPreservation()

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

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

◆ 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.

◆ setVersion()

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.

◆ size() [1/2]

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

Returns the size of the frame.

◆ size() [2/2]

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

Returns the size of the frame header in bytes.

◆ 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

◆ tagAlterPreservation()

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

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

virtual String TagLib::ID3v2::Frame::toString ( ) const

pure virtual

This returns the textual representation of the data in the frame. Subclasses must reimplement this method to provide a string representation of the frame's data.

◆ toStringList()

virtual StringList TagLib::ID3v2::Frame::toStringList ( ) const

virtual

This returns the textual representation of the data in the frame. Subclasses can reimplement this method to provide a string list representation of the frame's data. The default implementation returns the single string representation from toString().

Reimplemented in TagLib::ID3v2::AttachedPictureFrame, TagLib::ID3v2::GeneralEncapsulatedObjectFrame, TagLib::ID3v2::OwnershipFrame, TagLib::ID3v2::PopularimeterFrame, and TagLib::ID3v2::TextIdentificationFrame.

◆ unsynchronisation()

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

Returns true if unsynchronisation is enabled for this frame.

◆ version()

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

◆ FramePrivate

friend class FramePrivate

friend

◆ Tag

friend class Tag

friend

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:

id3v2frame.h

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ~Frame()

◆ Frame() [1/3]

◆ Frame() [2/3]

◆ Frame() [3/3]

◆ ~Header()

Member Function Documentation

◆ asProperties()

◆ checkTextEncoding()

◆ compression()

◆ dataLengthIndicator()

◆ encryption()

◆ fieldData()

◆ fileAlterPreservation()

◆ frameID() [1/2]

◆ frameID() [2/2]

◆ frameIDToKey()

◆ frameSize()

◆ groupingIdentity()

◆ header()

◆ Header() [1/2]

◆ Header() [2/2]

◆ headerSize()

◆ keyToFrameID()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ parse()

◆ parseFields()

◆ readOnly()

◆ readStringField()

◆ render() [1/2]

◆ render() [2/2]

◆ renderFields()

◆ setData() [1/2]

◆ setData() [2/2]

◆ setFrameID()

◆ setFrameSize()

◆ setHeader()

◆ setTagAlterPreservation()

◆ setText()

◆ setVersion()

◆ size() [1/2]

◆ size() [2/2]

◆ splitProperties()

◆ tagAlterPreservation()

◆ textDelimiter()

◆ toString()

◆ toStringList()

◆ unsynchronisation()

◆ version()

Friends And Related Function Documentation

◆ FramePrivate

◆ Tag

Member Data Documentation

◆ commentPrefix

◆ instrumentPrefix

◆ lyricsPrefix

◆ urlPrefix