<!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>liboggz: oggz_comments.h File Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.6.3 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<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 class="tabs">
<ul>
<li><a href="files.html"><span>File List</span></a></li>
<li><a href="globals.html"><span>Globals</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<h1>oggz_comments.h File Reference</h1>
<p>Reading of comments.
<a href="#_details">More...</a></p>
<code>#include <<a class="el" href="oggz_8h_source.html">oggz/oggz.h</a>></code><br/>
<p><a href="oggz__comments_8h_source.html">Go to the source code of this file.</a></p>
<table border="0" cellpadding="0" cellspacing="0">
<tr><td colspan="2"><h2>Data Structures</h2></td></tr>
<tr><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><td class="mdescLeft"> </td><td class="mdescRight">A comment. <a href="structOggzComment.html#_details">More...</a><br/></td></tr>
<tr><td colspan="2"><h2>Functions</h2></td></tr>
<tr><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><td class="mdescLeft"> </td><td class="mdescRight">Retrieve the vendor string. <a href="#ae5d522df5fce262953d8bb5cb8c00b00"></a><br/></td></tr>
<tr><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><td class="mdescLeft"> </td><td class="mdescRight">Set the vendor string. <a href="#a281a0956a9a160337f7d00f102d18131"></a><br/></td></tr>
<tr><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><td class="mdescLeft"> </td><td class="mdescRight">Retrieve the first comment. <a href="#a306a979d84b61932930d44ea5d4f95d9"></a><br/></td></tr>
<tr><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><td class="mdescLeft"> </td><td class="mdescRight">Retrieve the next comment. <a href="#a9501d8c166187c8d503e1335827b2d5e"></a><br/></td></tr>
<tr><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><td class="mdescLeft"> </td><td class="mdescRight">Retrieve the first comment with a given name. <a href="#a9a3a72be012b6474a1e1d95f7ce7afe8"></a><br/></td></tr>
<tr><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><td class="mdescLeft"> </td><td class="mdescRight">Retrieve the next comment following and with the same name as a given comment. <a href="#a1dd05e02a121ba639b8012acaa21a37c"></a><br/></td></tr>
<tr><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><td class="mdescLeft"> </td><td class="mdescRight">Add a comment. <a href="#ade23081a738d67bec473bdaf317a68d8"></a><br/></td></tr>
<tr><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><td class="mdescLeft"> </td><td class="mdescRight">Add a comment by name and value. <a href="#ad869a8a7246567ba4162183436127a6f"></a><br/></td></tr>
<tr><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><td class="mdescLeft"> </td><td class="mdescRight">Remove a comment. <a href="#a75ca47a020dcddce846a320481120a8e"></a><br/></td></tr>
<tr><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><td class="mdescLeft"> </td><td class="mdescRight">Remove all comments with a given name. <a href="#aa0f3f3a3ea3ca28d8678b94495634876"></a><br/></td></tr>
<tr><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><td class="mdescLeft"> </td><td class="mdescRight">Output a comment packet for the specified stream. <a href="#a1ee69481fa517d80e63db962a23d53ae"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="a486cd52284cb03032360265d2027f8db"></a><!-- doxytag: member="oggz_comments.h::oggz_comments_copy" ref="a486cd52284cb03032360265d2027f8db" args="(OGGZ *src, long src_serialno, OGGZ *dest, long dest_serialno)" -->
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><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><td class="mdescLeft"> </td><td class="mdescRight">Free a packet and its payload. <a href="#a9301332e99b0397cff54c3593595b809"></a><br/></td></tr>
</table>
<hr/><a name="_details"></a><h2>Detailed Description</h2>
<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>
<h2><a class="anchor" id="comments_get">
Reading comments</a></h2>
<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>
<h2><a class="anchor" id="comments_set">
Writing comments</a></h2>
<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>
<hr/><h2>Function Documentation</h2>
<a class="anchor" id="ade23081a738d67bec473bdaf317a68d8"></a><!-- doxytag: member="oggz_comments.h::oggz_comment_add" ref="ade23081a738d67bec473bdaf317a68d8" args="(OGGZ *oggz, long serialno, OggzComment *comment)" -->
<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><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Add a comment. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>oggz</em> </td><td>A OGGZ* handle (created with mode OGGZ_WRITE) </td></tr>
<tr><td valign="top"></td><td valign="top"><em>serialno</em> </td><td>Identify a logical bitstream within <em>oggz</em> </td></tr>
<tr><td valign="top"></td><td valign="top"><em>comment</em> </td><td>The comment to add </td></tr>
</table>
</dd>
</dl>
<dl><dt><b>Return values:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>0</em> </td><td>Success </td></tr>
<tr><td valign="top"></td><td valign="top"><em>OGGZ_ERR_BAD</em> </td><td><em>oggz</em> is not a valid OGGZ* handle </td></tr>
<tr><td valign="top"></td><td valign="top"><em>OGGZ_ERR_INVALID</em> </td><td>Operation not suitable for this OGGZ </td></tr>
<tr><td valign="top"></td><td valign="top"><em>OGGZ_ERR_OUT_OF_MEMORY</em> </td><td>Out of memory </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="ad869a8a7246567ba4162183436127a6f"></a><!-- doxytag: member="oggz_comments.h::oggz_comment_add_byname" ref="ad869a8a7246567ba4162183436127a6f" args="(OGGZ *oggz, long serialno, const char *name, const char *value)" -->
<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><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Add a comment by name and value. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>oggz</em> </td><td>A OGGZ* handle (created with mode OGGZ_WRITE) </td></tr>
<tr><td valign="top"></td><td valign="top"><em>serialno</em> </td><td>Identify a logical bitstream within <em>oggz</em> </td></tr>
<tr><td valign="top"></td><td valign="top"><em>name</em> </td><td>The name of the comment to add </td></tr>
<tr><td valign="top"></td><td valign="top"><em>value</em> </td><td>The contents of the comment to add </td></tr>
</table>
</dd>
</dl>
<dl><dt><b>Return values:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>0</em> </td><td>Success </td></tr>
<tr><td valign="top"></td><td valign="top"><em>OGGZ_ERR_BAD</em> </td><td><em>oggz</em> is not a valid OGGZ* handle </td></tr>
<tr><td valign="top"></td><td valign="top"><em>OGGZ_ERR_INVALID</em> </td><td>Operation not suitable for this OGGZ </td></tr>
<tr><td valign="top"></td><td valign="top"><em>OGGZ_ERR_OUT_OF_MEMORY</em> </td><td>Out of memory </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="a306a979d84b61932930d44ea5d4f95d9"></a><!-- doxytag: member="oggz_comments.h::oggz_comment_first" ref="a306a979d84b61932930d44ea5d4f95d9" args="(OGGZ *oggz, long serialno)" -->
<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><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Retrieve the first comment. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>oggz</em> </td><td>A OGGZ* handle </td></tr>
<tr><td valign="top"></td><td valign="top"><em>serialno</em> </td><td>Identify a logical bitstream within <em>oggz</em> </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>A read-only copy of the first comment. </dd></dl>
<dl><dt><b>Return values:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>NULL</em> </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><!-- doxytag: member="oggz_comments.h::oggz_comment_first_byname" ref="a9a3a72be012b6474a1e1d95f7ce7afe8" args="(OGGZ *oggz, long serialno, char *name)" -->
<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><td> </td>
</tr>
<tr>
<td></td>
<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><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>oggz</em> </td><td>A OGGZ* handle </td></tr>
<tr><td valign="top"></td><td valign="top"><em>serialno</em> </td><td>Identify a logical bitstream within <em>oggz</em> </td></tr>
<tr><td valign="top"></td><td valign="top"><em>name</em> </td><td>the name of the comment to retrieve. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>A read-only copy of the first comment matching the given <em>name</em>. </dd></dl>
<dl><dt><b>Return values:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>NULL</em> </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="note"><dt><b>Note:</b></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><!-- doxytag: member="oggz_comments.h::oggz_comment_get_vendor" ref="ae5d522df5fce262953d8bb5cb8c00b00" args="(OGGZ *oggz, long serialno)" -->
<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><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Retrieve the vendor string. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>oggz</em> </td><td>A OGGZ* handle </td></tr>
<tr><td valign="top"></td><td valign="top"><em>serialno</em> </td><td>Identify a logical bitstream within <em>oggz</em> </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>A read-only copy of the vendor string. </dd></dl>
<dl><dt><b>Return values:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>NULL</em> </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><!-- doxytag: member="oggz_comments.h::oggz_comment_next" ref="a9501d8c166187c8d503e1335827b2d5e" args="(OGGZ *oggz, long serialno, const OggzComment *comment)" -->
<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><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Retrieve the next comment. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>oggz</em> </td><td>A OGGZ* handle </td></tr>
<tr><td valign="top"></td><td valign="top"><em>serialno</em> </td><td>Identify a logical bitstream within <em>oggz</em> </td></tr>
<tr><td valign="top"></td><td valign="top"><em>comment</em> </td><td>The previous comment. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>A read-only copy of the comment immediately following the given comment. </dd></dl>
<dl><dt><b>Return values:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>NULL</em> </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><!-- doxytag: member="oggz_comments.h::oggz_comment_next_byname" ref="a1dd05e02a121ba639b8012acaa21a37c" args="(OGGZ *oggz, long serialno, const OggzComment *comment)" -->
<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><td> </td>
</tr>
<tr>
<td></td>
<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><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>oggz</em> </td><td>A OGGZ* handle </td></tr>
<tr><td valign="top"></td><td valign="top"><em>serialno</em> </td><td>Identify a logical bitstream within <em>oggz</em> </td></tr>
<tr><td valign="top"></td><td valign="top"><em>comment</em> </td><td>A comment </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>A read-only copy of the next comment with the same name as <em>comment</em>. </dd></dl>
<dl><dt><b>Return values:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>NULL</em> </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><!-- doxytag: member="oggz_comments.h::oggz_comment_remove" ref="a75ca47a020dcddce846a320481120a8e" args="(OGGZ *oggz, long serialno, OggzComment *comment)" -->
<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><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Remove a comment. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>oggz</em> </td><td>A OGGZ* handle (created with OGGZ_WRITE) </td></tr>
<tr><td valign="top"></td><td valign="top"><em>serialno</em> </td><td>Identify a logical bitstream within <em>oggz</em> </td></tr>
<tr><td valign="top"></td><td valign="top"><em>comment</em> </td><td>The comment to remove. </td></tr>
</table>
</dd>
</dl>
<dl><dt><b>Return values:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>1</em> </td><td>Success: comment removed </td></tr>
<tr><td valign="top"></td><td valign="top"><em>0</em> </td><td>No-op: comment not found, nothing to remove </td></tr>
<tr><td valign="top"></td><td valign="top"><em>OGGZ_ERR_BAD</em> </td><td><em>oggz</em> is not a valid OGGZ* handle </td></tr>
<tr><td valign="top"></td><td valign="top"><em>OGGZ_ERR_INVALID</em> </td><td>Operation not suitable for this OGGZ </td></tr>
<tr><td valign="top"></td><td valign="top"><em>OGGZ_ERR_BAD_SERIALNO</em> </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><!-- doxytag: member="oggz_comments.h::oggz_comment_remove_byname" ref="aa0f3f3a3ea3ca28d8678b94495634876" args="(OGGZ *oggz, long serialno, char *name)" -->
<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><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Remove all comments with a given name. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>oggz</em> </td><td>A OGGZ* handle (created with OGGZ_WRITE) </td></tr>
<tr><td valign="top"></td><td valign="top"><em>serialno</em> </td><td>Identify a logical bitstream within <em>oggz</em> </td></tr>
<tr><td valign="top"></td><td valign="top"><em>name</em> </td><td>The name of the comments to remove </td></tr>
</table>
</dd>
</dl>
<dl><dt><b>Return values:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>>= 0</em> </td><td>The number of comments removed </td></tr>
<tr><td valign="top"></td><td valign="top"><em>OGGZ_ERR_BAD</em> </td><td><em>oggz</em> is not a valid OGGZ* handle </td></tr>
<tr><td valign="top"></td><td valign="top"><em>OGGZ_ERR_INVALID</em> </td><td>Operation not suitable for this OGGZ </td></tr>
<tr><td valign="top"></td><td valign="top"><em>OGGZ_ERR_BAD_SERIALNO</em> </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><!-- doxytag: member="oggz_comments.h::oggz_comment_set_vendor" ref="a281a0956a9a160337f7d00f102d18131" args="(OGGZ *oggz, long serialno, const char *vendor_string)" -->
<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><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Set the vendor string. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>oggz</em> </td><td>A OGGZ* handle </td></tr>
<tr><td valign="top"></td><td valign="top"><em>serialno</em> </td><td>Identify a logical bitstream within <em>oggz</em> </td></tr>
<tr><td valign="top"></td><td valign="top"><em>vendor_string</em> </td><td>The contents of the vendor string to add </td></tr>
</table>
</dd>
</dl>
<dl><dt><b>Return values:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>0</em> </td><td>Success </td></tr>
<tr><td valign="top"></td><td valign="top"><em>OGGZ_ERR_BAD</em> </td><td><em>oggz</em> is not a valid OGGZ* handle </td></tr>
<tr><td valign="top"></td><td valign="top"><em>OGGZ_ERR_INVALID</em> </td><td>Operation not suitable for this OGGZ </td></tr>
<tr><td valign="top"></td><td valign="top"><em>OGGZ_ERR_OUT_OF_MEMORY</em> </td><td>Out of memory </td></tr>
</table>
</dd>
</dl>
<dl class="note"><dt><b>Note:</b></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><!-- doxytag: member="oggz_comments.h::oggz_comments_generate" ref="a1ee69481fa517d80e63db962a23d53ae" args="(OGGZ *oggz, long serialno, int FLAC_final_metadata_block)" -->
<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><td> </td>
</tr>
<tr>
<td></td>
<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><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>oggz</em> </td><td>A OGGZ* handle (created with OGGZ_WRITE) </td></tr>
<tr><td valign="top"></td><td valign="top"><em>serialno</em> </td><td>Identify a logical bitstream within <em>oggz</em> </td></tr>
<tr><td valign="top"></td><td valign="top"><em>FLAC_final_metadata_block</em> </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="return"><dt><b>Returns:</b></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><dt><b>Return values:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>NULL</em> </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="note"><dt><b>Note:</b></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><!-- doxytag: member="oggz_comments.h::oggz_packet_destroy" ref="a9301332e99b0397cff54c3593595b809" args="(ogg_packet *packet)" -->
<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><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>packet</em> </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()...">oggz_comment_generate()</a>. User generated packets should not be passed. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
</div>
<hr class="footer"/><address style="text-align: right;"><small>Generated on Sat Apr 24 09:13:55 2010 for liboggz 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>