Main Page   Class Hierarchy   Compound List   File List   Compound Members   File Members  

ID3_Tag Class Reference

The representative class of an id3 tag. More...

#include <tag.h>

Inheritance diagram for ID3_Tag::

ID3_Speccable List of all members.

Public Methods

 ID3_Tag (const char *name=((void *) 0))
 Default constructor; it can accept an optional filename as a parameter. More...

 ID3_Tag (const ID3_Tag &tag)
 Standard copy constructor. More...

virtual ~ID3_Tag ()
void Clear ()
 Clears the object and disassociates it from any files. More...

bool HasChanged () const
 Indicates whether the tag has been altered since the last parse, render, or update. More...

size_t Size () const
 Returns an over estimate of the number of bytes required to store a binary version of a tag. More...

bool SetUnsync (bool bSync)
 Turns unsynchronization on or off, dependant on the value of the boolean parameter. More...

bool SetExtendedHeader (bool bExt)
 Turns extended header rendering on or off, dependant on the value of the boolean parameter. More...

bool SetPadding (bool bPad)
 Turns padding on or off, dependant on the value of the boolean parameter. More...

void AddFrame (const ID3_Frame &)
void AddFrame (const ID3_Frame *)
 Attaches a frame to the tag; the tag doesn't take responsibility for releasing the frame's memory when tag goes out of scope. More...

void AttachFrame (ID3_Frame *)
 Attaches a frame to the tag; the tag takes responsibility for releasing the frame's memory when tag goes out of scope. More...

ID3_FrameRemoveFrame (const ID3_Frame *)
 Removes a frame from the tag. More...

size_t Parse (const uchar *, size_t)
size_t Parse (const uchar header[(10)], const uchar *buffer)
size_t Render (uchar *, ID3_TagType=ID3TT_ID3V2) const
size_t Link (const char *fileInfo, flags_t=(flags_t) ID3TT_ALL)
 Attaches a file to the tag, parses the file, and adds any tag information found in the file to the tag. More...

flags_t Update (flags_t=(flags_t) ID3TT_ALL)
 Renders the tag and writes it to the attached file; the type of tag rendered can be specified as a parameter. More...

flags_t Strip (flags_t=(flags_t) ID3TT_ALL)
 Strips the tag(s) from the attached file. More...

size_t GetPrependedBytes () const
size_t GetAppendedBytes () const
size_t GetFileSize () const
const char * GetFileName () const
ID3_FrameFind (ID3_FrameID id) const
 Finds frame with given frame id. More...

ID3_FrameFind (ID3_FrameID id, ID3_FieldID fld, uint32 data) const
 Finds frame with given frame id, fld id, and integer data. More...

ID3_FrameFind (ID3_FrameID id, ID3_FieldID fld, const char *) const
 Finds frame with given frame id, fld id, and ascii data. More...

ID3_FrameFind (ID3_FrameID id, ID3_FieldID fld, const unicode_t *) const
 Finds frame with given frame id, fld id, and unicode data. More...

size_t NumFrames () const
 Returns the number of frames present in the tag object. More...

ID3_FrameGetFrameNum (size_t) const
ID3_Frameoperator[] (size_t) const
ID3_Tag & operator= (const ID3_Tag &)
bool GetUnsync () const
bool HasTagType (uint16 tt) const
ID3_V2Spec GetSpec () const
void AddNewFrame (ID3_Frame *f)
size_t Link (const char *fileInfo, bool parseID3v1, bool parseLyrics3)
void SetCompression (bool)
void AddFrames (const ID3_Frame *, size_t)
 Copies an array of frames to the tag. More...

bool HasLyrics () const
bool HasV2Tag () const
bool HasV1Tag () const

Static Public Methods

size_t IsV2Tag (const uchar *)

Protected Methods

bool SetSpec (ID3_V2Spec)
ID3_ElemFind (const ID3_Frame *) const
size_t PaddingSize (size_t) const
void RenderExtHeader (uchar *)
void ParseFile ()
size_t RenderV2 (uchar *) const
 Renders a binary image of the tag into the supplied buffer. More...


Detailed Description

The representative class of an id3 tag.

This is the 'container' class for everything else. It is through an ID3_Tag that most of the productive stuff happens. Let's look at what's required to start using ID3v2 tags.

   #include <id3/tag.h>

This simple #include does it all. In order to read an existing tag, do the following:

   ID3_Tag myTag;
   myTag.Link("something.mp3");

