← Back to branch summary

~ubuntu-branches/ubuntu/hardy/libfishsound/hardy-security

« back to all changes in this revision

Viewing changes to doc/libfishsound/html/comments_8h.html

  • Committer: Bazaar Package Importer
  • Author(s): Jamie Wilkinson
  • Date: 2005-04-14 09:09:34 UTC
  • Revision ID: james.westby@ubuntu.com-20050414090934-3hub4x7n627qrmch
Tags: upstream-0.6.3
Import upstream version 0.6.3

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/libfishsound/html/comments_8h.html
 
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 
2
<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
 
3
<title>libfishsound: comments.h File Reference</title>
 
4
<link href="doxygen.css" rel="stylesheet" type="text/css">
 
5
</head><body>
 
6
<!-- Generated by Doxygen 1.3.5 -->
 
7
<div class="qindex"><a class="qindex" href="index.html">Main&nbsp;Page</a> | <a class="qindex" href="modules.html">Modules</a> | <a class="qindex" href="annotated.html">Data&nbsp;Structures</a> | <a class="qindex" href="files.html">File&nbsp;List</a> | <a class="qindex" href="functions.html">Data&nbsp;Fields</a> | <a class="qindex" href="globals.html">Globals</a></div>
 
8
<h1>comments.h File Reference</h1>Encoding and decoding of comments.  
 
9
<a href="#_details">More...</a>
 
10
<p>
 
11
<code>#include &lt;<a class="el" href="fishsound_8h-source.html">fishsound/fishsound.h</a>&gt;</code><br>
 
12
 
 
13
<p>
 
14
<a href="comments_8h-source.html">Go to the source code of this file.</a><table border=0 cellpadding=0 cellspacing=0>
 
15
<tr><td></td></tr>
 
16
<tr><td colspan=2><br><h2>Data Structures</h2></td></tr>
 
17
<tr><td class="memItemLeft" nowrap align=right valign=top>struct &nbsp;</td><td class="memItemRight" valign=bottom><a class="el" href="structFishSoundComment.html">FishSoundComment</a></td></tr>
 
18
 
 
19
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">A comment. </em> <a href="structFishSoundComment.html#_details">More...</a><em><br><br></td></tr>
 
20
<tr><td colspan=2><br><h2>Functions</h2></td></tr>
 
21
<tr><td class="memItemLeft" nowrap align=right valign=top>const char *&nbsp;</td><td class="memItemRight" valign=bottom><a class="el" href="comments_8h.html#a0">fish_sound_comment_get_vendor</a> (<a class="el" href="fishsound_8h.html#a0">FishSound</a> *fsound)</td></tr>
 
22
 
 
23
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Retrieve the vendor string.  <a href="#a0"></a><br><br></td></tr>
 
24
<tr><td class="memItemLeft" nowrap align=right valign=top>const <a class="el" href="structFishSoundComment.html">FishSoundComment</a> *&nbsp;</td><td class="memItemRight" valign=bottom><a class="el" href="comments_8h.html#a1">fish_sound_comment_first</a> (<a class="el" href="fishsound_8h.html#a0">FishSound</a> *fsound)</td></tr>
 
25
 
 
26
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Retrieve the first comment.  <a href="#a1"></a><br><br></td></tr>
 
27
<tr><td class="memItemLeft" nowrap align=right valign=top>const <a class="el" href="structFishSoundComment.html">FishSoundComment</a> *&nbsp;</td><td class="memItemRight" valign=bottom><a class="el" href="comments_8h.html#a2">fish_sound_comment_next</a> (<a class="el" href="fishsound_8h.html#a0">FishSound</a> *fsound, const <a class="el" href="structFishSoundComment.html">FishSoundComment</a> *comment)</td></tr>
 
28
 
 
29
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Retrieve the next comment.  <a href="#a2"></a><br><br></td></tr>
 
30
<tr><td class="memItemLeft" nowrap align=right valign=top>const <a class="el" href="structFishSoundComment.html">FishSoundComment</a> *&nbsp;</td><td class="memItemRight" valign=bottom><a class="el" href="comments_8h.html#a3">fish_sound_comment_first_byname</a> (<a class="el" href="fishsound_8h.html#a0">FishSound</a> *fsound, char *name)</td></tr>
 
