Tag Parser  6.2.1
C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
Public Member Functions | Static Public Member Functions | Protected Member Functions | Friends | List of all members
Media::Id3v2Frame Class Reference

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

#include <id3v2frame.h>

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

Public Member Functions

 Id3v2Frame ()
 Constructs a new Id3v2Frame. More...
 
 Id3v2Frame (const identifierType &id, const TagValue &value, const byte group=0, const int16 flag=0)
 Constructs a new Id3v2Frame with the specified id, value, group and flag. More...
 
void parse (IoUtilities::BinaryReader &reader, const uint32 version, const uint32 maximalSize=0)
 Parses a frame from the stream read using the specified reader. More...
 
Id3v2FrameMaker prepareMaking (const uint32 version)
 Prepares making. More...
 
void make (IoUtilities::BinaryWriter &writer, const uint32 version)
 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...
 
int32 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)
 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=false)
 Parses a substring in the specified buffer. More...
 
std::string parseString (const char *buffer, std::size_t maxSize, TagTextEncoding &encoding, bool addWarnings=false)
 Parses a substring in the specified buffer. More...
 
std::u16string parseWideString (const char *buffer, std::size_t dataSize, TagTextEncoding &encoding, bool addWarnings=false)
 Parses a substring in the specified buffer. More...
 
void parseLegacyPicture (const char *buffer, std::size_t maxSize, TagValue &tagValue, byte &typeInfo)
 Parses the ID3v2.2 picture from the specified buffer. More...
 
void parsePicture (const char *buffer, std::size_t maxSize, TagValue &tagValue, byte &typeInfo)
 Parses the ID3v2.3 picture from the specified buffer. More...
 
void parseComment (const char *buffer, std::size_t maxSize, TagValue &tagValue)
 Parses the comment/unsynchronized lyrics from the specified buffer. More...
 
void parseBom (const char *buffer, std::size_t maxSize, TagTextEncoding &encoding)
 Parses a byte order mark from the specified buffer. More...
 
byte makeTextEncodingByte (TagTextEncoding textEncoding)
 Returns a text encoding byte for the specified textEncoding. 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). More...
 
void makePicture (std::unique_ptr< char[]> &buffer, uint32 &bufferSize, const TagValue &picture, byte typeInfo)
 Writes the specified picture to the specified buffer (ID3v2.3). More...
 
void makeComment (std::unique_ptr< char[]> &buffer, uint32 &bufferSize, const TagValue &comment)
 Writes the specified comment to the specified buffer. More...
 
- Public Member Functions inherited from Media::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 and sets default flag to false. 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...
 
- Public Member Functions inherited from Media::StatusProvider
const NotificationListnotifications () const
 Returns notifications for the current object. More...
 
bool hasNotifications () const
 Returns an indication whether there are notifications for the current object. More...
 
bool hasCriticalNotifications () const
 Returns an indication whether there are critical notifications for the current object. More...
 
NotificationType worstNotificationType () const
 Returns the worst notification type. More...
 
const std::string & currentStatus () const
 Returns a status information for the current object. More...
 
double currentPercentage () const
 Returns the progress percentage of the current object. More...
 
size_t registerCallback (CallbackFunction callback)
 Registers a callback function. More...
 
void unregisterCallback (size_t id)
 Unregisters a previously registered callback function whith the specified id. More...
 
void unregisterAllCallbacks ()
 Unregisters all callback functions. More...
 
void forwardStatusUpdateCalls (StatusProvider *other=nullptr)
 Forwards all status updates calls to the specified statusProvider. More...
 
StatusProviderusedProvider ()
 Returns the provider which callback functions will be called when the status or the percentage is updated. More...
 
void tryToAbort ()
 Commands the object to abort the current operation. More...
 
bool isAborted () const
 Returns an indication whether the current operation should be aborted. More...
 
void invalidateStatus ()
 Invalidates the current status. More...
 
void invalidateNotifications ()
 Invalidates the object's notifications. More...
 
void updateStatus (const std::string &status)
 This method is meant to be called by the derived class to report updated status information. More...
 
