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

Implementation of TagParser::Tag for ID3v2 tags. More...

#include <id3v2tag.h>

Inheritance diagram for TagParser::Id3v2Tag:
[legend]
Collaboration diagram for TagParser::Id3v2Tag:
[legend]

Public Member Functions

 Id3v2Tag ()
 Constructs a new tag. More...
 
TagTextEncoding proposedTextEncoding () const override
 Returns the proposed text encoding. More...
 
bool canEncodingBeUsed (TagTextEncoding encoding) const override
 Returns an indication whether the specified encoding can be used to provide string values for the tag. More...
 
bool supportsDescription (KnownField field) const override
 Returns an indications whether the specified field supports descriptions. More...
 
bool supportsMimeType (KnownField field) const override
 Returns an indications whether the specified field supports mime types. More...
 
bool supportsMultipleValues (KnownField field) const override
 Allows multiple values for some fields. More...
 
void parse (std::istream &sourceStream, const uint64 maximalSize, Diagnostics &diag)
 Parses tag information from the specified stream. More...
 
Id3v2TagMaker prepareMaking (Diagnostics &diag)
 Prepares making. More...
 
void make (std::ostream &targetStream, uint32 padding, Diagnostics &diag)
 Writes tag information to the specified stream. More...
 
byte majorVersion () const
 Returns the major version if known; otherwise returns 0. More...
 
byte revisionVersion () const
 Returns the revision version if known; otherwise returns 0. More...
 
void setVersion (byte majorVersion, byte revisionVersion)
 Sets the version to the specified majorVersion and the specified revisionVersion. More...
 
bool isVersionSupported () const
 Returns an indication whether the version is supported by the Id3v2Tag class. More...
 
byte flags () const
 Returns the flags read from the ID3v2 header. More...
 
bool isUnsynchronisationUsed () const
 Returns an indication whether unsynchronisation is used. More...
 
bool hasExtendedHeader () const
 Returns an indication whether an extended header is used. More...
 
bool isExperimental () const
 Returns an indication whether the tag is labeled as experimental. More...
 
bool hasFooter () const
 Returns an indication whether a footer is present. More...
 
uint32 extendedHeaderSize () const
 Returns the size of the extended header if one is present; otherwise returns 0. More...
 
uint32 paddingSize () const
 Returns the size of the padding between the tag and the first MPEG frame if one is present; otherwise returns 0. More...
 
- Public Member Functions inherited from TagParser::FieldMapBasedTag< Id3v2Tag >
 FieldMapBasedTag ()
 Constructs a new FieldMapBasedTag. More...
 
TagType type () const
 Returns the type of the tag as TagParser::TagType. More...
 
const char * typeName () const
 Returns the type name of the tag as C-style string. More...
 
TagTextEncoding proposedTextEncoding () const
 Returns the proposed text encoding. More...
 
const TagValuevalue (const IdentifierType &id) const
 Returns the value of the field with the specified id. More...
 
const TagValuevalue (KnownField field) const
 Returns the value of the specified field. More...
 
std::vector< const TagValue *> values (const IdentifierType &id) const
 Returns the values of the field with the specified id. More...
 
std::vector< const TagValue *> values (KnownField field) const
 Returns the values of the specified field. More...
 
bool setValue (const IdentifierType &id, const TagValue &value)
 Assigns the given value to the field with the specified id. More...
 
bool setValue (KnownField field, const TagValue &value)
 Assigns the given value to the specified field. More...
 
bool setValues (const IdentifierType &id, const std::vector< TagValue > &values)
 Assigns the given values to the field with the specified id. More...
 
bool setValues (KnownField field, const std::vector< TagValue > &values)
 Assigns the given values to the field with the specified id. More...
 
bool hasField (KnownField field) const
 Returns an indication whether the specified field is present. More...
 
bool hasField (const IdentifierType &id) const
 Returns an indication whether the field with the specified id is present. More...
 
void removeAllFields ()
 Removes all fields from the tag. More...
 
const std::multimap< IdentifierType, FieldType, Compare > & fields () const
 Returns the fields of the tag by providing direct access to the field map of the tag. More...
 
std::multimap< IdentifierType, FieldType, Compare > & fields ()
 Returns the fields of the tag by providing direct access to the field map of the tag. More...
 
