Tag Parser  6.4.0
C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
Media::Tag Class Referenceabstract

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

#include <tag.h>

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

Public Member Functions

virtual ~Tag ()
 Destroys the Tag. More...
 
virtual TagType type () const
 Returns the type of the tag as Media::TagType. More...
 
virtual const char * typeName () const
 Returns the type name of the tag as C-style string. More...
 
std::string toString () const
 Returns a string representation of the tag. More...
 
virtual TagTextEncoding proposedTextEncoding () const
 Returns the proposed text encoding. More...
 
virtual bool canEncodingBeUsed (TagTextEncoding encoding) const
 Returns an indication whether the specified encoding can be used to provide string values for the tag. More...
 
virtual const TagValuevalue (KnownField field) const =0
 Returns the value of the specified field. More...
 
virtual std::vector< const TagValue * > values (KnownField field) const
 Returns the values of the specified field. More...
 
virtual bool setValue (KnownField field, const TagValue &value)=0
 Assigns the given value to the specified field. More...
 
virtual bool setValues (KnownField field, const std::vector< TagValue > &values)
 Assigns the given values to the specified field. More...
 
virtual bool hasField (KnownField field) const =0
 Returns an indication whether the specified field is present. More...
 
virtual void removeAllFields ()=0
 Removes all fields from 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 unsigned int fieldCount () const =0
 Returns the number of present fields. More...
 
virtual bool supportsField (KnownField field) const =0
 Returns an indication whether the specified field is supported by the tag. More...
 
virtual TagDataType proposedDataType (KnownField field) const
 Returns the proposed data type for the specified field as TagDataType. More...
 
virtual bool supportsDescription (KnownField field) const
 Returns an indications whether the specified field supports descriptions. More...
 
virtual bool supportsMimeType (KnownField field) const
 Returns an indications whether the specified field supports mime types. More...
 
virtual unsigned int insertValues (const Tag &from, bool overwrite)
 Inserts all compatible values from another Tag. More...
 
virtual void ensureTextValuesAreProperlyEncoded ()=0
 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 Media::StatusProvider
const NotificationListnotifications () const
 Returns notifications for the current object. More...
 
bool hasNotifications () const
 Returns an indication whether there are notifications for the current object. More...
 
bool hasCriticalNotifications () const
 Returns an indication whether there are critical notifications for the current object. More...
 
NotificationType worstNotificationType () const
 Returns the worst notification type. More...
 
const std::string & currentStatus () const
 Returns a status information for the current object. More...
 
double currentPercentage () const
 Returns the progress percentage of the current object. More...
 
size_t registerCallback (CallbackFunction callback)
 Registers a callback function. More...
 
void unregisterCallback (size_t id)
 Unregisters a previously registered callback function whith the specified id. More...
 
void unregisterAllCallbacks ()
 Unregisters all callback functions. More...
 
void forwardStatusUpdateCalls (StatusProvider *other=nullptr)
 Forwards all status updates calls to the specified statusProvider. More...
 
StatusProviderusedProvider ()
 Returns the provider which callback functions will be called when the status or the percentage is updated. More...
 
void tryToAbort ()
 Commands the object to abort the current operation. More...
 
bool isAborted () const
 Returns an indication whether the current operation should be aborted. More...
 
void invalidateStatus ()
 Invalidates the current status. More...
 
void invalidateNotifications ()
 Invalidates the object's notifications. More...
 
void updateStatus (const std::string &status)
 This method is meant to be called by the derived class to report updated status information. More...
 
void updateStatus (const std::string &status, double percentage)
 This method is meant to be called by the derived class to report updated status information. More...
 
void updatePercentage (double percentage)
 This method is meant to be called by the derived class to report updated progress percentage only. More...
 
void addNotification (const Notification &notification)
 This protected method is meant to be called by the derived class to add a notification. More...
 
void addNotification (NotificationType type, const std::string &message, const std::string &context)
 This protected method is meant to be called by the derived class to add a notification of the specified type, message and context. More...
 
void addNotifications (const StatusProvider &from)
 This protected method is meant to be called by the derived class to add all notifications from another StatusProvider instance. More...
 
void addNotifications (const std::string &higherContext, const StatusProvider &from)
 This protected method is meant to be called by the derived class to add all notifications from another StatusProvider instance. More...
 
void addNotifications (const NotificationList &notifications)
 This protected method is meant to be called by the derived class to add the specified notifications. More...
 

Protected Member Functions

 Tag ()
 Constructs a new Tag. More...
 
- Protected Member Functions inherited from Media::StatusProvider
 StatusProvider ()
 Constructs a new StatusProvider. More...
 

Protected Attributes

std::string m_version
 
uint32 m_size
 
TagTarget m_target
 

Additional Inherited Members

- Public Types inherited from Media::StatusProvider
typedef std::function< void(StatusProvider &sender)> CallbackFunction
 
typedef std::vector< CallbackFunctionCallbackVector
 
typedef std::pair< int, CallbackFunctionCallbackPair
 

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

Constructor & Destructor Documentation

◆ ~Tag()

Media::Tag::~Tag ( )
virtual

Destroys the Tag.

Definition at line 28 of file tag.cpp.

◆ Tag()

Media::Tag::Tag ( )
protected

Constructs a new Tag.

Definition at line 21 of file tag.cpp.

Member Function Documentation

◆ canEncodingBeUsed()

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

Definition at line 202 of file tag.h.

◆ ensureTextValuesAreProperlyEncoded()

Media::Tag::ensureTextValuesAreProperlyEncoded ( )
pure virtual

◆ fieldCount()

Media::Tag::fieldCount ( ) const
pure virtual

◆ hasField()