void updateStatus (const std::string &status, double percentage)
 This method is meant to be called by the derived class to report updated status information. More...
 
void updatePercentage (double percentage)
 This method is meant to be called by the derived class to report updated progress percentage only. More...
 
void addNotification (const Notification &notification)
 This protected method is meant to be called by the derived class to add a notification. More...
 
void addNotification (NotificationType type, const std::string &message, const std::string &context)
 This protected method is meant to be called by the derived class to add a notification of the specified type, message and context. More...
 
void addNotifications (const StatusProvider &from)
 This protected method is meant to be called by the derived class to add all notifications from another StatusProvider instance. More...
 
void addNotifications (const std::string &higherContext, const StatusProvider &from)
 This protected method is meant to be called by the derived class to add all notifications from another StatusProvider instance. More...
 
void addNotifications (const NotificationList &notifications)
 This protected method is meant to be called by the derived class to add the specified notifications. 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...
 

Protected Member Functions

void cleared ()
 Ensures the field is cleared. More...
 
- Protected Member Functions inherited from Media::StatusProvider
 StatusProvider ()
 Constructs a new StatusProvider. More...
 

Friends

class TagField< Id3v2Frame >
 

Additional Inherited Members

- Public Types inherited from Media::TagField< Id3v2Frame >
typedef TagFieldTraits< Id3v2Frame >::implementationType implementationType
 
typedef TagFieldTraits< Id3v2Frame >::identifierType identifierType
 
typedef TagFieldTraits< Id3v2Frame >::typeInfoType typeInfoType
 
- Public Types inherited from Media::StatusProvider
typedef std::function< void(StatusProvider &sender)> CallbackFunction
 
typedef std::vector< CallbackFunctionCallbackVector
 
typedef std::pair< int, CallbackFunctionCallbackPair
 

Detailed Description

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

Definition at line 100 of file id3v2frame.h.

Constructor & Destructor Documentation

◆ Id3v2Frame() [1/2]

Media::Id3v2Frame::Id3v2Frame ( )

Constructs a new Id3v2Frame.

Definition at line 31 of file id3v2frame.cpp.

◆ Id3v2Frame() [2/2]

Media::Id3v2Frame::Id3v2Frame ( const identifierType id,
const TagValue value,
const byte  group = 0,
const int16  flag = 0 
)

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

Definition at line 43 of file id3v2frame.cpp.

Member Function Documentation

◆ cleared()

void Media::Id3v2Frame::cleared ( )
protected

Ensures the field is cleared.

Definition at line 339 of file id3v2frame.cpp.

◆ dataSize()

uint32 Media::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 Media::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 Media::Id3v2Frame::fieldIdToString ( identifierType  id)
inlinestatic

Returns the string representation for the specified id.

Definition at line 349 of file id3v2frame.h.

◆ flag()

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

Returns the flags.

Definition at line 204 of file id3v2frame.h.

◆ frameIdString()

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

Returns the frame ID as string.

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

Definition at line 196 of file id3v2frame.h.

◆ group()

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

Returns the group.

See also
hasGroupInformation()

Definition at line 302 of file id3v2frame.h.

◆ hasDataLengthIndicator()

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

Returns whether the frame has a data length indicator.

Definition at line 293 of file id3v2frame.h.

◆ hasGroupInformation()

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

Returns whether the frame contains group information.

Definition at line 277 of file id3v2frame.h.

◆ hasPaddingReached()

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

Returns whether the padding has reached.

Definition at line 187 of file id3v2frame.h.

◆ isAdditionalTypeInfoUsed()

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

Returns whether the instance uses the additional type info.

Definition at line 171 of file id3v2frame.h.

◆ isCompressed()

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

Returns whether the frame is compressed.

Definition at line 260 of file id3v2frame.h.

◆ isEncrypted()

bool Media::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 Media::Id3v2Frame::isReadOnly ( ) const
inline

Returns whether the frame is flagged as read-only.

Definition at line 252 of file id3v2frame.h.

