TagLib::MP4::ItemFactory Class Reference

A factory for creating MP4 items during parsing. More...

`#include <mp4itemfactory.h>`

## Public Member Functions

| ItemFactory (const ItemFactory &)=delete
ItemFactory & | operator= (const ItemFactory &)=delete
virtual std::pair< String, Item > | parseItem (const Atom *atom, const ByteVector &data) const
virtual ByteVector | renderItem (const String &itemName, const Item &item) const
virtual std::pair< ByteVector, Item > | itemFromProperty (const String &key, const StringList &values) const
virtual std::pair< String, StringList > | itemToProperty (const ByteVector &itemName, const Item &item) const
virtual String | propertyKeyForName (const ByteVector &name) const
virtual ByteVector | nameForPropertyKey (const String &key) const

## Static Public Member Functions

static ItemFactory * | instance ()

## Protected Types

enum class | ItemHandlerType { Unknown , FreeForm , IntPair , IntPairNoTrailing , Bool , Int , TextOrInt , UInt , LongLong , Byte , Gnre , Covr , Stem , TextImplicit , Text }
using | NameHandlerMap = Map<ByteVector, ItemHandlerType>

## Protected Member Functions

| ItemFactory ()
| ~ItemFactory ()
virtual NameHandlerMap | nameHandlerMap () const
virtual ItemHandlerType | handlerTypeForName (const ByteVector &name) const
virtual Map< ByteVector, String > | namePropertyMap () const

## Static Protected Member Functions

static MP4::AtomDataList | parseData2 (const MP4::Atom *atom, const ByteVector &data, int expectedFlags=-1, bool freeForm=false)
static ByteVectorList | parseData (const MP4::Atom *atom, const ByteVector &bytes, int expectedFlags=-1, bool freeForm=false)
static std::pair< String, Item > | parseText (const MP4::Atom *atom, const ByteVector &bytes, int expectedFlags=1)
static std::pair< String, Item > | parseFreeForm (const MP4::Atom *atom, const ByteVector &bytes)
static std::pair< String, Item > | parseInt (const MP4::Atom *atom, const ByteVector &bytes)
static std::pair< String, Item > | parseByte (const MP4::Atom *atom, const ByteVector &bytes)
static std::pair< String, Item > | parseTextOrInt (const MP4::Atom *atom, const ByteVector &bytes)
static std::pair< String, Item > | parseUInt (const MP4::Atom *atom, const ByteVector &bytes)
static std::pair< String, Item > | parseLongLong (const MP4::Atom *atom, const ByteVector &bytes)
static std::pair< String, Item > | parseGnre (const MP4::Atom *atom, const ByteVector &bytes)
static std::pair< String, Item > | parseIntPair (const MP4::Atom *atom, const ByteVector &bytes)
static std::pair< String, Item > | parseBool (const MP4::Atom *atom, const ByteVector &bytes)
static std::pair< String, Item > | parseCovr (const MP4::Atom *atom, const ByteVector &data)
static std::pair< String, Item > | parseStem (const MP4::Atom *atom, const ByteVector &data)
static ByteVector | renderAtom (const ByteVector &name, const ByteVector &data)
static ByteVector | renderData (const ByteVector &name, int flags, const ByteVectorList &data)
static ByteVector | renderText (const ByteVector &name, const MP4::Item &item, int flags=TypeUTF8)
static ByteVector | renderFreeForm (const String &name, const MP4::Item &item)
static ByteVector | renderBool (const ByteVector &name, const MP4::Item &item)
static ByteVector | renderInt (const ByteVector &name, const MP4::Item &item)
static ByteVector | renderTextOrInt (const ByteVector &name, const MP4::Item &item)
static ByteVector | renderByte (const ByteVector &name, const MP4::Item &item)
static ByteVector | renderUInt (const ByteVector &name, const MP4::Item &item)
static ByteVector | renderLongLong (const ByteVector &name, const MP4::Item &item)
static ByteVector | renderIntPair (const ByteVector &name, const MP4::Item &item)
static ByteVector | renderIntPairNoTrailing (const ByteVector &name, const MP4::Item &item)
static ByteVector | renderCovr (const ByteVector &name, const MP4::Item &item)
static ByteVector | renderStem (const ByteVector &name, const MP4::Item &item)

