#include <tag.h>
Inheritance diagram for ID3_Tag::
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_Frame * | RemoveFrame (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_Frame * | Find (ID3_FrameID id) const |
Finds frame with given frame id. More... | |
ID3_Frame * | Find (ID3_FrameID id, ID3_FieldID fld, uint32 data) const |
Finds frame with given frame id, fld id, and integer data. More... | |
ID3_Frame * | Find (ID3_FrameID id, ID3_FieldID fld, const char *) const |
Finds frame with given frame id, fld id, and ascii data. More... | |
ID3_Frame * | Find (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_Frame * | GetFrameNum (size_t) const |
ID3_Frame * | operator[] (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_Elem * | Find (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... |
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:
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.
|
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).
|
|
Standard copy constructor.
|
|
|
|
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.
|
|
|
|
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);
|
|
|
|
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.
|
|
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. |
|
|
|
Finds frame with given frame id, fld id, and unicode data.
|
|
Finds frame with given frame id, fld id, and ascii data.
|
|
Finds frame with given frame id, fld id, and integer data.
|
|
Finds frame with given frame id.
|
|
|
|
|
|
|
|
|
|
|
|
Reimplemented from ID3_Speccable. |
|
|
|
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 }
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 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; }
|
|
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.
|
|
|
|
|
|
|
|
|
|
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); }
|
|
|
|
|
|
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.
|
|
|
|
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);
|
|
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);
|
|
Reimplemented from ID3_Speccable. |
|
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);
|
|
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; } } }
|
|
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.
|
|
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.
|
|
|
|
|