That is all there is to it. Now all you have to do is use the Find() method to locate the frames you are interested in is the following:

   ID3_Frame *myFrame;
   if (myTag.Find(ID3FID_TITLE) == myFrame)
   {
     char title[1024];
     myFrame->Field(ID3FN_TEXT).Get(title, 1024);
     cout << "Title: " << title << endl;
   }

This code snippet locates the ID3FID_TITLE frame and copies the contents of the text field into a buffer and displays the buffer. Not difficult, eh?

When using the ID3_Tag::Link() method, you automatically gain access to any ID3v1/1.1, ID3v2, and Lyrics3 v2.0 tags present in the file. The class will automaticaly parse and convert any of these foreign tag formats into ID3v2 tags. Also, id3lib will correctly parse any correctly formatted 'CDM' frames from the unreleased ID3v2 2.01 draft specification.

Author:
Dirk Mahoney
Version:
Id:
tag.cpp,v 1.25 2000/09/11 07:46:32 eldamitri Exp
See also:
ID3_Frame , ID3_Field , ID3_Err


Constructor & Destructor Documentation

ID3_Tag::ID3_Tag const char * name = ((void*) 0)
 

Default constructor; it can accept an optional filename as a parameter.

If this file exists, it will be opened and all id3lib-supported tags will be parsed and converted to id3v2 if necessary. After the conversion, the file will remain unchanged, and will continue to do so until you use the Update() method on the tag (if you choose to Update() at all).

Parameters:
name   The filename of the mp3 file to link to

ID3_Tag::ID3_Tag const ID3_Tag & tag
 

Standard copy constructor.

Parameters:
tag   What is copied into this tag

ID3_Tag::~ID3_Tag [virtual]
 


Member Function Documentation

void ID3_Tag::AddFrame const ID3_Frame * frame
 

Attaches a frame to the tag; the tag doesn't take responsibility for releasing the frame's memory when tag goes out of scope.

Optionally, operator<< can also be used to attach a frame to a tag. To use, simply supply its parameter a pointer to the ID3_Frame object you wish to attach.

   ID3_Frame myFrame;
   myTag.AddFrame(&myFrame);

As stated, this method attaches the frames to the tag---the tag does not create its own copy of the frame. Frames created by an application must exist until the frame is removed or the tag is finished with it.

Parameters:
pFrame   A pointer to the frame that is being added to the tag.
See also:
ID3_Frame

void ID3_Tag::AddFrame const ID3_Frame & frame
 

void ID3_Tag::AddFrames const ID3_Frame * frames,
size_t numFrames
 

Copies an array of frames to the tag.

This method copies each frame in an array to the tag. As in AddFrame, the tag adds a copy of the frame, and it assumes responsiblity for freeing the frames' memory when the tag goes out of scope.

   ID3_Frame myFrames[10];
   myTag.AddFrames(myFrames, 10);

See also:
ID3_Frame , ID3_Frame::AddFrame
Parameters:
pNewFrames   A pointer to an array of frames to be added to the tag.
nFrames   The number of frames in the array pNewFrames.

void ID3_Tag::AddNewFrame ID3_Frame * f [inline]
 

void ID3_Tag::AttachFrame ID3_Frame * frame
 

Attaches a frame to the tag; the tag takes responsibility for releasing the frame's memory when tag goes out of scope.

This method accepts responsibility for the attached frame's memory, and will delete the frame and its contents when the tag goes out of scope or is deleted. Therefore, be sure the frame isn't "Attached" to other tags.

   ID3_Frame *frame = new ID3_Frame;
   myTag.AttachFrame(frame);
Parameters:
frame   A pointer to the frame that is being added to the tag.

void ID3_Tag::Clear
 

Clears the object and disassociates it from any files.

It frees any resources for which the object is responsible, and the object is now free to be used again for any new or existing tag.

ID3_Elem * ID3_Tag::Find const ID3_Frame * frame const [protected]
 

ID3_Frame * ID3_Tag::Find ID3_FrameID id,
ID3_FieldID fld,
const unicode_t * data
const
 

Finds frame with given frame id, fld id, and unicode data.

ID3_Frame * ID3_Tag::Find ID3_FrameID id,
ID3_FieldID fld,
const char * data
const
 

Finds frame with given frame id, fld id, and ascii data.

ID3_Frame * ID3_Tag::Find ID3_FrameID id,
ID3_FieldID fld,
uint32 data
const
 

Finds frame with given frame id, fld id, and integer data.

