Tag Parser  8.2.0
C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
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. More...
 
 Id3v2Frame (const IdentifierType &id, const TagValue &value, byte group=0, uint16 flag=0)
 Constructs a new Id3v2Frame with the specified id, value, group and flag. More...
 
void parse (IoUtilities::BinaryReader &reader, uint32 version, uint32 maximalSize, Diagnostics &diag)
 Parses a frame from the stream read using the specified reader. More...
 
Id3v2FrameMaker prepareMaking (byte version, Diagnostics &diag)
 Prepares making. More...
 
void make (IoUtilities::BinaryWriter &writer, byte version, Diagnostics &diag)
 Writes the frame to a stream using the specified writer and the specified ID3v2 version. More...
 
const std::vector< TagValue > & additionalValues () const
 Returns additional values. More...
 
std::vector< TagValue > & additionalValues ()
 Returns additional values. More...
 
bool isAdditionalTypeInfoUsed () const
 Returns whether the instance uses the additional type info. More...
 
bool isValid () const
 Returns whether the frame is valid. More...
 
bool hasPaddingReached () const
 Returns whether the padding has reached. More...
 
uint16 flag () const
 Returns the flags. More...
 
void setFlag (uint16 value)
 Sets the flags. More...
 
uint32 totalSize () const
 Returns the total size of the frame in bytes. More...
 
uint32 dataSize () const
 Returns the size of the data stored in the frame in bytes. More...
 
bool toDiscardWhenUnknownAndTagIsAltered () const
 Returns whether the frame is flaged to be discarded when it is unknown and the tag is altered. More...
 
bool toDiscardWhenUnknownAndFileIsAltered () const
 Returns whether the frame is flaged to be discarded when it is unknown and the file (but NOT the tag) is altered. More...
 
bool isReadOnly () const
 Returns whether the frame is flagged as read-only. More...
 
bool isCompressed () const
 Returns whether the frame is compressed. More...
 
bool isEncrypted () const
 Returns whether the frame is encrypted. More...
 
bool hasGroupInformation () const
 Returns whether the frame contains group information. More...
 
bool isUnsynchronized () const
 Returns whether the frame is unsynchronized. More...
 
bool hasDataLengthIndicator () const
 Returns whether the frame has a data length indicator. More...
 
byte group () const
 Returns the group. More...
 
void setGroup (byte value)
 Sets the group information. More...
 
uint32 parsedVersion () const
 Returns the version of the frame (read when parsing the frame). More...
 
bool supportsNestedFields () const
 Returns whether nested fields are supported. More...
 
TagTextEncoding parseTextEncodingByte (byte textEncodingByte, Diagnostics &diag)
 Returns the text encoding for the specified textEncodingByte. More...
 
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. More...
 
std::string parseString (const char *buffer, std::size_t maxSize, TagTextEncoding &encoding, bool addWarnings, Diagnostics &diag)
 Parses a substring from the specified buffer. More...
 
std::u16string parseWideString (const char *buffer, std::size_t dataSize, TagTextEncoding &encoding, bool addWarnings, Diagnostics &diag)
 Parses a substring from the specified buffer. More...
 
void parseLegacyPicture (const char *buffer, std::size_t maxSize, TagValue &tagValue, byte &typeInfo, Diagnostics &diag)
 Parses the ID3v2.2 picture from the specified buffer. More...
 
void parsePicture (const char *buffer, std::size_t maxSize, TagValue &tagValue, byte &typeInfo, Diagnostics &diag)
 Parses the ID3v2.3 picture from the specified buffer. More...
 
void parseComment (const char *buffer, std::size_t maxSize, TagValue &tagValue, Diagnostics &diag)
 Parses the comment/unsynchronized lyrics from the specified buffer. More...
 
void parseBom (const char *buffer, std::size_t maxSize, TagTextEncoding &encoding, Diagnostics &diag)
 Parses a byte order mark from the specified buffer. More...
 
- Public Member Functions inherited from TagParser::TagField< ImplementationType >
 TagField ()
 Constructs an empty TagField. More...
 
 TagField (const IdentifierType &id, const TagValue &value)
 Constructs a new TagField with the specified id and value. More...
 
 ~TagField ()
 Destroys the TagField. More...
 
