id3lib 3.8.3
Classes | Public Member Functions | List of all members
ID3_Tag Class Reference

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

#include <id3/tag.h>

Classes

class  ConstIterator
 
class  Iterator
 

Public Member Functions

 ID3_Tag (const char *name=NULL)
 Default constructor; it can accept an optional filename as a parameter.
 
 ID3_Tag (const ID3_Tag &tag)
 Standard copy constructor.
 
virtual ~ID3_Tag ()
 
void Clear ()
 Clears the object and disassociates it from any files.
 
bool HasChanged () const
 Indicates whether the tag has been altered since the last parse, render, or update.
 
size_t Size () const
 Returns an over estimate of the number of bytes required to store a binary version of a tag.
 
bool SetUnsync (bool)
 Turns unsynchronization on or off, dependant on the value of the boolean parameter.
 
bool SetExtendedHeader (bool)
 Turns extended header rendering on or off, dependant on the value of the boolean parameter.
 
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.
 
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.
 
bool 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.
 
ID3_FrameRemoveFrame (const ID3_Frame *)
 Removes a frame from the tag.
 
size_t Parse (const uchar *, size_t)
 
bool Parse (ID3_Reader &reader)
 
size_t Render (uchar *, ID3_TagType=ID3TT_ID3V2) const
 Renders the tag and writes it to the attached file; the type of tag rendered can be specified as a parameter.
 
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.
 
size_t Link (ID3_Reader &reader, flags_t=(flags_t) ID3TT_ALL)
 Same as above, but takes a ID3_Reader as argument.
 
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.
 
size_t GetPrependedBytes () const
 
size_t GetAppendedBytes () const
 
size_t GetFileSize () const
 
const char * GetFileName () const
 
const Mp3_HeaderinfoGetMp3HeaderInfo () const
 Get's the mp3 Info like bitrate, mpeg version, etc.
 
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.
 
Find

Finds frame with given frame id

Returns a pointer to the next ID3_Frame with the given ID3_FrameID; returns NULL if no such frame found.

If there are multiple frames in the tag with the same ID (which, for some frames, is allowed), then subsequent calls to Find() will return subsequent frame pointers, wrapping if necessary.

ID3_Frame *myFrame;
if (myFrame = myTag.Find(ID3FID_TITLE))
{
// do something with the frame, like copy
// the contents into a buffer, display the
// contents in a window, etc.
// ...
}
The representative class of an id3v2 frame.
@ ID3FID_TITLE
Title/songname/content description.
Definition globals.h:278

You may optionally supply to more parameters ot this method, being an ID3_FieldID and a value of some sort. Depending on the field name/ID you supply, you may supply an integer, a char* or a unicode_t* as the third parameter. If you supply an ID3_FrameID, you must also supply a data value to compare against.

This method will then return the first frame that has a matching frame ID, and which has a field with the same name as that which you supplied in the second parameter, whose calue matches that which you supplied as the third parameter. For example:

ID3_Frame *myFrame;
if (myFrame = myTag.Find(ID3FID_TITLE, ID3FN_TEXT, "Nirvana"))
{
// found it, do something with it.
// ...
}
@ ID3FN_TEXT
Text field.
Definition globals.h:201

This example will return the first TITLE frame and whose TEXT field is 'Nirvana'. Currently there is no provision for things like 'contains', 'greater than', or 'less than'. If there happens to be more than one of these frames, subsequent calls to the Find() method will return subsequent frames and will wrap around to the beginning.

Another example...

ID3_Frame *myFrame;
if (myFrame = myTag.Find(ID3FID_COMMENT, ID3FN_TEXTENC, ID3TE_UNICODE))
{
// found it, do something with it.
// ...
}
@ ID3FN_TEXTENC
Text encoding (unicode or ASCII)
Definition globals.h:200
@ ID3TE_UNICODE
Definition globals.h:146
@ ID3FID_COMMENT
Comments.
Definition globals.h:235

This returns the first COMMENT frame that uses Unicode as its text encdoing.

Parameters
idThe ID of the frame that is to be located
Returns
A pointer to the first frame found that has the given frame id, or NULL if no such frame.
ID3_FrameFind (ID3_FrameID) const
 Finds frame with given frame id, fld id, and integer data.
 
ID3_FrameFind (ID3_FrameID, ID3_FieldID, uint32) const
 Finds frame with given frame id, fld id, and integer data.
 
