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

#include <tag.h>

Inheritance diagram for TagParser::Tag:

Collaboration diagram for TagParser::Tag:

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 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 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 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 166 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()

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

◆ ensureTextValuesAreProperlyEncoded()

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()

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()

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()

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

◆ proposedDataType()

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

◆ proposedTextEncoding()

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

◆ removeAllFields()

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()

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

◆ setValue()

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()

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

◆ supportsDescription()

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

◆ supportsField()

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()

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

◆ supportsMultipleValues()

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

◆ supportsTarget()

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

◆ target() [1/2]

TagParser::Tag::target ( )

inline

Returns the target of tag.

See also: supportsTarget(); setTarget()

Definition at line 249 of file tag.h.

◆ target() [2/2]

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

inline

Definition at line 244 of file tag.h.

◆ targetLevel()

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

◆ targetLevelName()

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

◆ targetString()

TagParser::Tag::targetString ( ) const

inline

Returns the string representation for the assigned tag target.

Definition at line 274 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()

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

◆ typeName()

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

◆ value()

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

◆ 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()

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

Member Data Documentation

◆ m_p

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

protected

Definition at line 205 of file tag.h.

◆ m_size

std::uint64_t TagParser::Tag::m_size

protected

Definition at line 204 of file tag.h.

◆ m_target

TagTarget TagParser::Tag::m_target

protected

Definition at line 206 of file tag.h.

◆ m_version

std::string TagParser::Tag::m_version

protected

Definition at line 203 of file tag.h.

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

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~Tag()

◆ Tag()

Member Function Documentation

◆ canEncodingBeUsed()

◆ ensureTextValuesAreProperlyEncoded()

◆ fieldCount()

◆ hasField()

◆ insertValues()

◆ isTargetingLevel()

◆ proposedDataType()

◆ proposedTextEncoding()

◆ removeAllFields()

◆ setTarget()

◆ setValue()

◆ setValues()

◆ size()

◆ supportsDescription()

◆ supportsField()

◆ supportsMimeType()

◆ supportsMultipleValues()

◆ supportsTarget()

◆ target() [1/2]

◆ target() [2/2]

◆ targetLevel()

◆ targetLevelName()

◆ targetString()

◆ toString()

◆ type()

◆ typeName()

◆ value()

◆ values()

◆ version()

Member Data Documentation

◆ m_p

◆ m_size

◆ m_target

◆ m_version