ID3_Frame * ID3_Tag::Find ID3_FrameID id const
 

Finds frame with given frame id.

size_t ID3_Tag::GetAppendedBytes const [inline]
 

const char* ID3_Tag::GetFileName const [inline]
 

size_t ID3_Tag::GetFileSize const [inline]
 

ID3_Frame* ID3_Tag::GetFrameNum size_t const
 

size_t ID3_Tag::GetPrependedBytes const [inline]
 

ID3_V2Spec ID3_Tag::GetSpec const [virtual]
 

Reimplemented from ID3_Speccable.

bool ID3_Tag::GetUnsync const [inline]
 

bool ID3_Tag::HasChanged const
 

Indicates whether the tag has been altered since the last parse, render, or update.

If you have a tag linked to a file, you do not need this method since the Update() method will check for changes before writing the tag.

This method is primarily intended as a status indicator for applications and for applications that use the Parse() and Render() methods.

Setting a field, changed the ID of an attached frame, setting or grouping or encryption IDs, and clearing a frame or field all constitute a change to the tag, as do calls to the SetUnsync(), SetExtendedHeader(), and SetPadding() methods.

   if (myTag.HasChanged())
   {
     // render and output the tag
   }

Returns:
Whether or not the tag has been altered.

bool ID3_Tag::HasLyrics const [inline]
 

bool ID3_Tag::HasTagType uint16 tt const [inline]
 

bool ID3_Tag::HasV1Tag const [inline]
 

bool ID3_Tag::HasV2Tag const [inline]
 

size_t ID3_Tag::IsV2Tag const uchar * [static]
 

size_t ID3_Tag::Link const char * fileInfo,
bool parseID3v1,
bool parseLyrics3
 

size_t ID3_Tag::Link const char * fileInfo,
flags_t tag_types = (flags_t) ID3TT_ALL
 

Attaches a file to the tag, parses the file, and adds any tag information found in the file to the tag.

Use this method if you created your ID3_Tag object without supplying a parameter to the constructor (maybe you created an array of ID3_Tag pointers). This is the preferred method of interacting with files, since id3lib can automatically do things like parse foreign tag formats and handle padding when linked to a file. When a tag is linked to a file, you do not need to use the Size, Render, or Parse methods or the ID3_IsTagHeader function---id3lib will take care of those details for you. The single parameter is a pointer to a file name.

Link returns a 'luint' which is the byte position within the file that the audio starts (i.e., where the id3v2 tag ends).

   ID3_Tag *myTag;
   if (myTag = new ID3_Tag)
   {
     myTag->Link("mysong.mp3");
     
     // do whatever we want with the tag
     // ...
   
     // setup all our rendering parameters
     myTag->SetUnsync(false);
     myTag->SetExtendedHeader(true);
     myTag->SetCompression(true);
     myTag->SetPadding(true);
     
     // write any changes to the file
     myTag->Update()
     
     // free the tag
     delete myTag;
   }

See also:
ID3_IsTagHeader
Parameters:
fileInfo   The filename of the file to link to.

size_t ID3_Tag::NumFrames const [inline]
 

Returns the number of frames present in the tag object.

This includes only those frames that id3lib recognises. This is used as the upper bound on calls to the GetFrame() and operator[]() methods.

Returns:
The number of frames present in the tag object.

size_t ID3_Tag::PaddingSize size_t curSize const [protected]
 

size_t ID3_Tag::Parse const uchar header[(10)],
const uchar * buffer
 

size_t ID3_Tag::Parse const uchar * ,
size_t
 

void ID3_Tag::ParseFile [protected]
 

ID3_Frame * ID3_Tag::RemoveFrame const ID3_Frame * frame
 

Removes a frame from the tag.

If you already own the frame object in question, then you should already have a pointer to the frame you want to delete. If not, or if you wish to delete a pre-existing frame (from a tag you have parsed, for example), the use one of the Find methods to obtain a frame pointer to pass to this method.

   ID3_Frame *someFrame;
   if (someFrame = myTag.Find(ID3FID_TITLE))
   {
     myTag.RemoveFrame(someFrame);
   }

See also:
ID3_Tag::Find
Parameters:
pOldFrame   A pointer to the frame that is to be removed from the tag

size_t ID3_Tag::Render uchar * buffer,
ID3_TagType tt = ID3TT_ID3V2
const
 

void ID3_Tag::RenderExtHeader uchar * buffer [protected]
 

size_t ID3_Tag::RenderV2 uchar * buffer const [protected]
 