ID3_FrameFind (ID3_FrameID, ID3_FieldID, const char *) const
 Finds frame with given frame id, fld id, and ascii data.
 
ID3_FrameFind (ID3_FrameID, ID3_FieldID, const unicode_t *) const
 Finds frame with given frame id, fld id, and unicode data.
 
size_t NumFrames () const
 Returns the number of frames present in the tag object.
 
operator<<

Copies a frame to the tag.

The frame parameter can thus safely be deleted or allowed to go out of scope.

Operator<< supports the addition of a pointer to a frame object, or the frame object itself.

ID3_Frame *pFrame, frame;
p_frame = &frame;
myTag << pFrame;
myTag << frame;

Both these methods copy the given frame to the tag—the tag creates its own copy of the frame.

Parameters
frameThe frame to be added to the tag.
IteratorCreateIterator ()
 
ConstIteratorCreateIterator () const
 
ID3_Tagoperator<< (const ID3_Frame &)
 
ID3_Tagoperator<< (const ID3_Frame *)
 

operator[]

Returns a pointer to the frame with the given index; returns NULL if there is no such frame at that index.

Optionally, operator[](size_t) can be used as an alternative to this method. Indexing is 0-based (that is, the first frame is number 0, and the last frame in a tag that holds n frames is n-1).

If you wish to have a more comlex searching facility, then at least for now you will have to devise it yourself and implement it useing these methods.

Parameters
nIndexThe index of the frame that is to be retrieved
Returns
A pointer to the requested frame, or NULL if no such frame. Returns a pointer to the frame with the given index; returns NULL if there is no such frame at that index.
Parameters
indexThe index of the frame that is to be retrieved
Returns
A pointer to the requested frame, or NULL if no such frame.
See also
#GetFrameNum
ID3_Tagoperator= (const ID3_Tag &)
 Deprecated.
 
bool HasTagType (ID3_TagType tt) const
 Deprecated.
 
ID3_V2Spec GetSpec () const
 Deprecated.
 
bool SetSpec (ID3_V2Spec)
 Deprecated.
 
void AddNewFrame (ID3_Frame *f)
 Deprecated.
 
size_t Link (const char *fileInfo, bool parseID3v1, bool parseLyrics3)
 Deprecated.
 
void SetCompression (bool)
 Deprecated.
 
void AddFrames (const ID3_Frame *, size_t)
 Copies an array of frames to the tag.
 
bool HasLyrics () const
 Deprecated.
 
bool HasV2Tag () const
 Deprecated.
 
bool HasV1Tag () const
 Deprecated.
 
static size_t IsV2Tag (const uchar *)
 Analyses a buffer to determine if we have a valid ID3v2 tag header.
 
static size_t IsV2Tag (ID3_Reader &)
 Deprecated.
 

Detailed Description

The representative class of an id3 tag.

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:

ID3_Tag myTag;
myTag.Link("something.mp3");
The representative class of an id3 tag.
Definition tag.h:42
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 ta...
Definition tag.cpp:704

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;
}
ID3_Field * GetField(ID3_FieldID name) const
Definition frame.cpp:147
ID3_Frame * Find(ID3_FrameID) const
Finds frame with given frame id, fld id, and integer data.
Definition tag.cpp:836
#define NULL
Definition globals.h:743

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.

Author
Dirk Mahoney
Version
Id
tag.cpp,v 1.55 2003/03/02 13:35:58 t1mpy Exp
See also
ID3_Frame
ID3_Field
ID3_Err

Definition at line 41 of file tag.h.

Constructor & Destructor Documentation

◆ ID3_Tag() [1/2]

ID3_Tag::ID3_Tag ( const char * name = NULL)

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
nameThe filename of the mp3 file to link to

Definition at line 289 of file tag.cpp.

◆ ID3_Tag() [2/2]

ID3_Tag::ID3_Tag ( const ID3_Tag & tag)

Standard copy constructor.

Parameters
tagWhat is copied into this tag

Definition at line 298 of file tag.cpp.

◆ ~ID3_Tag()

ID3_Tag::~ID3_Tag ( )
virtual

Definition at line 303 of file tag.cpp.

Member Function Documentation

◆ AddFrame() [1/2]

void ID3_Tag::AddFrame ( const ID3_Frame & frame)

Definition at line 478 of file tag.cpp.

◆ AddFrame() [2/2]

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
pFrameA pointer to the frame that is being added to the tag.
See also
ID3_Frame

Definition at line 502 of file tag.cpp.

