The Id3v2Frame class is used by Id3v2Tag to store the fields. More...

#include <id3v2frame.h>

Inheritance diagram for TagParser::Id3v2Frame:

Collaboration diagram for TagParser::Id3v2Frame:

Public Member Functions
	Id3v2Frame ()
	Constructs a new Id3v2Frame.

	Id3v2Frame (const IdentifierType &id, const TagValue &value, std::uint8_t group=0, std::uint16_t flag=0)
	Constructs a new Id3v2Frame with the specified id, value, group and flag.

void	parse (CppUtilities::BinaryReader &reader, std::uint32_t version, std::uint32_t maximalSize, Diagnostics &diag)
	Parses a frame from the stream read using the specified reader.

Id3v2FrameMaker	prepareMaking (std::uint8_t version, Diagnostics &diag)
	Prepares making.

void	make (CppUtilities::BinaryWriter &writer, std::uint8_t version, Diagnostics &diag)
	Writes the frame to a stream using the specified writer and the specified ID3v2 version.

const std::vector< TagValue > &	additionalValues () const
	Returns additional values.

std::vector< TagValue > &	additionalValues ()
	Returns additional values.

bool	isAdditionalTypeInfoUsed () const
	Returns whether the instance uses the additional type info.

bool	isValid () const
	Returns whether the frame is valid.

bool	hasPaddingReached () const
	Returns whether the padding has reached.

std::uint16_t	flag () const
	Returns the flags.

void	setFlag (std::uint16_t value)
	Sets the flags.

std::uint32_t	totalSize () const
	Returns the total size of the frame in bytes.

std::uint32_t	dataSize () const
	Returns the size of the data stored in the frame in bytes.

bool	toDiscardWhenUnknownAndTagIsAltered () const
	Returns whether the frame is flagged to be discarded when it is unknown and the tag is altered.

bool	toDiscardWhenUnknownAndFileIsAltered () const
	Returns whether the frame is flagged to be discarded when it is unknown and the file (but NOT the tag) is altered.

bool	isReadOnly () const
	Returns whether the frame is flagged as read-only.

bool	isCompressed () const
	Returns whether the frame is compressed.

bool	isEncrypted () const
	Returns whether the frame is encrypted.

bool	hasGroupInformation () const
	Returns whether the frame contains group information.

bool	isUnsynchronized () const
	Returns whether the frame is unsynchronized.

bool	hasDataLengthIndicator () const
	Returns whether the frame has a data length indicator.

std::uint8_t	group () const
	Returns the group.

void	setGroup (std::uint8_t value)
	Sets the group information.

std::uint32_t	parsedVersion () const
	Returns the version of the frame (read when parsing the frame).

bool	supportsNestedFields () const
	Returns whether nested fields are supported.

TagTextEncoding	parseTextEncodingByte (std::uint8_t textEncodingByte, Diagnostics &diag)
	Returns the text encoding for the specified textEncodingByte.

std::tuple< const char , std::size_t, const char >	parseSubstring (const char *buffer, std::size_t maxSize, TagTextEncoding &encoding, bool addWarnings, Diagnostics &diag)
	Parses a substring from the specified buffer.

std::string	parseString (const char *buffer, std::size_t maxSize, TagTextEncoding &encoding, bool addWarnings, Diagnostics &diag)
	Parses a substring from the specified buffer.

std::u16string	parseWideString (const char *buffer, std::size_t dataSize, TagTextEncoding &encoding, bool addWarnings, Diagnostics &diag)
	Parses a substring from the specified buffer.

void	parseLegacyPicture (const char *buffer, std::size_t maxSize, TagValue &tagValue, std::uint8_t &typeInfo, Diagnostics &diag)
	Parses the ID3v2.2 picture from the specified buffer.

void	parsePicture (const char *buffer, std::size_t maxSize, TagValue &tagValue, std::uint8_t &typeInfo, Diagnostics &diag)
	Parses the ID3v2.3 picture from the specified buffer.

