Tag Parser: TagParser::Id3v2Tag Class Reference

Tag Parser 12.5.3 C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags

Loading...
Searching...
No Matches
Public Member Functions | Static Public Attributes | Protected Member Functions | Friends | List of all members
TagParser::Id3v2Tag Class Referencefinal

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

## Static Public Attributes
static constexpr TagType | tagType = TagType::Id3v2Tag
static constexpr std::string_view | 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 std::uint32_t &id) const
void | internallyGetValuesFromField (const FieldType &field, std::vector< const TagValue * > &values) const
| Adds additional values as well.
bool | internallySetValues (const IdentifierType &id, const std::vector< TagValue > &values)
| Uses default implementation for non-text frames and applies special handling to text frames.
Protected Member Functions inherited from TagParser::FieldMapBasedTag< Id3v2Tag >
const TagValue & | internallyGetValue (const IdentifierType &id) const
| Default implementation for value().
void | internallyGetValuesFromField (const FieldType &field, std::vector< const TagValue * > &values) const
| Default way to gather values from a field in internallyGetValues().
std::vector< const TagValue * > | internallyGetValues (const IdentifierType &id) const
| Default implementation for values().
bool | internallySetValue (const IdentifierType &id, const TagValue &value)
| Default implementation for setValue().
bool | internallySetValues (const IdentifierType &id, const std::vector< TagValue > &values)
| Default implementation for setValues().
bool | internallyHasField (const IdentifierType &id) const
| Default implementation for hasField().
TagDataType | internallyGetProposedDataType (const IdentifierType &id) const
| Default implementation for proposedDataType().
Protected Member Functions inherited from TagParser::Tag
| Tag ()
| Constructs a new Tag.

## Friends
class | FieldMapBasedTag< Id3v2Tag >
class | Id3v2TagMaker

## Additional Inherited Members
Public Types inherited from TagParser::FieldMapBasedTag< Id3v2Tag >
using | FieldType
using | IdentifierType
using | Compare
Protected Types inherited from TagParser::FieldMapBasedTag< Id3v2Tag >
using | CRTPBase
Protected Attributes inherited from TagParser::Tag
std::string | m_version
std::uint64_t | m_size
std::unique_ptr< TagPrivate > | m_p
TagTarget | m_target

## Detailed Description

Implementation of TagParser::Tag for ID3v2 tags.

Definition at line 78 of file id3v2tag.h.

## Constructor & Destructor Documentation

## ◆ Id3v2Tag()

TagParser::Id3v2Tag::Id3v2Tag | ( |  | ) |
| inline

Constructs a new tag.

Definition at line 139 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 155 of file id3v2tag.h.

## ◆ ensureTextValuesAreProperlyEncoded()

void TagParser::Id3v2Tag::ensureTextValuesAreProperlyEncoded | ( |  | ) |
| overridevirtual

Ensures the encoding of all assigned text values is supported by the tag by converting the character set if necessary.

Reimplemented from TagParser::FieldMapBasedTag< Id3v2Tag >.

Definition at line 65 of file id3v2tag.cpp.

## ◆ extendedHeaderSize()

std::uint32_t TagParser::Id3v2Tag::extendedHeaderSize | ( |  | ) | const
| inline

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

Definition at line 264 of file id3v2tag.h.

## ◆ flags()

std::uint8_t TagParser::Id3v2Tag::flags | ( |  | ) | const
| inline

Returns the flags read from the ID3v2 header.

Definition at line 224 of file id3v2tag.h.

## ◆ handlingFlags()

Id3v2HandlingFlags TagParser::Id3v2Tag::handlingFlags | ( |  | ) | const
| inline

Returns flags influencing the behavior when parsing/making the ID3v2 tag.

Definition at line 181 of file id3v2tag.h.

## ◆ hasExtendedHeader()

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

Returns an indication whether an extended header is used.

Definition at line 240 of file id3v2tag.h.

## ◆ hasFooter()

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

Returns an indication whether a footer is present.

Definition at line 256 of file id3v2tag.h.

## ◆ internallyGetFieldId()

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

Definition at line 138 of file id3v2tag.cpp.

## ◆ internallyGetKnownField()

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

Definition at line 287 of file id3v2tag.cpp.