const IdentifierTypeid () const
 Returns the id of the current TagField. More...
 
std::string idToString () const
 
void setId (const IdentifierType &id)
 Sets the id of the current Tag Field. More...
 
void clearId ()
 Clears the id of the current TagField. More...
 
TagValuevalue ()
 Returns the value of the current TagField. More...
 
const TagValuevalue () const
 Returns the value of the current TagField. More...
 
void setValue (const TagValue &value)
 Sets the value of the current TagField. More...
 
void clearValue ()
 Clears the value of the current TagField. More...
 
const TypeInfoTypetypeInfo () const
 Returns the type info of the current TagField. More...
 
void setTypeInfo (const TypeInfoType &typeInfo)
 Sets the type info of the current TagField. More...
 
void removeTypeInfo ()
 Removes the type info from the current TagField. More...
 
bool isTypeInfoAssigned () const
 Returns an indication whether a type info is assigned. More...
 
bool isDefault () const
 Returns an indication whether the field is labeled as default. More...
 
void setDefault (bool isDefault)
 Sets whether the field is labeled as default. More...
 
void clear ()
 Clears id, value, type info, sets default flag to false and resets further implementation specific values. More...
 
bool isAdditionalTypeInfoUsed () const
 Returns an indication whether the additional type info is used. More...
 
const std::vector< ImplementationType > & nestedFields () const
 Returns the nested fields. More...
 
std::vector< ImplementationType > & nestedFields ()
 Returns the nested fields. More...
 
bool supportsNestedFields () const
 Returns whether nested fields are supported by the implementation. More...
 

Static Public Member Functions

static byte makeTextEncodingByte (TagTextEncoding textEncoding)
 Returns a text encoding byte for the specified textEncoding. More...
 
static std::size_t makeBom (char *buffer, TagTextEncoding encoding)
 Writes the BOM for the specified encoding to the specified buffer. More...
 
static void makeString (std::unique_ptr< char[]> &buffer, uint32 &bufferSize, const std::string &value, TagTextEncoding encoding)
 Writes an encoding denoation and the specified string value to a buffer. More...
 
static void makeEncodingAndData (std::unique_ptr< char[]> &buffer, uint32 &bufferSize, TagTextEncoding encoding, const char *data, std::size_t m_dataSize)
 Writes an encoding denoation and the specified data to a buffer. More...
 
static void makeLegacyPicture (std::unique_ptr< char[]> &buffer, uint32 &bufferSize, const TagValue &picture, byte typeInfo)
 Writes the specified picture to the specified buffer (ID3v2.2 compatible). More...
 
static void makePicture (std::unique_ptr< char[]> &buffer, uint32 &bufferSize, const TagValue &picture, byte typeInfo, byte version)
 Writes the specified picture to the specified buffer. More...
 
static void makeComment (std::unique_ptr< char[]> &buffer, uint32 &bufferSize, const TagValue &comment, byte version, Diagnostics &diag)
 Writes the specified comment to the specified buffer. More...
 
static IdentifierType fieldIdFromString (const char *idString, std::size_t idStringSize=std::string::npos)
 Converts the specified ID string representation to an actual ID. More...
 
static std::string fieldIdToString (IdentifierType id)
 Returns the string representation for the specified id. More...
 

Friends

class TagField< Id3v2Frame >
 
class Id3v2FrameMaker
 

Additional Inherited Members

- Public Types inherited from TagParser::TagField< ImplementationType >
using IdentifierType = typename TagFieldTraits< ImplementationType >::IdentifierType
 
using TypeInfoType = typename TagFieldTraits< ImplementationType >::TypeInfoType
 

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,
byte  group = 0,
uint16  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]

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 163 of file id3v2frame.h.