void	parseComment (const char *buffer, std::size_t maxSize, TagValue &tagValue, Diagnostics &diag)
	Parses the comment/unsynchronized lyrics from the specified buffer.

void	parseBom (const char *buffer, std::size_t maxSize, TagTextEncoding &encoding, Diagnostics &diag)
	Parses a byte order mark from the specified buffer.

Public Member Functions inherited from TagParser::TagField< Id3v2Frame >
	TagField ()
	Constructs an empty TagField.

	TagField (const IdentifierType &id, const TagValue &value)
	Constructs a new TagField with the specified id and value.

	~TagField ()
	Destroys the TagField.

IdentifierType &	id ()
	Returns the id of the current TagField.

const IdentifierType &	id () const
	Returns the id of the current TagField.

std::string	idToString () const
	Returns the id of the current TagField as string.

void	setId (const IdentifierType &id)
	Sets the id of the current Tag Field.

void	clearId ()
	Clears the id of the current TagField.

TagValue &	value ()
	Returns the value of the current TagField.

const TagValue &	value () const
	Returns the value of the current TagField.

void	setValue (const TagValue &value)
	Sets the value of the current TagField.

void	clearValue ()
	Clears the value of the current TagField.

const TypeInfoType &	typeInfo () const
	Returns the type info of the current TagField.

void	setTypeInfo (const TypeInfoType &typeInfo)
	Sets the type info of the current TagField.

void	removeTypeInfo ()
	Removes the type info from the current TagField.

bool	isTypeInfoAssigned () const
	Returns an indication whether a type info is assigned.

bool	isDefault () const
	Returns an indication whether the field is labeled as default.

void	setDefault (bool isDefault)
	Sets whether the field is labeled as default.

void	clear ()
	Clears id, value, type info, sets default flag to false and resets further implementation specific values.

bool	isAdditionalTypeInfoUsed () const
	Returns an indication whether the additional type info is used.

const std::vector< Id3v2Frame > &	nestedFields () const
	Returns the nested fields.

std::vector< Id3v2Frame > &	nestedFields ()
	Returns the nested fields.

bool	supportsNestedFields () const
	Returns whether nested fields are supported by the implementation.

Static Public Member Functions
static std::uint8_t	makeTextEncodingByte (TagTextEncoding textEncoding)
	Returns a text encoding byte for the specified textEncoding.

static std::size_t	makeBom (char *buffer, TagTextEncoding encoding)
	Writes the BOM for the specified encoding to the specified buffer.

static void	makeLegacyPicture (std::unique_ptr< char[]> &buffer, std::uint32_t &bufferSize, const TagValue &picture, std::uint8_t typeInfo, Diagnostics &diag)
	Writes the specified picture to the specified buffer (ID3v2.2 compatible).

static void	makePicture (std::unique_ptr< char[]> &buffer, std::uint32_t &bufferSize, const TagValue &picture, std::uint8_t typeInfo, std::uint8_t version, Diagnostics &diag)
	Writes the specified picture to the specified buffer.

static void	makeComment (std::unique_ptr< char[]> &buffer, std::uint32_t &bufferSize, const TagValue &comment, std::uint8_t version, Diagnostics &diag)
	Writes the specified comment to the specified buffer.

static IdentifierType	fieldIdFromString (std::string_view idString)
	Converts the specified ID string representation to an actual ID.

static std::string	fieldIdToString (IdentifierType id)
	Returns the string representation for the specified id.

Friends
class	TagField< Id3v2Frame >

class	Id3v2FrameMaker

Additional Inherited Members
Public Types inherited from TagParser::TagField< Id3v2Frame >
using	IdentifierType = typename TagFieldTraits< Id3v2Frame >::IdentifierType

using	TypeInfoType = typename TagFieldTraits< Id3v2Frame >::TypeInfoType

Protected Member Functions inherited from TagParser::TagField< Id3v2Frame >
void	internallyClearValue ()
	Clears the assigned value; called via clearValue() and clear().