◆ AddFrames()

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
pNewFramesA pointer to an array of frames to be added to the tag.
nFramesThe number of frames in the array pNewFrames.

Definition at line 988 of file tag.cpp.

◆ AddNewFrame()

void ID3_Tag::AddNewFrame ( ID3_Frame * f)

Deprecated.

Definition at line 967 of file tag.cpp.

◆ AttachFrame()

bool 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
frameA pointer to the frame that is being added to the tag.

Definition at line 521 of file tag.cpp.

◆ Clear()

void ID3_Tag::Clear ( )

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 314 of file tag.cpp.

◆ CreateIterator() [1/2]

ID3_Tag::Iterator * ID3_Tag::CreateIterator ( )

Definition at line 1115 of file tag.cpp.

◆ CreateIterator() [2/2]

ID3_Tag::ConstIterator * ID3_Tag::CreateIterator ( ) const

Definition at line 1121 of file tag.cpp.

◆ Find() [1/4]

ID3_Frame * ID3_Tag::Find ( ID3_FrameID id) const

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

Definition at line 836 of file tag.cpp.

◆ Find() [2/4]

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.

Definition at line 848 of file tag.cpp.

◆ Find() [3/4]

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.

Definition at line 855 of file tag.cpp.

◆ Find() [4/4]

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.

Definition at line 842 of file tag.cpp.

◆ GetAppendedBytes()

size_t ID3_Tag::GetAppendedBytes ( ) const

Definition at line 748 of file tag.cpp.

◆ GetExperimental()

bool ID3_Tag::GetExperimental ( ) const

Definition at line 473 of file tag.cpp.

◆ GetExtendedHeader()

bool ID3_Tag::GetExtendedHeader ( ) const

Definition at line 468 of file tag.cpp.

◆ GetFileName()

const char * ID3_Tag::GetFileName ( ) const

Definition at line 758 of file tag.cpp.

◆ GetFileSize()

size_t ID3_Tag::GetFileSize ( ) const

Definition at line 753 of file tag.cpp.

◆ GetMp3HeaderInfo()

const Mp3_Headerinfo * ID3_Tag::GetMp3HeaderInfo ( ) const

Get's the mp3 Info like bitrate, mpeg version, etc.

Can be run after Link(<filename>)

Definition at line 727 of file tag.cpp.

◆ GetPrependedBytes()

size_t ID3_Tag::GetPrependedBytes ( ) const

Definition at line 743 of file tag.cpp.

◆ GetSpec()

ID3_V2Spec ID3_Tag::GetSpec ( ) const

Deprecated.

Definition at line 941 of file tag.cpp.

◆ GetUnsync()

bool ID3_Tag::GetUnsync ( ) const

Definition at line 463 of file tag.cpp.

◆ HasChanged()

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.

Definition at line 343 of file tag.cpp.

◆ HasLyrics()

bool ID3_Tag::HasLyrics ( ) const

Deprecated.

Definition at line 1006 of file tag.cpp.

◆ HasTagType()

bool ID3_Tag::HasTagType ( ID3_TagType tt) const

Deprecated.

Definition at line 936 of file tag.cpp.

◆ HasV1Tag()

bool ID3_Tag::HasV1Tag ( ) const

Deprecated.

Definition at line 1014 of file tag.cpp.

◆ HasV2Tag()

bool ID3_Tag::HasV2Tag ( ) const

Deprecated.

Definition at line 1010 of file tag.cpp.

◆ IsV2Tag() [1/2]

size_t ID3_Tag::IsV2Tag ( const uchar * data)
static

Analyses a buffer to determine if we have a valid ID3v2 tag header.

If so, return the total number of bytes (including the header) to read so we get all of the tag

Definition at line 955 of file tag.cpp.

◆ IsV2Tag() [2/2]

size_t ID3_Tag::IsV2Tag ( ID3_Reader & reader)
static

Deprecated.

Definition at line 961 of file tag.cpp.

◆ Link() [1/3]

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

Deprecated.

Definition at line 996 of file tag.cpp.

◆ Link() [2/3]

