Tag Parser: TagParser::Tag 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 | Protected Member Functions | Protected Attributes | List of all members
TagParser::Tag Class Referenceabstract

The Tag class is used to store, read and write tag information. More...

`#include <tag.h>`

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

## Public Member Functions
virtual | ~Tag ()
| Destroys the Tag.
virtual TagType | type () const
| Returns the type of the tag as TagParser::TagType.
virtual std::string_view | typeName () const
| Returns the type name of the tag.
std::string | toString () const
| Returns a string representation of the tag.
virtual TagTextEncoding | proposedTextEncoding () const
| Returns the proposed text encoding.
virtual bool | canEncodingBeUsed (TagTextEncoding encoding) const
| Returns an indication whether the specified encoding can be used to provide string values for 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.
virtual bool | hasField (KnownField field) const =0
| Returns an indication whether the specified field is present.
virtual void | removeAllFields ()=0
| Removes all fields from the tag.
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.
virtual std::size_t | fieldCount () const =0
| Returns the number of present fields.
virtual bool | supportsField (KnownField field) const =0
| Returns an indication whether the specified field is supported by the tag.
virtual TagDataType | proposedDataType (KnownField field) const
| Returns the proposed data type for the specified field as TagDataType.
virtual bool | supportsDescription (KnownField field) const
| Returns an indications whether the specified field supports descriptions.
virtual bool | supportsMimeType (KnownField field) const
| Returns an indications whether the specified field supports mime types.
virtual bool | supportsMultipleValues (KnownField field) const
| Returns an indications whether the specified field supports multiple values.
virtual std::size_t | insertValues (const Tag &from, bool overwrite)
| Inserts all compatible values from another Tag.
virtual void | ensureTextValuesAreProperlyEncoded ()=0
| Ensures the encoding of all assigned text values is supported by the tag by converting the character set if necessary.

## Protected Member Functions
| Tag ()
| Constructs a new Tag.

## Protected Attributes
std::string | m_version
std::uint64_t | m_size
std::unique_ptr< TagPrivate > | m_p
TagTarget | m_target

## Detailed Description

The Tag class is used to store, read and write tag information.

The Tag class only provides the interface and common functionality. It is meant to be subclassed.This interface does not include parse/make methods to read/write a tag from/to a stream because the availability and signature of these methods may differ between the individual implementations (eg. an Mp4Tag is read from the "meta" Mp4Atom).

Definition at line 179 of file tag.h.

## Constructor & Destructor Documentation

## ◆ ~Tag()

TagParser::Tag::~Tag | ( |  | ) |
| virtual

Destroys the Tag.

Definition at line 32 of file tag.cpp.

## ◆ Tag()

TagParser::Tag::Tag | ( |  | ) |
| protected

Constructs a new Tag.

Definition at line 24 of file tag.cpp.

## Member Function Documentation

## ◆ canEncodingBeUsed()

bool TagParser::Tag::canEncodingBeUsed | ( | TagTextEncoding | encoding | ) | const
| inlinevirtual

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 in TagParser::Id3v1Tag, TagParser::Id3v2Tag, TagParser::MatroskaTag, TagParser::Mp4Tag, and TagParser::VorbisComment.

Definition at line 237 of file tag.h.

## ◆ ensureTextValuesAreProperlyEncoded()

virtual void TagParser::Tag::ensureTextValuesAreProperlyEncoded | ( |  | ) |
| pure virtual

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

Implemented in TagParser::FieldMapBasedTag< ImplementationType >, TagParser::FieldMapBasedTag< Id3v2Tag >, TagParser::FieldMapBasedTag< MatroskaTag >, TagParser::FieldMapBasedTag< Mp4Tag >, TagParser::FieldMapBasedTag< VorbisComment >, TagParser::Id3v1Tag, and TagParser::Id3v2Tag.

## ◆ fieldCount()

virtual std::size_t TagParser::Tag::fieldCount | ( |  | ) | const
| pure virtual

Returns the number of present fields.

Implemented in TagParser::FieldMapBasedTag< ImplementationType >, TagParser::FieldMapBasedTag< Id3v2Tag >, TagParser::FieldMapBasedTag< MatroskaTag >, TagParser::FieldMapBasedTag< Mp4Tag >, TagParser::FieldMapBasedTag< VorbisComment >, and TagParser::Id3v1Tag.

## ◆ hasField()

