<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>id3lib: id3lib Library Documentation</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="id3lib.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.6.3 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li class="current"><a href="index.html"><span>Main Page</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<h1>id3lib Library Documentation </h1><h3 class="version">3.8.3 </h3><h2><a class="anchor" id="tutorial">
Quick Tutorial</a></h2>
<p>This tutorial will quickly get you up and running with id3lib.</p>
<h3><a class="anchor" id="download">
Downloading id3lib</a></h3>
<p>First, id3lib must be a part of your development environment. The latest files can always be downloaded from the <a href="http://id3lib.sourceforge.net">id3lib homepage</a>.</p>
<h3><a class="anchor" id="include">
Preparing your source code</a></h3>
<p>To use the basic functionality of id3lib in your C++ code, a single <code>include</code> is necessary.</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor"> #include <<a class="code" href="tag_8h.html">id3/tag.h</a>></span>
</pre></div><p>There are other files that must be included to access more advanced functionality, but this will do most of the core functionality.</p>
<h3><a class="anchor" id="creation">
Creating a tag</a></h3>
<p>Almost all functionality occurs via an <a class="el" href="class_i_d3___tag.html" title="The representative class of an id3 tag.">ID3_Tag</a> object. An <a class="el" href="class_i_d3___tag.html" title="The representative class of an id3 tag.">ID3_Tag</a> object basically encapsulates two things: a collection of <a class="el" href="class_i_d3___frame.html" title="The representative class of an id3v2 frame.">ID3_Frame</a> objects and file information. The goal is to populate an <a class="el" href="class_i_d3___tag.html" title="The representative class of an id3 tag.">ID3_Tag</a> object with <a class="el" href="class_i_d3___frame.html" title="The representative class of an id3v2 frame.">ID3_Frame</a> objects, and the easiest way to do this is to associate the tag with a file. This is done primarily via the <a class="el" href="class_i_d3___tag.html" title="The representative class of an id3 tag.">ID3_Tag</a> constructor, like so:</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="class_i_d3___tag.html" title="The representative class of an id3 tag.">ID3_Tag</a> myTag(<span class="stringliteral">"song.mp3"</span>);
</pre></div><p>This constructor links, or associates, the object <code>myTag</code> with the file "song.mp3". In doing so, the tagging information from "song.mp3" is parsed and added to <code>myTag</code>. This association can also be accomplished by creating an empty tag and making an explicit call to Link().</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="class_i_d3___tag.html" title="The representative class of an id3 tag.">ID3_Tag</a> myTag;
myTag.<a class="code" href="class_i_d3___tag.html#abd5f6a802f6fca6ec4687533de031bed" title="Attaches a file to the tag, parses the file, and adds any tag information found in...">Link</a>(<span class="stringliteral">"song.mp3"</span>);
</pre></div><p>The default behavior of Link() is to parse all possible tagging information and convert it into ID3v2 frames. The tagging information parsed can be limited to a particular type (or types) of tag by passing an ID3_TagType (or combination of ID3_TagTypes). For example, to read only the ID3v1 tag, pass in the constant ID3TT_ID3V1.</p>
<div class="fragment"><pre class="fragment"> myTag.<a class="code" href="class_i_d3___tag.html#abd5f6a802f6fca6ec4687533de031bed" title="Attaches a file to the tag, parses the file, and adds any tag information found in...">Link</a>(<span class="stringliteral">"song.mp3"</span>, <a class="code" href="globals_8h.html#a2d783dffbb1bb13e23080984b277b348ad874770876eb09c8d37ed7f6e60546f8" title="Represents an id3v1 or id3v1.1 tag.">ID3TT_ID3V1</a>);
</pre></div><p>Another example would be to read in all tags that could possibly appear at the end of the file.</p>
<div class="fragment"><pre class="fragment"> myTag.<a class="code" href="class_i_d3___tag.html#abd5f6a802f6fca6ec4687533de031bed" title="Attaches a file to the tag, parses the file, and adds any tag information found in...">Link</a>(<span class="stringliteral">"song.mp3"</span>, <a class="code" href="globals_8h.html#a2d783dffbb1bb13e23080984b277b348ad874770876eb09c8d37ed7f6e60546f8" title="Represents an id3v1 or id3v1.1 tag.">ID3TT_ID3V1</a> | <a class="code" href="globals_8h.html#a2d783dffbb1bb13e23080984b277b348a9d07484735acecbae86d2ffca7bd0cfa" title="Represents a Lyrics3 v2.00 tag.">ID3TT_LYRICS3V2</a> | <a class="code" href="globals_8h.html#a2d783dffbb1bb13e23080984b277b348aa1f5f9868591b0393236e35fd3c5d416" title="Represents a MusicMatch tag.">ID3TT_MUSICMATCH</a>);
</pre></div><h2><a class="anchor" id="accessing">
Accessing the Tag Data</a></h2>
<p>After linking with a file, the object <code>myTag</code> now contains some or all of the tagging information present in the file "song.mp3", represented as ID3v2 frames. How can that information be accessed? There are a variety of ways to do this. One is to iterate through all the frames in the tag.</p>
<div class="fragment"><pre class="fragment"> <span class="comment">// use an std::auto_ptr here to handle object cleanup automatically</span>
<a class="code" href="class_i_d3___tag_1_1_iterator.html">ID3_Tag::Iterator</a>* iter = myTag.<a class="code" href="class_i_d3___tag.html#ad63ed5e405467892b3d4413b185c43ba">CreateIterator</a>();
<a class="code" href="class_i_d3___frame.html" title="The representative class of an id3v2 frame.">ID3_Frame</a>* myFrame = <a class="code" href="globals_8h.html#a070d2ce7b6bb7e5c05602aa8c308d0c4">NULL</a>;
<span class="keywordflow">while</span> (<a class="code" href="globals_8h.html#a070d2ce7b6bb7e5c05602aa8c308d0c4">NULL</a> != (myFrame = iter-><a class="code" href="class_i_d3___tag_1_1_iterator.html#ace2ed8451590035990151741432d89df">GetNext</a>()))
{
<span class="comment">// do something with myFrame</span>
}
<span class="keyword">delete</span> iter;
</pre></div><p>Another way to access tagging information is by searching for specific frames using the Find() method. For example, the album frame can be found in the following manner:</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="class_i_d3___frame.html" title="The representative class of an id3v2 frame.">ID3_Frame</a>* myFrame = myTag.<a class="code" href="class_i_d3___tag.html#aad2a8e5a801bc09eac967d24ff3539c3" title="Finds frame with given frame id, fld id, and integer data.">Find</a>(<a class="code" href="globals_8h.html#a78f454bf66f16b1e1c9f8e37bda9ab8aa8b1cc72205175363486074e6e56b072a" title="Album/Movie/Show title.">ID3FID_ALBUM</a>);
<span class="keywordflow">if</span> (<a class="code" href="globals_8h.html#a070d2ce7b6bb7e5c05602aa8c308d0c4">NULL</a> != myFrame)
{
<span class="comment">// do something with myFrame</span>
}
</pre></div><p>The Find() method can be used to search for frames with specific information. For example, the following code can be used to find the frame with the title "Nirvana".</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="class_i_d3___frame.html" title="The representative class of an id3v2 frame.">ID3_Frame</a>* myFrame = myTag.<a class="code" href="class_i_d3___tag.html#aad2a8e5a801bc09eac967d24ff3539c3" title="Finds frame with given frame id, fld id, and integer data.">Find</a>(<a class="code" href="globals_8h.html#a78f454bf66f16b1e1c9f8e37bda9ab8aaf7e8a066a7c9debd6dfd742cfb5a080b" title="Title/songname/content description.">ID3FID_TITLE</a>, <a class="code" href="globals_8h.html#a23cab982426a968437cd731900cfeb2cab4a3b9cafedc2cede90380c79edca044" title="Text field.">ID3FN_TEXT</a>, <span class="stringliteral">"Nirvana"</span>)));
<span class="keywordflow">if</span> (<a class="code" href="globals_8h.html#a070d2ce7b6bb7e5c05602aa8c308d0c4">NULL</a> != myFrame)
{
<span class="comment">// do something with myFrame</span>
}
</pre></div><p>As indicated, the Find() method will return a NULL pointer if no such frame can be found. If more than one frame meets the search criteria, subsequent calls to Find() with the same parameters will return the other matching frames. The Find() method is guaranteed to return all matching frames before it wraps around to return the first matching frame.</p>
<p>All <a class="el" href="class_i_d3___frame.html" title="The representative class of an id3v2 frame.">ID3_Frame</a> objects are comprised of a collection of <a class="el" href="class_i_d3___field.html" title="The representative class of an ID3v2 field.">ID3_Field</a> objects. These fields can represent text, numbers, or binary data. As with frames, fields can be accessed in a variety of manners. The fields of a frame can be iterated over in much the same manner of the frames of a tag.</p>
<div class="fragment"><pre class="fragment"> <span class="comment">// use an std::auto_ptr here to handle object cleanup automatically</span>
ID3_Frame::Iterator* iter = myFrame->CreateIterator();
<a class="code" href="class_i_d3___field.html" title="The representative class of an ID3v2 field.">ID3_Field</a>* myField = <a class="code" href="globals_8h.html#a070d2ce7b6bb7e5c05602aa8c308d0c4">NULL</a>;
<span class="keywordflow">while</span> (<a class="code" href="globals_8h.html#a070d2ce7b6bb7e5c05602aa8c308d0c4">NULL</a> != (myField = iter->GetNext()))
{
<span class="comment">// do something with myField</span>
}
<span class="keyword">delete</span> iter;
</pre></div><p>If you know which field type you're looking for, you can access it directly.</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="class_i_d3___field.html" title="The representative class of an ID3v2 field.">ID3_Field</a>* myField = myFrame->GetField(<a class="code" href="globals_8h.html#a23cab982426a968437cd731900cfeb2cab4a3b9cafedc2cede90380c79edca044" title="Text field.">ID3FN_TEXT</a>);
<span class="keywordflow">while</span> (<a class="code" href="globals_8h.html#a070d2ce7b6bb7e5c05602aa8c308d0c4">NULL</a> != myField)
{
<span class="comment">// do something with myField</span>
}
</pre></div><p>Note: The <a class="el" href="class_i_d3___frame_info.html" title="Provides information about the frame and field types supported by id3lib.">ID3_FrameInfo</a> class provides information about the frame types known to id3lib.</p>
<p>The <a class="el" href="class_i_d3___field.html" title="The representative class of an ID3v2 field.">ID3_Field</a> represents a single piece of data within an ID3v2 frame. As mentioned, an <a class="el" href="class_i_d3___field.html" title="The representative class of an ID3v2 field.">ID3_Field</a> can represent three possible types of data: integers, binary data, and text strings. The type of a particular field object is immutable; it is determined at the time of its construction (almost always when a frame is constructed) and can't be changed. If in doubt, the field type can be accessed through its GetType() method.</p>
<p>Having an <a class="el" href="class_i_d3___field.html" title="The representative class of an ID3v2 field.">ID3_Field</a> object isn't much use if you cannot access and/or alter its data. Luckily, the id3lib API provides overloaded <code>Set</code> and <code>Get</code> methods for all data types.</p>
<p>If the field is an integer, the following methods can be used to access the data.</p>
<div class="fragment"><pre class="fragment"> uint32 val = myField-><a class="code" href="class_i_d3___field.html#a363d1034fb4e60e85f15bcf9818d33ef" title="Returns the value of the integer field.">Get</a>();
myField-><a class="code" href="class_i_d3___field.html#a16387cf6c54df5432a0c048d6a931f03">Set</a>(5);
(*myField) = 10;
</pre></div><p>All text data is accessed in a slightly different manner. The following code example best illustrates these differences.</p>
<div class="fragment"><pre class="fragment"> <span class="comment">// for ascii strings</span>
<span class="keywordtype">char</span> str1[1024];
<span class="keyword">const</span> <span class="keywordtype">char</span>* p1 = <span class="stringliteral">"My String"</span>;
<span class="keyword">const</span> <span class="keywordtype">char</span>* p2 = <span class="stringliteral">"My Other String"</span>;
myField-><a class="code" href="class_i_d3___field.html#a16387cf6c54df5432a0c048d6a931f03">Set</a>(p1);
(*myField) = p2; <span class="comment">// equivalent to Set</span>
myField-><a class="code" href="class_i_d3___field.html#a363d1034fb4e60e85f15bcf9818d33ef" title="Returns the value of the integer field.">Get</a>(str1, 1024); <span class="comment">// copies up to 1024 bytes of the field data into str1</span>
p1 = myField-><a class="code" href="class_i_d3___field.html#a1b306f45543afd5459e77200a0fc0a1f">GetRawText</a>(); <span class="comment">// returns a pointer to the internal string</span>
</pre></div><p>Binary data is similar to text data, except that its base type is a pointer to an unsigned, rather than a signed, char.</p>
<div class="fragment"><pre class="fragment"> <span class="comment">// for binary strings</span>
<a class="code" href="globals_8h.html#a65f85814a8290f9797005d3b28e7e5fc">uchar</a> data[1024];
<span class="keyword">const</span> <a class="code" href="globals_8h.html#a65f85814a8290f9797005d3b28e7e5fc">uchar</a> *p1 = getBinaryData(); <span class="comment">// not an id3lib function</span>
<span class="keywordtype">size_t</span> size = getBinarySize(); <span class="comment">// not an id3lib function</span>
myField-><a class="code" href="class_i_d3___field.html#a16387cf6c54df5432a0c048d6a931f03">Set</a>(p1, size);
myField-><a class="code" href="class_i_d3___field.html#a363d1034fb4e60e85f15bcf9818d33ef" title="Returns the value of the integer field.">Get</a>(data, 1024); <span class="comment">// copies up to 1024 bytes of the field data into str1</span>
p1 = myField-><a class="code" href="class_i_d3___field.html#ac2ad64c889eae4aa614a85d0aa38b2ab">GetRawBinary</a>(); <span class="comment">// returns a pointer to the internal string</span>
</pre></div><h2><a class="anchor" id="updating">
Updating the Tag</a></h2>
<p>When you're ready to save your changes back to the file, a single call to Update() is sufficient.</p>
<div class="fragment"><pre class="fragment"> tag.Update();
</pre></div> </div>
<hr class="footer"/><address style="text-align: right;"><small>Generated on Wed Jan 12 23:46:35 2011 for id3lib by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.3 </small></address>
</body>
</html>
distrib
>
Mageia
>
1
>
i586
>
media
>
core-release
>
by-pkgid
>
1b812d1b0e765bcc0430721ff58676d2
>
files
>
242
