Tag Parser  7.0.1
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

#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...
 
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...
 
std::string frameIdString () const
 Returns the frame ID as string. 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 *, size_t, const char * > parseSubstring (const char *buffer, std::size_t maxSize, TagTextEncoding &encoding, bool addWarnings, Diagnostics &diag)
 Parses a substring in the specified buffer. More...
 
std::string parseString (const char *buffer, std::size_t maxSize, TagTextEncoding &encoding, bool addWarnings, Diagnostics &diag)
 Parses a substring in the specified buffer. More...
 
std::u16string parseWideString (const char *buffer, std::size_t dataSize, TagTextEncoding &encoding, bool addWarnings, Diagnostics &diag)
 Parses a substring in 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...
 
byte makeTextEncodingByte (TagTextEncoding textEncoding)
 Returns a text encoding byte for the specified textEncoding. More...
 
std::size_t makeBom (char *buffer, TagTextEncoding encoding)
 Writes the BOM for the specified encoding to the specified buffer. More...
 
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...
 
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...
 
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...
 
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...
 
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...
 
- Public Member Functions inherited from TagParser::TagField< Id3v2Frame >
 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< Id3v2Frame > & nestedFields () const
 Returns the nested fields. More...
 
std::vector< Id3v2Frame > & nestedFields ()
 Returns the nested fields. More...
 
bool supportsNestedFields () const
 Returns whether nested fields are supported by the implementation. More...
 

Static Public Member Functions

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 >
 

Additional Inherited Members

- Public Types inherited from TagParser::TagField< Id3v2Frame >
typedef TagFieldTraits< Id3v2Frame >::IdentifierType IdentifierType
 
typedef TagFieldTraits< Id3v2Frame >::TypeInfoType TypeInfoType
 

Detailed Description

Definition at line 84 of file id3v2frame.h.

Constructor & Destructor Documentation

◆ Id3v2Frame() [1/2]

TagParser::Id3v2Frame::Id3v2Frame ( )

Constructs a new Id3v2Frame.

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

Member Function Documentation

◆ dataSize()

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

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

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

◆ fieldIdToString()

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

Returns the string representation for the specified id.

Definition at line 332 of file id3v2frame.h.

◆ flag()

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

Returns the flags.

Definition at line 187 of file id3v2frame.h.

◆ frameIdString()

std::string TagParser::Id3v2Frame::frameIdString ( ) const
inline

Returns the frame ID as string.

Deprecated:
Will be removed in favour of generic idToString().

Definition at line 179 of file id3v2frame.h.

◆ group()

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

Returns the group.

See also
hasGroupInformation()

Definition at line 285 of file id3v2frame.h.

◆ hasDataLengthIndicator()

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

Returns whether the frame has a data length indicator.

Definition at line 276 of file id3v2frame.h.

◆ hasGroupInformation()

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

Returns whether the frame contains group information.

Definition at line 260 of file id3v2frame.h.

◆ hasPaddingReached()

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

Returns whether the padding has reached.

Definition at line 170 of file id3v2frame.h.

◆ isAdditionalTypeInfoUsed()

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

Returns whether the instance uses the additional type info.

Definition at line 154 of file id3v2frame.h.

◆ isCompressed()

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

Returns whether the frame is compressed.

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

◆ isReadOnly()

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

Returns whether the frame is flagged as read-only.

Definition at line 235 of file id3v2frame.h.

◆ isUnsynchronized()

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

Returns whether the frame is unsynchronized.

Definition at line 268 of file id3v2frame.h.

◆ isValid()

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

Returns whether the frame is valid.

Definition at line 162 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.
ThrowsMedia::Failure or a derived exception when a making error occurs.

Definition at line 328 of file id3v2frame.cpp.

◆ makeBom()

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

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

Returns
Returns the number of bytes written to the buffer.

Definition at line 858 of file id3v2frame.cpp.

◆ makeComment()

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

Writes the specified comment to the specified buffer.

Definition at line 992 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 
)

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.

Definition at line 818 of file id3v2frame.cpp.

◆ makeLegacyPicture()

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

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

Definition at line 875 of file id3v2frame.cpp.

◆ makePicture()

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

Writes the specified picture to the specified buffer.

Definition at line 934 of file id3v2frame.cpp.

◆ makeString()

void TagParser::Id3v2Frame::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.

Parameters
bufferSpecifies the buffer.
bufferSizeSpecifies the size of buffer.
valueSpecifies the string to make.
encodingSpecifies the encoding of the string to make.

Definition at line 805 of file id3v2frame.cpp.

◆ makeTextEncodingByte()

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

Returns a text encoding byte for the specified textEncoding.

Definition at line 557 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.
ThrowsMedia::Failure or a derived exception when a parsing error occurs.

Definition at line 112 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 690 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 776 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 301 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 716 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 742 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 in the specified buffer.

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

Definition at line 660 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 in 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 587 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 536 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 in 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 673 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
ThrowsMedia::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 315 of file id3v2frame.cpp.

◆ setFlag()

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

Sets the flags.

Definition at line 195 of file id3v2frame.h.

◆ setGroup()

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

Sets the group information.

Definition at line 293 of file id3v2frame.h.

◆ supportsNestedFields()

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

Returns whether nested fields are supported.

Definition at line 309 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 227 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 219 of file id3v2frame.h.

◆ totalSize()

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

Returns the total size of the frame in bytes.

Definition at line 203 of file id3v2frame.h.

Friends And Related Function Documentation

◆ TagField< Id3v2Frame >

friend class TagField< Id3v2Frame >
friend

Definition at line 85 of file id3v2frame.h.


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