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

Implementation of Media::Tag for the MP4 container. More...

#include <mp4tag.h>

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

Public Member Functions

 Mp4Tag ()
 Constructs a new tag. More...
 
TagType type () const
 Returns the type of the tag as Media::TagType. More...
 
const char * typeName () const
 Returns the type name of the tag as C-style string. More...
 
TagTextEncoding proposedTextEncoding () const
 Returns the proposed text encoding. More...
 
bool canEncodingBeUsed (TagTextEncoding encoding) const
 Returns an indication whether the specified encoding can be used to provide string values for the tag. More...
 
uint32 fieldId (KnownField field) const
 Returns the ID for the specified field. More...
 
KnownField knownField (const uint32 &id) const
 
bool supportsField (KnownField field) const
 Returns an indication whether the specified field is supported by the tag. More...
 
const TagValuevalue (KnownField value) const
 Returns the value of the specified field. More...
 
std::vector< const TagValue * > values (KnownField field) const
 Returns the values of the specified field. More...
 
const TagValuevalue (const std::string &mean, const std::string &name) const
 Returns the value of the field with the specified mean and name attributes. More...
 
const TagValuevalue (const char *mean, const char *name) const
 Returns the value of the field with the specified mean and name attributes. More...
 
bool setValue (KnownField field, const TagValue &value)
 Assigns the given value to the specified field. More...
 
bool setValues (KnownField field, const std::vector< TagValue > &values)
 Assigns the given values to the specified field. More...
 
bool setValue (const std::string &mean, const std::string &name, const TagValue &value)
 Assigns the given value to the field with the specified mean and name attributes. More...
 
bool setValue (const char *mean, const char *name, const TagValue &value)
 Assigns the given value to the field with the specified mean and name attributes. More...
 
bool hasField (KnownField value) const
 Returns an indication whether the specified field is present. More...
 
void parse (Mp4Atom &metaAtom)
 Parses tag information from the specified metaAtom. More...
 
Mp4TagMaker prepareMaking ()
 Prepares making. More...
 
void make (std::ostream &stream)
 Writes tag information to the specified stream. More...
 
- Public Member Functions inherited from Media::FieldMapBasedTag< Mp4TagField >
 FieldMapBasedTag ()
 Constructs a new FieldMapBasedTag. More...
 
virtual const TagValuevalue (const typename Mp4TagField ::identifierType &id) const
 Returns the value of the field with the specified id. More...
 
const TagValuevalue (KnownField field) const
 Returns the value of the specified field. More...
 
std::vector< const TagValue *> values (const typename Mp4TagField ::identifierType &id) const
 Returns the values of the field with the specified id. More...
 
std::vector< const TagValue *> values (KnownField field) const
 Returns the values of the specified field. More...
 
virtual bool setValue (const typename Mp4TagField ::identifierType &id, const TagValue &value)
 Assigns the given value to the field with the specified id. More...
 
bool setValue (KnownField field, const TagValue &value)
 Assigns the given value to the specified field. More...
 
bool setValues (const typename Mp4TagField ::identifierType &id, const std::vector< TagValue > &values)
 Assigns the given values to the field with the specified id. More...
 
bool setValues (KnownField field, const std::vector< TagValue > &values)
 Assigns the given values to the field with the specified id. More...
 
bool hasField (KnownField field) const
 Returns an indication whether the specified field is present. More...
 
virtual bool hasField (const typename Mp4TagField ::identifierType &id) const
 Returns an indication whether the field with the specified id is present. More...
 
void removeAllFields ()
 Removes all fields from the tag. More...
 
const std::multimap< typename Mp4TagField ::identifierType, Mp4TagField, std::less< typename Mp4TagField ::identifierType > > & fields () const
 Returns the fields of the tag by providing direct access to the field map of the tag. More...
 
std::multimap< typename Mp4TagField ::identifierType, Mp4TagField, std::less< typename Mp4TagField ::identifierType > > & fields ()
 Returns the fields of the tag by providing direct access to the field map of the tag. More...
 
unsigned int fieldCount () const
 Returns the number of present fields. More...
 
virtual KnownField knownField (const typename Mp4TagField ::identifierType &id) const=0
 Returns the field for the specified ID. More...
 
bool supportsField (KnownField field) const
 Returns an indication whether the specified field is supported by the tag. More...
 
virtual TagDataType proposedDataType (const typename Mp4TagField ::identifierType &id) const
 Returns the proposed data type for the field with the specified id. More...
 
int insertFields (const FieldMapBasedTag< Mp4TagField, std::less< typename Mp4TagField ::identifierType > > &from, bool overwrite)
 Inserts all fields from another tag of the same field type and compare function. More...
 
unsigned int insertValues (const Tag &from, bool overwrite)
 Inserts all compatible values from another Tag. More...
 
void ensureTextValuesAreProperlyEncoded ()
 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::Tag
virtual ~Tag ()
 Destroys the Tag. More...
 
std::string toString () const
 Returns a string representation of 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 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...
 
- 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...
 

Static Public Attributes

static constexpr TagType tagType = TagType::Mp4Tag
 

Additional Inherited Members

- Public Types inherited from Media::FieldMapBasedTag< Mp4TagField >
typedef Mp4TagField fieldType
 
- Public Types inherited from Media::StatusProvider
typedef std::function< void(StatusProvider &sender)> CallbackFunction
 
typedef std::vector< CallbackFunctionCallbackVector
 