31
 
 
32
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Retrieve the first comment with a given name.  <a href="#a3"></a><br><br></td></tr>
 
33
<tr><td class="memItemLeft" nowrap align=right valign=top>const <a class="el" href="structFishSoundComment.html">FishSoundComment</a> *&nbsp;</td><td class="memItemRight" valign=bottom><a class="el" href="comments_8h.html#a4">fish_sound_comment_next_byname</a> (<a class="el" href="fishsound_8h.html#a0">FishSound</a> *fsound, const <a class="el" href="structFishSoundComment.html">FishSoundComment</a> *comment)</td></tr>
 
34
 
 
35
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Retrieve the next comment following and with the same name as a given comment.  <a href="#a4"></a><br><br></td></tr>
 
36
<tr><td class="memItemLeft" nowrap align=right valign=top>int&nbsp;</td><td class="memItemRight" valign=bottom><a class="el" href="comments_8h.html#a5">fish_sound_comment_add</a> (<a class="el" href="fishsound_8h.html#a0">FishSound</a> *fsound, <a class="el" href="structFishSoundComment.html">FishSoundComment</a> *comment)</td></tr>
 
37
 
 
38
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Add a comment.  <a href="#a5"></a><br><br></td></tr>
 
39
<tr><td class="memItemLeft" nowrap align=right valign=top>int&nbsp;</td><td class="memItemRight" valign=bottom><a class="el" href="comments_8h.html#a6">fish_sound_comment_add_byname</a> (<a class="el" href="fishsound_8h.html#a0">FishSound</a> *fsound, const char *name, const char *value)</td></tr>
 
40
 
 
41
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Add a comment by name and value.  <a href="#a6"></a><br><br></td></tr>
 
42
<tr><td class="memItemLeft" nowrap align=right valign=top>int&nbsp;</td><td class="memItemRight" valign=bottom><a class="el" href="comments_8h.html#a7">fish_sound_comment_remove</a> (<a class="el" href="fishsound_8h.html#a0">FishSound</a> *fsound, <a class="el" href="structFishSoundComment.html">FishSoundComment</a> *comment)</td></tr>
 
43
 
 
44
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Remove a comment.  <a href="#a7"></a><br><br></td></tr>
 
45
<tr><td class="memItemLeft" nowrap align=right valign=top>int&nbsp;</td><td class="memItemRight" valign=bottom><a class="el" href="comments_8h.html#a8">fish_sound_comment_remove_byname</a> (<a class="el" href="fishsound_8h.html#a0">FishSound</a> *fsound, char *name)</td></tr>
 
46
 
 
47
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Remove all comments with a given name.  <a href="#a8"></a><br><br></td></tr>
 
48
</table>
 
49
<hr><a name="_details"></a><h2>Detailed Description</h2>
 
50
Encoding and decoding of comments. 
 
51
<p>
 
52
Vorbis and Speex 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>
 
53
The following general features of Vorbiscomment are relevant to this API:<ul>
 
54
<li>Each stream has one comment packet, which occurs before any encoded audio data in the stream.</li><li>When encoding, FishSound will generate the comment block and pass it to the encoded() callback in sequence, just like any other packet. Hence, all comments must be set before any call to <a class="el" href="fishsound_8h.html#a8">fish_sound_encode()</a>.</li><li>When decoding, FishSound will decode the comment block before calling the first decoded() callback. Hence, retrieving comment data is possible from as soon as the decoded() callback is first called.</li></ul>
 
55
<p>
 
56
Each comment block contains one Vendor string, which can be retrieved with <a class="el" href="comments_8h.html#a0">fish_sound_comment_get_vendor()</a>. When encoding, this string is effectively fixed by the codec libraries; it cannot be set by the application.<p>
 
57
The rest of a comment block consists of <em>name</em> = <em>value</em> pairs, with the following restrictions:<ul>
 
58
<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>
 
59
<h2><a class="anchor" name="comments_get">
 
60
Retrieving comments</a></h2>
 
