TagLib API Documentation
Public Member Functions | Static Public Member Functions | Protected Types | Protected Member Functions | Static Protected Member Functions | List of all members
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 ,
  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 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)
 

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::List
A generic, implicitly shared list.
Definition tlist.h:54
TagLib::List::insert
Iterator insert(Iterator it, const T &item)
TagLib::MP4::ItemFactory
A factory for creating MP4 items during parsing.
Definition mp4itemfactory.h:70
TagLib::Map
A generic, implicitly shared map.
Definition tmap.h:45
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
strongprotected

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 
TextImplicit 
Text 

Constructor & Destructor Documentation

◆ ItemFactory() [1/2]

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

◆ 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
protectedvirtual

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

◆ instance()

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

◆ 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
protectedvirtual

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
protectedvirtual

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

◆ parseBool()

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

◆ parseByte()

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

◆ parseCovr()

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

◆ parseData()

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

◆ parseData2()

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

◆ parseFreeForm()

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

◆ parseGnre()

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

◆ parseInt()

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

◆ parseIntPair()

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

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

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

◆ parseText()

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

◆ parseTextOrInt()

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

◆ parseUInt()

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

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

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

◆ renderBool()

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

◆ renderByte()

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

◆ renderCovr()

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

◆ renderData()

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

◆ renderFreeForm()

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

◆ renderInt()

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

◆ renderIntPair()

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

◆ renderIntPairNoTrailing()

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

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

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

◆ renderText()

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

◆ renderTextOrInt()

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

◆ renderUInt()

static ByteVector TagLib::MP4::ItemFactory::renderUInt ( const ByteVector &  name,
const MP4::Item &  item 
)
staticprotected
The documentation for this class was generated from the following file: