<!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>libkate: kate_comment access</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.1 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</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><a href="files.html"><span>Files</span></a></li>
<li><a href="examples.html"><span>Examples</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<h1>kate_comment access</h1><table border="0" cellpadding="0" cellspacing="0">
<tr><td colspan="2"><h2>Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__comments.html#ga4f717746ed53e557e57bb1e2b40dbd84">kate_comment_init</a> (<a class="el" href="structkate__comment.html">kate_comment</a> *kc)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__comments.html#ga92e532be93459a5b1d6835b64c1129da">kate_comment_clear</a> (<a class="el" href="structkate__comment.html">kate_comment</a> *kc)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__comments.html#ga337da40d0b1797656f4f8b9201fb4629">kate_comment_add_length</a> (<a class="el" href="structkate__comment.html">kate_comment</a> *kc, const char *comment, size_t len)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__comments.html#ga788d04e42f01305f88b3e6d4ba93e743">kate_comment_add</a> (<a class="el" href="structkate__comment.html">kate_comment</a> *kc, const char *comment)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__comments.html#ga8d0af9117470d1bfefd5128055e55dac">kate_comment_add_tag</a> (<a class="el" href="structkate__comment.html">kate_comment</a> *kc, const char *tag, const char *value)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">const char * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__comments.html#ga48b9d250bc5d13c25d44fc1645aea605">kate_comment_query</a> (const <a class="el" href="structkate__comment.html">kate_comment</a> *kc, const char *tag, int count)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__comments.html#ga27f193c35d8224539319801a9bfe9033">kate_comment_query_count</a> (const <a class="el" href="structkate__comment.html">kate_comment</a> *kc, const char *tag)</td></tr>
</table>
<hr/><a name="_details"></a><h2>Detailed Description</h2>
<hr/><h2>Function Documentation</h2>
<a class="anchor" id="ga788d04e42f01305f88b3e6d4ba93e743"></a><!-- doxytag: member="kate_comment.c::kate_comment_add" ref="ga788d04e42f01305f88b3e6d4ba93e743" args="(kate_comment *kc, const char *comment)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int kate_comment_add </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structkate__comment.html">kate_comment</a> * </td>
<td class="paramname"> <em>kc</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </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>Adds a comment to the <a class="el" href="structkate__comment.html">kate_comment</a> structure. The comment must be of the form "tag=value" The comment tag must be 7 bit ASCII, and may not contain embedded NULs The comment value is UTF-8 and may not contain embedded NULs as the comments ends at the first NUL encountered </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>kc</em> </td><td>the <a class="el" href="structkate__comment.html">kate_comment</a> structure to add the comment to </td></tr>
<tr><td valign="top"></td><td valign="top"><em>comment</em> </td><td>the comment to add, NUL terminated </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 success </dd>
<dd>
KATE_E_* error </dd></dl>
<p>References <a class="el" href="kate__comment_8c_source.html#l00086">kate_comment_add_length()</a>, and <a class="el" href="kate_8h_source.html#l00653">KATE_E_INVALID_PARAMETER</a>.</p>
<p>Referenced by <a class="el" href="kate__comment_8c_source.html#l00156">kate_comment_add_tag()</a>.</p>
</div>
</div>
<a class="anchor" id="ga337da40d0b1797656f4f8b9201fb4629"></a><!-- doxytag: member="kate_comment.c::kate_comment_add_length" ref="ga337da40d0b1797656f4f8b9201fb4629" args="(kate_comment *kc, const char *comment, size_t len)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int kate_comment_add_length </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structkate__comment.html">kate_comment</a> * </td>
<td class="paramname"> <em>kc</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>comment</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">size_t </td>
<td class="paramname"> <em>len</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Adds a comment to the <a class="el" href="structkate__comment.html">kate_comment</a> structure. The comment must be of the form "tag=value" The comment tag must be 7 bit ASCII, and may not contain embedded NULs The comment value is UTF-8 and may contain embedded NULs </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>kc</em> </td><td>the <a class="el" href="structkate__comment.html">kate_comment</a> structure to add the comment to </td></tr>
<tr><td valign="top"></td><td valign="top"><em>comment</em> </td><td>the comment to add (a stream of len bytes) </td></tr>
<tr><td valign="top"></td><td valign="top"><em>len</em> </td><td>the number of bytes in the comment </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 success </dd>
<dd>
KATE_E_* error </dd></dl>
<p>References <a class="el" href="kate_8h_source.html#l00338">kate_comment::comment_lengths</a>, <a class="el" href="kate_8h_source.html#l00339">kate_comment::comments</a>, <a class="el" href="kate_8h_source.html#l00662">KATE_E_BAD_TAG</a>, <a class="el" href="kate_8h_source.html#l00653">KATE_E_INVALID_PARAMETER</a>, <a class="el" href="kate_8h_source.html#l00654">KATE_E_OUT_OF_MEMORY</a>, <a class="el" href="kate__text_8c_source.html#l00341">kate_text_validate()</a>, <a class="el" href="kate_8h_source.html#l00034">kate_utf8</a>, and <a class="el" href="kate_8h_source.html#l00337">kate_comment::user_comments</a>.</p>
<p>Referenced by <a class="el" href="kate__comment_8c_source.html#l00136">kate_comment_add()</a>.</p>
</div>
</div>
<a class="anchor" id="ga8d0af9117470d1bfefd5128055e55dac"></a><!-- doxytag: member="kate_comment.c::kate_comment_add_tag" ref="ga8d0af9117470d1bfefd5128055e55dac" args="(kate_comment *kc, const char *tag, const char *value)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int kate_comment_add_tag </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structkate__comment.html">kate_comment</a> * </td>
<td class="paramname"> <em>kc</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>tag</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>Adds a comment to the <a class="el" href="structkate__comment.html">kate_comment</a> structure, formatted as "tag=value". The tag must be 7 bit ASCII and comply with Vorbis comment tag rules. The value must be valid UTF-8 text. Neither tag nor value may contain embedded NULs. To embed comments with embedded NUL in the payload, see kate_comment_add_length. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>kc</em> </td><td>the <a class="el" href="structkate__comment.html">kate_comment</a> structure to add the comment to </td></tr>
<tr><td valign="top"></td><td valign="top"><em>tag</em> </td><td>the tag 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 class="return"><dt><b>Returns:</b></dt><dd>0 success </dd>
<dd>
KATE_E_* error </dd></dl>
<p>References <a class="el" href="kate__comment_8c_source.html#l00136">kate_comment_add()</a>, <a class="el" href="kate_8h_source.html#l00653">KATE_E_INVALID_PARAMETER</a>, and <a class="el" href="kate_8h_source.html#l00654">KATE_E_OUT_OF_MEMORY</a>.</p>
</div>
</div>
<a class="anchor" id="ga92e532be93459a5b1d6835b64c1129da"></a><!-- doxytag: member="kate_comment.c::kate_comment_clear" ref="ga92e532be93459a5b1d6835b64c1129da" args="(kate_comment *kc)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int kate_comment_clear </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structkate__comment.html">kate_comment</a> * </td>
<td class="paramname"> <em>kc</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Destroys a <a class="el" href="structkate__comment.html">kate_comment</a> structure, it must be initialized again before being used. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>kc</em> </td><td>the structure to clear </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 success </dd>
<dd>
KATE_E_* error </dd></dl>
<p>References <a class="el" href="kate_8h_source.html#l00338">kate_comment::comment_lengths</a>, <a class="el" href="kate_8h_source.html#l00339">kate_comment::comments</a>, <a class="el" href="kate_8h_source.html#l00653">KATE_E_INVALID_PARAMETER</a>, <a class="el" href="kate_8h_source.html#l00337">kate_comment::user_comments</a>, and <a class="el" href="kate_8h_source.html#l00340">kate_comment::vendor</a>.</p>
</div>
</div>
<a class="anchor" id="ga4f717746ed53e557e57bb1e2b40dbd84"></a><!-- doxytag: member="kate_comment.c::kate_comment_init" ref="ga4f717746ed53e557e57bb1e2b40dbd84" args="(kate_comment *kc)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int kate_comment_init </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structkate__comment.html">kate_comment</a> * </td>
<td class="paramname"> <em>kc</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Initializes a <a class="el" href="structkate__comment.html">kate_comment</a> structure. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>kc</em> </td><td>the structure to initialize </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 success </dd>
<dd>
KATE_E_* error </dd></dl>
<p>References <a class="el" href="kate_8h_source.html#l00338">kate_comment::comment_lengths</a>, <a class="el" href="kate_8h_source.html#l00339">kate_comment::comments</a>, <a class="el" href="kate_8h_source.html#l00653">KATE_E_INVALID_PARAMETER</a>, <a class="el" href="kate_8h_source.html#l00337">kate_comment::user_comments</a>, and <a class="el" href="kate_8h_source.html#l00340">kate_comment::vendor</a>.</p>
<p>Referenced by <a class="el" href="kate__high_8c_source.html#l00027">kate_high_decode_init()</a>.</p>
</div>
</div>
<a class="anchor" id="ga48b9d250bc5d13c25d44fc1645aea605"></a><!-- doxytag: member="kate_comment.c::kate_comment_query" ref="ga48b9d250bc5d13c25d44fc1645aea605" args="(const kate_comment *kc, const char *tag, int count)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">const char* kate_comment_query </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="structkate__comment.html">kate_comment</a> * </td>
<td class="paramname"> <em>kc</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>tag</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"> <em>count</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Queries the value of a comment that has the given tag. The tags are case insensitive, so "tag", "TAG", "Tag", and "TaG" are all equivalent. If there are multiple comments with the same tag, count may be used to select which one to return. The number of comments with a given tag may be retrieved using kate_comment_query_count. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>kc</em> </td><td>the <a class="el" href="structkate__comment.html">kate_comment</a> structure to look into </td></tr>
<tr><td valign="top"></td><td valign="top"><em>tag</em> </td><td>the title of the comment to look for </td></tr>
<tr><td valign="top"></td><td valign="top"><em>count</em> </td><td>the index of the matching comment to return (if there are several) </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 success </dd>
<dd>
KATE_E_* error </dd></dl>
<p>References <a class="el" href="kate_8h_source.html#l00339">kate_comment::comments</a>, and <a class="el" href="kate_8h_source.html#l00337">kate_comment::user_comments</a>.</p>
</div>
</div>
<a class="anchor" id="ga27f193c35d8224539319801a9bfe9033"></a><!-- doxytag: member="kate_comment.c::kate_comment_query_count" ref="ga27f193c35d8224539319801a9bfe9033" args="(const kate_comment *kc, const char *tag)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int kate_comment_query_count </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="structkate__comment.html">kate_comment</a> * </td>
<td class="paramname"> <em>kc</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>tag</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Returns the number of comments with the given tag. The tags are case insensitive, so "tag", "TAG", "Tag", and "TaG" are all equivalent. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>kc</em> </td><td>the <a class="el" href="structkate__comment.html">kate_comment</a> structure to look into </td></tr>
<tr><td valign="top"></td><td valign="top"><em>tag</em> </td><td>the title of the comment to look for </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 success </dd>
<dd>
KATE_E_* error </dd></dl>
<p>References <a class="el" href="kate_8h_source.html#l00339">kate_comment::comments</a>, <a class="el" href="kate_8h_source.html#l00653">KATE_E_INVALID_PARAMETER</a>, and <a class="el" href="kate_8h_source.html#l00337">kate_comment::user_comments</a>.</p>
</div>
</div>
</div>
<hr size="1"/><address style="text-align: right;"><small>Generated on Wed Dec 23 04:05:07 2009 for libkate by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.1 </small></address>
</body>
</html>