virtual bool TagParser::Tag::hasField | ( | KnownField | field | ) | const
| pure virtual

Returns an indication whether the specified field is present.

See also
  value(), setValue()

Implemented in TagParser::FieldMapBasedTag< ImplementationType >, TagParser::FieldMapBasedTag< Id3v2Tag >, TagParser::FieldMapBasedTag< MatroskaTag >, TagParser::FieldMapBasedTag< Mp4Tag >, TagParser::FieldMapBasedTag< VorbisComment >, TagParser::Id3v1Tag, and TagParser::Mp4Tag.

## ◆ insertValues()

std::size_t TagParser::Tag::insertValues | ( | const Tag & | from,
|  | bool | overwrite )
| virtual

Inserts all compatible values from another Tag.

Parameters

  from | Specifies the Tag the values should be inserted from.
  overwrite | Indicates whether existing values should be overwritten.

Returns
  Returns the number of values that have been inserted.

Remarks
  The encoding of the inserted text values might not be supported by the tag. To fix this, call ensureTextValuesAreProperlyEncoded() after insertion.

Reimplemented in TagParser::FieldMapBasedTag< ImplementationType >, TagParser::FieldMapBasedTag< Id3v2Tag >, TagParser::FieldMapBasedTag< MatroskaTag >, TagParser::FieldMapBasedTag< Mp4Tag >, and TagParser::FieldMapBasedTag< VorbisComment >.

Definition at line 89 of file tag.cpp.

## ◆ isTargetingLevel()

bool TagParser::Tag::isTargetingLevel | ( | TagTargetLevel | tagTargetLevel | ) | const
| inline

Returns whether the tag is targeting the specified tagTargetLevel.

Remarks
  If targets are not supported by the tag it is considered targeting everything and hence this method returns always true in this case.

Definition at line 282 of file tag.h.

## ◆ proposedDataType()

TagDataType TagParser::Tag::proposedDataType | ( | KnownField | field | ) | const
| inlinevirtual

Returns the proposed data type for the specified field as TagDataType.

Most values need to be provided as string (see proposedTextEncoding() and canEncodingBeUsed()). Other values need to be provided as integer or an other TagDataType. This method helps to determine which type is required for a particular field.

Remarks
  - The tag class and its subclasses try to convert the provided values. So using exactly the proposed type is not neccassary. Nevertheless it can help to detect conversion errors early. A GUI application could use this method to determine which widget should be used.
  - The default implementation returns a data type which is most commonly used for the specified field. The default implementation might be overwritten when subclassing.

Reimplemented in TagParser::FieldMapBasedTag< ImplementationType >, TagParser::FieldMapBasedTag< Id3v2Tag >, TagParser::FieldMapBasedTag< MatroskaTag >, TagParser::FieldMapBasedTag< Mp4Tag >, and TagParser::FieldMapBasedTag< VorbisComment >.

Definition at line 292 of file tag.h.

## ◆ proposedTextEncoding()

TagTextEncoding TagParser::Tag::proposedTextEncoding | ( |  | ) | const
| inlinevirtual

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 in TagParser::FieldMapBasedTag< ImplementationType >, TagParser::FieldMapBasedTag< Id3v2Tag >, TagParser::FieldMapBasedTag< MatroskaTag >, TagParser::FieldMapBasedTag< Mp4Tag >, TagParser::FieldMapBasedTag< VorbisComment >, and TagParser::Id3v2Tag.

Definition at line 232 of file tag.h.

## ◆ removeAllFields()

virtual void TagParser::Tag::removeAllFields | ( |  | ) |
| pure virtual

Removes all fields from the tag.

Implemented in TagParser::FieldMapBasedTag< ImplementationType >, TagParser::FieldMapBasedTag< Id3v2Tag >, TagParser::FieldMapBasedTag< MatroskaTag >, TagParser::FieldMapBasedTag< Mp4Tag >, TagParser::FieldMapBasedTag< VorbisComment >, and TagParser::Id3v1Tag.

## ◆ setTarget()

void TagParser::Tag::setTarget | ( | const TagTarget & | target | ) |
| inline

Sets the target of tag.

Most tag types don't support this feature so setting the target has no effect when saving the file.

See also
  supportsTarget()
  target()

Definition at line 267 of file tag.h.

## ◆ setValue()

virtual bool TagParser::Tag::setValue | ( | KnownField | field,
|  | const TagValue & | value )
| pure virtual