void	internallyClearFurtherData ()
	Clears further data; called via clear().

Detailed Description

The Id3v2Frame class is used by Id3v2Tag to store the fields.

Definition at line 86 of file id3v2frame.h.

Constructor & Destructor Documentation

◆ Id3v2Frame() [1/2]

TagParser::Id3v2Frame::Id3v2Frame ( )

Constructs a new Id3v2Frame.

Definition at line 40 of file id3v2frame.cpp.

◆ Id3v2Frame() [2/2]

TagParser::Id3v2Frame::Id3v2Frame	(	const IdentifierType &	id,
		const TagValue &	value,
		std::uint8_t	group = `0`,
		std::uint16_t	flag = `0`
	)

Constructs a new Id3v2Frame with the specified id, value, group and flag.

Definition at line 53 of file id3v2frame.cpp.

Member Function Documentation

◆ additionalValues() [1/2]

std::vector< TagValue > & TagParser::Id3v2Frame::additionalValues ( )

inline

Returns additional values.

Remarks: Frames might allow to store multiple values, eg. ID3v2.4 text frames allow to store multiple strings.

Definition at line 173 of file id3v2frame.h.

◆ additionalValues() [2/2]

const std::vector< TagValue > & TagParser::Id3v2Frame::additionalValues ( ) const

inline

Returns additional values.

Remarks: Frames might allow to store multiple values, eg. ID3v2.4 text frames allow to store multiple strings.

Definition at line 164 of file id3v2frame.h.

◆ dataSize()

std::uint32_t TagParser::Id3v2Frame::dataSize ( ) const

inline

Returns the size of the data stored in the frame in bytes.

Definition at line 229 of file id3v2frame.h.

◆ fieldIdFromString()

Id3v2Frame::IdentifierType TagParser::Id3v2Frame::fieldIdFromString ( std::string_view idString )

inlinestatic

Converts the specified ID string representation to an actual ID.

Definition at line 335 of file id3v2frame.h.

◆ fieldIdToString()

std::string TagParser::Id3v2Frame::fieldIdToString ( IdentifierType id )

inlinestatic

Returns the string representation for the specified id.

Definition at line 350 of file id3v2frame.h.

◆ flag()

std::uint16_t TagParser::Id3v2Frame::flag ( ) const

inline

Returns the flags.

Definition at line 205 of file id3v2frame.h.

◆ group()

std::uint8_t TagParser::Id3v2Frame::group ( ) const

inline

Returns the group.

See also: hasGroupInformation()

Definition at line 303 of file id3v2frame.h.

◆ hasDataLengthIndicator()

bool TagParser::Id3v2Frame::hasDataLengthIndicator ( ) const

inline

Returns whether the frame has a data length indicator.

Definition at line 294 of file id3v2frame.h.

◆ hasGroupInformation()

bool TagParser::Id3v2Frame::hasGroupInformation ( ) const

inline

Returns whether the frame contains group information.

Definition at line 278 of file id3v2frame.h.

◆ hasPaddingReached()

bool TagParser::Id3v2Frame::hasPaddingReached ( ) const

inline

Returns whether the padding has reached.

Definition at line 197 of file id3v2frame.h.

◆ isAdditionalTypeInfoUsed()

bool TagParser::Id3v2Frame::isAdditionalTypeInfoUsed ( ) const

inline

Returns whether the instance uses the additional type info.

Definition at line 181 of file id3v2frame.h.

◆ isCompressed()

bool TagParser::Id3v2Frame::isCompressed ( ) const

inline

Returns whether the frame is compressed.

Definition at line 261 of file id3v2frame.h.

◆ isEncrypted()

bool TagParser::Id3v2Frame::isEncrypted ( ) const

inline

Returns whether the frame is encrypted.

Remarks: Reading encrypted frames is not supported.

Definition at line 270 of file id3v2frame.h.

◆ isReadOnly()

bool TagParser::Id3v2Frame::isReadOnly ( ) const

inline

Returns whether the frame is flagged as read-only.