unsigned int fieldCount () const
 Returns the number of present fields. More...
 
IdentifierType fieldId (KnownField value) const
 Returns the ID for the specified field. More...
 
KnownField knownField (const IdentifierType &id) const
 Returns the field for the specified ID. More...
 
bool supportsField (KnownField field) const
 Returns an indication whether the specified field is supported by the tag. More...
 
TagDataType proposedDataType (const IdentifierType &id) const
 Returns the proposed data type for the field with the specified id. More...
 
virtual TagDataType proposedDataType (KnownField field) const
 Returns the proposed data type for the specified field as TagDataType. More...
 
int insertFields (const FieldMapBasedTag< Id3v2Tag > &from, bool overwrite)
 Inserts all fields from another tag of the same field type and compare function. More...
 
unsigned int insertValues (const Tag &from, bool overwrite)
 Inserts all compatible values from another Tag. More...
 
void ensureTextValuesAreProperlyEncoded ()
 Ensures the encoding of all assigned text values is supported by the tag by converting the character set if neccessary. More...
 
- Public Member Functions inherited from TagParser::Tag
virtual ~Tag ()
 Destroys the Tag. More...
 
std::string toString () const
 Returns a string representation of the tag. More...
 
const std::string & version () const
 Returns the version of the tag as std::string. More...
 
uint32 size () const
 Returns the size of the tag in bytes. More...
 
virtual bool supportsTarget () const
 Returns an indication whether a target is supported by the tag. More...
 
const TagTargettarget () const
 Returns the target of tag. More...
 
void setTarget (const TagTarget &target)
 Sets the target of tag. More...
 
virtual TagTargetLevel targetLevel () const
 Returns the name of the current tag target level. More...
 
const char * targetLevelName () const
 Returns the name of the current target level. More...
 
bool isTargetingLevel (TagTargetLevel tagTargetLevel) const
 Returns whether the tag is targeting the specified tagTargetLevel. More...
 
std::string targetString () const
 Returns the string representation for the assigned tag target. More...
 
virtual TagDataType proposedDataType (KnownField field) const
 Returns the proposed data type for the specified field as TagDataType. More...
 

Static Public Attributes

static constexpr TagType tagType = TagType::Id3v2Tag
 
static constexpr const char * tagName = "ID3v2 tag"
 
static constexpr TagTextEncoding defaultTextEncoding = TagTextEncoding::Utf16LittleEndian
 

Protected Member Functions

IdentifierType internallyGetFieldId (KnownField field) const
 
KnownField internallyGetKnownField (const IdentifierType &id) const
 
TagDataType internallyGetProposedDataType (const uint32 &id) const
 
std::vector< const TagValue * > internallyGetValues (const IdentifierType &id) const
 Works like the default implementation but adds additional values as well. More...
 
bool internallySetValues (const IdentifierType &id, const std::vector< TagValue > &values)
 Uses default implementation for non-text frames and applies special handling to text frames. More...
 
- Protected Member Functions inherited from TagParser::FieldMapBasedTag< Id3v2Tag >
const TagValueinternallyGetValue (const IdentifierType &id) const
 Default implementation for value(). More...
 
std::vector< const TagValue *> internallyGetValues (const IdentifierType &id) const
 Default implementation for values(). More...
 
bool internallySetValue (const IdentifierType &id, const TagValue &value)
 Default implementation for setValue(). More...
 
bool internallySetValues (const IdentifierType &id, const std::vector< TagValue > &values)
 Default implementation for setValues(). More...
 
bool internallyHasField (const IdentifierType &id) const
 Default implementation for hasField(). More...
 
TagDataType internallyGetProposedDataType (const IdentifierType &id) const
 Default implementation for proposedDataType(). More...
 
- Protected Member Functions inherited from TagParser::Tag
 Tag ()
 Constructs a new Tag. More...
 

Friends

class FieldMapBasedTag< Id3v2Tag >
 

Additional Inherited Members

- Public Types inherited from TagParser::FieldMapBasedTag< Id3v2Tag >
using FieldType = typename FieldMapBasedTagTraits< Id3v2Tag >::FieldType
 
using IdentifierType = typename FieldMapBasedTagTraits< Id3v2Tag >::FieldType::IdentifierType
 
using Compare = typename FieldMapBasedTagTraits< Id3v2Tag >::Compare
 