size_t ID3_Tag::Link ( const char * fileInfo,
flags_t flags = (flags_tID3TT_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(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()
void SetCompression(bool)
Deprecated.
Definition tag.cpp:1001
bool SetPadding(bool)
Turns padding on or off, dependant on the value of the boolean parameter.
Definition tag.cpp:453
flags_t Update(flags_t=(flags_t) ID3TT_ALL)
Definition tag.cpp:717
bool SetUnsync(bool)
Turns unsynchronization on or off, dependant on the value of the boolean parameter.
Definition tag.cpp:400
bool SetExtendedHeader(bool)
Turns extended header rendering on or off, dependant on the value of the boolean parameter.
Definition tag.cpp:419
See also
IsV2Tag
Parameters
fileInfoThe filename of the file to link to.

Definition at line 704 of file tag.cpp.

◆ Link() [3/3]

size_t ID3_Tag::Link ( ID3_Reader & reader,
flags_t flags = (flags_tID3TT_ALL )

Same as above, but takes a ID3_Reader as argument.

Definition at line 712 of file tag.cpp.

◆ NumFrames()

size_t ID3_Tag::NumFrames ( ) const

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.

Definition at line 868 of file tag.cpp.

◆ operator<<() [1/2]

ID3_Tag & ID3_Tag::operator<< ( const ID3_Frame & frame)

Definition at line 1038 of file tag.cpp.

◆ operator<<() [2/2]

ID3_Tag & ID3_Tag::operator<< ( const ID3_Frame * frame)

Definition at line 1045 of file tag.cpp.

◆ operator=()

ID3_Tag & ID3_Tag::operator= ( const ID3_Tag & rTag)

Deprecated.

Definition at line 927 of file tag.cpp.

◆ Parse() [1/3]

size_t ID3_Tag::Parse ( const uchar * buffer,
size_t bytes )

Definition at line 557 of file tag.cpp.

◆ Parse() [2/3]

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

Turns a binary tag into a series of ID3_Frame objects attached to the tag.

ID3_Tag myTag;
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;
}
}
size_t Parse(const uchar *, size_t)
Definition tag.cpp:557
long unsigned int luint
Definition globals.h:115
unsigned char uchar
Definition globals.h:114
#define ID3_TAGHEADERSIZE
Definition globals.h:104
int32 ID3_C_EXPORT ID3_IsTagHeader(const uchar header[ID3_TAGHEADERSIZE])
Definition tag.cpp:1054
See also
ID3_Frame
Parameters
headerThe byte header read in from the data source.
bufferThe remainder of the tag (not including the data source) read in from the data source.

Definition at line 604 of file tag.cpp.

◆ Parse() [3/3]

bool ID3_Tag::Parse ( ID3_Reader & reader)

Definition at line 552 of file tag.cpp.

◆ RemoveFrame()

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
pOldFrameA pointer to the frame that is to be removed from the tag

Definition at line 547 of file tag.cpp.

◆ Render() [1/2]

size_t ID3_Tag::Render ( ID3_Writer & writer,
ID3_TagType tt = ID3TT_ID3V2 ) const

Definition at line 653 of file tag.cpp.

◆ Render() [2/2]

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

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 documentation for an example of this method in use.

See also
ID3_TagType
Link
Parameters
ttThe type of tag to update. 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
bufferThe buffer that will contain the rendered tag.

Definition at line 647 of file tag.cpp.

◆ SetCompression()

void ID3_Tag::SetCompression ( bool b)

Deprecated.

Definition at line 1001 of file tag.cpp.

◆ SetExperimental()

bool ID3_Tag::SetExperimental ( bool exp)

Definition at line 458 of file tag.cpp.

◆ SetExtendedHeader()

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.

myTag.SetExtendedHeader(true);
Parameters
bExtWhether to render an extended header

Definition at line 419 of file tag.cpp.

◆ SetPadding()

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
bPadWhether or not render the tag with padding.

Definition at line 453 of file tag.cpp.

◆ SetSpec()

bool ID3_Tag::SetSpec ( ID3_V2Spec spec)

Deprecated.

Definition at line 946 of file tag.cpp.

◆ SetUnsync()

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
bSyncWhether the tag should be unsynchronized

Definition at line 400 of file tag.cpp.

◆ Size()

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.

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;
}
}
}
See also
Render
Returns
The (overestimated) number of bytes required to store a binary version of a tag

Definition at line 378 of file tag.cpp.

◆ Strip()

flags_t ID3_Tag::Strip ( flags_t flags = (flags_tID3TT_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
ttThe type of tag to strip
See also
ID3_TagType

Definition at line 738 of file tag.cpp.

◆ Update()

flags_t ID3_Tag::Update ( flags_t flags = (flags_tID3TT_ALL)

Definition at line 717 of file tag.cpp.


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

Generated for id3lib by doxygen 1.10.0