Renders a binary image of the tag into the supplied buffer.

See Size for an example. This method returns the actual number of the bytes of the buffer used to store the tag. This will be no more than the size of the buffer itself, because Size over estimates the required buffer size when padding is enabled.

Before calling this method, it is advisable to call HasChanged first as this will let you know whether you should bother rendering the tag.

See also:
ID3_IsTagHeader , ID3_Tag::HasChanged
Returns:
The actual number of the bytes of the buffer used to store the tag
Parameters:
buffer   The buffer that will contain the rendered tag.

void ID3_Tag::SetCompression bool [inline]
 

bool ID3_Tag::SetExtendedHeader bool ext
 

Turns extended header rendering on or off, dependant on the value of the boolean parameter.

This option is currently ignored as id3lib doesn't yet create extended headers. This option only applies when rendering tags for id3v2 versions that support extended headers.

By default, id3lib will generate extended headers for all tags in which extended headers are supported.

   myTag.SetExtendedHeader(true);
Parameters:
bExt   Whether to render an extended header

bool ID3_Tag::SetPadding bool pad
 

Turns padding on or off, dependant on the value of the boolean parameter.

When using id3v2 tags in association with files, id3lib can optionally add padding to the tags to ensure minmal file write times when updating the tag in the future.

When the padding option is switched on, id3lib automatically creates padding according to the 'ID3v2 Programming Guidelines'. Specifically, enough padding will be added to round out the entire file (song plus tag) to an even multiple of 2K. Padding will only be created when the tag is attached to a file and that file is not empty (aside from a pre-existing tag).

id3lib's addition to the guidelines for padding, is that if frames are removed from a pre-existing tag (or the tag simply shrinks because of other reasons), the new tag will continue to stay the same size as the old tag (with padding making the difference of course) until such time as the padding is greater than 4K. When this happens, the padding will be reduced and the new tag will be smaller than the old.

By default, padding is switched on.

   myTag.SetPadding(false);
Parameters:
bPad   Whether or not render the tag with padding.

bool ID3_Tag::SetSpec ID3_V2Spec spec [protected, virtual]
 

Reimplemented from ID3_Speccable.

bool ID3_Tag::SetUnsync bool b
 

Turns unsynchronization on or off, dependant on the value of the boolean parameter.

If you call this method with 'false' as the parameter, the binary tag will not be unsync'ed, regardless of whether the tag should be. This option is useful when the file is only going to be used by ID3v2-compliant software. See the id3v2 standard document for futher details on unsync.

Be default, tags are created without unsync.

   myTag.SetUnsync(false);
Parameters:
bSync   Whether the tag should be unsynchronized

size_t ID3_Tag::Size const
 

Returns an over estimate of the number of bytes required to store a binary version of a tag.

When using Render to render a binary tag to a memory buffer, first use the result of this call to allocate a buffer of unsigned chars.

   luint tagSize;
   uchar *buffer;
   if (myTag.HasChanged())
   {
     if ((tagSize= myTag.Size()) > 0)
     {
       if (buffer = new uchar[tagSize])
       {
         luint actualSize = myTag.Render(buffer);
         // do something useful with the first
         // 'actualSize' bytes of the buffer,
         // like push it down a socket
         delete [] buffer;
       }
     }
   }

See also:
Render
Returns:
The (overestimated) number of bytes required to store a binary version of a tag

flags_t ID3_Tag::Strip flags_t ulTagFlag = (flags_t) ID3TT_ALL
 

Strips the tag(s) from the attached file.

The type of tag stripped can be specified as a parameter. The default is to strip all tag types.

Parameters:
tt   The type of tag to strip
See also:
ID3_TagType@see

flags_t ID3_Tag::Update flags_t ulTagFlag = (flags_t) ID3TT_ALL
 

Renders the tag and writes it to the attached file; the type of tag rendered can be specified as a parameter.

The default is to update only the ID3v2 tag. See the ID3_TagType enumeration for the constants that can be used.

Make sure the rendering parameters are set before calling the method. See the Link dcoumentation for an example of this method in use.

See also:
ID3_TagType , Link
Parameters:
tt   The type of tag to update.

ID3_Tag & ID3_Tag::operator= const ID3_Tag & rTag
 

ID3_Frame* ID3_Tag::operator[] size_t const
 


The documentation for this class was generated from the following files:
Generated at Wed Sep 5 16:53:39 2001 for id3lib by doxygen1.2.9.1 written by Dimitri van Heesch, © 1997-2001