![]() |
|
ID3v2 frame implementation. More...
#include <id3v2frame.h>
Public Member Functions | |
virtual | ~Frame () |
ByteVector | frameID () const |
uint | size () const |
void | setData (const ByteVector &data) |
virtual void | setText (const String &text) |
virtual String | toString () const =0 |
ByteVector | render () const |
Header (const ByteVector &data, bool synchSafeInts) | |
Header (const ByteVector &data, uint version=4) | |
virtual | ~Header () |
void | setData (const ByteVector &data, bool synchSafeInts) |
void | setData (const ByteVector &data, uint version=4) |
ByteVector | frameID () const |
void | setFrameID (const ByteVector &id) |
uint | frameSize () const |
void | setFrameSize (uint size) |
uint | version () const |
void | setVersion (uint version) |
bool | tagAlterPreservation () const |
void | setTagAlterPreservation (bool discard) |
bool | fileAlterPreservation () const |
bool | readOnly () const |
bool | groupingIdentity () const |
bool | compression () const |
bool | encryption () const |
bool | unsynchronisation () const |
bool | dataLengthIndicator () const |
ByteVector | render () const |
bool | frameAlterPreservation () const |
Static Public Member Functions | |
static Frame * | createTextualFrame (const String &key, const StringList &values) |
static uint | headerSize () |
static uint | headerSize (uint version) |
static ByteVector | textDelimiter (String::Type t) |
static uint | size () |
static uint | size (uint version) |
Static Public Attributes | |
static const String | instrumentPrefix |
static const String | commentPrefix |
static const String | lyricsPrefix |
static const String | urlPrefix |
Protected Member Functions | |
Frame (const ByteVector &data) | |
Frame (Header *h) | |
Header * | header () const |
void | setHeader (Header *h, bool deleteCurrent=true) |
void | parse (const ByteVector &data) |
virtual void | parseFields (const ByteVector &data)=0 |
virtual ByteVector | renderFields () const =0 |
ByteVector | fieldData (const ByteVector &frameData) const |
String | readStringField (const ByteVector &data, String::Type encoding, int *positon=0) |
String::Type | checkTextEncoding (const StringList &fields, String::Type encoding) const |
PropertyMap | asProperties () const |
Static Protected Member Functions | |
static String::Type | checkEncoding (const StringList &fields, String::Type encoding) |
static String::Type | checkEncoding (const StringList &fields, String::Type encoding, uint version) |
static ByteVector | keyToFrameID (const String &) |
static String | frameIDToKey (const ByteVector &) |
static String | keyToTXXX (const String &) |
static String | txxxToKey (const String &) |
static void | splitProperties (const PropertyMap &original, PropertyMap &singleFrameProperties, PropertyMap &tiplProperties, PropertyMap &tmclProperties) |
Friends | |
class | Tag |
class | FrameFactory |
class | FramePrivate |
ID3v2 frame implementation.
ID3v2 frame header implementation.
This class is the main ID3v2 frame implementation. In ID3v2, a tag is split between a collection of frames (which are in turn split into fields (Structure, 4) (Frames). This class provides an API for gathering information about and modifying ID3v2 frames. Funtionallity specific to a given frame type is handed in one of the many subclasses.
The ID3v2 Frame Header (Structure, 4)
Every ID3v2::Frame has an associated header that gives some general properties of the frame and also makes it possible to identify the frame type.
As such when reading an ID3v2 tag ID3v2::FrameFactory first creates the frame headers and then creates the appropriate Frame subclass based on the type and attaches the header.
virtual TagLib::ID3v2::Frame::~Frame | ( | ) | [virtual] |
Destroys this Frame instance.
TagLib::ID3v2::Frame::Frame | ( | const ByteVector & | data | ) | [explicit, protected] |
Constructs an ID3v2 frame using data to read the header information. All other processing of data should be handled in a subclass.
TagLib::ID3v2::Frame::Frame | ( | Header * | h | ) | [protected] |
This creates an Frame using the header h.
The ownership of this header will be assigned to the frame and the header will be deleted when the frame is destroyed.
virtual TagLib::ID3v2::Frame::~Header | ( | ) | [virtual] |
Destroys this Header instance.
Reimplemented from TagLib::ID3v2::Header.
PropertyMap TagLib::ID3v2::Frame::asProperties | ( | ) | const [protected] |
Parses the contents of this frame as PropertyMap. If that fails, the returend PropertyMap will be empty, and its unsupportedData() will contain this frame's ID. BIC: Will be a virtual function in future releases.
Reimplemented in TagLib::ID3v2::ChapterFrame, TagLib::ID3v2::CommentsFrame, TagLib::ID3v2::TableOfContentsFrame, TagLib::ID3v2::TextIdentificationFrame, TagLib::ID3v2::UserTextIdentificationFrame, TagLib::ID3v2::UniqueFileIdentifierFrame, TagLib::ID3v2::UnsynchronizedLyricsFrame, TagLib::ID3v2::UrlLinkFrame, and TagLib::ID3v2::UserUrlLinkFrame.
static String::Type TagLib::ID3v2::Frame::checkEncoding | ( | const StringList & | fields, |
String::Type | encoding | ||
) | [static, protected] |
Checks a the list of string values to see if they can be used with the specified encoding and returns the recommended encoding.
static String::Type TagLib::ID3v2::Frame::checkEncoding | ( | const StringList & | fields, |
String::Type | encoding, | ||
uint | version | ||
) | [static, protected] |
Checks a the list of string values to see if they can be used with the specified encoding and returns the recommended encoding. This method also checks the ID3v2 version and makes sure the encoding can be used in the specified version.
String::Type TagLib::ID3v2::Frame::checkTextEncoding | ( | const StringList & | fields, |
String::Type | encoding | ||
) | const [protected] |
Checks a the list of string values to see if they can be used with the specified encoding and returns the recommended encoding. This method also checks the ID3v2 version and makes sure the encoding can be used in the version specified by the frame's header.
bool TagLib::ID3v2::Frame::compression | ( | ) | const |
Returns true if compression is enabled for this frame.
static Frame* TagLib::ID3v2::Frame::createTextualFrame | ( | const String & | key, |
const StringList & | values | ||
) | [static] |
Creates a textual frame which corresponds to a single key in the PropertyMap interface. These are all (User)TextIdentificationFrames except TIPL and TMCL, all (User)URLLinkFrames, CommentsFrames, and UnsynchronizedLyricsFrame.
bool TagLib::ID3v2::Frame::dataLengthIndicator | ( | ) | const |
Returns true if the flag for a data length indicator is set.
bool TagLib::ID3v2::Frame::encryption | ( | ) | const |
Returns true if encryption is enabled for this frame.
ByteVector TagLib::ID3v2::Frame::fieldData | ( | const ByteVector & | frameData | ) | const [protected] |
Returns a ByteVector containing the field data given the frame data. This correctly adjusts for the header size plus any additional frame data that's specified in the frame header flags.
bool TagLib::ID3v2::Frame::fileAlterPreservation | ( | ) | const |
Returns true if the flag for file alter preservation is set.
bool TagLib::ID3v2::Frame::frameAlterPreservation | ( | ) | const |
ByteVector TagLib::ID3v2::Frame::frameID | ( | ) | const |
ByteVector TagLib::ID3v2::Frame::frameID | ( | ) | const |
static String TagLib::ID3v2::Frame::frameIDToKey | ( | const ByteVector & | ) | [static, protected] |
Returns a free-form tag name for the given ID3 frame ID. Note that this does not work for general frame IDs such as TXXX or WXXX; in such a case String::null is returned.
uint TagLib::ID3v2::Frame::frameSize | ( | ) | const |
Returns the size of the frame data portion, as set when setData() was called or set explicitly via setFrameSize().
bool TagLib::ID3v2::Frame::groupingIdentity | ( | ) | const |
Returns true if the flag for the grouping identity is set.
Header* TagLib::ID3v2::Frame::header | ( | ) | const [protected] |
Returns a pointer to the frame header.
TagLib::ID3v2::Frame::Header | ( | const ByteVector & | data, |
bool | synchSafeInts | ||
) |
TagLib::ID3v2::Frame::Header | ( | const ByteVector & | data, |
uint | version = 4 |
||
) | [explicit] |
static uint TagLib::ID3v2::Frame::headerSize | ( | ) | [static] |
Returns the size of the frame header
Returns the size of the frame header for the given ID3v2 version.
static ByteVector TagLib::ID3v2::Frame::keyToFrameID | ( | const String & | ) | [static, protected] |
Returns an appropriate ID3 frame ID for the given free-form tag key. This method will return ByteVector::null if no specialized translation is found.
Returns an appropriate TXXX frame description for the given free-form tag key.
void TagLib::ID3v2::Frame::parse | ( | const ByteVector & | data | ) | [protected] |
Called by setData() to parse the frame data. It makes this information available through the public API.
Reimplemented from TagLib::ID3v2::Header.
virtual void TagLib::ID3v2::Frame::parseFields | ( | const ByteVector & | data | ) | [protected, pure virtual] |
Called by parse() to parse the field data. It makes this information available through the public API. This must be overridden by the subclasses.
Implemented in TagLib::ID3v2::AttachedPictureFrame, TagLib::ID3v2::AttachedPictureFrameV22, TagLib::ID3v2::ChapterFrame, TagLib::ID3v2::CommentsFrame, TagLib::ID3v2::EventTimingCodesFrame, TagLib::ID3v2::GeneralEncapsulatedObjectFrame, TagLib::ID3v2::OwnershipFrame, TagLib::ID3v2::PopularimeterFrame, TagLib::ID3v2::PrivateFrame, TagLib::ID3v2::RelativeVolumeFrame, TagLib::ID3v2::SynchronizedLyricsFrame, TagLib::ID3v2::TableOfContentsFrame, TagLib::ID3v2::TextIdentificationFrame, TagLib::ID3v2::UniqueFileIdentifierFrame, TagLib::ID3v2::UnknownFrame, TagLib::ID3v2::UnsynchronizedLyricsFrame, TagLib::ID3v2::UrlLinkFrame, and TagLib::ID3v2::UserUrlLinkFrame.
bool TagLib::ID3v2::Frame::readOnly | ( | ) | const |
Returns true if the frame is meant to be read only.
String TagLib::ID3v2::Frame::readStringField | ( | const ByteVector & | data, |
String::Type | encoding, | ||
int * | positon = 0 |
||
) | [protected] |
Reads a String of type encoding from the ByteVector data. If position is passed in it is used both as the starting point and is updated to return the position just after the string that has been read. This is useful for reading strings sequentially.
ByteVector TagLib::ID3v2::Frame::render | ( | ) | const |
Render the frame back to its binary format in a ByteVector.
Reimplemented from TagLib::ID3v2::Header.
ByteVector TagLib::ID3v2::Frame::render | ( | ) | const |
Render the Header back to binary format in a ByteVector.
Reimplemented from TagLib::ID3v2::Header.
virtual ByteVector TagLib::ID3v2::Frame::renderFields | ( | ) | const [protected, pure virtual] |
Render the field data back to a binary format in a ByteVector. This must be overridden by subclasses.
Implemented in TagLib::ID3v2::AttachedPictureFrame, TagLib::ID3v2::ChapterFrame, TagLib::ID3v2::CommentsFrame, TagLib::ID3v2::EventTimingCodesFrame, TagLib::ID3v2::GeneralEncapsulatedObjectFrame, TagLib::ID3v2::OwnershipFrame, TagLib::ID3v2::PopularimeterFrame, TagLib::ID3v2::PrivateFrame, TagLib::ID3v2::RelativeVolumeFrame, TagLib::ID3v2::SynchronizedLyricsFrame, TagLib::ID3v2::TableOfContentsFrame, TagLib::ID3v2::TextIdentificationFrame, TagLib::ID3v2::UniqueFileIdentifierFrame, TagLib::ID3v2::UnknownFrame, TagLib::ID3v2::UnsynchronizedLyricsFrame, TagLib::ID3v2::UrlLinkFrame, and TagLib::ID3v2::UserUrlLinkFrame.
void TagLib::ID3v2::Frame::setData | ( | const ByteVector & | data | ) |
Sets the data that will be used as the frame. Since the length is not known before the frame has been parsed, this should just be a pointer to the first byte of the frame. It will determine the length internally and make that available through size().
Reimplemented from TagLib::ID3v2::Header.
Reimplemented in TagLib::ID3v2::PrivateFrame.
void TagLib::ID3v2::Frame::setData | ( | const ByteVector & | data, |
uint | version = 4 |
||
) |
void TagLib::ID3v2::Frame::setData | ( | const ByteVector & | data, |
bool | synchSafeInts | ||
) |
Sets the data for the Header.
void TagLib::ID3v2::Frame::setFrameID | ( | const ByteVector & | id | ) |
Sets the frame's ID to id. Only the first four bytes of id will be used.
void TagLib::ID3v2::Frame::setFrameSize | ( | uint | size | ) |
Sets the size of the frame data portion.
void TagLib::ID3v2::Frame::setHeader | ( | Header * | h, |
bool | deleteCurrent = true |
||
) | [protected] |
Sets the header to h. If deleteCurrent is true, this will free the memory of the current header.
The ownership of this header will be assigned to the frame and the header will be deleted when the frame is destroyed.
void TagLib::ID3v2::Frame::setTagAlterPreservation | ( | bool | discard | ) |
Sets the flag for preservation of this frame if the tag is set. If this is set to true the frame will not be written when the tag is saved.
The semantics are a little backwards from what would seem natural (setting the preservation flag to throw away the frame), but this follows the ID3v2 standard.
virtual void TagLib::ID3v2::Frame::setText | ( | const String & | text | ) | [virtual] |
Set the text of frame in the sanest way possible. This should only be reimplemented in frames where there is some logical mapping to text.
Reimplemented in TagLib::ID3v2::CommentsFrame, TagLib::ID3v2::TextIdentificationFrame, TagLib::ID3v2::UserTextIdentificationFrame, TagLib::ID3v2::UnsynchronizedLyricsFrame, and TagLib::ID3v2::UrlLinkFrame.
void TagLib::ID3v2::Frame::setVersion | ( | uint | version | ) |
Sets the ID3v2 version of the header, changing has impact on the correct parsing/rendering of frame data.
Returns the size of the frame header in bytes for the ID3v2 version that's given.
uint TagLib::ID3v2::Frame::size | ( | ) | const |
Returns the size of the frame.
static uint TagLib::ID3v2::Frame::size | ( | ) | [static] |
Returns the size of the frame header in bytes.
Reimplemented from TagLib::ID3v2::Header.
static void TagLib::ID3v2::Frame::splitProperties | ( | const PropertyMap & | original, |
PropertyMap & | singleFrameProperties, | ||
PropertyMap & | tiplProperties, | ||
PropertyMap & | tmclProperties | ||
) | [static, protected] |
This helper function splits the PropertyMap original into three ProperytMaps singleFrameProperties, tiplProperties, and tmclProperties, such that:
bool TagLib::ID3v2::Frame::tagAlterPreservation | ( | ) | const |
Returns true if the flag for tag alter preservation is set.
The semantics are a little backwards from what would seem natural (setting the preservation flag to throw away the frame), but this follows the ID3v2 standard.
static ByteVector TagLib::ID3v2::Frame::textDelimiter | ( | String::Type | t | ) | [static] |
Returns the text delimiter that is used between fields for the string type t.
virtual String TagLib::ID3v2::Frame::toString | ( | ) | const [pure virtual] |
This returns the textual representation of the data in the frame. Subclasses must reimplement this method to provide a string representation of the frame's data.
Implemented in TagLib::ID3v2::AttachedPictureFrame, TagLib::ID3v2::ChapterFrame, TagLib::ID3v2::CommentsFrame, TagLib::ID3v2::EventTimingCodesFrame, TagLib::ID3v2::GeneralEncapsulatedObjectFrame, TagLib::ID3v2::OwnershipFrame, TagLib::ID3v2::PopularimeterFrame, TagLib::ID3v2::PrivateFrame, TagLib::ID3v2::RelativeVolumeFrame, TagLib::ID3v2::SynchronizedLyricsFrame, TagLib::ID3v2::TableOfContentsFrame, TagLib::ID3v2::TextIdentificationFrame, TagLib::ID3v2::UserTextIdentificationFrame, TagLib::ID3v2::UniqueFileIdentifierFrame, TagLib::ID3v2::UnknownFrame, TagLib::ID3v2::UnsynchronizedLyricsFrame, TagLib::ID3v2::UrlLinkFrame, and TagLib::ID3v2::UserUrlLinkFrame.
Returns a free-form tag name for the given ID3 frame description.
bool TagLib::ID3v2::Frame::unsynchronisation | ( | ) | const |
Returns true if unsynchronisation is enabled for this frame.
Reimplemented from TagLib::ID3v2::Header.
uint TagLib::ID3v2::Frame::version | ( | ) | const |
Returns the ID3v2 version of the header, as passed in from the construction of the header or set via setVersion().
friend class FrameFactory [friend] |
Reimplemented in TagLib::ID3v2::AttachedPictureFrame, TagLib::ID3v2::AttachedPictureFrameV22, TagLib::ID3v2::ChapterFrame, TagLib::ID3v2::CommentsFrame, TagLib::ID3v2::EventTimingCodesFrame, TagLib::ID3v2::GeneralEncapsulatedObjectFrame, TagLib::ID3v2::OwnershipFrame, TagLib::ID3v2::PopularimeterFrame, TagLib::ID3v2::PrivateFrame, TagLib::ID3v2::RelativeVolumeFrame, TagLib::ID3v2::SynchronizedLyricsFrame, TagLib::ID3v2::TableOfContentsFrame, TagLib::ID3v2::TextIdentificationFrame, TagLib::ID3v2::UserTextIdentificationFrame, TagLib::ID3v2::UniqueFileIdentifierFrame, TagLib::ID3v2::UnknownFrame, TagLib::ID3v2::UnsynchronizedLyricsFrame, TagLib::ID3v2::UrlLinkFrame, and TagLib::ID3v2::UserUrlLinkFrame.
friend class FramePrivate [friend] |
friend class Tag [friend] |
const String TagLib::ID3v2::Frame::commentPrefix [static] |
The PropertyMap key prefix which triggers the use of a COMM frame instead of a TXXX frame for a non-standard key. In the current implementation, this is "COMMENT:".
const String TagLib::ID3v2::Frame::instrumentPrefix [static] |
The string with which an instrument name is prefixed to build a key in a PropertyMap; used to translate PropertyMaps to TMCL frames. In the current implementation, this is "PERFORMER:".
const String TagLib::ID3v2::Frame::lyricsPrefix [static] |
The PropertyMap key prefix which triggers the use of a USLT frame instead of a TXXX frame for a non-standard key. In the current implementation, this is "LYRICS:".
const String TagLib::ID3v2::Frame::urlPrefix [static] |
The PropertyMap key prefix which triggers the use of a WXXX frame instead of a TXX frame for a non-standard key. In the current implementation, this is "URL:".