Definition at line 253 of file id3v2frame.h.

◆ isUnsynchronized()

bool TagParser::Id3v2Frame::isUnsynchronized ( ) const

inline

Returns whether the frame is unsynchronized.

Definition at line 286 of file id3v2frame.h.

◆ isValid()

bool TagParser::Id3v2Frame::isValid ( ) const

inline

Returns whether the frame is valid.

Definition at line 189 of file id3v2frame.h.

◆ make()

void TagParser::Id3v2Frame::make	(	CppUtilities::BinaryWriter &	writer,
		std::uint8_t	version,
		Diagnostics &	diag
	)

Writes the frame to a stream using the specified writer and the specified ID3v2 version.

Exceptions

Throws	std::ios_base::failure when an IO error occurs.
Throws	TagParser::Failure or a derived exception when a making error occurs.

Definition at line 434 of file id3v2frame.cpp.

◆ makeBom()

size_t TagParser::Id3v2Frame::makeBom	(	char *	buffer,
		TagTextEncoding	encoding
	)

static

Writes the BOM for the specified encoding to the specified buffer.

Returns: Returns the number of bytes written to the buffer.

Definition at line 1112 of file id3v2frame.cpp.

◆ makeComment()

void TagParser::Id3v2Frame::makeComment	(	std::unique_ptr< char[]> &	buffer,
		std::uint32_t &	bufferSize,
		const TagValue &	comment,
		std::uint8_t	version,
		Diagnostics &	diag
	)

static

Writes the specified comment to the specified buffer.

Definition at line 1268 of file id3v2frame.cpp.

◆ makeLegacyPicture()

void TagParser::Id3v2Frame::makeLegacyPicture	(	std::unique_ptr< char[]> &	buffer,
		std::uint32_t &	bufferSize,
		const TagValue &	picture,
		std::uint8_t	typeInfo,
		Diagnostics &	diag
	)

static

Writes the specified picture to the specified buffer (ID3v2.2 compatible).

Definition at line 1129 of file id3v2frame.cpp.

◆ makePicture()

void TagParser::Id3v2Frame::makePicture	(	std::unique_ptr< char[]> &	buffer,
		std::uint32_t &	bufferSize,
		const TagValue &	picture,
		std::uint8_t	typeInfo,
		std::uint8_t	version,
		Diagnostics &	diag
	)

static

Writes the specified picture to the specified buffer.

Definition at line 1199 of file id3v2frame.cpp.

◆ makeTextEncodingByte()

std::uint8_t TagParser::Id3v2Frame::makeTextEncodingByte ( TagTextEncoding textEncoding )

static

Returns a text encoding byte for the specified textEncoding.

Definition at line 873 of file id3v2frame.cpp.

◆ parse()

void TagParser::Id3v2Frame::parse	(	CppUtilities::BinaryReader &	reader,
		std::uint32_t	version,
		std::uint32_t	maximalSize,
		Diagnostics &	diag
	)

Parses a frame from the stream read using the specified reader.

The position of the current character in the input stream is expected to be at the beginning of the frame to be parsed.

Exceptions

Throws	std::ios_base::failure when an IO error occurs.
Throws	TagParser::Failure or a derived exception when a parsing error occurs.

Definition at line 151 of file id3v2frame.cpp.

◆ parseBom()

void TagParser::Id3v2Frame::parseBom	(	const char *	buffer,
		std::size_t	maxSize,
		TagTextEncoding &	encoding,
		Diagnostics &	diag
	)

Parses a byte order mark from the specified buffer.

Parameters

buffer	Specifies the buffer holding the byte order mark.
maxSize	Specifies the maximal number of bytes to read from the buffer.
encoding	Specifies the encoding of the string. Might be reset if a byte order mark is found.

Remarks: This method is not used anymore and might be deleted.

Definition at line 1000 of file id3v2frame.cpp.

◆ parseComment()