◆ isUnsynchronized()

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

Returns whether the frame is unsynchronized.

Definition at line 285 of file id3v2frame.h.

◆ isValid()

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

Returns whether the frame is valid.

Definition at line 179 of file id3v2frame.h.

◆ make()

void Media::Id3v2Frame::make ( IoUtilities::BinaryWriter &  writer,
const uint32  version 
)

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 331 of file id3v2frame.cpp.

◆ makeComment()

void Media::Id3v2Frame::makeComment ( std::unique_ptr< char[]> &  buffer,
uint32 &  bufferSize,
const TagValue comment 
)

Writes the specified comment to the specified buffer.

Definition at line 929 of file id3v2frame.cpp.

◆ makeEncodingAndData()

void Media::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 822 of file id3v2frame.cpp.

◆ makeLegacyPicture()

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

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

Definition at line 850 of file id3v2frame.cpp.

◆ makePicture()

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

Writes the specified picture to the specified buffer (ID3v2.3).

Definition at line 893 of file id3v2frame.cpp.

◆ makeString()

void Media::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 809 of file id3v2frame.cpp.

◆ makeTextEncodingByte()

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

Returns a text encoding byte for the specified textEncoding.

Definition at line 554 of file id3v2frame.cpp.

◆ parse()

void Media::Id3v2Frame::parse ( IoUtilities::BinaryReader &  reader,
const uint32  version,
const uint32  maximalSize = 0 
)

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 109 of file id3v2frame.cpp.

◆ parseBom()

void Media::Id3v2Frame::parseBom ( const char *  buffer,
std::size_t  maxSize,
TagTextEncoding encoding 
)

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 693 of file id3v2frame.cpp.

◆ parseComment()

void Media::Id3v2Frame::parseComment ( const char *  buffer,
std::size_t  dataSize,
TagValue tagValue 
)

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 780 of file id3v2frame.cpp.

◆ parsedVersion()

int32 Media::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 Media::Id3v2Frame::parseLegacyPicture ( const char *  buffer,
std::size_t  maxSize,
TagValue tagValue,
byte &  typeInfo 
)

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 719 of file id3v2frame.cpp.

◆ parsePicture()

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

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 746 of file id3v2frame.cpp.

◆ parseString()

string Media::Id3v2Frame::parseString ( const char *  buffer,
std::size_t  maxSize,
TagTextEncoding encoding,
bool  addWarnings = false 
)

Parses a substring in the specified buffer.

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

Definition at line 650 of file id3v2frame.cpp.

◆ parseSubstring()

tuple< const char *, size_t, const char * > Media::Id3v2Frame::parseSubstring ( const char *  buffer,
std::size_t  bufferSize,
TagTextEncoding encoding,
bool  addWarnings = false 
)

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 to the status provider 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 UTF-16 encodings).

Definition at line 584 of file id3v2frame.cpp.

◆ parseTextEncodingByte()

TagTextEncoding Media::Id3v2Frame::parseTextEncodingByte ( byte  textEncodingByte)

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 534 of file id3v2frame.cpp.

◆ parseWideString()

u16string Media::Id3v2Frame::parseWideString ( const char *  buffer,
std::size_t  dataSize,
TagTextEncoding encoding,
bool  addWarnings = false 
)

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 663 of file id3v2frame.cpp.

◆ prepareMaking()

Id3v2FrameMaker Media::Id3v2Frame::prepareMaking ( const uint32  version)

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 318 of file id3v2frame.cpp.

◆ setFlag()

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

Sets the flags.

Definition at line 212 of file id3v2frame.h.

◆ setGroup()

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

Sets the group information.

Definition at line 310 of file id3v2frame.h.

◆ supportsNestedFields()

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

Returns whether nested fields are supported.

Definition at line 326 of file id3v2frame.h.

◆ toDiscardWhenUnknownAndFileIsAltered()

bool Media::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 Media::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 Media::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

◆ TagField< Id3v2Frame >

friend class TagField< Id3v2Frame >
friend

Definition at line 102 of file id3v2frame.h.


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