## ◆ internallyGetProposedDataType()

TagDataType TagParser::Id3v2Tag::internallyGetProposedDataType | ( | const std::uint32_t & | id | ) | const
| protected

Definition at line 435 of file id3v2tag.cpp.

## ◆ internallyGetValuesFromField()

void TagParser::Id3v2Tag::internallyGetValuesFromField | ( | const FieldType & | field,
|  | std::vector< const TagValue * > & | values ) const
| protected

Adds additional values as well.

Definition at line 78 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 96 of file id3v2tag.cpp.

## ◆ isExperimental()

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

Returns an indication whether the tag is labeled as experimental.

Definition at line 248 of file id3v2tag.h.

## ◆ isUnsynchronisationUsed()

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

Returns an indication whether unsynchronisation is used.

Definition at line 232 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 216 of file id3v2tag.h.

## ◆ majorVersion()

std::uint8_t TagParser::Id3v2Tag::majorVersion | ( |  | ) | const
| inline

Returns the major version if known; otherwise returns 0.

Definition at line 197 of file id3v2tag.h.

## ◆ make()

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

Writes tag information to the specified stream.

Exceptions

  Throws | std::ios_base::failure when an IO error occurs.
  Throws | TagParser::Failure or a derived exception when a making error occurs.

Definition at line 682 of file id3v2tag.cpp.

## ◆ paddingSize()

std::uint64_t 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 273 of file id3v2tag.h.

## ◆ parse()

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

Parses tag information from the specified stream.

Exceptions

  Throws | std::ios_base::failure when an IO error occurs.
  Throws | TagParser::Failure or a derived exception when a parsing error occurs.

Definition at line 550 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

  Throws | TagParser::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 670 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::FieldMapBasedTag< Id3v2Tag >.

Definition at line 150 of file id3v2tag.h.

## ◆ revisionVersion()

std::uint8_t TagParser::Id3v2Tag::revisionVersion | ( |  | ) | const
| inline

Returns the revision version if known; otherwise returns 0.

Definition at line 205 of file id3v2tag.h.

## ◆ setHandlingFlags()

void TagParser::Id3v2Tag::setHandlingFlags | ( | Id3v2HandlingFlags | flags | ) |
| inline

Sets flags influencing the behavior when parsing/making the ID3v2 tag.

Definition at line 189 of file id3v2tag.h.

## ◆ setVersion()

void TagParser::Id3v2Tag::setVersion | ( | std::uint8_t | majorVersion,
|  | std::uint8_t | revisionVersion )

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

Definition at line 691 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 161 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 173 of file id3v2tag.h.

## ◆ supportsMultipleValues() [1/2]

bool TagParser::Id3v2Tag::supportsMultipleValues | ( | IdentifierType | id | ) | const

Allows multiple values for some fields.

Remarks
  The standard defines no general rule applicable to all fields except that that all text allow multiple values as of ID3v2.4.0.

Definition at line 37 of file id3v2tag.cpp.

## ◆ supportsMultipleValues() [2/2]

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

Allows multiple values for some fields.

Reimplemented from TagParser::Tag.

Definition at line 26 of file id3v2tag.cpp.

## Friends And Related Symbol Documentation

## ◆ FieldMapBasedTag< Id3v2Tag >

friend class FieldMapBasedTag< Id3v2Tag >
| friend

Definition at line 49 of file id3v2tag.h.

## ◆ Id3v2TagMaker

friend class Id3v2TagMaker
| friend

Definition at line 80 of file id3v2tag.h.

## Member Data Documentation

## ◆ defaultTextEncoding

TagTextEncoding TagParser::Id3v2Tag::defaultTextEncoding = TagTextEncoding::Utf16LittleEndian
| staticconstexpr

Definition at line 87 of file id3v2tag.h.

## ◆ tagName

std::string_view TagParser::Id3v2Tag::tagName = "ID3v2 tag"
| staticconstexpr

Definition at line 86 of file id3v2tag.h.

## ◆ tagType

TagType TagParser::Id3v2Tag::tagType = TagType::Id3v2Tag
| staticconstexpr

Definition at line 85 of file id3v2tag.h.

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

- id3/id3v2tag.h
- id3/id3v2tag.cpp