- Protected Types inherited from TagParser::FieldMapBasedTag< Id3v2Tag >
using CRTPBase = FieldMapBasedTag< Id3v2Tag >
 
- Protected Attributes inherited from TagParser::Tag
std::string m_version
 
uint32 m_size
 
TagTarget m_target
 

Detailed Description

Implementation of TagParser::Tag for ID3v2 tags.

Definition at line 61 of file id3v2tag.h.

Constructor & Destructor Documentation

◆ Id3v2Tag()

TagParser::Id3v2Tag::Id3v2Tag ( )
inline

Constructs a new tag.

Definition at line 111 of file id3v2tag.h.

Member Function Documentation

◆ canEncodingBeUsed()

bool TagParser::Id3v2Tag::canEncodingBeUsed ( TagTextEncoding  encoding) const
inlineoverridevirtual

Returns an indication whether the specified encoding can be used to provide string values for the tag.

Only the proposedTextEncoding() is accepted by default. This might be overwritten when subclassing.

The tag class and its subclasses do not perform any conversions. You have to provide all string values using an encoding which is appropriate for the specific tag type. This method is meant to determine if a particular encoding can be used.

See also
canEncodingBeUsed()

Reimplemented from TagParser::Tag.

Definition at line 126 of file id3v2tag.h.

◆ extendedHeaderSize()

uint32 TagParser::Id3v2Tag::extendedHeaderSize ( ) const
inline

Returns the size of the extended header if one is present; otherwise returns 0.

Definition at line 219 of file id3v2tag.h.

◆ flags()

byte TagParser::Id3v2Tag::flags ( ) const
inline

Returns the flags read from the ID3v2 header.

Definition at line 179 of file id3v2tag.h.

◆ hasExtendedHeader()

bool TagParser::Id3v2Tag::hasExtendedHeader ( ) const
inline

Returns an indication whether an extended header is used.

Definition at line 195 of file id3v2tag.h.

◆ hasFooter()

bool TagParser::Id3v2Tag::hasFooter ( ) const
inline

Returns an indication whether a footer is present.

Definition at line 211 of file id3v2tag.h.

◆ internallyGetFieldId()

Id3v2Tag::IdentifierType TagParser::Id3v2Tag::internallyGetFieldId ( KnownField  field) const
protected

Definition at line 127 of file id3v2tag.cpp.

◆ internallyGetKnownField()

KnownField TagParser::Id3v2Tag::internallyGetKnownField ( const IdentifierType id) const
protected

Definition at line 230 of file id3v2tag.cpp.

◆ internallyGetProposedDataType()

TagDataType TagParser::Id3v2Tag::internallyGetProposedDataType ( const uint32 &  id) const
protected

Definition at line 317 of file id3v2tag.cpp.

◆ internallyGetValues()

std::vector< const TagValue * > TagParser::Id3v2Tag::internallyGetValues ( const IdentifierType id) const
protected

Works like the default implementation but adds additional values as well.

Definition at line 63 of file id3v2tag.cpp.

◆ internallySetValues()

bool TagParser::Id3v2Tag::internallySetValues ( const IdentifierType id,
const std::vector< TagValue > &  values 
)
protected

Uses default implementation for non-text frames and applies special handling to text frames.

  • Ensure text frames are unique
  • Allow to store multiple values inside the same text frame.

Definition at line 85 of file id3v2tag.cpp.

◆ isExperimental()

bool TagParser::Id3v2Tag::isExperimental ( ) const
inline

Returns an indication whether the tag is labeled as experimental.

Definition at line 203 of file id3v2tag.h.

◆ isUnsynchronisationUsed()

bool TagParser::Id3v2Tag::isUnsynchronisationUsed ( ) const
inline

Returns an indication whether unsynchronisation is used.

Definition at line 187 of file id3v2tag.h.

◆ isVersionSupported()

bool TagParser::Id3v2Tag::isVersionSupported ( ) const
inline

Returns an indication whether the version is supported by the Id3v2Tag class.

Major versions 2, 3 and 4 are currently supported.

Definition at line 171 of file id3v2tag.h.

◆ majorVersion()

byte TagParser::Id3v2Tag::majorVersion ( ) const
inline

Returns the major version if known; otherwise returns 0.

