Tag Parser 12.3.1
C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
Loading...
Searching...
No Matches
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 as C-style string.
 
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 TagValuevalue (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 as std::string.
 
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 TagTargettarget () const
 
TagTargettarget ()
 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< TagPrivatem_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).

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 226 of file tag.h.

◆ ensureTextValuesAreProperlyEncoded()

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

◆ fieldCount()

◆ hasField()

◆ insertValues()

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

Inserts all compatible values from another Tag.

Parameters
fromSpecifies the Tag the values should be inserted from.
overwriteIndicates 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 271 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 281 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 221 of file tag.h.

◆ removeAllFields()

◆ 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 256 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::FieldMapBasedTag< Id3v2Tag >, TagParser::FieldMapBasedTag< MatroskaTag >, TagParser::FieldMapBasedTag< Mp4Tag >, TagParser::FieldMapBasedTag< VorbisComment >, 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 >, TagParser::FieldMapBasedTag< Id3v2Tag >, TagParser::FieldMapBasedTag< MatroskaTag >, TagParser::FieldMapBasedTag< Mp4Tag >, TagParser::FieldMapBasedTag< VorbisComment >, 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

Definition at line 236 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 313 of file tag.h.

◆ supportsField()

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

◆ 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 318 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 323 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 241 of file tag.h.

◆ target() [1/2]

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

Returns the target of tag.

See also
supportsTarget()
setTarget()

Definition at line 251 of file tag.h.

◆ target() [2/2]

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

Definition at line 246 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 261 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 266 of file tag.h.

◆ targetString()

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

Returns the string representation for the assigned tag target.

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

◆ typeName()

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

Returns the type name of the tag as C-style string.

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 216 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::FieldMapBasedTag< Id3v2Tag >, TagParser::FieldMapBasedTag< MatroskaTag >, TagParser::FieldMapBasedTag< Mp4Tag >, TagParser::FieldMapBasedTag< VorbisComment >, 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 >, TagParser::FieldMapBasedTag< Id3v2Tag >, TagParser::FieldMapBasedTag< MatroskaTag >, TagParser::FieldMapBasedTag< Mp4Tag >, TagParser::FieldMapBasedTag< VorbisComment >, 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 as std::string.

The version denotation depends on the tag type.

Definition at line 231 of file tag.h.

Member Data Documentation

◆ m_p

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

Definition at line 207 of file tag.h.

◆ m_size

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

Definition at line 206 of file tag.h.

◆ m_target

TagTarget TagParser::Tag::m_target
protected

Definition at line 208 of file tag.h.

◆ m_version

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

Definition at line 205 of file tag.h.


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