TagLib 1.6.1 (TagLib: TagLib::ID3v2::Frame Class Reference)

TagLib::ID3v2::Frame Class Reference

ID3v2 frame implementation. More...

#include <id3v2frame.h>

Inheritance diagram for TagLib::ID3v2::Frame:
Collaboration diagram for TagLib::ID3v2::Frame:

List of all members.

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
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 uint headerSize ()
static uint headerSize (uint version)
static ByteVector textDelimiter (String::Type t)
static uint size ()
static uint size (uint version)

Protected Member Functions

 Frame (const ByteVector &data)
 Frame (Header *h)
Headerheader () 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)

Static Protected Member Functions

static String::Type checkEncoding (const StringList &fields, String::Type encoding)

Friends

class Tag
class FrameFactory
class FramePrivate


Detailed Description

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.


Constructor & Destructor Documentation

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.

Note:
This need not contain anything more than a frame ID, but must constain at least that.

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.


Member Function Documentation

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.

bool TagLib::ID3v2::Frame::compression (  )  const

Returns true if compression is enabled for this frame.

Note:
This flag is currently ignored internally in TagLib.

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.

Note:
This flag is currently ignored internally in TagLib.

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.

Note:
This flag is currently ignored internally in TagLib.

bool TagLib::ID3v2::Frame::frameAlterPreservation (  )  const

ByteVector TagLib::ID3v2::Frame::frameID (  )  const

Returns the Frame ID (Structure, 4) (Frames, 4)

ByteVector TagLib::ID3v2::Frame::frameID (  )  const

Returns the Frame ID (Structure, 4) (Frames, 4)

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 identifity is set.

Note:
This flag is currently ignored internally in TagLib.

TagLib::ID3v2::Frame::Header ( const ByteVector data,
uint  version = 4 
) [explicit]

Construct a Frame Header based on data. data must at least contain a 4 byte frame ID, and optionally can contain flag data and the frame size. i.e. Just the frame id -- "TALB" -- is a valid value.

version should be the ID3v2 version of the tag.

TagLib::ID3v2::Frame::Header ( const ByteVector data,
bool  synchSafeInts 
)

Construct a Frame Header based on data. data must at least contain a 4 byte frame ID, and optionally can contain flag data and the frame size. i.e. Just the frame id -- "TALB" -- is a valid value.

Header* TagLib::ID3v2::Frame::header (  )  const [protected]

Returns a pointer to the frame header.

static uint TagLib::ID3v2::Frame::headerSize ( uint  version  )  [static]

Returns the size of the frame header for the given ID3v2 version.

static uint TagLib::ID3v2::Frame::headerSize (  )  [static]

Returns the size of the frame header

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.

bool TagLib::ID3v2::Frame::readOnly (  )  const

Returns true if the frame is meant to be read only.

Note:
This flag is currently ignored internally in TagLib.

String TagLib::ID3v2::Frame::readStringField ( const ByteVector data,
String::Type  encoding,
int *  positon = 0 
) [protected]

Reads a String of type encodiong from the ByteVector data. If position is passed in it is used both as the starting point and is updated to replect 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 Header back to binary format in a ByteVector.

Reimplemented from TagLib::ID3v2::Header.

ByteVector TagLib::ID3v2::Frame::render (  )  const

Render the frame back to its binary format in a ByteVector.

Reimplemented from TagLib::ID3v2::Header.

void TagLib::ID3v2::Frame::setData ( const ByteVector data,
uint  version = 4 
)

Sets the data for the Header. version should indicate the ID3v2 version number of the tag that this frame is contained in.

void TagLib::ID3v2::Frame::setData ( const ByteVector data,
bool  synchSafeInts 
)

Sets the data for the Header.

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::setFrameID ( const ByteVector id  ) 

Sets the frame's ID to id. Only the first four bytes of id will be used.

Warning:
This method should in general be avoided. It exists simply to provide a mechanism for transforming frames from a deprecated frame type to a newer one -- i.e. TYER to TDRC from ID3v2.3 to ID3v2.4.

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.

See also:
tagAlterPreservation()

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.

Note:
If the frame type supports multiple text encodings, this will not change the text encoding of the frame; the string will be converted to that frame's encoding. Please use the specific APIs of the frame types to set the encoding if that is desired.

Reimplemented in TagLib::ID3v2::CommentsFrame, TagLib::ID3v2::TextIdentificationFrame, TagLib::ID3v2::UserTextIdentificationFrame, TagLib::ID3v2::UnsynchronizedLyricsFrame, and TagLib::ID3v2::UrlLinkFrame.

static uint TagLib::ID3v2::Frame::size ( uint  version  )  [static]

Returns the size of the frame header in bytes for the ID3v2 version that's given.

static uint TagLib::ID3v2::Frame::size (  )  [static]

Returns the size of the frame header in bytes.

Reimplemented from TagLib::ID3v2::Header.

uint TagLib::ID3v2::Frame::size (  )  const

Returns the size of the frame.

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.

See also:
setTagAlterPreservation()

static ByteVector TagLib::ID3v2::Frame::textDelimiter ( String::Type  t  )  [static]

Returns the text delimiter that is used between fields for the string type t.

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).


Friends And Related Function Documentation

friend class FramePrivate [friend]

friend class Tag [friend]


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