void TagParser::Id3v2Frame::parseComment	(	const char *	buffer,
		std::size_t	dataSize,
		TagValue &	tagValue,
		Diagnostics &	diag
	)

Parses the comment/unsynchronized lyrics from the specified buffer.

Parameters

buffer	Specifies the buffer holding the picture.
dataSize	Specifies the maximal number of bytes to read from the buffer.
tagValue	Specifies the tag value used to store the results.

Definition at line 1086 of file id3v2frame.cpp.

◆ parsedVersion()

std::uint32_t TagParser::Id3v2Frame::parsedVersion ( ) const

inline

Returns the version of the frame (read when parsing the frame).

Definition at line 319 of file id3v2frame.h.

◆ parseLegacyPicture()

void TagParser::Id3v2Frame::parseLegacyPicture	(	const char *	buffer,
		std::size_t	maxSize,
		TagValue &	tagValue,
		std::uint8_t &	typeInfo,
		Diagnostics &	diag
	)

Parses the ID3v2.2 picture from the specified buffer.

Parameters

buffer	Specifies the buffer holding the picture.
maxSize	Specifies the maximal number of bytes to read from the buffer.
tagValue	Specifies the tag value used to store the results.
typeInfo	Specifies a byte used to store the type info.

Definition at line 1026 of file id3v2frame.cpp.

◆ parsePicture()

void TagParser::Id3v2Frame::parsePicture	(	const char *	buffer,
		std::size_t	maxSize,
		TagValue &	tagValue,
		std::uint8_t &	typeInfo,
		Diagnostics &	diag
	)

Parses the ID3v2.3 picture from the specified buffer.

Parameters

buffer	Specifies the buffer holding the picture.
maxSize	Specifies the maximal number of bytes to read from the buffer.
tagValue	Specifies the tag value used to store the results.
typeInfo	Specifies a byte used to store the type info.

Definition at line 1052 of file id3v2frame.cpp.

◆ parseString()

string TagParser::Id3v2Frame::parseString	(	const char *	buffer,
		std::size_t	maxSize,
		TagTextEncoding &	encoding,
		bool	addWarnings,
		Diagnostics &	diag
	)

Parses a substring from the specified buffer.

Same as Id3v2Frame::parseSubstring() but returns the substring as string object.

Definition at line 976 of file id3v2frame.cpp.

◆ parseSubstring()

tuple< const char , size_t, const char > TagParser::Id3v2Frame::parseSubstring	(	const char *	buffer,
		std::size_t	bufferSize,
		TagTextEncoding &	encoding,
		bool	addWarnings,
		Diagnostics &	diag
	)

Parses a substring from the specified buffer.

This method ensures that byte order marks and termination characters for the specified encoding are omitted. It might add a warning if the substring is not terminated.

Parameters

buffer	Specifies a pointer to the possibly terminated string.
bufferSize	Specifies the size of the string in byte.
encoding	Specifies the encoding of the string. Might be adjusted if a byte order marks is found.
addWarnings	Specifies whether warnings should be added if the string is not terminated.

Returns: Returns the start offset, the length of the string (without termination) and the end offset (after termination).

Remarks: The length is always returned as the number of bytes, not as the number of characters (makes a difference for Unicode encodings).

Definition at line 903 of file id3v2frame.cpp.

◆ parseTextEncodingByte()

TagTextEncoding TagParser::Id3v2Frame::parseTextEncodingByte	(	std::uint8_t	textEncodingByte,
		Diagnostics &	diag
	)

Returns the text encoding for the specified textEncodingByte.

If the textEncodingByte doesn't match any encoding TagTextEncoding::Latin1 is returned and a parsing notification is added.

Definition at line 852 of file id3v2frame.cpp.

◆ parseWideString()

u16string TagParser::Id3v2Frame::parseWideString	(	const char *	buffer,
		std::size_t	dataSize,
		TagTextEncoding &	encoding,
		bool	addWarnings,
		Diagnostics &	diag
	)

Parses a substring from the specified buffer.

Same as Id3v2Frame::parseSubstring() but returns the substring as u16string object

