Tag Parser
6.5.0
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... | |
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) |
Writes the specified picture to the specified buffer (ID3v2.3 compatible). More... | |
void | makePictureConsideringVersion (std::unique_ptr< char[]> &buffer, uint32 &bufferSize, const TagValue &picture, byte typeInfo, byte version) |
Writes the specified picture to the specified buffer. More... | |
void | makeCommentConsideringVersion (std::unique_ptr< char[]> &buffer, uint32 &bufferSize, const TagValue &comment, byte version) |
Writes the specified comment to the specified buffer. 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 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 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 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 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 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 > |
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 346 of file id3v2frame.cpp.
|
inline |
Returns the size of the data stored in the frame in bytes.
Definition at line 231 of file id3v2frame.h.
|
inlinestatic |
Converts the specified ID string representation to an actual ID.
Definition at line 337 of file id3v2frame.h.
|
inlinestatic |
Returns the string representation for the specified id.
Definition at line 352 of file id3v2frame.h.
|
inline |
Returns the flags.
Definition at line 207 of file id3v2frame.h.
|
inline |
Returns the frame ID as string.
Definition at line 199 of file id3v2frame.h.
|
inline |
|
inline |
Returns whether the frame has a data length indicator.
Definition at line 296 of file id3v2frame.h.
|
inline |
Returns whether the frame contains group information.
Definition at line 280 of file id3v2frame.h.
|
inline |
Returns whether the padding has reached.
Definition at line 190 of file id3v2frame.h.
|
inline |
Returns whether the instance uses the additional type info.
Definition at line 174 of file id3v2frame.h.
|
inline |
Returns whether the frame is compressed.
Definition at line 263 of file id3v2frame.h.
|
inline |
Returns whether the frame is encrypted.
Definition at line 272 of file id3v2frame.h.
|
inline |
Returns whether the frame is flagged as read-only.
Definition at line 255 of file id3v2frame.h.
|
inline |
Returns whether the frame is unsynchronized.
Definition at line 288 of file id3v2frame.h.
|
inline |
Returns whether the frame is valid.
Definition at line 182 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 338 of file id3v2frame.cpp.
size_t Media::Id3v2Frame::makeBom | ( | char * | buffer, |
TagTextEncoding | encoding | ||
) |
Writes the BOM for the specified encoding to the specified buffer.
Definition at line 854 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 990 of file id3v2frame.cpp.
void Media::Id3v2Frame::makeCommentConsideringVersion | ( | std::unique_ptr< char[]> & | buffer, |
uint32 & | bufferSize, | ||
const TagValue & | comment, | ||
byte | version | ||
) |
Writes the specified comment to the specified buffer.
Definition at line 998 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 816 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 compatible).
Definition at line 871 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 compatible).
Definition at line 927 of file id3v2frame.cpp.
void Media::Id3v2Frame::makePictureConsideringVersion | ( | 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 935 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 803 of file id3v2frame.cpp.
byte Media::Id3v2Frame::makeTextEncodingByte | ( | TagTextEncoding | textEncoding | ) |
Returns a text encoding byte for the specified textEncoding.
Definition at line 561 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 116 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 688 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 774 of file id3v2frame.cpp.
|
inline |
Returns the version of the frame (read when parsing the frame).
Definition at line 321 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 714 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 740 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 658 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 591 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 541 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 671 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 325 of file id3v2frame.cpp.
|
inline |
Sets the flags.
Definition at line 215 of file id3v2frame.h.
|
inline |
Sets the group information.
Definition at line 313 of file id3v2frame.h.
|
inline |
Returns whether nested fields are supported.
Definition at line 329 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 247 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 239 of file id3v2frame.h.
|
inline |
Returns the total size of the frame in bytes.
Definition at line 223 of file id3v2frame.h.
|
friend |
Definition at line 102 of file id3v2frame.h.