typedef std::pair< int, CallbackFunctionCallbackPair
 
- Protected Member Functions inherited from Media::Tag
 Tag ()
 Constructs a new Tag. More...
 
- Protected Member Functions inherited from Media::StatusProvider
 StatusProvider ()
 Constructs a new StatusProvider. More...
 
- Protected Attributes inherited from Media::Tag
std::string m_version
 
uint32 m_size
 
TagTarget m_target
 

Detailed Description

Implementation of Media::Tag for the MP4 container.

Definition at line 90 of file mp4tag.h.

Constructor & Destructor Documentation

◆ Mp4Tag()

Media::Mp4Tag::Mp4Tag ( )
inline

Constructs a new tag.

Definition at line 133 of file mp4tag.h.

Member Function Documentation

◆ canEncodingBeUsed()

bool Media::Mp4Tag::canEncodingBeUsed ( TagTextEncoding  encoding) const
virtual

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

Definition at line 46 of file mp4tag.cpp.

◆ fieldId()

uint32 Media::Mp4Tag::fieldId ( KnownField  value) const
virtual

Returns the ID for the specified field.

Needs to be implemented when subclassing.

Implements Media::FieldMapBasedTag< Mp4TagField >.

Definition at line 122 of file mp4tag.cpp.

◆ hasField()

bool Media::Mp4Tag::hasField ( KnownField  field) const
virtual

Returns an indication whether the specified field is present.

See also
value(), setValue()

Implements Media::Tag.

Definition at line 259 of file mp4tag.cpp.

◆ knownField()

KnownField Media::Mp4Tag::knownField ( const uint32 &  id) const

Definition at line 149 of file mp4tag.cpp.

◆ make()

void Media::Mp4Tag::make ( std::ostream &  stream)

Writes tag information to the specified stream.

Exceptions
Throwsstd::ios_base::failure when an IO error occurs.
ThrowsMedia::Failure or a derived exception when a making error occurs.

Definition at line 357 of file mp4tag.cpp.

◆ parse()

void Media::Mp4Tag::parse ( Mp4Atom metaAtom)

Parses tag information from the specified metaAtom.

Exceptions
Throwsstd::ios_base::failure when an IO error occurs.
ThrowsMedia::Failure or a derived exception when a parsing error occurs.

Definition at line 277 of file mp4tag.cpp.

◆ prepareMaking()

Mp4TagMaker Media::Mp4Tag::prepareMaking ( )

Prepares making.

Returns
Returns a Mp4TagMaker 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
ThrowsMedia::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 345 of file mp4tag.cpp.

◆ proposedTextEncoding()

TagTextEncoding Media::Mp4Tag::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 from Media::Tag.

Definition at line 146 of file mp4tag.h.

◆ setValue() [1/3]

bool Media::Mp4Tag::setValue ( KnownField  field,
const TagValue value 
)
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()

Implements Media::Tag.

Definition at line 176 of file mp4tag.cpp.

◆ setValue() [2/3]

bool Media::Mp4Tag::setValue ( const std::string &  mean,
const std::string &  name,
const TagValue value 
)
inline

Assigns the given value to the field with the specified mean and name attributes.

Definition at line 172 of file mp4tag.h.

◆ setValue() [3/3]

bool Media::Mp4Tag::setValue ( const char *  mean,
const char *  name,
const TagValue value 
)

Assigns the given value to the field with the specified mean and name attributes.

Remarks
  • If there are multiple fields with specified mean and name only the first will be altered.
  • If no field is present, a new one will be created.
  • If value is empty, the field will be removed.

Definition at line 238 of file mp4tag.cpp.

◆ setValues()

bool Media::Mp4Tag::setValues ( KnownField  field,
const std::vector< TagValue > &  values 
)
virtual

Assigns the given values to the specified field.

Remarks
  • There might me more then 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 from Media::Tag.

Definition at line 200 of file mp4tag.cpp.

◆ supportsField()

bool Media::Mp4Tag::supportsField ( KnownField  field) const
inlinevirtual

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

Implements Media::Tag.

Definition at line 151 of file mp4tag.h.

◆ type()

TagType Media::Mp4Tag::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 from Media::Tag.

Definition at line 136 of file mp4tag.h.

◆ typeName()

const char * Media::Mp4Tag::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 from Media::Tag.

Definition at line 141 of file mp4tag.h.

◆ value() [1/3]

const TagValue & Media::Mp4Tag::value ( KnownField  field) const
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()

Implements Media::Tag.

Definition at line 58 of file mp4tag.cpp.

◆ value() [2/3]

const TagValue & Media::Mp4Tag::value ( const std::string &  mean,
const std::string &  name 
) const
inline

Returns the value of the field with the specified mean and name attributes.

Definition at line 164 of file mp4tag.h.

◆ value() [3/3]

const TagValue & Media::Mp4Tag::value ( const char *  mean,
const char *  name 
) const

Returns the value of the field with the specified mean and name attributes.

Remarks
  • If there are multiple fields with specified mean and name only the first value will be returned.

Definition at line 103 of file mp4tag.cpp.

◆ values()

std::vector< const TagValue * > Media::Mp4Tag::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 from Media::Tag.

Definition at line 83 of file mp4tag.cpp.

Member Data Documentation

◆ tagType

constexpr TagType Media::Mp4Tag::tagType = TagType::Mp4Tag
static

Definition at line 95 of file mp4tag.h.


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