61
FishSound contains API methods to iterate through all comments associated with a FishSound* handle (<a class="el" href="comments_8h.html#a1">fish_sound_comment_first()</a> and <a class="el" href="comments_8h.html#a2">fish_sound_comment_next()</a>, and to iterate through comments matching a particular name (<a class="el" href="comments_8h.html#a3">fish_sound_comment_first_byname()</a> and <a class="el" href="comments_8h.html#a4">fish_sound_comment_next_byname()</a>). Given that multiple comments may exist with the same <em>name</em>, you should not use <a class="el" href="comments_8h.html#a3">fish_sound_comment_first_byname()</a> as a simple "get" function.<h2><a class="anchor" name="comments_set">
 
62
Encoding comments</a></h2>
 
63
For encoding, FishSound contains API methods for adding comments (<a class="el" href="comments_8h.html#a5">fish_sound_comment_add()</a> and <a class="el" href="comments_8h.html#a6">fish_sound_comment_add_byname()</a> and for removing comments (<a class="el" href="comments_8h.html#a7">fish_sound_comment_remove()</a> and <a class="el" href="comments_8h.html#a8">fish_sound_comment_remove_byname()</a>).<hr><h2>Function Documentation</h2>
 
64
<a class="anchor" name="a5" doxytag="comments.h::fish_sound_comment_add" ></a><p>
 
65
<table class="mdTable" width="100%" cellpadding="2" cellspacing="0">
 
66
  <tr>
 
67
    <td class="mdRow">
 
68
      <table cellpadding="0" cellspacing="0" border="0">
 
69
        <tr>
 
70
          <td class="md" nowrap valign="top"> int fish_sound_comment_add </td>
 
71
          <td class="md" valign="top">(&nbsp;</td>
 
72
          <td class="md" nowrap valign="top"><a class="el" href="fishsound_8h.html#a0">FishSound</a> *&nbsp;</td>
 
73
          <td class="mdname" nowrap> <em>fsound</em>, </td>
 
74
        </tr>
 
75
        <tr>
 
76
          <td></td>
 
77
          <td></td>
 
78
          <td class="md" nowrap><a class="el" href="structFishSoundComment.html">FishSoundComment</a> *&nbsp;</td>
 
79
          <td class="mdname" nowrap> <em>comment</em></td>
 
80
        </tr>
 
81
        <tr>
 
82
          <td></td>
 
83
          <td class="md">)&nbsp;</td>
 
84
          <td class="md" colspan="2"></td>
 
85
        </tr>
 
86
 
 
87
      </table>
 
88
    </td>
 
89
  </tr>
 
90
</table>
 
91
<table cellspacing=5 cellpadding=0 border=0>
 
92
  <tr>
 
93
    <td>
 
94
      &nbsp;
 
95
    </td>
 
96
    <td>
 
97
 
 
98
<p>
 
99
Add a comment. 
 
100
<p>
 
101
<dl compact><dt><b>Parameters:</b></dt><dd>
 
102
  <table border="0" cellspacing="2" cellpadding="0">
 
103
    <tr><td valign=top><em>fsound</em>&nbsp;</td><td>A FishSound* handle (created with mode FISH_SOUND_ENCODE) </td></tr>
 
104
    <tr><td valign=top><em>comment</em>&nbsp;</td><td>The comment to add </td></tr>
 
105
  </table>
 
106
</dl>
 
107
<dl compact><dt><b>Return values:</b></dt><dd>
 
108
  <table border="0" cellspacing="2" cellpadding="0">
 
109
    <tr><td valign=top><em>0</em>&nbsp;</td><td>Success </td></tr>
 
110
    <tr><td valign=top><em>FISH_SOUND_ERR_BAD</em>&nbsp;</td><td><em>fsound</em> is not a valid FishSound* handle </td></tr>
 
111
    <tr><td valign=top><em>FISH_SOUND_ERR_INVALID</em>&nbsp;</td><td>Operation not suitable for this FishSound </td></tr>
 
112
  </table>
 
113
</dl>
 
114
    </td>
 
115
  </tr>
 
116
</table>
 
117
<a class="anchor" name="a6" doxytag="comments.h::fish_sound_comment_add_byname" ></a><p>
 
118
<table class="mdTable" width="100%" cellpadding="2" cellspacing="0">
 
119
  <tr>
 
120
    <td class="mdRow">
 
121
      <table cellpadding="0" cellspacing="0" border="0">
 
122
        <tr>
 
123
          <td class="md" nowrap valign="top"> int fish_sound_comment_add_byname </td>
 
124
          <td class="md" valign="top">(&nbsp;</td>
 
125
          <td class="md" nowrap valign="top"><a class="el" href="fishsound_8h.html#a0">FishSound</a> *&nbsp;</td>
 
126
          <td class="mdname" nowrap> <em>fsound</em>, </td>
 
127
        </tr>
 
128
        <tr>
 
129
          <td></td>
 
130
          <td></td>
 
131
          <td class="md" nowrap>const char *&nbsp;</td>
 
132
          <td class="mdname" nowrap> <em>name</em>, </td>
 
133
        </tr>
 
134
        <tr>
 
135
          <td></td>
 
136
          <td></td>
 
137
          <td class="md" nowrap>const char *&nbsp;</td>
 
138
          <td class="mdname" nowrap> <em>value</em></td>
 
139
        </tr>
 
140
        <tr>
 
141
          <td></td>
 
142
          <td class="md">)&nbsp;</td>
 
143
          <td class="md" colspan="2"></td>
 
144
        </tr>
 
145
 
 
146
      </table>
 
147
    </td>
 
148
  </tr>
 
149
</table>
 
150
<table cellspacing=5 cellpadding=0 border=0>
 
151
  <tr>
 
152
    <td>
 
153
      &nbsp;
 
154
    </td>
 
155
    <td>
 
156
 
 
157
<p>
 
158
Add a comment by name and value. 
 
159
<p>
 
160
<dl compact><dt><b>Parameters:</b></dt><dd>
 
161
  <table border="0" cellspacing="2" cellpadding="0">
 
162
    <tr><td valign=top><em>fsound</em>&nbsp;</td><td>A FishSound* handle (created with mode FISH_SOUND_ENCODE) </td></tr>
 
163
    <tr><td valign=top><em>name</em>&nbsp;</td><td>The name of the comment to add </td></tr>
 
164
    <tr><td valign=top><em>value</em>&nbsp;</td><td>The contents of the comment to add </td></tr>
 
165
  </table>
 
166
</dl>
 
167
<dl compact><dt><b>Return values:</b></dt><dd>
 
168
  <table border="0" cellspacing="2" cellpadding="0">
 
169
    <tr><td valign=top><em>0</em>&nbsp;</td><td>Success </td></tr>
 
170
    <tr><td valign=top><em>FISH_SOUND_ERR_BAD</em>&nbsp;</td><td><em>fsound</em> is not a valid FishSound* handle </td></tr>
 
171
    <tr><td valign=top><em>FISH_SOUND_ERR_INVALID</em>&nbsp;</td><td>Operation not suitable for this FishSound </td></tr>
 
172
  </table>
 
173
</dl>
 
174
    </td>
 
175
  </tr>
 
176
</table>
 
177
<a class="anchor" name="a1" doxytag="comments.h::fish_sound_comment_first" ></a><p>
 
178
<table class="mdTable" width="100%" cellpadding="2" cellspacing="0">
 
179
  <tr>
 
180
    <td class="mdRow">
 
181
      <table cellpadding="0" cellspacing="0" border="0">
 
182
        <tr>
 
183
          <td class="md" nowrap valign="top"> const <a class="el" href="structFishSoundComment.html">FishSoundComment</a>* fish_sound_comment_first </td>
 
184
          <td class="md" valign="top">(&nbsp;</td>
 
185
          <td class="md" nowrap valign="top"><a class="el" href="fishsound_8h.html#a0">FishSound</a> *&nbsp;</td>
 
186
          <td class="mdname1" valign="top" nowrap> <em>fsound</em>          </td>
 
187
          <td class="md" valign="top">&nbsp;)&nbsp;</td>
 
188
          <td class="md" nowrap></td>
 
189
        </tr>
 
190
 
 
191
      </table>
 
192
    </td>
 
193
  </tr>
 
194
</table>
 
195
<table cellspacing=5 cellpadding=0 border=0>
 
196
  <tr>
 
197
    <td>
 
198
      &nbsp;
 
199
    </td>
 
200
    <td>
 
201
 
 
202
<p>
 
203
Retrieve the first comment. 
 
204
<p>
 
205
<dl compact><dt><b>Parameters:</b></dt><dd>
 
206
  <table border="0" cellspacing="2" cellpadding="0">
 
207
    <tr><td valign=top><em>fsound</em>&nbsp;</td><td>A FishSound* handle </td></tr>
 
208
  </table>
 
209
</dl>
 
210
<dl compact><dt><b>Returns:</b></dt><dd>A read-only copy of the first comment, or NULL if no comments exist for this FishSound* object. </dd></dl>
 
211
    </td>
 
212
  </tr>
 
213
</table>
 
214
<a class="anchor" name="a3" doxytag="comments.h::fish_sound_comment_first_byname" ></a><p>
 
215
<table class="mdTable" width="100%" cellpadding="2" cellspacing="0">
 
216
  <tr>
 
217
    <td class="mdRow">
 
218
      <table cellpadding="0" cellspacing="0" border="0">
 
219
        <tr>
 
220
          <td class="md" nowrap valign="top"> const <a class="el" href="structFishSoundComment.html">FishSoundComment</a>* fish_sound_comment_first_byname </td>
 
221
          <td class="md" valign="top">(&nbsp;</td>
 
222
          <td class="md" nowrap valign="top"><a class="el" href="fishsound_8h.html#a0">FishSound</a> *&nbsp;</td>
 
223
          <td class="mdname" nowrap> <em>fsound</em>, </td>
 
224
        </tr>
 
225
        <tr>
 
226
          <td></td>
 
227
          <td></td>
 
228
          <td class="md" nowrap>char *&nbsp;</td>
 
229
          <td class="mdname" nowrap> <em>name</em></td>
 
230
        </tr>
 
231
        <tr>
 
232
          <td></td>
 
233
          <td class="md">)&nbsp;</td>
 
234
          <td class="md" colspan="2"></td>
 
235
        </tr>
 
236
 
 
237
      </table>
 
238
    </td>
 
239
  </tr>
 
240
</table>
 
241
<table cellspacing=5 cellpadding=0 border=0>
 
242
  <tr>
 
243
    <td>
 
244
      &nbsp;
 
245
    </td>
 
246
    <td>
 
247
 
 
248
<p>
 
249
Retrieve the first comment with a given name. 
 
250
<p>
 
251
<dl compact><dt><b>Parameters:</b></dt><dd>
 
252
  <table border="0" cellspacing="2" cellpadding="0">
 
253
    <tr><td valign=top><em>fsound</em>&nbsp;</td><td>A FishSound* handle </td></tr>
 
254
    <tr><td valign=top><em>name</em>&nbsp;</td><td>the name of the comment to retrieve. </td></tr>
 
255
  </table>
 
256
</dl>
 
257
<dl compact><dt><b>Returns:</b></dt><dd>A read-only copy of the first comment matching the given <em>name</em>. </dd></dl>
 
258
<dl compact><dt><b>Return values:</b></dt><dd>
 
259
  <table border="0" cellspacing="2" cellpadding="0">
 
260
    <tr><td valign=top><em>NULL</em>&nbsp;</td><td>no match was found. </td></tr>
 
261
  </table>
 
262
</dl>
 
263
<dl compact><dt><b>Note:</b></dt><dd>If <em>name</em> is NULL, the behaviour is the same as for <a class="el" href="comments_8h.html#a1">fish_sound_comment_first()</a> </dd></dl>
 
264
    </td>
 
265
  </tr>
 
266
</table>
 
267
<a class="anchor" name="a0" doxytag="comments.h::fish_sound_comment_get_vendor" ></a><p>
 
268
<table class="mdTable" width="100%" cellpadding="2" cellspacing="0">
 
269
  <tr>
 
270
    <td class="mdRow">
 
271
      <table cellpadding="0" cellspacing="0" border="0">
 
272
        <tr>
 
273
          <td class="md" nowrap valign="top"> const char* fish_sound_comment_get_vendor </td>
 
274
          <td class="md" valign="top">(&nbsp;</td>
 
275
          <td class="md" nowrap valign="top"><a class="el" href="fishsound_8h.html#a0">FishSound</a> *&nbsp;</td>
 
276
          <td class="mdname1" valign="top" nowrap> <em>fsound</em>          </td>
 
277
          <td class="md" valign="top">&nbsp;)&nbsp;</td>
 
278
          <td class="md" nowrap></td>
 
279
        </tr>
 
280
 
 
281
      </table>
 
282
    </td>
 
283
  </tr>
 
284
</table>
 
285
<table cellspacing=5 cellpadding=0 border=0>
 
286
  <tr>
 
287
    <td>
 
288
      &nbsp;
 
289
    </td>
 
290
    <td>
 
291
 
 
292
<p>
 
293
Retrieve the vendor string. 
 
294
<p>
 
295
<dl compact><dt><b>Parameters:</b></dt><dd>
 
296
  <table border="0" cellspacing="2" cellpadding="0">
 
297
    <tr><td valign=top><em>fsound</em>&nbsp;</td><td>A FishSound* handle </td></tr>
 
298
  </table>
 
299
</dl>
 
300
<dl compact><dt><b>Returns:</b></dt><dd>A read-only copy of the vendor string </dd></dl>
 
301
<dl compact><dt><b>Return values:</b></dt><dd>
 
302
  <table border="0" cellspacing="2" cellpadding="0">
 
303
    <tr><td valign=top><em>NULL</em>&nbsp;</td><td>No vendor string is associated with <em>fsound</em>, or <em>fsound</em> is NULL. </td></tr>
 
304
  </table>
 
305
</dl>
 
306
    </td>
 
307
  </tr>
 
308
</table>
 
309
<a class="anchor" name="a2" doxytag="comments.h::fish_sound_comment_next" ></a><p>
 
310
<table class="mdTable" width="100%" cellpadding="2" cellspacing="0">
 
311
  <tr>
 
312
    <td class="mdRow">
 
313
      <table cellpadding="0" cellspacing="0" border="0">
 
314
        <tr>
 
315
          <td class="md" nowrap valign="top"> const <a class="el" href="structFishSoundComment.html">FishSoundComment</a>* fish_sound_comment_next </td>
 
316
          <td class="md" valign="top">(&nbsp;</td>
 
317
          <td class="md" nowrap valign="top"><a class="el" href="fishsound_8h.html#a0">FishSound</a> *&nbsp;</td>
 
318
          <td class="mdname" nowrap> <em>fsound</em>, </td>
 
319
        </tr>
 
320
        <tr>
 
321
          <td></td>
 
322
          <td></td>
 
323
          <td class="md" nowrap>const <a class="el" href="structFishSoundComment.html">FishSoundComment</a> *&nbsp;</td>
 
324
          <td class="mdname" nowrap> <em>comment</em></td>
 
325
        </tr>
 
326
        <tr>
 
327
          <td></td>
 
328
          <td class="md">)&nbsp;</td>
 
329
          <td class="md" colspan="2"></td>
 
330
        </tr>
 
331
 
 
332
      </table>
 
333
    </td>
 
334
  </tr>
 
335
</table>
 
336
<table cellspacing=5 cellpadding=0 border=0>
 
337
  <tr>
 
338
    <td>
 
339
      &nbsp;
 
340
    </td>
 
341
    <td>
 
342
 
 
343
<p>
 
344
Retrieve the next comment. 
 
345
<p>
 
346
<dl compact><dt><b>Parameters:</b></dt><dd>
 
347
  <table border="0" cellspacing="2" cellpadding="0">
 
348
    <tr><td valign=top><em>fsound</em>&nbsp;</td><td>A FishSound* handle </td></tr>
 
349
    <tr><td valign=top><em>comment</em>&nbsp;</td><td>The previous comment. </td></tr>
 
350
  </table>
 
351
</dl>
 
352
<dl compact><dt><b>Returns:</b></dt><dd>A read-only copy of the comment immediately following the given comment. </dd></dl>
 
353
    </td>
 
354
  </tr>
 
355
</table>
 
356
<a class="anchor" name="a4" doxytag="comments.h::fish_sound_comment_next_byname" ></a><p>
 
357
<table class="mdTable" width="100%" cellpadding="2" cellspacing="0">
 
358
  <tr>
 
359
    <td class="mdRow">
 
360
      <table cellpadding="0" cellspacing="0" border="0">
 
361
        <tr>
 
362
          <td class="md" nowrap valign="top"> const <a class="el" href="structFishSoundComment.html">FishSoundComment</a>* fish_sound_comment_next_byname </td>
 
363
          <td class="md" valign="top">(&nbsp;</td>
 
364
          <td class="md" nowrap valign="top"><a class="el" href="fishsound_8h.html#a0">FishSound</a> *&nbsp;</td>
 
365
          <td class="mdname" nowrap> <em>fsound</em>, </td>
 
366
        </tr>
 
367
        <tr>
 
368
          <td></td>
 
369
          <td></td>
 
370
          <td class="md" nowrap>const <a class="el" href="structFishSoundComment.html">FishSoundComment</a> *&nbsp;</td>
 
371
          <td class="mdname" nowrap> <em>comment</em></td>
 
372
        </tr>
 
373
        <tr>
 
374
          <td></td>
 
375
          <td class="md">)&nbsp;</td>
 
376
          <td class="md" colspan="2"></td>
 
377
        </tr>
 
378
 
 
379
      </table>
 
380
    </td>
 
381
  </tr>
 
382
</table>
 
383
<table cellspacing=5 cellpadding=0 border=0>
 
384
  <tr>
 
385
    <td>
 
386
      &nbsp;
 
387
    </td>
 
388
    <td>
 
389
 
 
390
<p>
 
391
Retrieve the next comment following and with the same name as a given comment. 
 
392
<p>
 
393
<dl compact><dt><b>Parameters:</b></dt><dd>
 
394
  <table border="0" cellspacing="2" cellpadding="0">
 
395
    <tr><td valign=top><em>fsound</em>&nbsp;</td><td>A FishSound* handle </td></tr>
 
396
    <tr><td valign=top><em>comment</em>&nbsp;</td><td>A comment </td></tr>
 
397
  </table>
 
398
</dl>
 
399
<dl compact><dt><b>Returns:</b></dt><dd>A read-only copy of the next comment with the same name as <em>comment</em>. </dd></dl>
 
400
<dl compact><dt><b>Return values:</b></dt><dd>
 
401
  <table border="0" cellspacing="2" cellpadding="0">
 
402
    <tr><td valign=top><em>NULL</em>&nbsp;</td><td>no further comments with the same name exist for this FishSound* object. </td></tr>
 
403
  </table>
 
404
</dl>
 
405
    </td>
 
406
  </tr>
 
407
</table>
 
408
<a class="anchor" name="a7" doxytag="comments.h::fish_sound_comment_remove" ></a><p>
 
409
<table class="mdTable" width="100%" cellpadding="2" cellspacing="0">
 
410
  <tr>
 
411
    <td class="mdRow">
 
412
      <table cellpadding="0" cellspacing="0" border="0">
 
413
        <tr>
 
414
          <td class="md" nowrap valign="top"> int fish_sound_comment_remove </td>
 
415
          <td class="md" valign="top">(&nbsp;</td>
 
416
          <td class="md" nowrap valign="top"><a class="el" href="fishsound_8h.html#a0">FishSound</a> *&nbsp;</td>
 
417
          <td class="mdname" nowrap> <em>fsound</em>, </td>
 
418
        </tr>
 
419
        <tr>
 
420
          <td></td>
 
421
          <td></td>
 
422
          <td class="md" nowrap><a class="el" href="structFishSoundComment.html">FishSoundComment</a> *&nbsp;</td>
 
423
          <td class="mdname" nowrap> <em>comment</em></td>
 
424
        </tr>
 
425
        <tr>
 
426
          <td></td>
 
427
          <td class="md">)&nbsp;</td>
 
428
          <td class="md" colspan="2"></td>
 
429
        </tr>
 
430
 
 
431
      </table>
 
432
    </td>
 
433
  </tr>
 
434
</table>
 
435
<table cellspacing=5 cellpadding=0 border=0>
 
436
  <tr>
 
437
    <td>
 
438
      &nbsp;
 
439
    </td>
 
440
    <td>
 
441
 
 
442
<p>
 
443
Remove a comment. 
 
444
<p>
 
445
<dl compact><dt><b>Parameters:</b></dt><dd>
 
446
  <table border="0" cellspacing="2" cellpadding="0">
 
447
    <tr><td valign=top><em>fsound</em>&nbsp;</td><td>A FishSound* handle (created with FISH_SOUND_ENCODE) </td></tr>
 
448
    <tr><td valign=top><em>comment</em>&nbsp;</td><td>The comment to remove. </td></tr>
 
449
  </table>
 
450
</dl>
 
451
<dl compact><dt><b>Return values:</b></dt><dd>
 
452
  <table border="0" cellspacing="2" cellpadding="0">
 
453
    <tr><td valign=top><em>1</em>&nbsp;</td><td>Success: comment removed </td></tr>
 
454
    <tr><td valign=top><em>0</em>&nbsp;</td><td>No-op: comment not found, nothing to remove </td></tr>
 
455
    <tr><td valign=top><em>FISH_SOUND_ERR_BAD</em>&nbsp;</td><td><em>fsound</em> is not a valid FishSound* handle </td></tr>
 
456
    <tr><td valign=top><em>FISH_SOUND_ERR_INVALID</em>&nbsp;</td><td>Operation not suitable for this FishSound </td></tr>
 
457
  </table>
 
458
</dl>
 
459
    </td>
 
460
  </tr>
 
461
</table>
 
462
<a class="anchor" name="a8" doxytag="comments.h::fish_sound_comment_remove_byname" ></a><p>
 
463
<table class="mdTable" width="100%" cellpadding="2" cellspacing="0">
 
464
  <tr>
 
465
    <td class="mdRow">
 
466
      <table cellpadding="0" cellspacing="0" border="0">
 
467
        <tr>
 
468
          <td class="md" nowrap valign="top"> int fish_sound_comment_remove_byname </td>
 
469
          <td class="md" valign="top">(&nbsp;</td>
 
470
          <td class="md" nowrap valign="top"><a class="el" href="fishsound_8h.html#a0">FishSound</a> *&nbsp;</td>
 
471
          <td class="mdname" nowrap> <em>fsound</em>, </td>
 
472
        </tr>
 
473
        <tr>
 
474
          <td></td>
 
475
          <td></td>
 
476
          <td class="md" nowrap>char *&nbsp;</td>
 
477
          <td class="mdname" nowrap> <em>name</em></td>
 
478
        </tr>
 
479
        <tr>
 
480
          <td></td>
 
481
          <td class="md">)&nbsp;</td>
 
482
          <td class="md" colspan="2"></td>
 
483
        </tr>
 
484
 
 
485
      </table>
 
486
    </td>
 
487
  </tr>
 
488
</table>
 
489
<table cellspacing=5 cellpadding=0 border=0>
 
490
  <tr>
 
491
    <td>
 
492
      &nbsp;
 
493
    </td>
 
494
    <td>
 
495
 
 
496
<p>
 
497
Remove all comments with a given name. 
 
498
<p>
 
499
<dl compact><dt><b>Parameters:</b></dt><dd>
 
500
  <table border="0" cellspacing="2" cellpadding="0">
 
501
    <tr><td valign=top><em>fsound</em>&nbsp;</td><td>A FishSound* handle (created with FISH_SOUND_ENCODE) </td></tr>
 
502
    <tr><td valign=top><em>name</em>&nbsp;</td><td>The name of the comments to remove </td></tr>
 
503
  </table>
 
504
</dl>
 
505
<dl compact><dt><b>Return values:</b></dt><dd>
 
506
  <table border="0" cellspacing="2" cellpadding="0">
 
507
    <tr><td valign=top><em>&gt;= 0</em>&nbsp;</td><td>The number of comments removed </td></tr>
 
508
    <tr><td valign=top><em>FISH_SOUND_ERR_BAD</em>&nbsp;</td><td><em>fsound</em> is not a valid FishSound* handle </td></tr>
 
509
    <tr><td valign=top><em>FISH_SOUND_ERR_INVALID</em>&nbsp;</td><td>Operation not suitable for this FishSound </td></tr>
 
510
  </table>
 
511
</dl>
 
512
    </td>
 
513
  </tr>
 
514
</table>
 
515
<hr size="1"><address style="align: right;"><small>Generated on Thu Jun 24 18:46:04 2004 for libfishsound by
 
516
<a href="http://www.doxygen.org/index.html">
 
517
<img src="doxygen.png" alt="doxygen" align="middle" border=0 > 
 
518
</a>1.3.5 </small></address>
 
519
</body>
 
520
</html>