TagLib::ID3v2::FrameFactory Class Reference

A factory for creating ID3v2 frames during parsing. More...

`#include <id3v2framefactory.h>`

## Public Member Functions

| FrameFactory (const FrameFactory &)=delete
FrameFactory & | operator= (const FrameFactory &)=delete
virtual Frame * | createFrame (const ByteVector &origData, const Header *tagHeader) const
virtual Frame * | createFrameForProperty (const String &key, const StringList &values) const
virtual void | rebuildAggregateFrames (ID3v2::Tag *tag) const
String::Type | defaultTextEncoding () const
void | setDefaultTextEncoding (String::Type encoding)
bool | isUsingDefaultTextEncoding () const

## Static Public Member Functions

static FrameFactory * | instance ()

## Protected Member Functions

| FrameFactory ()
| ~FrameFactory ()
virtual bool | updateFrame (Frame::Header *header) const
std::pair< Frame::Header *, bool > | prepareFrameHeader (ByteVector &data, const Header *tagHeader) const
virtual Frame * | createFrame (const ByteVector &data, Frame::Header *header, const Header *tagHeader) const

## Detailed Description

A factory for creating ID3v2 frames during parsing.

This factory abstracts away the frame creation process and instantiates the appropriate ID3v2::Frame subclasses based on the contents of the data.

Reimplementing this factory is the key to adding support for frame types not directly supported by TagLib to your application. To do so you would subclass this factory and reimplement createFrame(). Then by setting your factory to be the default factory in ID3v2::Tag constructor you can implement behavior that will allow for new ID3v2::Frame subclasses (also provided by you) to be used. See tests/test_id3v2framefactory.cpp for an example.

This implements both abstract factory and singleton patterns of which more information is available on the web and in software design textbooks (notably Design Patterns).

Note
  You do not need to use this factory to create new frames to add to an ID3v2::Tag. You can instantiate frame subclasses directly (with `new`) and add them to a tag using ID3v2::Tag::addFrame()

See also
  ID3v2::Tag::addFrame()

## Constructor & Destructor Documentation

## FrameFactory() [1/2]

TagLib::ID3v2::FrameFactory::FrameFactory | ( | const FrameFactory & |  | ) |

delete

References FrameFactory().

Referenced by createFrame(), FrameFactory(), instance(), and operator=().

## FrameFactory() [2/2]

TagLib::ID3v2::FrameFactory::FrameFactory | ( |  | ) |

protected

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

## ~FrameFactory()

TagLib::ID3v2::FrameFactory::~FrameFactory | ( |  | ) |

protected

Destroys the frame factory.

## Member Function Documentation

## createFrame() [1/2]

virtual Frame * TagLib::ID3v2::FrameFactory::createFrame | ( | const ByteVector & | data,
|  | Frame::Header * | header,
|  | const Header * | tagHeader ) const

protected virtual

Create a frame based on data. header should be a valid frame header and tagHeader a valid ID3v2::Header instance.

This method is called by the public overloaded method createFrame(const ByteVector &, const Header *) after creating header from verified data using prepareFrameHeader(), so this method is provided to be reimplemented in derived classes.

References FrameFactory(), and TAGLIB_MSVC_SUPPRESS_WARNING_NEEDS_TO_HAVE_DLL_INTERFACE.

## createFrame() [2/2]

virtual Frame * TagLib::ID3v2::FrameFactory::createFrame | ( | const ByteVector & | origData,
|  | const Header * | tagHeader ) const

virtual

Create a frame based on origData. tagHeader should be a valid ID3v2::Header instance.

## createFrameForProperty()

virtual Frame * TagLib::ID3v2::FrameFactory::createFrameForProperty | ( | const String & | key,
|  | const StringList & | values ) const

virtual

Creates a textual frame which corresponds to a single key in the PropertyMap interface. TIPL and TMCL do not belong to this category and are thus handled explicitly in the Frame class.

## defaultTextEncoding()

String::Type TagLib::ID3v2::FrameFactory::defaultTextEncoding | ( |  | ) | const

Returns the default text encoding for text frames. If setTextEncoding() has not been explicitly called this will only be used for new text frames. However, if this value has been set explicitly all frames will be converted to this type (unless it's explicitly set differently for the individual frame) when being rendered.

See also
  setDefaultTextEncoding()

## instance()

FrameFactory * TagLib::ID3v2::FrameFactory::instance | ( |  | ) |

static

References FrameFactory().

Referenced by TagLib::ID3v2::Tag::Tag().

## isUsingDefaultTextEncoding()

bool TagLib::ID3v2::FrameFactory::isUsingDefaultTextEncoding | ( |  | ) | const

Returns `true` if defaultTextEncoding() is used. The default text encoding is used when setDefaultTextEncoding() has been called. In this case, reimplementations of FrameFactory should use defaultTextEncoding() on the frames (having a text encoding field) they create.

See also
  defaultTextEncoding()
  setDefaultTextEncoding()

## operator=()

FrameFactory & TagLib::ID3v2::FrameFactory::operator= | ( | const FrameFactory & |  | ) |

delete

References FrameFactory().

## prepareFrameHeader()

std::pair< Frame::Header *, bool > TagLib::ID3v2::FrameFactory::prepareFrameHeader | ( | ByteVector & | data,
|  | const Header * | tagHeader ) const

protected

Creates and prepares the frame header for createFrame().

Parameters

  data | data of the frame (might be modified)
  tagHeader | the tag header

Returns
  {header, ok}: header is a created frame header or nullptr if the frame is invalid; ok is `true` if the frame is supported.

## rebuildAggregateFrames()

virtual void TagLib::ID3v2::FrameFactory::rebuildAggregateFrames | ( | ID3v2::Tag * | tag | ) | const

virtual

After a tag has been read, this tries to rebuild some of them information, most notably the recording date, from frames that have been deprecated and can't be upgraded directly.

## setDefaultTextEncoding()

void TagLib::ID3v2::FrameFactory::setDefaultTextEncoding | ( | String::Type | encoding | ) |

Set the default text encoding for all text frames that are created to encoding. If no value is set the frames with either default to the encoding type that was parsed and new frames default to Latin1.

Valid string types for ID3v2 tags are Latin1, UTF8, UTF16 and UTF16BE.

See also
  defaultTextEncoding()

## updateFrame()

virtual bool TagLib::ID3v2::FrameFactory::updateFrame | ( | Frame::Header * | header | ) | const

protected virtual

This method checks for compliance to the current ID3v2 standard (2.4) and does nothing in the common case. However if a frame is found that is not compatible with the current standard, this method either updates the frame or indicates that it should be discarded.

This method with return `true` (with or without changes to the frame) if this frame should be kept or `false` if it should be discarded.

See the id3v2.4.0-changes.txt document for further information.

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

- id3v2framefactory.h