Assigns the given value to the specified field.

Remarks
  - If an empty value is given, the field will be be removed.
  - Some tags support more than just one value per field. This method will only alter the first value.

See also
  value(), hasField()

Implemented in TagParser::FieldMapBasedTag< ImplementationType >, TagParser::Id3v1Tag, TagParser::Mp4Tag, and TagParser::VorbisComment.

## ◆ setValues()

bool TagParser::Tag::setValues | ( | KnownField | field,
|  | const std::vector< TagValue > & | values )
| virtual

Assigns the given values to the specified field.

Remarks
  - There might me more than one value assigned to a field. Whereas setValue() only alters the first value, this method will replace all currently assigned values with the specified values.
  - However, the default implementation just sets the first value and discards additional values assuming multiple values per field are not supported by the tag.

Reimplemented in TagParser::FieldMapBasedTag< ImplementationType >, and TagParser::Mp4Tag.

Definition at line 76 of file tag.cpp.

## ◆ size()

std::uint64_t TagParser::Tag::size | ( |  | ) | const
| inline

Returns the size the tag within the file it is parsed from in bytes.

Remarks
  - Zero is returned if the tag has not been parsed yet. If the corresponding MediaFileInfo objects tags have already been parsed this shouldn't be the case unless the tag is not actually present in the file yet, e.g. it has been added via MediaFileInfo::createAppropriateTags() but has not been applied yet via MediaFileInfo::applyChanges().
  - Can not be used to determine the number of bytes it would require to write the tag in its current state. For this, use functions like Mp4Tag::prepareMaking() instead.

Definition at line 247 of file tag.h.

## ◆ supportsDescription()

bool TagParser::Tag::supportsDescription | ( | KnownField | field | ) | const
| inlinevirtual

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 in TagParser::Id3v2Tag.

Definition at line 324 of file tag.h.

## ◆ supportsField()

virtual bool TagParser::Tag::supportsField | ( | KnownField | field | ) | const
| pure virtual

Returns an indication whether the specified field is supported by the tag.

Implemented in TagParser::FieldMapBasedTag< ImplementationType >, TagParser::FieldMapBasedTag< Id3v2Tag >, TagParser::FieldMapBasedTag< MatroskaTag >, TagParser::FieldMapBasedTag< Mp4Tag >, TagParser::FieldMapBasedTag< VorbisComment >, TagParser::Id3v1Tag, and TagParser::Mp4Tag.

## ◆ supportsMimeType()

bool TagParser::Tag::supportsMimeType | ( | KnownField | field | ) | const
| inlinevirtual

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 in TagParser::Id3v2Tag.

Definition at line 329 of file tag.h.

## ◆ supportsMultipleValues()

bool TagParser::Tag::supportsMultipleValues | ( | KnownField | field | ) | const
| inlinevirtual

Returns an indications whether the specified field supports multiple values.

Remarks
  - If you assign multiple values to a field which doesn't support multiple values, the tag implementation might just ignore additional values. It might also try to preserve the values nevertheless by bending the rules of the tag format specification when it is safe to do so. (Usually it is safe because additional values would be simply ignored by other applications.)
  - So it is not really mandatory to check this before adding multiple values. Nothing bad will happen otherwise. However, a GUI application could use this method to determine which widget to use.
  - In case it is not known whether multiple values are supported, this method returns false. If you know better, you can try to assign multiple values anyways.
  - If this method returns true, there might be further constraints, though. Eg. only one cover of a certain type may be present at a time in an ID3v2 tag.
  - The default implementation returns false for all fields. This might be overwritten when subclassing.

Reimplemented in TagParser::Id3v2Tag, TagParser::MatroskaTag, TagParser::Mp4Tag, and TagParser::VorbisComment.

Definition at line 334 of file tag.h.

## ◆ supportsTarget()

bool TagParser::Tag::supportsTarget | ( |  | ) | const
| inlinevirtual

Returns an indication whether a target is supported by the tag.

If no target is supported, setting a target using setTarget() has no effect when saving the tag.

Most tag types don't support this feature so the default implementation returns always false. This might be overwritten when subclassing.

Reimplemented in TagParser::MatroskaTag, and TagParser::OggVorbisComment.

Definition at line 252 of file tag.h.

## ◆ target() [1/2]

TagTarget & TagParser::Tag::target | ( |  | ) |
| inline