Definition at line 152 of file id3v2tag.h.

◆ make()

void TagParser::Id3v2Tag::make ( std::ostream &  targetStream,
uint32  padding,
Diagnostics diag 
)

Writes tag information to the specified stream.

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

Definition at line 478 of file id3v2tag.cpp.

◆ paddingSize()

uint32 TagParser::Id3v2Tag::paddingSize ( ) const
inline

Returns the size of the padding between the tag and the first MPEG frame if one is present; otherwise returns 0.

Definition at line 228 of file id3v2tag.h.

◆ parse()

void TagParser::Id3v2Tag::parse ( std::istream &  sourceStream,
const uint64  maximalSize,
Diagnostics diag 
)

Parses tag information from the specified stream.

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

Definition at line 350 of file id3v2tag.cpp.

◆ prepareMaking()

Id3v2TagMaker TagParser::Id3v2Tag::prepareMaking ( Diagnostics diag)

Prepares making.

Returns
Returns a Id3v2TagMaker object which can be used to actually make the tag.
Remarks
The tag must NOT be mutated after making is prepared when it is intended to actually make the tag 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 tag before making it.

See also
make()

Definition at line 466 of file id3v2tag.cpp.

◆ proposedTextEncoding()

TagTextEncoding TagParser::Id3v2Tag::proposedTextEncoding ( ) const
inlineoverridevirtual

Returns the proposed text encoding.

This is TagTextEncoding::Latin1 by default an might be overwritten when subclassing.

The tag class and its subclasses do not perform any conversions. You have to provide all string values using an encoding which is appropriate for the specific tag type. This method returns such an encoding.

See also
canEncodingBeUsed()

Reimplemented from TagParser::Tag.

Definition at line 121 of file id3v2tag.h.

◆ revisionVersion()

byte TagParser::Id3v2Tag::revisionVersion ( ) const
inline

Returns the revision version if known; otherwise returns 0.

Definition at line 160 of file id3v2tag.h.

◆ setVersion()

void TagParser::Id3v2Tag::setVersion ( byte  majorVersion,
byte  revisionVersion 
)

Sets the version to the specified majorVersion and the specified revisionVersion.

Definition at line 487 of file id3v2tag.cpp.

◆ supportsDescription()

bool TagParser::Id3v2Tag::supportsDescription ( KnownField  field) const
inlineoverridevirtual

Returns an indications whether the specified field supports descriptions.

Remarks
  • If you assign a description to a field value and the field does not support descriptions the description is ignored when saving the tag.
  • The default implementation returns false for all fields. This might be overwritten when subclassing.

Reimplemented from TagParser::Tag.

Definition at line 132 of file id3v2tag.h.

◆ supportsMimeType()

bool TagParser::Id3v2Tag::supportsMimeType ( KnownField  field) const
inlineoverridevirtual

Returns an indications whether the specified field supports mime types.

Remarks
  • If you assign a mime types to a field value and the field does not support mime types the mime type is ignored when saving the tag.
  • The default implementation returns false for all fields. This might be overwritten when subclassing.

Reimplemented from TagParser::Tag.

Definition at line 144 of file id3v2tag.h.

◆ supportsMultipleValues()

bool TagParser::Id3v2Tag::supportsMultipleValues ( KnownField  field) const
overridevirtual

Allows multiple values for some fields.

Remarks
The standard defines no general rule applicable to all fields.

Reimplemented from TagParser::Tag.

Definition at line 27 of file id3v2tag.cpp.

Friends And Related Function Documentation

◆ FieldMapBasedTag< Id3v2Tag >

friend class FieldMapBasedTag< Id3v2Tag >
friend

Definition at line 62 of file id3v2tag.h.

Member Data Documentation

◆ defaultTextEncoding

constexpr TagTextEncoding TagParser::Id3v2Tag::defaultTextEncoding = TagTextEncoding::Utf16LittleEndian
static

Definition at line 69 of file id3v2tag.h.

◆ tagName

constexpr const char* TagParser::Id3v2Tag::tagName = "ID3v2 tag"
static

Definition at line 68 of file id3v2tag.h.

◆ tagType

constexpr TagType TagParser::Id3v2Tag::tagType = TagType::Id3v2Tag
static

Definition at line 67 of file id3v2tag.h.


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