## Detailed Description

A factory for creating MP4 items during parsing.

This factory abstracts away the parsing and rendering between atom data and MP4 items.

Reimplementing this factory is the key to adding support for atom types not directly supported by TagLib to your application. To do so you would subclass this factory and reimplement nameHandlerMap() to add support for new atoms. If the new atoms do not have the same behavior as other supported atoms, it may be necessary to reimplement parseItem() and renderItem(). Then by setting your factory in the MP4::Tag constructor you can implement behavior that will allow for new atom types to be used.

A custom item factory adding support for a "tsti" integer atom and a "tstt" text atom can be implemented like this:

class CustomItemFactory : public MP4::ItemFactory {
protected:
NameHandlerMap nameHandlerMap() const override
{
return MP4::ItemFactory::nameHandlerMap()
.insert("tsti", ItemHandlerType::Int)
.insert("tstt", ItemHandlerType::Text);
}
};
TagLib::MP4::ItemFactory
A factory for creating MP4 items during parsing.
Definition mp4itemfactory.h:70
TagLib::MP4::ItemFactory::NameHandlerMap
Map< ByteVector, ItemHandlerType > NameHandlerMap
Definition mp4itemfactory.h:151
TagLib::MP4::ItemFactory::ItemHandlerType::Int
@ Int
Definition mp4itemfactory.h:138
TagLib::MP4::ItemFactory::ItemHandlerType::Text
@ Text
Definition mp4itemfactory.h:147
TagLib::MP4::ItemFactory::nameHandlerMap
virtual NameHandlerMap nameHandlerMap() const
TagLib::Map::insert
Map< Key, T > & insert(const Key &key, const T &value)

If the custom item shall also be accessible via a property, namePropertyMap() can be overridden in the same way.

## Member Typedef Documentation

## NameHandlerMap

using TagLib::MP4::ItemFactory::NameHandlerMap = Map<ByteVector, ItemHandlerType>

protected

Mapping of atom name to handler type.

## Member Enumeration Documentation

## ItemHandlerType

enum class TagLib::MP4::ItemFactory::ItemHandlerType

strong protected

Type that determines the parsing and rendering between the data and the item representation of an atom.

Enumerator
Unknown |
FreeForm |
IntPair |
IntPairNoTrailing |
Bool |
Int |
TextOrInt |
UInt |
LongLong |
Byte |
Gnre |
Covr |
Stem |
TextImplicit |
Text |

## Constructor & Destructor Documentation

## ItemFactory() [1/2]

TagLib::MP4::ItemFactory::ItemFactory | ( | const ItemFactory & |  | ) |

delete

References ItemFactory().

Referenced by instance(), ItemFactory(), operator=(), and renderStem().

## ItemFactory() [2/2]

TagLib::MP4::ItemFactory::ItemFactory | ( |  | ) |

protected

Constructs an item factory. Because this is a singleton this method is protected, but may be used for subclasses.

## ~ItemFactory()

TagLib::MP4::ItemFactory::~ItemFactory | ( |  | ) |

protected

Destroys the frame factory.

## Member Function Documentation

## handlerTypeForName()

virtual ItemHandlerType TagLib::MP4::ItemFactory::handlerTypeForName | ( | const ByteVector & | name | ) | const

protected virtual

Returns handler type for atom name. The default method looks up the map created by nameHandlerMap() and should be enough for most uses.

## instance()

ItemFactory * TagLib::MP4::ItemFactory::instance | ( |  | ) |

static

References ItemFactory().

## itemFromProperty()

virtual std::pair< ByteVector, Item > TagLib::MP4::ItemFactory::itemFromProperty | ( | const String & | key,
|  | const StringList & | values ) const

virtual

Create an MP4 item from a property with key and values. If the property is not supported, an invalid item is returned. The default implementation uses the map returned by namePropertyMap().

