Tag Parser: TagParser::Id3v2Frame Class Reference

Tag Parser 12.5.2 C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags

Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Friends | List of all members
TagParser::Id3v2Frame Class Reference

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

`#include <id3v2frame.h>`

Inheritance diagram for TagParser::Id3v2Frame:
[legend]
Collaboration diagram for TagParser::Id3v2Frame:
[legend]

## 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 ()
| Destroys the TagField.
IdentifierType & | id ()
| 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.
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.
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
using | 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 436 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 1127 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 1283 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 1144 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 1214 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 888 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 1015 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 1101 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 1041 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 1067 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 991 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 918 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 867 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 1003 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 423 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