Tag Parser
6.2.2
C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
|
The Id3v2Frame class is used by Id3v2Tag to store the fields. More...
#include <id3v2frame.h>
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... | |
![]() | |
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 identifierType & | id () 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... | |
TagValue & | value () |
Returns the value of the current TagField. More... | |
const TagValue & | value () 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 typeInfoType & | typeInfo () 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... | |
![]() | |
const NotificationList & | notifications () 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... | |
StatusProvider * | usedProvider () |
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 ¬ification) |
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 ¬ifications) |
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... | |
![]() | |
StatusProvider () | |
Constructs a new StatusProvider. More... | |
Friends | |
class | TagField< Id3v2Frame > |
class | Id3v2FrameMaker |
Additional Inherited Members | |
![]() | |
typedef TagFieldTraits< Id3v2Frame >::implementationType | implementationType |
typedef TagFieldTraits< Id3v2Frame >::identifierType | identifierType |
typedef TagFieldTraits< Id3v2Frame >::typeInfoType | typeInfoType |
![]() | |
typedef std::function< void(StatusProvider &sender)> | CallbackFunction |
typedef std::vector< CallbackFunction > | CallbackVector |
typedef std::pair< int, CallbackFunction > | CallbackPair |
The Id3v2Frame class is used by Id3v2Tag to store the fields.
Definition at line 100 of file id3v2frame.h.
Media::Id3v2Frame::Id3v2Frame | ( | ) |
Constructs a new Id3v2Frame.
Definition at line 41 of file id3v2frame.cpp.
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 53 of file id3v2frame.cpp.
|
protected |
Ensures the field is cleared.
Definition at line 349 of file id3v2frame.cpp.
|
inline |
Returns the size of the data stored in the frame in bytes.
Definition at line 233 of file id3v2frame.h.
|
inlinestatic |
Converts the specified ID string representation to an actual ID.
Definition at line 339 of file id3v2frame.h.
|
inlinestatic |
Returns the string representation for the specified id.
Definition at line 354 of file id3v2frame.h.
|
inline |
Returns the flags.
Definition at line 209 of file id3v2frame.h.
|
inline |
Returns the frame ID as string.
Definition at line 201 of file id3v2frame.h.
|
inline |
|
inline |
Returns whether the frame has a data length indicator.
Definition at line 298 of file id3v2frame.h.
|
inline |
Returns whether the frame contains group information.
Definition at line 282 of file id3v2frame.h.
|
inline |
Returns whether the padding has reached.
Definition at line 192 of file id3v2frame.h.
|
inline |
Returns whether the instance uses the additional type info.
Definition at line 176 of file id3v2frame.h.
|
inline |
Returns whether the frame is compressed.
Definition at line 265 of file id3v2frame.h.
|
inline |
Returns whether the frame is encrypted.
Definition at line 274 of file id3v2frame.h.
|
inline |
Returns whether the frame is flagged as read-only.
Definition at line 257 of file id3v2frame.h.
|
inline |
Returns whether the frame is unsynchronized.
Definition at line 290 of file id3v2frame.h.
|
inline |
Returns whether the frame is valid.
Definition at line 184 of file id3v2frame.h.
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.
Throws | std::ios_base::failure when an IO error occurs. |
Throws | Media::Failure or a derived exception when a making error occurs. |
Definition at line 341 of file id3v2frame.cpp.
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 997 of file id3v2frame.cpp.
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.
buffer | Specifies the buffer. |
bufferSize | Specifies the size of buffer. |
encoding | Specifies the data encoding. |
data | Specifies the data. |
dataSize | Specifies size of data. |
Definition at line 836 of file id3v2frame.cpp.
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 887 of file id3v2frame.cpp.
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 945 of file id3v2frame.cpp.
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.
buffer | Specifies the buffer. |
bufferSize | Specifies the size of buffer. |
value | Specifies the string to make. |
encoding | Specifies the encoding of the string to make. |
Definition at line 823 of file id3v2frame.cpp.
byte Media::Id3v2Frame::makeTextEncodingByte | ( | TagTextEncoding | textEncoding | ) |
Returns a text encoding byte for the specified textEncoding.
Definition at line 568 of file id3v2frame.cpp.
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.
Throws | std::ios_base::failure when an IO error occurs. |
Throws | Media::Failure or a derived exception when a parsing error occurs. |
Definition at line 119 of file id3v2frame.cpp.
void Media::Id3v2Frame::parseBom | ( | const char * | buffer, |
std::size_t | maxSize, | ||
TagTextEncoding & | encoding | ||
) |
Parses a byte order mark from the specified buffer.
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. |
Definition at line 708 of file id3v2frame.cpp.
void Media::Id3v2Frame::parseComment | ( | const char * | buffer, |
std::size_t | dataSize, | ||
TagValue & | tagValue | ||
) |
Parses the comment/unsynchronized lyrics from the specified buffer.
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 794 of file id3v2frame.cpp.
|
inline |
Returns the version of the frame (read when parsing the frame).
Definition at line 323 of file id3v2frame.h.
void Media::Id3v2Frame::parseLegacyPicture | ( | const char * | buffer, |
std::size_t | maxSize, | ||
TagValue & | tagValue, | ||
byte & | typeInfo | ||
) |
Parses the ID3v2.2 picture from the specified buffer.
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 734 of file id3v2frame.cpp.
void Media::Id3v2Frame::parsePicture | ( | const char * | buffer, |
std::size_t | maxSize, | ||
TagValue & | tagValue, | ||
byte & | typeInfo | ||
) |
Parses the ID3v2.3 picture from the specified buffer.
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 760 of file id3v2frame.cpp.
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 665 of file id3v2frame.cpp.
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.
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 to the status provider if the string is not terminated. |
Definition at line 598 of file id3v2frame.cpp.
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 548 of file id3v2frame.cpp.
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
Definition at line 678 of file id3v2frame.cpp.
Id3v2FrameMaker Media::Id3v2Frame::prepareMaking | ( | const uint32 | version | ) |
Prepares making.
Throws | Media::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 328 of file id3v2frame.cpp.
|
inline |
Sets the flags.
Definition at line 217 of file id3v2frame.h.
|
inline |
Sets the group information.
Definition at line 315 of file id3v2frame.h.
|
inline |
Returns whether nested fields are supported.
Definition at line 331 of file id3v2frame.h.
|
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 249 of file id3v2frame.h.
|
inline |
Returns whether the frame is flaged to be discarded when it is unknown and the tag is altered.
Definition at line 241 of file id3v2frame.h.
|
inline |
Returns the total size of the frame in bytes.
Definition at line 225 of file id3v2frame.h.
|
friend |
Definition at line 103 of file id3v2frame.h.
|
friend |
Definition at line 102 of file id3v2frame.h.