Remarks: Converts byte order to match host byte order (otherwise it wouldn't make much sense to use the resulting u16string).

Definition at line 988 of file id3v2frame.cpp.

◆ prepareMaking()

Id3v2FrameMaker TagParser::Id3v2Frame::prepareMaking	(	std::uint8_t	version,
		Diagnostics &	diag
	)

Prepares making.

Returns: Returns a Id3v2FrameMaker object which can be used to actually make the frame.

Remarks: The field must NOT be mutated after making is prepared when it is intended to actually make the field using the make method of the returned object.

Exceptions

Throws TagParser::Failure or a derived exception when a making error occurs.

This method might be useful when it is necessary to know the size of the field before making it.

Definition at line 421 of file id3v2frame.cpp.

◆ setFlag()

void TagParser::Id3v2Frame::setFlag ( std::uint16_t value )

inline

Sets the flags.

Definition at line 213 of file id3v2frame.h.

◆ setGroup()

void TagParser::Id3v2Frame::setGroup ( std::uint8_t value )

inline

Sets the group information.

Definition at line 311 of file id3v2frame.h.

◆ supportsNestedFields()

bool TagParser::Id3v2Frame::supportsNestedFields ( ) const

inline

Returns whether nested fields are supported.

Definition at line 327 of file id3v2frame.h.

◆ toDiscardWhenUnknownAndFileIsAltered()

bool TagParser::Id3v2Frame::toDiscardWhenUnknownAndFileIsAltered ( ) const

inline

Returns whether the frame is flagged to be discarded when it is unknown and the file (but NOT the tag) is altered.

Definition at line 245 of file id3v2frame.h.

◆ toDiscardWhenUnknownAndTagIsAltered()

bool TagParser::Id3v2Frame::toDiscardWhenUnknownAndTagIsAltered ( ) const

inline

Returns whether the frame is flagged to be discarded when it is unknown and the tag is altered.

Definition at line 237 of file id3v2frame.h.

◆ totalSize()

std::uint32_t TagParser::Id3v2Frame::totalSize ( ) const

inline

Returns the total size of the frame in bytes.

Definition at line 221 of file id3v2frame.h.

Friends And Related Symbol Documentation

◆ Id3v2FrameMaker

friend class Id3v2FrameMaker

friend

Definition at line 88 of file id3v2frame.h.

◆ TagField< Id3v2Frame >

friend class TagField< Id3v2Frame >

friend

Definition at line 42 of file id3v2frame.h.

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

id3/id3v2frame.h
id3/id3v2frame.cpp

Public Member Functions

Static Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Id3v2Frame() [1/2]

◆ Id3v2Frame() [2/2]

Member Function Documentation

◆ additionalValues() [1/2]

◆ additionalValues() [2/2]

◆ dataSize()

◆ fieldIdFromString()

◆ fieldIdToString()

◆ flag()

◆ group()

◆ hasDataLengthIndicator()

◆ hasGroupInformation()

◆ hasPaddingReached()

◆ isAdditionalTypeInfoUsed()

◆ isCompressed()

◆ isEncrypted()

◆ isReadOnly()

◆ isUnsynchronized()

◆ isValid()

◆ make()

◆ makeBom()

◆ makeComment()

◆ makeLegacyPicture()

◆ makePicture()

◆ makeTextEncodingByte()

◆ parse()

◆ parseBom()

◆ parseComment()

◆ parsedVersion()

◆ parseLegacyPicture()

◆ parsePicture()

◆ parseString()

◆ parseSubstring()

◆ parseTextEncodingByte()

◆ parseWideString()

◆ prepareMaking()

◆ setFlag()

◆ setGroup()

◆ supportsNestedFields()

◆ toDiscardWhenUnknownAndFileIsAltered()

◆ toDiscardWhenUnknownAndTagIsAltered()

◆ totalSize()

Friends And Related Symbol Documentation

◆ Id3v2FrameMaker

◆ TagField< Id3v2Frame >