EVOLUTION-MANAGER
Edit File: oggz__comments_8h.html
<!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"/> <meta http-equiv="X-UA-Compatible" content="IE=9"/> <meta name="generator" content="Doxygen 1.8.5"/> <title>liboggz: oggz_comments.h File Reference</title> <link href="tabs.css" rel="stylesheet" type="text/css"/> <script type="text/javascript" src="jquery.js"></script> <script type="text/javascript" src="dynsections.js"></script> <link href="doxygen.css" rel="stylesheet" type="text/css" /> </head> <body> <div id="top"><!-- do not remove this div, it is closed by doxygen! --> <div id="titlearea"> <table cellspacing="0" cellpadding="0"> <tbody> <tr style="height: 56px;"> <td style="padding-left: 0.5em;"> <div id="projectname">liboggz  <span id="projectnumber">1.1.1</span> </div> </td> </tr> </tbody> </table> </div> <!-- end header part --> <!-- Generated by Doxygen 1.8.5 --> <div id="navrow1" class="tabs"> <ul class="tablist"> <li><a href="index.html"><span>Main Page</span></a></li> <li><a href="modules.html"><span>Modules</span></a></li> <li><a href="annotated.html"><span>Data Structures</span></a></li> <li class="current"><a href="files.html"><span>Files</span></a></li> </ul> </div> <div id="navrow2" class="tabs2"> <ul class="tablist"> <li><a href="files.html"><span>File List</span></a></li> <li><a href="globals.html"><span>Globals</span></a></li> </ul> </div> <div id="nav-path" class="navpath"> <ul> <li class="navelem"><a class="el" href="dir_d44c64559bbebec7f509842c48db8b23.html">include</a></li><li class="navelem"><a class="el" href="dir_d87111fb9e25a5f2a11bf853c53bb708.html">oggz</a></li> </ul> </div> </div><!-- top --> <div class="header"> <div class="summary"> <a href="#nested-classes">Data Structures</a> | <a href="#func-members">Functions</a> </div> <div class="headertitle"> <div class="title">oggz_comments.h File Reference</div> </div> </div><!--header--> <div class="contents"> <p>Reading of comments. <a href="#details">More...</a></p> <div class="textblock"><code>#include <<a class="el" href="oggz_8h_source.html">oggz/oggz.h</a>></code><br/> </div> <p><a href="oggz__comments_8h_source.html">Go to the source code of this file.</a></p> <table class="memberdecls"> <tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="nested-classes"></a> Data Structures</h2></td></tr> <tr class="memitem:"><td class="memItemLeft" align="right" valign="top">struct  </td><td class="memItemRight" valign="bottom"><a class="el" href="structOggzComment.html">OggzComment</a></td></tr> <tr class="memdesc:"><td class="mdescLeft"> </td><td class="mdescRight">A comment. <a href="structOggzComment.html#details">More...</a><br/></td></tr> <tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr> </table><table class="memberdecls"> <tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a> Functions</h2></td></tr> <tr class="memitem:ae5d522df5fce262953d8bb5cb8c00b00"><td class="memItemLeft" align="right" valign="top">const char * </td><td class="memItemRight" valign="bottom"><a class="el" href="oggz__comments_8h.html#ae5d522df5fce262953d8bb5cb8c00b00">oggz_comment_get_vendor</a> (<a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> *oggz, long serialno)</td></tr> <tr class="memdesc:ae5d522df5fce262953d8bb5cb8c00b00"><td class="mdescLeft"> </td><td class="mdescRight">Retrieve the vendor string. <a href="#ae5d522df5fce262953d8bb5cb8c00b00">More...</a><br/></td></tr> <tr class="separator:ae5d522df5fce262953d8bb5cb8c00b00"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:a281a0956a9a160337f7d00f102d18131"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="oggz__comments_8h.html#a281a0956a9a160337f7d00f102d18131">oggz_comment_set_vendor</a> (<a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> *oggz, long serialno, const char *vendor_string)</td></tr> <tr class="memdesc:a281a0956a9a160337f7d00f102d18131"><td class="mdescLeft"> </td><td class="mdescRight">Set the vendor string. <a href="#a281a0956a9a160337f7d00f102d18131">More...</a><br/></td></tr> <tr class="separator:a281a0956a9a160337f7d00f102d18131"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:a306a979d84b61932930d44ea5d4f95d9"><td class="memItemLeft" align="right" valign="top">const <a class="el" href="structOggzComment.html">OggzComment</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="oggz__comments_8h.html#a306a979d84b61932930d44ea5d4f95d9">oggz_comment_first</a> (<a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> *oggz, long serialno)</td></tr> <tr class="memdesc:a306a979d84b61932930d44ea5d4f95d9"><td class="mdescLeft"> </td><td class="mdescRight">Retrieve the first comment. <a href="#a306a979d84b61932930d44ea5d4f95d9">More...</a><br/></td></tr> <tr class="separator:a306a979d84b61932930d44ea5d4f95d9"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:a9501d8c166187c8d503e1335827b2d5e"><td class="memItemLeft" align="right" valign="top">const <a class="el" href="structOggzComment.html">OggzComment</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="oggz__comments_8h.html#a9501d8c166187c8d503e1335827b2d5e">oggz_comment_next</a> (<a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> *oggz, long serialno, const <a class="el" href="structOggzComment.html">OggzComment</a> *comment)</td></tr> <tr class="memdesc:a9501d8c166187c8d503e1335827b2d5e"><td class="mdescLeft"> </td><td class="mdescRight">Retrieve the next comment. <a href="#a9501d8c166187c8d503e1335827b2d5e">More...</a><br/></td></tr> <tr class="separator:a9501d8c166187c8d503e1335827b2d5e"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:a9a3a72be012b6474a1e1d95f7ce7afe8"><td class="memItemLeft" align="right" valign="top">const <a class="el" href="structOggzComment.html">OggzComment</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="oggz__comments_8h.html#a9a3a72be012b6474a1e1d95f7ce7afe8">oggz_comment_first_byname</a> (<a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> *oggz, long serialno, char *name)</td></tr> <tr class="memdesc:a9a3a72be012b6474a1e1d95f7ce7afe8"><td class="mdescLeft"> </td><td class="mdescRight">Retrieve the first comment with a given name. <a href="#a9a3a72be012b6474a1e1d95f7ce7afe8">More...</a><br/></td></tr> <tr class="separator:a9a3a72be012b6474a1e1d95f7ce7afe8"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:a1dd05e02a121ba639b8012acaa21a37c"><td class="memItemLeft" align="right" valign="top">const <a class="el" href="structOggzComment.html">OggzComment</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="oggz__comments_8h.html#a1dd05e02a121ba639b8012acaa21a37c">oggz_comment_next_byname</a> (<a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> *oggz, long serialno, const <a class="el" href="structOggzComment.html">OggzComment</a> *comment)</td></tr> <tr class="memdesc:a1dd05e02a121ba639b8012acaa21a37c"><td class="mdescLeft"> </td><td class="mdescRight">Retrieve the next comment following and with the same name as a given comment. <a href="#a1dd05e02a121ba639b8012acaa21a37c">More...</a><br/></td></tr> <tr class="separator:a1dd05e02a121ba639b8012acaa21a37c"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:ade23081a738d67bec473bdaf317a68d8"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="oggz__comments_8h.html#ade23081a738d67bec473bdaf317a68d8">oggz_comment_add</a> (<a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> *oggz, long serialno, <a class="el" href="structOggzComment.html">OggzComment</a> *comment)</td></tr> <tr class="memdesc:ade23081a738d67bec473bdaf317a68d8"><td class="mdescLeft"> </td><td class="mdescRight">Add a comment. <a href="#ade23081a738d67bec473bdaf317a68d8">More...</a><br/></td></tr> <tr class="separator:ade23081a738d67bec473bdaf317a68d8"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:ad869a8a7246567ba4162183436127a6f"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="oggz__comments_8h.html#ad869a8a7246567ba4162183436127a6f">oggz_comment_add_byname</a> (<a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> *oggz, long serialno, const char *name, const char *value)</td></tr> <tr class="memdesc:ad869a8a7246567ba4162183436127a6f"><td class="mdescLeft"> </td><td class="mdescRight">Add a comment by name and value. <a href="#ad869a8a7246567ba4162183436127a6f">More...</a><br/></td></tr> <tr class="separator:ad869a8a7246567ba4162183436127a6f"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:a75ca47a020dcddce846a320481120a8e"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="oggz__comments_8h.html#a75ca47a020dcddce846a320481120a8e">oggz_comment_remove</a> (<a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> *oggz, long serialno, <a class="el" href="structOggzComment.html">OggzComment</a> *comment)</td></tr> <tr class="memdesc:a75ca47a020dcddce846a320481120a8e"><td class="mdescLeft"> </td><td class="mdescRight">Remove a comment. <a href="#a75ca47a020dcddce846a320481120a8e">More...</a><br/></td></tr> <tr class="separator:a75ca47a020dcddce846a320481120a8e"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:aa0f3f3a3ea3ca28d8678b94495634876"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="oggz__comments_8h.html#aa0f3f3a3ea3ca28d8678b94495634876">oggz_comment_remove_byname</a> (<a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> *oggz, long serialno, char *name)</td></tr> <tr class="memdesc:aa0f3f3a3ea3ca28d8678b94495634876"><td class="mdescLeft"> </td><td class="mdescRight">Remove all comments with a given name. <a href="#aa0f3f3a3ea3ca28d8678b94495634876">More...</a><br/></td></tr> <tr class="separator:aa0f3f3a3ea3ca28d8678b94495634876"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:a1ee69481fa517d80e63db962a23d53ae"><td class="memItemLeft" align="right" valign="top">ogg_packet * </td><td class="memItemRight" valign="bottom"><a class="el" href="oggz__comments_8h.html#a1ee69481fa517d80e63db962a23d53ae">oggz_comments_generate</a> (<a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> *oggz, long serialno, int FLAC_final_metadata_block)</td></tr> <tr class="memdesc:a1ee69481fa517d80e63db962a23d53ae"><td class="mdescLeft"> </td><td class="mdescRight">Output a comment packet for the specified stream. <a href="#a1ee69481fa517d80e63db962a23d53ae">More...</a><br/></td></tr> <tr class="separator:a1ee69481fa517d80e63db962a23d53ae"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:a486cd52284cb03032360265d2027f8db"><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="a486cd52284cb03032360265d2027f8db"></a> int </td><td class="memItemRight" valign="bottom"><b>oggz_comments_copy</b> (<a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> *src, long src_serialno, <a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> *dest, long dest_serialno)</td></tr> <tr class="separator:a486cd52284cb03032360265d2027f8db"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:a9301332e99b0397cff54c3593595b809"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="oggz__comments_8h.html#a9301332e99b0397cff54c3593595b809">oggz_packet_destroy</a> (ogg_packet *packet)</td></tr> <tr class="memdesc:a9301332e99b0397cff54c3593595b809"><td class="mdescLeft"> </td><td class="mdescRight">Free a packet and its payload. <a href="#a9301332e99b0397cff54c3593595b809">More...</a><br/></td></tr> <tr class="separator:a9301332e99b0397cff54c3593595b809"><td class="memSeparator" colspan="2"> </td></tr> </table> <a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2> <div class="textblock"><p>Reading of comments. </p> <p>Vorbis, Speex and Theora bitstreams use a comment format called "Vorbiscomment", defined <a href="http://www.xiph.org/ogg/vorbis/doc/v-comment.html">here</a>. Many standard comment names (such as TITLE, COPYRIGHT and GENRE) are defined in that document.</p> <p>The following general features of Vorbiscomment are relevant to this API:</p> <ul> <li>Each stream has one comment packet, which occurs before any encoded audio data in the stream.</li> <li>When reading, Oggz will decode the comment block before calling the second read() callback for each stream. Hence, retrieving comment data is possible once the read() callback has been called a second time.</li> <li>When writing, Oggz allows you to set up the comments in memory, and provides a single function to generate a corresponding ogg_packet. It is your responsibility to then actually write that packet in sequence.</li> </ul> <p>Each comment block contains one Vendor string, which can be retrieved with <a class="el" href="oggz__comments_8h.html#ae5d522df5fce262953d8bb5cb8c00b00" title="Retrieve the vendor string. ">oggz_comment_get_vendor()</a>.</p> <p>The rest of a comment block consists of <em>name</em> = <em>value</em> pairs, with the following restrictions:</p> <ul> <li>Both the <em>name</em> and <em>value</em> must be non-empty</li> <li>The <em>name</em> is case-insensitive and must consist of ASCII within the range 0x20 to 0x7D inclusive, 0x3D ('=') excluded.</li> <li>The <em>name</em> is not unique; multiple entries may exist with equivalent <em>name</em> within a Vorbiscomment block.</li> <li>The <em>value</em> may be any UTF-8 string.</li> </ul> <h1><a class="anchor" id="comments_get"></a> Reading comments</h1> <p>Oggz contains API methods to iterate through all comments associated with the logical bitstreams of an OGGZ* handle (<a class="el" href="oggz__comments_8h.html#a306a979d84b61932930d44ea5d4f95d9" title="Retrieve the first comment. ">oggz_comment_first()</a> and <a class="el" href="oggz__comments_8h.html#a9501d8c166187c8d503e1335827b2d5e" title="Retrieve the next comment. ">oggz_comment_next()</a>, and to iterate through comments matching a particular name (<a class="el" href="oggz__comments_8h.html#a9a3a72be012b6474a1e1d95f7ce7afe8" title="Retrieve the first comment with a given name. ">oggz_comment_first_byname()</a> and <a class="el" href="oggz__comments_8h.html#a1dd05e02a121ba639b8012acaa21a37c" title="Retrieve the next comment following and with the same name as a given comment. ">oggz_comment_next_byname()</a>). Given that multiple comments may exist with the same <em>name</em>, you should not use <a class="el" href="oggz__comments_8h.html#a9a3a72be012b6474a1e1d95f7ce7afe8" title="Retrieve the first comment with a given name. ">oggz_comment_first_byname()</a> as a simple "get" function.</p> <h1><a class="anchor" id="comments_set"></a> Writing comments</h1> <p>For writing, Oggz contains API methods for adding comments (<a class="el" href="oggz__comments_8h.html#ade23081a738d67bec473bdaf317a68d8" title="Add a comment. ">oggz_comment_add()</a> and <a class="el" href="oggz__comments_8h.html#ad869a8a7246567ba4162183436127a6f" title="Add a comment by name and value. ">oggz_comment_add_byname()</a>), for removing comments (<a class="el" href="oggz__comments_8h.html#a75ca47a020dcddce846a320481120a8e" title="Remove a comment. ">oggz_comment_remove()</a> and <a class="el" href="oggz__comments_8h.html#aa0f3f3a3ea3ca28d8678b94495634876" title="Remove all comments with a given name. ">oggz_comment_remove_byname()</a>) and for setting the vendor string (<a class="el" href="oggz__comments_8h.html#a281a0956a9a160337f7d00f102d18131" title="Set the vendor string. ">oggz_comment_set_vendor()</a>). </p> </div><h2 class="groupheader">Function Documentation</h2> <a class="anchor" id="ade23081a738d67bec473bdaf317a68d8"></a> <div class="memitem"> <div class="memproto"> <table class="memname"> <tr> <td class="memname">int oggz_comment_add </td> <td>(</td> <td class="paramtype"><a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> * </td> <td class="paramname"><em>oggz</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">long </td> <td class="paramname"><em>serialno</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype"><a class="el" href="structOggzComment.html">OggzComment</a> * </td> <td class="paramname"><em>comment</em> </td> </tr> <tr> <td></td> <td>)</td> <td></td><td></td> </tr> </table> </div><div class="memdoc"> <p>Add a comment. </p> <dl class="params"><dt>Parameters</dt><dd> <table class="params"> <tr><td class="paramname">oggz</td><td>A OGGZ* handle (created with mode OGGZ_WRITE) </td></tr> <tr><td class="paramname">serialno</td><td>Identify a logical bitstream within <em>oggz</em> </td></tr> <tr><td class="paramname">comment</td><td>The comment to add </td></tr> </table> </dd> </dl> <dl class="retval"><dt>Return values</dt><dd> <table class="retval"> <tr><td class="paramname">0</td><td>Success </td></tr> <tr><td class="paramname">OGGZ_ERR_BAD</td><td><em>oggz</em> is not a valid OGGZ* handle </td></tr> <tr><td class="paramname">OGGZ_ERR_INVALID</td><td>Operation not suitable for this OGGZ </td></tr> <tr><td class="paramname">OGGZ_ERR_OUT_OF_MEMORY</td><td>Out of memory </td></tr> </table> </dd> </dl> </div> </div> <a class="anchor" id="ad869a8a7246567ba4162183436127a6f"></a> <div class="memitem"> <div class="memproto"> <table class="memname"> <tr> <td class="memname">int oggz_comment_add_byname </td> <td>(</td> <td class="paramtype"><a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> * </td> <td class="paramname"><em>oggz</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">long </td> <td class="paramname"><em>serialno</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">const char * </td> <td class="paramname"><em>name</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">const char * </td> <td class="paramname"><em>value</em> </td> </tr> <tr> <td></td> <td>)</td> <td></td><td></td> </tr> </table> </div><div class="memdoc"> <p>Add a comment by name and value. </p> <dl class="params"><dt>Parameters</dt><dd> <table class="params"> <tr><td class="paramname">oggz</td><td>A OGGZ* handle (created with mode OGGZ_WRITE) </td></tr> <tr><td class="paramname">serialno</td><td>Identify a logical bitstream within <em>oggz</em> </td></tr> <tr><td class="paramname">name</td><td>The name of the comment to add </td></tr> <tr><td class="paramname">value</td><td>The contents of the comment to add </td></tr> </table> </dd> </dl> <dl class="retval"><dt>Return values</dt><dd> <table class="retval"> <tr><td class="paramname">0</td><td>Success </td></tr> <tr><td class="paramname">OGGZ_ERR_BAD</td><td><em>oggz</em> is not a valid OGGZ* handle </td></tr> <tr><td class="paramname">OGGZ_ERR_INVALID</td><td>Operation not suitable for this OGGZ </td></tr> <tr><td class="paramname">OGGZ_ERR_OUT_OF_MEMORY</td><td>Out of memory </td></tr> </table> </dd> </dl> </div> </div> <a class="anchor" id="a306a979d84b61932930d44ea5d4f95d9"></a> <div class="memitem"> <div class="memproto"> <table class="memname"> <tr> <td class="memname">const <a class="el" href="structOggzComment.html">OggzComment</a>* oggz_comment_first </td> <td>(</td> <td class="paramtype"><a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> * </td> <td class="paramname"><em>oggz</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">long </td> <td class="paramname"><em>serialno</em> </td> </tr> <tr> <td></td> <td>)</td> <td></td><td></td> </tr> </table> </div><div class="memdoc"> <p>Retrieve the first comment. </p> <dl class="params"><dt>Parameters</dt><dd> <table class="params"> <tr><td class="paramname">oggz</td><td>A OGGZ* handle </td></tr> <tr><td class="paramname">serialno</td><td>Identify a logical bitstream within <em>oggz</em> </td></tr> </table> </dd> </dl> <dl class="section return"><dt>Returns</dt><dd>A read-only copy of the first comment. </dd></dl> <dl class="retval"><dt>Return values</dt><dd> <table class="retval"> <tr><td class="paramname">NULL</td><td>No comments exist for this OGGZ* object, or <em>serialno</em> does not identify an existing logical bitstream in <em>oggz</em>. </td></tr> </table> </dd> </dl> </div> </div> <a class="anchor" id="a9a3a72be012b6474a1e1d95f7ce7afe8"></a> <div class="memitem"> <div class="memproto"> <table class="memname"> <tr> <td class="memname">const <a class="el" href="structOggzComment.html">OggzComment</a>* oggz_comment_first_byname </td> <td>(</td> <td class="paramtype"><a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> * </td> <td class="paramname"><em>oggz</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">long </td> <td class="paramname"><em>serialno</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">char * </td> <td class="paramname"><em>name</em> </td> </tr> <tr> <td></td> <td>)</td> <td></td><td></td> </tr> </table> </div><div class="memdoc"> <p>Retrieve the first comment with a given name. </p> <dl class="params"><dt>Parameters</dt><dd> <table class="params"> <tr><td class="paramname">oggz</td><td>A OGGZ* handle </td></tr> <tr><td class="paramname">serialno</td><td>Identify a logical bitstream within <em>oggz</em> </td></tr> <tr><td class="paramname">name</td><td>the name of the comment to retrieve. </td></tr> </table> </dd> </dl> <dl class="section return"><dt>Returns</dt><dd>A read-only copy of the first comment matching the given <em>name</em>. </dd></dl> <dl class="retval"><dt>Return values</dt><dd> <table class="retval"> <tr><td class="paramname">NULL</td><td>No match was found, or <em>serialno</em> does not identify an existing logical bitstream in <em>oggz</em>. </td></tr> </table> </dd> </dl> <dl class="section note"><dt>Note</dt><dd>If <em>name</em> is NULL, the behaviour is the same as for <a class="el" href="oggz__comments_8h.html#a306a979d84b61932930d44ea5d4f95d9" title="Retrieve the first comment. ">oggz_comment_first()</a> </dd></dl> </div> </div> <a class="anchor" id="ae5d522df5fce262953d8bb5cb8c00b00"></a> <div class="memitem"> <div class="memproto"> <table class="memname"> <tr> <td class="memname">const char* oggz_comment_get_vendor </td> <td>(</td> <td class="paramtype"><a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> * </td> <td class="paramname"><em>oggz</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">long </td> <td class="paramname"><em>serialno</em> </td> </tr> <tr> <td></td> <td>)</td> <td></td><td></td> </tr> </table> </div><div class="memdoc"> <p>Retrieve the vendor string. </p> <dl class="params"><dt>Parameters</dt><dd> <table class="params"> <tr><td class="paramname">oggz</td><td>A OGGZ* handle </td></tr> <tr><td class="paramname">serialno</td><td>Identify a logical bitstream within <em>oggz</em> </td></tr> </table> </dd> </dl> <dl class="section return"><dt>Returns</dt><dd>A read-only copy of the vendor string. </dd></dl> <dl class="retval"><dt>Return values</dt><dd> <table class="retval"> <tr><td class="paramname">NULL</td><td>No vendor string is associated with <em>oggz</em>, or <em>oggz</em> is NULL, or <em>serialno</em> does not identify an existing logical bitstream in <em>oggz</em>. </td></tr> </table> </dd> </dl> </div> </div> <a class="anchor" id="a9501d8c166187c8d503e1335827b2d5e"></a> <div class="memitem"> <div class="memproto"> <table class="memname"> <tr> <td class="memname">const <a class="el" href="structOggzComment.html">OggzComment</a>* oggz_comment_next </td> <td>(</td> <td class="paramtype"><a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> * </td> <td class="paramname"><em>oggz</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">long </td> <td class="paramname"><em>serialno</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">const <a class="el" href="structOggzComment.html">OggzComment</a> * </td> <td class="paramname"><em>comment</em> </td> </tr> <tr> <td></td> <td>)</td> <td></td><td></td> </tr> </table> </div><div class="memdoc"> <p>Retrieve the next comment. </p> <dl class="params"><dt>Parameters</dt><dd> <table class="params"> <tr><td class="paramname">oggz</td><td>A OGGZ* handle </td></tr> <tr><td class="paramname">serialno</td><td>Identify a logical bitstream within <em>oggz</em> </td></tr> <tr><td class="paramname">comment</td><td>The previous comment. </td></tr> </table> </dd> </dl> <dl class="section return"><dt>Returns</dt><dd>A read-only copy of the comment immediately following the given comment. </dd></dl> <dl class="retval"><dt>Return values</dt><dd> <table class="retval"> <tr><td class="paramname">NULL</td><td><em>serialno</em> does not identify an existing logical bitstream in <em>oggz</em>. </td></tr> </table> </dd> </dl> </div> </div> <a class="anchor" id="a1dd05e02a121ba639b8012acaa21a37c"></a> <div class="memitem"> <div class="memproto"> <table class="memname"> <tr> <td class="memname">const <a class="el" href="structOggzComment.html">OggzComment</a>* oggz_comment_next_byname </td> <td>(</td> <td class="paramtype"><a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> * </td> <td class="paramname"><em>oggz</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">long </td> <td class="paramname"><em>serialno</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">const <a class="el" href="structOggzComment.html">OggzComment</a> * </td> <td class="paramname"><em>comment</em> </td> </tr> <tr> <td></td> <td>)</td> <td></td><td></td> </tr> </table> </div><div class="memdoc"> <p>Retrieve the next comment following and with the same name as a given comment. </p> <dl class="params"><dt>Parameters</dt><dd> <table class="params"> <tr><td class="paramname">oggz</td><td>A OGGZ* handle </td></tr> <tr><td class="paramname">serialno</td><td>Identify a logical bitstream within <em>oggz</em> </td></tr> <tr><td class="paramname">comment</td><td>A comment </td></tr> </table> </dd> </dl> <dl class="section return"><dt>Returns</dt><dd>A read-only copy of the next comment with the same name as <em>comment</em>. </dd></dl> <dl class="retval"><dt>Return values</dt><dd> <table class="retval"> <tr><td class="paramname">NULL</td><td>No further comments with the same name exist for this OGGZ* object, or <em>serialno</em> does not identify an existing logical bitstream in <em>oggz</em>. </td></tr> </table> </dd> </dl> </div> </div> <a class="anchor" id="a75ca47a020dcddce846a320481120a8e"></a> <div class="memitem"> <div class="memproto"> <table class="memname"> <tr> <td class="memname">int oggz_comment_remove </td> <td>(</td> <td class="paramtype"><a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> * </td> <td class="paramname"><em>oggz</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">long </td> <td class="paramname"><em>serialno</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype"><a class="el" href="structOggzComment.html">OggzComment</a> * </td> <td class="paramname"><em>comment</em> </td> </tr> <tr> <td></td> <td>)</td> <td></td><td></td> </tr> </table> </div><div class="memdoc"> <p>Remove a comment. </p> <dl class="params"><dt>Parameters</dt><dd> <table class="params"> <tr><td class="paramname">oggz</td><td>A OGGZ* handle (created with OGGZ_WRITE) </td></tr> <tr><td class="paramname">serialno</td><td>Identify a logical bitstream within <em>oggz</em> </td></tr> <tr><td class="paramname">comment</td><td>The comment to remove. </td></tr> </table> </dd> </dl> <dl class="retval"><dt>Return values</dt><dd> <table class="retval"> <tr><td class="paramname">1</td><td>Success: comment removed </td></tr> <tr><td class="paramname">0</td><td>No-op: comment not found, nothing to remove </td></tr> <tr><td class="paramname">OGGZ_ERR_BAD</td><td><em>oggz</em> is not a valid OGGZ* handle </td></tr> <tr><td class="paramname">OGGZ_ERR_INVALID</td><td>Operation not suitable for this OGGZ </td></tr> <tr><td class="paramname">OGGZ_ERR_BAD_SERIALNO</td><td><em>serialno</em> does not identify an existing logical bitstream in <em>oggz</em>. </td></tr> </table> </dd> </dl> </div> </div> <a class="anchor" id="aa0f3f3a3ea3ca28d8678b94495634876"></a> <div class="memitem"> <div class="memproto"> <table class="memname"> <tr> <td class="memname">int oggz_comment_remove_byname </td> <td>(</td> <td class="paramtype"><a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> * </td> <td class="paramname"><em>oggz</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">long </td> <td class="paramname"><em>serialno</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">char * </td> <td class="paramname"><em>name</em> </td> </tr> <tr> <td></td> <td>)</td> <td></td><td></td> </tr> </table> </div><div class="memdoc"> <p>Remove all comments with a given name. </p> <dl class="params"><dt>Parameters</dt><dd> <table class="params"> <tr><td class="paramname">oggz</td><td>A OGGZ* handle (created with OGGZ_WRITE) </td></tr> <tr><td class="paramname">serialno</td><td>Identify a logical bitstream within <em>oggz</em> </td></tr> <tr><td class="paramname">name</td><td>The name of the comments to remove </td></tr> </table> </dd> </dl> <dl class="retval"><dt>Return values</dt><dd> <table class="retval"> <tr><td class="paramname">>= 0</td><td>The number of comments removed </td></tr> <tr><td class="paramname">OGGZ_ERR_BAD</td><td><em>oggz</em> is not a valid OGGZ* handle </td></tr> <tr><td class="paramname">OGGZ_ERR_INVALID</td><td>Operation not suitable for this OGGZ </td></tr> <tr><td class="paramname">OGGZ_ERR_BAD_SERIALNO</td><td><em>serialno</em> does not identify an existing logical bitstream in <em>oggz</em>. </td></tr> </table> </dd> </dl> </div> </div> <a class="anchor" id="a281a0956a9a160337f7d00f102d18131"></a> <div class="memitem"> <div class="memproto"> <table class="memname"> <tr> <td class="memname">int oggz_comment_set_vendor </td> <td>(</td> <td class="paramtype"><a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> * </td> <td class="paramname"><em>oggz</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">long </td> <td class="paramname"><em>serialno</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">const char * </td> <td class="paramname"><em>vendor_string</em> </td> </tr> <tr> <td></td> <td>)</td> <td></td><td></td> </tr> </table> </div><div class="memdoc"> <p>Set the vendor string. </p> <dl class="params"><dt>Parameters</dt><dd> <table class="params"> <tr><td class="paramname">oggz</td><td>A OGGZ* handle </td></tr> <tr><td class="paramname">serialno</td><td>Identify a logical bitstream within <em>oggz</em> </td></tr> <tr><td class="paramname">vendor_string</td><td>The contents of the vendor string to add </td></tr> </table> </dd> </dl> <dl class="retval"><dt>Return values</dt><dd> <table class="retval"> <tr><td class="paramname">0</td><td>Success </td></tr> <tr><td class="paramname">OGGZ_ERR_BAD</td><td><em>oggz</em> is not a valid OGGZ* handle </td></tr> <tr><td class="paramname">OGGZ_ERR_INVALID</td><td>Operation not suitable for this OGGZ </td></tr> <tr><td class="paramname">OGGZ_ERR_OUT_OF_MEMORY</td><td>Out of memory </td></tr> </table> </dd> </dl> <dl class="section note"><dt>Note</dt><dd>The vendor string should identify the library used to produce the stream, e.g. libvorbis 1.0 used "Xiph.Org libVorbis I 20020717". If copying a bitstream it should be the same as the source. </dd></dl> </div> </div> <a class="anchor" id="a1ee69481fa517d80e63db962a23d53ae"></a> <div class="memitem"> <div class="memproto"> <table class="memname"> <tr> <td class="memname">ogg_packet* oggz_comments_generate </td> <td>(</td> <td class="paramtype"><a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> * </td> <td class="paramname"><em>oggz</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">long </td> <td class="paramname"><em>serialno</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">int </td> <td class="paramname"><em>FLAC_final_metadata_block</em> </td> </tr> <tr> <td></td> <td>)</td> <td></td><td></td> </tr> </table> </div><div class="memdoc"> <p>Output a comment packet for the specified stream. </p> <dl class="params"><dt>Parameters</dt><dd> <table class="params"> <tr><td class="paramname">oggz</td><td>A OGGZ* handle (created with OGGZ_WRITE) </td></tr> <tr><td class="paramname">serialno</td><td>Identify a logical bitstream within <em>oggz</em> </td></tr> <tr><td class="paramname">FLAC_final_metadata_block</td><td>Set this to zero unless the packet_type is FLAC, and there are no further metadata blocks to follow. See note below for details. </td></tr> </table> </dd> </dl> <dl class="section return"><dt>Returns</dt><dd>A comment packet for the stream. When no longer needed it should be freed with <a class="el" href="oggz__comments_8h.html#a9301332e99b0397cff54c3593595b809" title="Free a packet and its payload. ">oggz_packet_destroy()</a>. </dd></dl> <dl class="retval"><dt>Return values</dt><dd> <table class="retval"> <tr><td class="paramname">NULL</td><td>content type does not support comments, not enough memory or comment was too long for FLAC </td></tr> </table> </dd> </dl> <dl class="section note"><dt>Note</dt><dd>FLAC streams may contain multiple metadata blocks of different types. When encapsulated in Ogg the first of these must be a Vorbis comment packet but PADDING, APPLICATION, SEEKTABLE, CUESHEET and PICTURE may follow. The last metadata block must have its first bit set to 1. Since liboggz does not know whether you will supply more metadata blocks you must tell it if this is the last (or only) metadata block by setting FLAC_final_metadata_block to 1. <br/> As FLAC metadata blocks are limited in size to 16MB minus 1 byte, this function will refuse to produce longer comment packets for FLAC. <br/> See <a href="http://flac.sourceforge.net/format.html">http://flac.sourceforge.net/format.html</a> for more details. </dd></dl> </div> </div> <a class="anchor" id="a9301332e99b0397cff54c3593595b809"></a> <div class="memitem"> <div class="memproto"> <table class="memname"> <tr> <td class="memname">void oggz_packet_destroy </td> <td>(</td> <td class="paramtype">ogg_packet * </td> <td class="paramname"><em>packet</em></td><td>)</td> <td></td> </tr> </table> </div><div class="memdoc"> <p>Free a packet and its payload. </p> <dl class="params"><dt>Parameters</dt><dd> <table class="params"> <tr><td class="paramname">packet</td><td>A packet previously returned from a function such as <a class="el" href="oggz__deprecated_8h.html#aab908fe161372aceb99f98a3be54ead5" title="DEPRECATED FUNCTION This function has been replaced with oggz_comments_generate(), which does not require the packet_type argument. ">oggz_comment_generate()</a>. User generated packets should not be passed. </td></tr> </table> </dd> </dl> </div> </div> </div><!-- contents --> <!-- start footer part --> <hr class="footer"/><address class="footer"><small> Generated by  <a href="http://www.doxygen.org/index.html"> <img class="footer" src="doxygen.png" alt="doxygen"/> </a> 1.8.5 </small></address> </body> </html>