## itemToProperty()

virtual std::pair< String, StringList > TagLib::MP4::ItemFactory::itemToProperty | ( | const ByteVector & | itemName,
|  | const Item & | item ) const

virtual

Get an MP4 item as a property. If no property exists for itemName, an empty string is returned as the property key. The default implementation uses the map returned by namePropertyMap().

## nameForPropertyKey()

virtual ByteVector TagLib::MP4::ItemFactory::nameForPropertyKey | ( | const String & | key | ) | const

virtual

Returns atom name for property key, empty if no property is supported for this key. The default method uses the reverse mapping of propertyKeyForName() and should be enough for most uses.

## nameHandlerMap()

virtual NameHandlerMap TagLib::MP4::ItemFactory::nameHandlerMap | ( |  | ) | const

protected virtual

Returns mapping between atom names and handler types. This method is called once by handlerTypeForName() to initialize its internal cache. To add support for a new atom, it is sufficient in most cases to just reimplement this method and add new entries.

## namePropertyMap()

virtual Map< ByteVector, String > TagLib::MP4::ItemFactory::namePropertyMap | ( |  | ) | const

protected virtual

Returns mapping between atom names and property keys. This method is called once by propertyKeyForName() to initialize its internal cache. To add support for a new atom with a property, it is sufficient in most cases to just reimplement this method and add new entries.

## operator=()

ItemFactory & TagLib::MP4::ItemFactory::operator= | ( | const ItemFactory & |  | ) |

delete

References ItemFactory().

## parseBool()

std::pair< String, Item > TagLib::MP4::ItemFactory::parseBool | ( | const MP4::Atom * | atom,
|  | const ByteVector & | bytes )

static protected

## parseByte()

std::pair< String, Item > TagLib::MP4::ItemFactory::parseByte | ( | const MP4::Atom * | atom,
|  | const ByteVector & | bytes )

static protected

## parseCovr()

std::pair< String, Item > TagLib::MP4::ItemFactory::parseCovr | ( | const MP4::Atom * | atom,
|  | const ByteVector & | data )

static protected

## parseData()

ByteVectorList TagLib::MP4::ItemFactory::parseData | ( | const MP4::Atom * | atom,
|  | const ByteVector & | bytes,
|  | int | expectedFlags = -1,
|  | bool | freeForm = false )

static protected

## parseData2()

MP4::AtomDataList TagLib::MP4::ItemFactory::parseData2 | ( | const MP4::Atom * | atom,
|  | const ByteVector & | data,
|  | int | expectedFlags = -1,
|  | bool | freeForm = false )

static protected

## parseFreeForm()

std::pair< String, Item > TagLib::MP4::ItemFactory::parseFreeForm | ( | const MP4::Atom * | atom,
|  | const ByteVector & | bytes )

static protected

## parseGnre()

std::pair< String, Item > TagLib::MP4::ItemFactory::parseGnre | ( | const MP4::Atom * | atom,
|  | const ByteVector & | bytes )

static protected

## parseInt()

std::pair< String, Item > TagLib::MP4::ItemFactory::parseInt | ( | const MP4::Atom * | atom,
|  | const ByteVector & | bytes )

static protected

## parseIntPair()

std::pair< String, Item > TagLib::MP4::ItemFactory::parseIntPair | ( | const MP4::Atom * | atom,
|  | const ByteVector & | bytes )

static protected

## parseItem()

virtual std::pair< String, Item > TagLib::MP4::ItemFactory::parseItem | ( | const Atom * | atom,
|  | const ByteVector & | data ) const

virtual

Create an MP4 item from the data bytes of an atom. Returns the name (in most cases atom->name) and an item, an invalid item on failure. The default implementation uses the map returned by nameHandlerMap().

## parseLongLong()

std::pair< String, Item > TagLib::MP4::ItemFactory::parseLongLong | ( | const MP4::Atom * | atom,
|  | const ByteVector & | bytes )

static protected

## parseStem()

std::pair< String, Item > TagLib::MP4::ItemFactory::parseStem | ( | const MP4::Atom * | atom,
|  | const ByteVector & | data )