◆ additionalValues() [2/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 172 of file id3v2frame.h.

◆ dataSize()

uint32 TagParser::Id3v2Frame::dataSize ( ) const
inline

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

Definition at line 228 of file id3v2frame.h.

◆ fieldIdFromString()

Id3v2Frame::IdentifierType TagParser::Id3v2Frame::fieldIdFromString ( const char *  idString,
std::size_t  idStringSize = std::string::npos 
)
inlinestatic

Converts the specified ID string representation to an actual ID.

Definition at line 334 of file id3v2frame.h.

◆ fieldIdToString()

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

Returns the string representation for the specified id.

Definition at line 349 of file id3v2frame.h.

◆ flag()

uint16 TagParser::Id3v2Frame::flag ( ) const
inline

Returns the flags.

Definition at line 204 of file id3v2frame.h.

◆ group()

byte TagParser::Id3v2Frame::group ( ) const
inline

Returns the group.

See also
hasGroupInformation()

Definition at line 302 of file id3v2frame.h.

◆ hasDataLengthIndicator()

bool TagParser::Id3v2Frame::hasDataLengthIndicator ( ) const
inline

Returns whether the frame has a data length indicator.

Definition at line 293 of file id3v2frame.h.

◆ hasGroupInformation()

bool TagParser::Id3v2Frame::hasGroupInformation ( ) const
inline

Returns whether the frame contains group information.

Definition at line 277 of file id3v2frame.h.

◆ hasPaddingReached()

bool TagParser::Id3v2Frame::hasPaddingReached ( ) const
inline

Returns whether the padding has reached.

Definition at line 196 of file id3v2frame.h.

◆ isAdditionalTypeInfoUsed()

bool TagParser::Id3v2Frame::isAdditionalTypeInfoUsed ( ) const
inline

Returns whether the instance uses the additional type info.

Definition at line 180 of file id3v2frame.h.

◆ isCompressed()

bool TagParser::Id3v2Frame::isCompressed ( ) const
inline

Returns whether the frame is compressed.

Definition at line 260 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 269 of file id3v2frame.h.

◆ isReadOnly()

bool TagParser::Id3v2Frame::isReadOnly ( ) const
inline

Returns whether the frame is flagged as read-only.

Definition at line 252 of file id3v2frame.h.

◆ isUnsynchronized()

bool TagParser::Id3v2Frame::isUnsynchronized ( ) const
inline

Returns whether the frame is unsynchronized.

Definition at line 285 of file id3v2frame.h.

◆ isValid()

bool TagParser::Id3v2Frame::isValid ( ) const
inline

Returns whether the frame is valid.

Definition at line 188 of file id3v2frame.h.

◆ make()

void TagParser::Id3v2Frame::make ( IoUtilities::BinaryWriter &  writer,
byte  version,
Diagnostics diag 
)

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

Exceptions
Throwsstd::ios_base::failure when an IO error occurs.
ThrowsTagParser::Failure or a derived exception when a making error occurs.

Definition at line 386 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 1041 of file id3v2frame.cpp.

◆ makeComment()

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

Writes the specified comment to the specified buffer.

Definition at line 1184 of file id3v2frame.cpp.

◆ makeEncodingAndData()

void TagParser::Id3v2Frame::makeEncodingAndData ( std::unique_ptr< char[]> &  buffer,
uint32 &  bufferSize,
TagTextEncoding  encoding,
const char *  data,
std::size_t  dataSize 
)
static

Writes an encoding denoation and the specified data to a buffer.

Parameters
bufferSpecifies the buffer.
bufferSizeSpecifies the size of buffer.
encodingSpecifies the data encoding.
dataSpecifies the data.
dataSizeSpecifies size of data.
Deprecated:
No longer used.
Todo:
Remove in v9.

Definition at line 998 of file id3v2frame.cpp.

◆ makeLegacyPicture()

void TagParser::Id3v2Frame::makeLegacyPicture ( std::unique_ptr< char[]> &  buffer,
uint32 &  bufferSize,
const TagValue picture,
byte  typeInfo 
)
static

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

Definition at line 1058 of file id3v2frame.cpp.

◆ makePicture()

void TagParser::Id3v2Frame::makePicture ( std::unique_ptr< char[]> &  buffer,
uint32 &  bufferSize,
const TagValue picture,
byte  typeInfo,
byte  version 
)
static

Writes the specified picture to the specified buffer.

Definition at line 1126 of file id3v2frame.cpp.

◆ makeString()

void TagParser::Id3v2Frame::makeString ( std::unique_ptr< char[]> &  buffer,
uint32 &  bufferSize,
const std::string &  value,
TagTextEncoding  encoding 
)
static

Writes an encoding denoation and the specified string value to a buffer.

Parameters
bufferSpecifies the buffer.
bufferSizeSpecifies the size of buffer.
valueSpecifies the string to make.
encodingSpecifies the encoding of the string to make.
Deprecated:
No longer used.
Todo:
Remove in v9.

Definition at line 983 of file id3v2frame.cpp.

◆ makeTextEncodingByte()

byte TagParser::Id3v2Frame::makeTextEncodingByte ( TagTextEncoding  textEncoding)
static

Returns a text encoding byte for the specified textEncoding.

Definition at line 739 of file id3v2frame.cpp.

◆ parse()

void TagParser::Id3v2Frame::parse ( IoUtilities::BinaryReader &  reader,
uint32  version,
uint32  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
Throwsstd::ios_base::failure when an IO error occurs.
ThrowsTagParser::Failure or a derived exception when a parsing error occurs.

Definition at line 134 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
bufferSpecifies the buffer holding the byte order mark.
maxSizeSpecifies the maximal number of bytes to read from the buffer.
encodingSpecifies 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 866 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
bufferSpecifies the buffer holding the picture.
dataSizeSpecifies the maximal number of bytes to read from the buffer.
tagValueSpecifies the tag value used to store the results.

Definition at line 952 of file id3v2frame.cpp.

◆ parsedVersion()

uint32 TagParser::Id3v2Frame::parsedVersion ( ) const
inline

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

Definition at line 318 of file id3v2frame.h.

◆ parseLegacyPicture()

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

Parses the ID3v2.2 picture from the specified buffer.

Parameters
bufferSpecifies the buffer holding the picture.
maxSizeSpecifies the maximal number of bytes to read from the buffer.
tagValueSpecifies the tag value used to store the results.
typeInfoSpecifies a byte used to store the type info.

Definition at line 892 of file id3v2frame.cpp.

◆ parsePicture()

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

Parses the ID3v2.3 picture from the specified buffer.

Parameters
bufferSpecifies the buffer holding the picture.
maxSizeSpecifies the maximal number of bytes to read from the buffer.
tagValueSpecifies the tag value used to store the results.
typeInfoSpecifies a byte used to store the type info.

Definition at line 918 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 842 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 waring if the substring is not terminated.

Parameters
bufferSpecifies a pointer to the possibly terminated string.
bufferSizeSpecifies the size of the string in byte.
encodingSpecifies the encoding of the string. Might be adjusted if a byte order marks is found.
addWarningsSpecifies 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 769 of file id3v2frame.cpp.

◆ parseTextEncodingByte()

TagTextEncoding TagParser::Id3v2Frame::parseTextEncodingByte ( byte  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 718 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 854 of file id3v2frame.cpp.

◆ prepareMaking()

Id3v2FrameMaker TagParser::Id3v2Frame::prepareMaking ( byte  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
ThrowsTagParser::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 373 of file id3v2frame.cpp.

◆ setFlag()

void TagParser::Id3v2Frame::setFlag ( uint16  value)
inline

Sets the flags.

Definition at line 212 of file id3v2frame.h.

◆ setGroup()

void TagParser::Id3v2Frame::setGroup ( byte  value)
inline

Sets the group information.

Definition at line 310 of file id3v2frame.h.

◆ supportsNestedFields()

bool TagParser::Id3v2Frame::supportsNestedFields ( ) const
inline

Returns whether nested fields are supported.

Definition at line 326 of file id3v2frame.h.

◆ toDiscardWhenUnknownAndFileIsAltered()

bool TagParser::Id3v2Frame::toDiscardWhenUnknownAndFileIsAltered ( ) const
inline

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

Definition at line 244 of file id3v2frame.h.

◆ toDiscardWhenUnknownAndTagIsAltered()

bool TagParser::Id3v2Frame::toDiscardWhenUnknownAndTagIsAltered ( ) const
inline

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

Definition at line 236 of file id3v2frame.h.

◆ totalSize()

uint32 TagParser::Id3v2Frame::totalSize ( ) const
inline

Returns the total size of the frame in bytes.

Definition at line 220 of file id3v2frame.h.

Friends And Related Function Documentation

◆ Id3v2FrameMaker

friend class Id3v2FrameMaker
friend

Definition at line 88 of file id3v2frame.h.

◆ TagField< Id3v2Frame >

friend class TagField< Id3v2Frame >
friend

Definition at line 87 of file id3v2frame.h.


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