Media::Tag::hasField ( KnownField  field) const
pure virtual

◆ insertValues()

unsigned int Media::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 Media::FieldMapBasedTag< FieldType, Compare >, Media::FieldMapBasedTag< MatroskaTagField >, Media::FieldMapBasedTag< Id3v2Frame, FrameComparer >, Media::FieldMapBasedTag< Mp4TagField >, and Media::FieldMapBasedTag< VorbisCommentField, CaseInsensitiveStringComparer >.

Definition at line 127 of file tag.cpp.

◆ isTargetingLevel()

bool Media::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 287 of file tag.h.

◆ proposedDataType()

TagDataType Media::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. The tag class and its subclasses try to convert the provided values. Nevertheless it is recommend to use the proposed data types to avoid conversion failures.

The default implementation returns a data type which is most commonly used for the specified field. The default implementation might be overwritten when subclassing.

Definition at line 314 of file tag.h.

◆ proposedTextEncoding()

TagTextEncoding Media::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 Media::Mp4Tag, Media::Id3v2Tag, Media::MatroskaTag, and Media::VorbisComment.

Definition at line 183 of file tag.h.

◆ removeAllFields()

Media::Tag::removeAllFields ( )
pure virtual

◆ setTarget()

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

◆ setValue()

Media::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 Media::Mp4Tag, Media::FieldMapBasedTag< FieldType, Compare >, Media::FieldMapBasedTag< MatroskaTagField >, Media::FieldMapBasedTag< Id3v2Frame, FrameComparer >, Media::FieldMapBasedTag< Mp4TagField >, Media::FieldMapBasedTag< VorbisCommentField, CaseInsensitiveStringComparer >, Media::VorbisComment, and Media::Id3v1Tag.

◆ setValues()

bool Media::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 Media::Mp4Tag, Media::FieldMapBasedTag< FieldType, Compare >, Media::FieldMapBasedTag< MatroskaTagField >, Media::FieldMapBasedTag< Id3v2Frame, FrameComparer >, Media::FieldMapBasedTag< Mp4TagField >, and Media::FieldMapBasedTag< VorbisCommentField, CaseInsensitiveStringComparer >.

Definition at line 71 of file tag.cpp.

◆ size()

uint32 Media::Tag::size ( ) const
inline

Returns the size of the tag in bytes.

The tag needs to be parsed before.

Definition at line 220 of file tag.h.

◆ supportsDescription()

bool Media::Tag::supportsDescription ( KnownField  field) const
inlinevirtual

Returns an indications whether the specified field supports descriptions.

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 Media::Id3v2Tag.

Definition at line 346 of file tag.h.

◆ supportsField()

Media::Tag::supportsField ( KnownField  field) const
pure virtual

◆ supportsMimeType()

bool Media::Tag::supportsMimeType ( KnownField  field) const
inlinevirtual

Returns an indications whether the specified field supports mime types.

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 Media::Id3v2Tag.

Definition at line 360 of file tag.h.

◆ supportsTarget()

bool Media::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 Media::OggVorbisComment, and Media::MatroskaTag.

Definition at line 234 of file tag.h.

◆ target()

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

Returns the target of tag.

See also
supportsTarget()
setTarget()

Definition at line 245 of file tag.h.

◆ targetLevel()

TagTargetLevel Media::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 Media::MatroskaTag.

Definition at line 268 of file tag.h.

◆ targetLevelName()

const char * Media::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 Media::Tag::targetString ( ) const
inline

Returns the string representation for the assigned tag target.

Definition at line 295 of file tag.h.

◆ toString()

string Media::Tag::toString ( ) const

Returns a string representation of the tag.

Definition at line 34 of file tag.cpp.

◆ type()

TagType Media::Tag::type ( ) const
inlinevirtual

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

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

Reimplemented in Media::Mp4Tag, Media::OggVorbisComment, Media::Id3v2Tag, Media::MatroskaTag, Media::VorbisComment, and Media::Id3v1Tag.

Definition at line 154 of file tag.h.

◆ typeName()

const char * Media::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 Media::Mp4Tag, Media::OggVorbisComment, Media::Id3v2Tag, Media::MatroskaTag, Media::VorbisComment, and Media::Id3v1Tag.

Definition at line 165 of file tag.h.

◆ value()

Media::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 Media::Mp4Tag, Media::FieldMapBasedTag< FieldType, Compare >, Media::FieldMapBasedTag< MatroskaTagField >, Media::FieldMapBasedTag< Id3v2Frame, FrameComparer >, Media::FieldMapBasedTag< Mp4TagField >, Media::FieldMapBasedTag< VorbisCommentField, CaseInsensitiveStringComparer >, Media::VorbisComment, and Media::Id3v1Tag.

◆ values()

std::vector< const TagValue * > Media::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 Media::Mp4Tag, Media::FieldMapBasedTag< FieldType, Compare >, Media::FieldMapBasedTag< MatroskaTagField >, Media::FieldMapBasedTag< Id3v2Frame, FrameComparer >, Media::FieldMapBasedTag< Mp4TagField >, and Media::FieldMapBasedTag< VorbisCommentField, CaseInsensitiveStringComparer >.

Definition at line 53 of file tag.cpp.

◆ version()

const std::string & Media::Tag::version ( ) const
inline

Returns the version of the tag as std::string.

The version denotation depends on the tag type.

Definition at line 211 of file tag.h.

Member Data Documentation

◆ m_size

uint32 Media::Tag::m_size
protected

Definition at line 142 of file tag.h.

◆ m_target

TagTarget Media::Tag::m_target
protected

Definition at line 143 of file tag.h.

◆ m_version

std::string Media::Tag::m_version
protected

Definition at line 141 of file tag.h.


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