#include <id3/tag.h>
Public Methods | |
ID3_Tag (const char *name=NULL) | |
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) |
Turns unsynchronization on or off, dependant on the value of the boolean parameter. More... | |
bool | SetExtendedHeader (bool) |
Turns extended header rendering on or off, dependant on the value of the boolean parameter. More... | |
bool | SetExperimental (bool) |
bool | GetUnsync () const |
bool | GetExtendedHeader () const |
bool | GetExperimental () const |
bool | SetPadding (bool) |
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) |
bool | Parse (ID3_Reader &reader) |
size_t | Render (uchar *, ID3_TagType=ID3TT_ID3V2) const |
Renders a binary image of the tag into the supplied buffer. More... | |
size_t | Render (ID3_Writer &, 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) |
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) const |
ID3_Frame * | Find (ID3_FrameID, ID3_FieldID, uint32) const |
Finds frame with given frame id, fld id, and integer data. More... | |
ID3_Frame * | Find (ID3_FrameID, ID3_FieldID, const char *) const |
Finds frame with given frame id, fld id, and ascii data. More... | |
ID3_Frame * | Find (ID3_FrameID, ID3_FieldID, 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... | |
Iterator * | CreateIterator () |
ConstIterator * | CreateIterator () const |
ID3_Tag & | operator= (const ID3_Tag &) |
bool | HasTagType (uint16 tt) const |
ID3_V2Spec | GetSpec () const |
bool | SetSpec (ID3_V2Spec) |
void | AddNewFrame (ID3_Frame *f) |
Deprecated. More... | |
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 |
size_t | Parse (const uchar header[ID3_TAGHEADERSIZE], const uchar *buffer) |
Turns a binary tag into a series of ID3_Frame objects attached to the tag. More... | |
ID3_Tag & | operator<< (const ID3_Frame &) |
ID3_Tag & | operator<< (const ID3_Frame *) |
ID3_Tag (const char *name=NULL) | |
ID3_Tag (const ID3_Tag &tag) | |
virtual | ~ID3_Tag () |
void | Clear () |
bool | HasChanged () const |
size_t | Size () const |
bool | SetUnsync (bool) |
bool | SetExtendedHeader (bool) |
bool | SetExperimental (bool) |
bool | GetUnsync () const |
bool | GetExtendedHeader () const |
bool | GetExperimental () const |
bool | SetPadding (bool) |
void | AddFrame (const ID3_Frame &) |
void | AddFrame (const ID3_Frame *) |
void | AttachFrame (ID3_Frame *) |
ID3_Frame * | RemoveFrame (const ID3_Frame *) |
size_t | Parse (const uchar *, size_t) |
bool | Parse (ID3_Reader &reader) |
size_t | Render (uchar *, ID3_TagType=ID3TT_ID3V2) const |
size_t | Render (ID3_Writer &, ID3_TagType=ID3TT_ID3V2) const |
size_t | Link (const char *fileInfo, flags_t=(flags_t) ID3TT_ALL) |
flags_t | Update (flags_t=(flags_t) ID3TT_ALL) |
flags_t | Strip (flags_t=(flags_t) ID3TT_ALL) |
size_t | GetPrependedBytes () const |
size_t | GetAppendedBytes () const |
size_t | GetFileSize () const |
const char * | GetFileName () const |
ID3_Frame * | Find (ID3_FrameID) const |
ID3_Frame * | Find (ID3_FrameID, ID3_FieldID, uint32) const |
ID3_Frame * | Find (ID3_FrameID, ID3_FieldID, const char *) const |
ID3_Frame * | Find (ID3_FrameID, ID3_FieldID, const unicode_t *) const |
size_t | NumFrames () const |
Iterator * | CreateIterator () |
ConstIterator * | CreateIterator () const |
ID3_Tag & | operator= (const ID3_Tag &) |
bool | HasTagType (uint16 tt) const |
ID3_V2Spec | GetSpec () const |
bool | SetSpec (ID3_V2Spec) |
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) |
bool | HasLyrics () const |
bool | HasV2Tag () const |
bool | HasV1Tag () const |
size_t | Parse (const uchar header[ID3_TAGHEADERSIZE], const uchar *buffer) |
ID3_Tag & | operator<< (const ID3_Frame &) |
ID3_Tag & | operator<< (const ID3_Frame *) |
Static Public Methods | |
size_t | IsV2Tag (const uchar *) |
size_t | IsV2Tag (ID3_Reader &) |
size_t | IsV2Tag (const uchar *) |
size_t | IsV2Tag (ID3_Reader &) |
The ID3_Tag is, at its simplest, a container for ID3v2 frames. At its most complicated, it's a kitchen-sink, monolithic "catch-all" class for handling almost every task associated with creating, parsing, rendering, and manipulating digital audio data using id3lib.
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 = myTag.Find(ID3FID_TITLE); if (NULL != myFrame) { const char* title = myFrame->GetField(ID3FN_TEXT)->GetText(); cout << "Title: " << title << endl; }
This code snippet locates the ID3FID_TITLE frame and displays the text field.
When using the ID3_Tag::Link() method, you automatically gain access to any ID3v1/1.1, ID3v2, Lyrics3 v2.0, and MusicMatch 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.
Definition at line 39 of file tag.h.
|
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.
Definition at line 508 of file tag.cpp. References ID3_TagImpl::AddFrame(). |
|
Definition at line 484 of file tag.cpp. References ID3_TagImpl::AddFrame(). Referenced by AddFrames(), and operator<<(). |
|
|
|
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);
Definition at line 968 of file tag.cpp. References AddFrame(). |
|
|
|
Deprecated.
Definition at line 947 of file tag.cpp. References ID3_TagImpl::AttachFrame(). |
|
|
|
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.
Definition at line 527 of file tag.cpp. References ID3_TagImpl::AttachFrame(). Referenced by ID3_AddAlbum(), ID3_AddArtist(), ID3_AddComment(), ID3_AddGenre(), ID3_AddLyricist(), ID3_AddLyrics(), ID3_AddSyncLyrics(), ID3_AddTitle(), ID3_AddTrack(), and ID3_AddYear(). |
|
|
|
Clears the object and disassociates it from any files. Frees any resources for which the object is responsible, including all frames and files. After a call to Clear(), the object can be used again for any new or existing tag. Definition at line 320 of file tag.cpp. References ID3_TagImpl::Clear(). |
|
|
|
|
|
|
|
Definition at line 1095 of file tag.cpp. Referenced by ID3_AddComment(), ID3_RemoveComments(), and ID3_TagImpl::operator=(). |
|
|
|
|
|
|
|
|
|
Finds frame with given frame id, fld id, and unicode data.
Definition at line 835 of file tag.cpp. References ID3_TagImpl::Find(), ID3_FieldID, ID3_FrameID, and unicode_t. |
|
Finds frame with given frame id, fld id, and ascii data.
Definition at line 828 of file tag.cpp. References ID3_TagImpl::Find(), ID3_FieldID, and ID3_FrameID. |
|
Finds frame with given frame id, fld id, and integer data.
Definition at line 822 of file tag.cpp. References ID3_TagImpl::Find(), ID3_FieldID, ID3_FrameID, and uint32. |
|
Definition at line 816 of file tag.cpp. References ID3_TagImpl::Find(), and ID3_FrameID. Referenced by ID3_AddAlbum(), ID3_AddArtist(), ID3_AddGenre(), ID3_AddLyricist(), ID3_AddLyrics(), ID3_AddSyncLyrics(), ID3_AddTitle(), ID3_AddTrack(), ID3_AddYear(), ID3_GetAlbum(), ID3_GetArtist(), ID3_GetComment(), ID3_GetGenre(), ID3_GetLyricist(), ID3_GetLyrics(), ID3_GetSyncLyrics(), ID3_GetSyncLyricsInfo(), ID3_GetTitle(), ID3_GetTrack(), ID3_GetYear(), ID3_RemoveAlbums(), ID3_RemoveArtists(), ID3_RemoveGenres(), ID3_RemoveLyricist(), ID3_RemoveLyrics(), ID3_RemoveTitles(), ID3_RemoveTracks(), and ID3_RemoveYears(). |
|
|
|
Definition at line 737 of file tag.cpp. References ID3_TagImpl::GetAppendedBytes(). |
|
|
|
Definition at line 479 of file tag.cpp. References ID3_TagImpl::GetExperimental(). Referenced by ID3_TagImpl::operator=(). |
|
|
|
Definition at line 474 of file tag.cpp. References ID3_TagImpl::GetExtended(). Referenced by ID3_TagImpl::operator=(). |
|
|
|
Definition at line 747 of file tag.cpp. References ID3_TagImpl::GetFileName(). |
|
|
|
Definition at line 742 of file tag.cpp. References ID3_TagImpl::GetFileSize(). |
|
|
|
Definition at line 732 of file tag.cpp. References ID3_TagImpl::GetPrependedBytes(). |
|
|
|
Definition at line 921 of file tag.cpp. References ID3_TagImpl::GetSpec(), and ID3_V2Spec. |
|
|
|
Definition at line 469 of file tag.cpp. References ID3_TagImpl::GetUnsync(). Referenced by ID3_TagImpl::operator=(). |
|
|
|
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 }
Definition at line 349 of file tag.cpp. References ID3_TagImpl::HasChanged(). |
|
|
|
Definition at line 986 of file tag.cpp. References HasTagType(), and ID3TT_LYRICS. |
|
|
|
Definition at line 916 of file tag.cpp. References ID3_TagImpl::HasTagType(), and uint16. Referenced by HasLyrics(). |
|
|
|
Definition at line 994 of file tag.cpp. References ID3TT_ID3V1. |
|
|
|
Definition at line 990 of file tag.cpp. References ID3TT_ID3V2. |
|
|
|
|
|
Definition at line 941 of file tag.cpp. References ID3_TagImpl::IsV2Tag(). |
|
Referenced by ID3_IsTagHeader(), Parse(), and ID3_TagHeader::Parse(). |
|
|
|
|
|
Definition at line 976 of file tag.cpp. References ID3_TagImpl::Link(). |
|
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(const uchar*, size_t), or Parse(ID3_Reader&) methods or the IsV2Tag(ID3_Reader&) static function-- id3lib will take care of those details for you. The single parameter is a pointer to a file name. Link returns the size of the the ID3v2 tag (if any) that begins the file.
ID3_Tag myTag; 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()
Definition at line 711 of file tag.cpp. References flags_t, and ID3_TagImpl::Link(). |
|
|
|
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.
Definition at line 848 of file tag.cpp. References ID3_TagImpl::NumFrames(). |
|
|
|
|
|
Definition at line 1025 of file tag.cpp. References AddFrame(). |
|
Definition at line 1018 of file tag.cpp. References AddFrame(). |
|
|
|
|
|
|
|
|
|
|
|
Turns a binary tag into a series of ID3_Frame objects attached to the tag.
ID3_Tag myTag; uchar header[ID3_TAGHEADERSIZE]; uchar *buffer; luint tagSize; // get ID3_TAGHEADERSIZE from a socket or somewhere // ... if ((tagSize = ID3_IsTagHeader(ourSourceBuffer)) > -1) { // read a further 'tagSize' bytes in // from our data source // ... if (buffer = new uchar[tagSize]) { // now we will call ID3_Tag::Parse() // with these values (explained later) myTag.Parse(header, buffer); // do something with the objects, // like look for titles, artists, etc. // ... // free the buffer delete [] buffer; } }
Definition at line 610 of file tag.cpp. References ID3_TAGHEADERSIZE, IsV2Tag(), Parse(), ID3_TagHeader::SIZE, and uchar. |
|
|
|
Definition at line 563 of file tag.cpp. References ID3_MemoryReader::getCur(), ID3_MemoryReader::getEnd(), ID3_Reader::pos_type, and uchar. Referenced by Parse(). |
|
|
|
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); }
Definition at line 553 of file tag.cpp. References ID3_TagImpl::RemoveFrame(). Referenced by ID3_AddSyncLyrics(), ID3_RemoveAlbums(), ID3_RemoveArtists(), ID3_RemoveComments(), ID3_RemoveGenres(), ID3_RemoveLyricist(), ID3_RemoveLyrics(), ID3_RemoveTitles(), ID3_RemoveTracks(), and ID3_RemoveYears(). |
|
|
|
|
|
Definition at line 660 of file tag.cpp. References ID3_Writer::getCur(), ID3_TagType, ID3TT_ID3V1, ID3TT_ID3V2, and ID3_Writer::pos_type. |
|
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.
Definition at line 654 of file tag.cpp. References ID3_TagType, and uchar. |
|
|
|
|
|
|
|
Definition at line 464 of file tag.cpp. References ID3_TagImpl::SetExperimental(). |
|
|
|
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.
myTag.SetExtendedHeader(true);
Definition at line 425 of file tag.cpp. References ID3_TagImpl::SetExtended(). |
|
|
|
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);
Definition at line 459 of file tag.cpp. References ID3_TagImpl::SetPadding(). |
|
|
|
Definition at line 926 of file tag.cpp. References ID3_V2Spec, ID3_TagImpl::SetSpec(), ID3_TagHeader::SIZE, and uchar. |
|
|
|
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);
Definition at line 406 of file tag.cpp. References ID3_TagImpl::SetUnsync(). |
|
|
|
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.
if (myTag.HasChanged()) { size_t tagSize; = myTag.Size(); if (tagSize > 0) { uchar *buffer = new uchar[tagSize]; if (NULL != buffer) { size_t actualSize = myTag.Render(buffer); // do something useful with the first // 'actualSize' bytes of the buffer, // like push it down a socket delete [] buffer; } } }
Definition at line 384 of file tag.cpp. References ID3_TagImpl::Size(). |
|
|
|
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.
Definition at line 727 of file tag.cpp. References flags_t, and ID3_TagImpl::Strip(). |
|
|
|
Definition at line 716 of file tag.cpp. References flags_t, and ID3_TagImpl::Update(). |