static protected

## parseText()

std::pair< String, Item > TagLib::MP4::ItemFactory::parseText | ( | const MP4::Atom * | atom,
|  | const ByteVector & | bytes,
|  | int | expectedFlags = 1 )

static protected

## parseTextOrInt()

std::pair< String, Item > TagLib::MP4::ItemFactory::parseTextOrInt | ( | const MP4::Atom * | atom,
|  | const ByteVector & | bytes )

static protected

## parseUInt()

std::pair< String, Item > TagLib::MP4::ItemFactory::parseUInt | ( | const MP4::Atom * | atom,
|  | const ByteVector & | bytes )

static protected

## propertyKeyForName()

virtual String TagLib::MP4::ItemFactory::propertyKeyForName | ( | const ByteVector & | name | ) | const

virtual

Returns property key for atom name, empty if no property exists for this atom. The default method looks up the map created by namePropertyMap() and should be enough for most uses.

## renderAtom()

ByteVector TagLib::MP4::ItemFactory::renderAtom | ( | const ByteVector & | name,
|  | const ByteVector & | data )

static protected

## renderBool()

ByteVector TagLib::MP4::ItemFactory::renderBool | ( | const ByteVector & | name,
|  | const MP4::Item & | item )

static protected

## renderByte()

ByteVector TagLib::MP4::ItemFactory::renderByte | ( | const ByteVector & | name,
|  | const MP4::Item & | item )

static protected

## renderCovr()

ByteVector TagLib::MP4::ItemFactory::renderCovr | ( | const ByteVector & | name,
|  | const MP4::Item & | item )

static protected

## renderData()

ByteVector TagLib::MP4::ItemFactory::renderData | ( | const ByteVector & | name,
|  | int | flags,
|  | const ByteVectorList & | data )

static protected

## renderFreeForm()

ByteVector TagLib::MP4::ItemFactory::renderFreeForm | ( | const String & | name,
|  | const MP4::Item & | item )

static protected

## renderInt()

ByteVector TagLib::MP4::ItemFactory::renderInt | ( | const ByteVector & | name,
|  | const MP4::Item & | item )

static protected

## renderIntPair()

ByteVector TagLib::MP4::ItemFactory::renderIntPair | ( | const ByteVector & | name,
|  | const MP4::Item & | item )

static protected

## renderIntPairNoTrailing()

ByteVector TagLib::MP4::ItemFactory::renderIntPairNoTrailing | ( | const ByteVector & | name,
|  | const MP4::Item & | item )

static protected

## renderItem()

virtual ByteVector TagLib::MP4::ItemFactory::renderItem | ( | const String & | itemName,
|  | const Item & | item ) const

virtual

Render an MP4 item to the data bytes of an atom itemName. An empty byte vector is returned if the item is invalid or unknown. The default implementation uses the map returned by nameHandlerMap().

## renderLongLong()

ByteVector TagLib::MP4::ItemFactory::renderLongLong | ( | const ByteVector & | name,
|  | const MP4::Item & | item )

static protected

## renderStem()

ByteVector TagLib::MP4::ItemFactory::renderStem | ( | const ByteVector & | name,
|  | const MP4::Item & | item )

static protected

References ItemFactory(), and TAGLIB_MSVC_SUPPRESS_WARNING_NEEDS_TO_HAVE_DLL_INTERFACE.

## renderText()

ByteVector TagLib::MP4::ItemFactory::renderText | ( | const ByteVector & | name,
|  | const MP4::Item & | item,
|  | int | flags = TypeUTF8 )

static protected

References TagLib::MP4::TypeUTF8.

## renderTextOrInt()

ByteVector TagLib::MP4::ItemFactory::renderTextOrInt | ( | const ByteVector & | name,
|  | const MP4::Item & | item )

static protected

## renderUInt()

ByteVector TagLib::MP4::ItemFactory::renderUInt | ( | const ByteVector & | name,
|  | const MP4::Item & | item )

static protected

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

- mp4itemfactory.h