Returns the target of tag.

See also
  supportsTarget()
  setTarget()

Definition at line 262 of file tag.h.

## ◆ target() [2/2]

const TagTarget & TagParser::Tag::target | ( |  | ) | const
| inline

Definition at line 257 of file tag.h.

## ◆ targetLevel()

TagTargetLevel TagParser::Tag::targetLevel | ( |  | ) | const
| inlinevirtual

Returns the name of the current tag target level.

Remarks
  Returns TagTargetLevel::Unspecified if target levels are not supported by the tag.

Reimplemented in TagParser::MatroskaTag.

Definition at line 272 of file tag.h.

## ◆ targetLevelName()

std::string_view TagParser::Tag::targetLevelName | ( |  | ) | const
| inline

Returns the name of the current target level.

Remarks
  Returns nullptr if target levels are not supported by the tag.

Definition at line 277 of file tag.h.

## ◆ targetString()

std::string TagParser::Tag::targetString | ( |  | ) | const
| inline

Returns the string representation for the assigned tag target.

Definition at line 287 of file tag.h.

## ◆ toString()

string TagParser::Tag::toString | ( |  | ) | const

Returns a string representation of the tag.

Definition at line 39 of file tag.cpp.

## ◆ type()

TagType TagParser::Tag::type | ( |  | ) | const
| inlinevirtual

Returns the type of the tag as TagParser::TagType.

This is TagType::Unspecified by default and might be overwritten when subclassing.

Reimplemented in TagParser::FieldMapBasedTag< ImplementationType >, TagParser::FieldMapBasedTag< Id3v2Tag >, TagParser::FieldMapBasedTag< MatroskaTag >, TagParser::FieldMapBasedTag< Mp4Tag >, TagParser::FieldMapBasedTag< VorbisComment >, TagParser::Id3v1Tag, and TagParser::OggVorbisComment.

Definition at line 222 of file tag.h.

## ◆ typeName()

std::string_view TagParser::Tag::typeName | ( |  | ) | const
| inlinevirtual

Returns the type name of the tag.

Remarks
  This is "unspecified" by default and might be overwritten when subclassing.

Reimplemented in TagParser::FieldMapBasedTag< ImplementationType >, TagParser::FieldMapBasedTag< Id3v2Tag >, TagParser::FieldMapBasedTag< MatroskaTag >, TagParser::FieldMapBasedTag< Mp4Tag >, TagParser::FieldMapBasedTag< VorbisComment >, TagParser::Id3v1Tag, and TagParser::OggVorbisComment.

Definition at line 227 of file tag.h.

## ◆ value()

virtual const TagValue & TagParser::Tag::value | ( | KnownField | field | ) | const
| pure virtual

Returns the value of the specified field.

Remarks
  - If the specified field is not present an empty TagValue will be returned.
  - Some tags support more than just one value per field. If there are multiple values this method just returns the first one.

See also
  setValue(), hasField()

Implemented in TagParser::FieldMapBasedTag< ImplementationType >, TagParser::Id3v1Tag, TagParser::Mp4Tag, and TagParser::VorbisComment.

## ◆ values()

std::vector< const TagValue * > TagParser::Tag::values | ( | KnownField | field | ) | const
| virtual

Returns the values of the specified field.

Remarks
  - There might me more than one value assigned to a field. Whereas value() returns only the first value, this method returns all values.
  - However, the default implementation just returns the first value assuming multiple values per field are not supported by the tag.

Reimplemented in TagParser::FieldMapBasedTag< ImplementationType >, and TagParser::Mp4Tag.

Definition at line 58 of file tag.cpp.

## ◆ version()

const std::string & TagParser::Tag::version | ( |  | ) | const
| inline

Returns the version of the tag.

Remarks
  The version denotation depends on the tag type.

Definition at line 242 of file tag.h.

## Member Data Documentation

## ◆ m_p

std::unique_ptr<TagPrivate> TagParser::Tag::m_p
| protected

Definition at line 218 of file tag.h.

## ◆ m_size

std::uint64_t TagParser::Tag::m_size
| protected

Definition at line 217 of file tag.h.

## ◆ m_target

TagTarget TagParser::Tag::m_target
| protected

Definition at line 219 of file tag.h.

## ◆ m_version

std::string TagParser::Tag::m_version
| protected

Definition at line 216 of file tag.h.

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

- tag.h
- tag.cpp