1\section{comments.h File Reference}
2\label{comments_8h}\index{comments.h@{comments.h}}
3Encoding and decoding of comments.
4
5
6{\tt \#include $<$fishsound/fishsound.h$>$}\par
7\subsection*{Data Structures}
8\begin{CompactItemize}
9\item
10struct {\bf FishSoundComment}
11\begin{CompactList}\small\item\em A comment. \item\end{CompactList}\end{CompactItemize}
12\subsection*{Functions}
13\begin{CompactItemize}
14\item
15const char $\ast$ {\bf fish\_\-sound\_\-comment\_\-get\_\-vendor} ({\bf FishSound} $\ast$fsound)
16\begin{CompactList}\small\item\em Retrieve the vendor string. \item\end{CompactList}\item
17const {\bf FishSoundComment} $\ast$ {\bf fish\_\-sound\_\-comment\_\-first} ({\bf FishSound} $\ast$fsound)
18\begin{CompactList}\small\item\em Retrieve the first comment. \item\end{CompactList}\item
19const {\bf FishSoundComment} $\ast$ {\bf fish\_\-sound\_\-comment\_\-next} ({\bf FishSound} $\ast$fsound, const {\bf FishSoundComment} $\ast$comment)
20\begin{CompactList}\small\item\em Retrieve the next comment. \item\end{CompactList}\item
21const {\bf FishSoundComment} $\ast$ {\bf fish\_\-sound\_\-comment\_\-first\_\-byname} ({\bf FishSound} $\ast$fsound, char $\ast$name)
22\begin{CompactList}\small\item\em Retrieve the first comment with a given name. \item\end{CompactList}\item
23const {\bf FishSoundComment} $\ast$ {\bf fish\_\-sound\_\-comment\_\-next\_\-byname} ({\bf FishSound} $\ast$fsound, const {\bf FishSoundComment} $\ast$comment)
24\begin{CompactList}\small\item\em Retrieve the next comment following and with the same name as a given comment. \item\end{CompactList}\item
25int {\bf fish\_\-sound\_\-comment\_\-add} ({\bf FishSound} $\ast$fsound, {\bf FishSoundComment} $\ast$comment)
26\begin{CompactList}\small\item\em Add a comment. \item\end{CompactList}\item
27int {\bf fish\_\-sound\_\-comment\_\-add\_\-byname} ({\bf FishSound} $\ast$fsound, const char $\ast$name, const char $\ast$value)
28\begin{CompactList}\small\item\em Add a comment by name and value. \item\end{CompactList}\item
29int {\bf fish\_\-sound\_\-comment\_\-remove} ({\bf FishSound} $\ast$fsound, {\bf FishSoundComment} $\ast$comment)
30\begin{CompactList}\small\item\em Remove a comment. \item\end{CompactList}\item
31int {\bf fish\_\-sound\_\-comment\_\-remove\_\-byname} ({\bf FishSound} $\ast$fsound, char $\ast$name)
32\begin{CompactList}\small\item\em Remove all comments with a given name. \item\end{CompactList}\end{CompactItemize}
33
34
35\subsection{Detailed Description}
36Encoding and decoding of comments.
37
38Vorbis and Speex bitstreams use a comment format called \char`\"{}Vorbiscomment\char`\"{}, defined {\tt here}. Many standard comment names (such as TITLE, COPYRIGHT and GENRE) are defined in that document.
39
40The following general features of Vorbiscomment are relevant to this API:\begin{itemize}
41\item Each stream has one comment packet, which occurs before any encoded audio data in the stream.\item 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 fish\_\-sound\_\-encode\_\-$\ast$().\item 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.\end{itemize}
42
43
44Each comment block contains one Vendor string, which can be retrieved with \doxyref{fish\_\-sound\_\-comment\_\-get\_\-vendor()}{p.}{comments_8h_ecaa4422dade26c02553ba48697503ad}. When encoding, this string is effectively fixed by the codec libraries; it cannot be set by the application.
45
46The rest of a comment block consists of {\em name\/} = {\em value\/} pairs, with the following restrictions:\begin{itemize}
47\item Both the {\em name\/} and {\em value\/} must be non-empty\item The {\em name\/} is case-insensitive and must consist of ASCII within the range 0x20 to 0x7D inclusive, 0x3D ('=') excluded.\item The {\em name\/} is not unique; multiple entries may exist with equivalent {\em name\/} within a Vorbiscomment block.\item The {\em value\/} may be any UTF-8 string.\end{itemize}
48\subsection{Retrieving comments}\label{comments_8h_comments_get}
49FishSound contains API methods to iterate through all comments associated with a FishSound$\ast$ handle (\doxyref{fish\_\-sound\_\-comment\_\-first()}{p.}{comments_8h_1f0118f390450b28b19bd61ebb6cb7a3} and \doxyref{fish\_\-sound\_\-comment\_\-next()}{p.}{comments_8h_b68a529900d2546075193fa37cba76c8}, and to iterate through comments matching a particular name (\doxyref{fish\_\-sound\_\-comment\_\-first\_\-byname()}{p.}{comments_8h_8d4404ac25bc87a08bdd64cccb27f934} and \doxyref{fish\_\-sound\_\-comment\_\-next\_\-byname()}{p.}{comments_8h_7a57c6059a0c2c8b10cf655d78977940}). Given that multiple comments may exist with the same {\em name\/}, you should not use \doxyref{fish\_\-sound\_\-comment\_\-first\_\-byname()}{p.}{comments_8h_8d4404ac25bc87a08bdd64cccb27f934} as a simple \char`\"{}get\char`\"{} function.\subsection{Encoding comments}\label{comments_8h_comments_set}
50For encoding, FishSound contains API methods for adding comments (\doxyref{fish\_\-sound\_\-comment\_\-add()}{p.}{comments_8h_77493e66f0e4ce8870f6f5413b90317e} and \doxyref{fish\_\-sound\_\-comment\_\-add\_\-byname()}{p.}{comments_8h_ef6ec7d8894aac5da78cb0f5711e7d67} and for removing comments (\doxyref{fish\_\-sound\_\-comment\_\-remove()}{p.}{comments_8h_d6c456b3c1f943966d1bac04452b2e84} and \doxyref{fish\_\-sound\_\-comment\_\-remove\_\-byname()}{p.}{comments_8h_5a84f90f4f3d61acd7682675b874a359}).
51
52\subsection{Function Documentation}
53\index{comments.h@{comments.h}!fish\_\-sound\_\-comment\_\-add@{fish\_\-sound\_\-comment\_\-add}}
54\index{fish\_\-sound\_\-comment\_\-add@{fish\_\-sound\_\-comment\_\-add}!comments.h@{comments.h}}
55\subsubsection[{fish\_\-sound\_\-comment\_\-add}]{\setlength{\rightskip}{0pt plus 5cm}int fish\_\-sound\_\-comment\_\-add ({\bf FishSound} $\ast$ {\em fsound}, \/  {\bf FishSoundComment} $\ast$ {\em comment})}\label{comments_8h_77493e66f0e4ce8870f6f5413b90317e}
56
57
58Add a comment.
59
60\begin{Desc}
61\item[Parameters:]
62\begin{description}
63\item[{\em fsound}]A FishSound$\ast$ handle (created with mode FISH\_\-SOUND\_\-ENCODE) \item[{\em comment}]The comment to add \end{description}
64\end{Desc}
65\begin{Desc}
66\item[Return values:]
67\begin{description}
68\item[{\em 0}]Success \item[{\em FISH\_\-SOUND\_\-ERR\_\-BAD}]{\em fsound\/} is not a valid FishSound$\ast$ handle \item[{\em FISH\_\-SOUND\_\-ERR\_\-INVALID}]Operation not suitable for this FishSound \end{description}
69\end{Desc}
70\index{comments.h@{comments.h}!fish\_\-sound\_\-comment\_\-add\_\-byname@{fish\_\-sound\_\-comment\_\-add\_\-byname}}
71\index{fish\_\-sound\_\-comment\_\-add\_\-byname@{fish\_\-sound\_\-comment\_\-add\_\-byname}!comments.h@{comments.h}}
72\subsubsection[{fish\_\-sound\_\-comment\_\-add\_\-byname}]{\setlength{\rightskip}{0pt plus 5cm}int fish\_\-sound\_\-comment\_\-add\_\-byname ({\bf FishSound} $\ast$ {\em fsound}, \/  const char $\ast$ {\em name}, \/  const char $\ast$ {\em value})}\label{comments_8h_ef6ec7d8894aac5da78cb0f5711e7d67}
73
74
75Add a comment by name and value.
76
77\begin{Desc}
78\item[Parameters:]
79\begin{description}
80\item[{\em fsound}]A FishSound$\ast$ handle (created with mode FISH\_\-SOUND\_\-ENCODE) \item[{\em name}]The name of the comment to add \item[{\em value}]The contents of the comment to add \end{description}
81\end{Desc}
82\begin{Desc}
83\item[Return values:]
84\begin{description}
85\item[{\em 0}]Success \item[{\em FISH\_\-SOUND\_\-ERR\_\-BAD}]{\em fsound\/} is not a valid FishSound$\ast$ handle \item[{\em FISH\_\-SOUND\_\-ERR\_\-INVALID}]Operation not suitable for this FishSound \end{description}
86\end{Desc}
87\index{comments.h@{comments.h}!fish\_\-sound\_\-comment\_\-first@{fish\_\-sound\_\-comment\_\-first}}
88\index{fish\_\-sound\_\-comment\_\-first@{fish\_\-sound\_\-comment\_\-first}!comments.h@{comments.h}}
89\subsubsection[{fish\_\-sound\_\-comment\_\-first}]{\setlength{\rightskip}{0pt plus 5cm}const {\bf FishSoundComment}$\ast$ fish\_\-sound\_\-comment\_\-first ({\bf FishSound} $\ast$ {\em fsound})}\label{comments_8h_1f0118f390450b28b19bd61ebb6cb7a3}
90
91
92Retrieve the first comment.
93
94\begin{Desc}
95\item[Parameters:]
96\begin{description}
97\item[{\em fsound}]A FishSound$\ast$ handle \end{description}
98\end{Desc}
99\begin{Desc}
100\item[Returns:]A read-only copy of the first comment, or NULL if no comments exist for this FishSound$\ast$ object. \end{Desc}
101\index{comments.h@{comments.h}!fish\_\-sound\_\-comment\_\-first\_\-byname@{fish\_\-sound\_\-comment\_\-first\_\-byname}}
102\index{fish\_\-sound\_\-comment\_\-first\_\-byname@{fish\_\-sound\_\-comment\_\-first\_\-byname}!comments.h@{comments.h}}
103\subsubsection[{fish\_\-sound\_\-comment\_\-first\_\-byname}]{\setlength{\rightskip}{0pt plus 5cm}const {\bf FishSoundComment}$\ast$ fish\_\-sound\_\-comment\_\-first\_\-byname ({\bf FishSound} $\ast$ {\em fsound}, \/  char $\ast$ {\em name})}\label{comments_8h_8d4404ac25bc87a08bdd64cccb27f934}
104
105
106Retrieve the first comment with a given name.
107
108\begin{Desc}
109\item[Parameters:]
110\begin{description}
111\item[{\em fsound}]A FishSound$\ast$ handle \item[{\em name}]the name of the comment to retrieve. \end{description}
112\end{Desc}
113\begin{Desc}
114\item[Returns:]A read-only copy of the first comment matching the given {\em name\/}. \end{Desc}
115\begin{Desc}
116\item[Return values:]
117\begin{description}
118\item[{\em NULL}]no match was found. \end{description}
119\end{Desc}
120\begin{Desc}
121\item[Note:]If {\em name\/} is NULL, the behaviour is the same as for \doxyref{fish\_\-sound\_\-comment\_\-first()}{p.}{comments_8h_1f0118f390450b28b19bd61ebb6cb7a3} \end{Desc}
122\index{comments.h@{comments.h}!fish\_\-sound\_\-comment\_\-get\_\-vendor@{fish\_\-sound\_\-comment\_\-get\_\-vendor}}
123\index{fish\_\-sound\_\-comment\_\-get\_\-vendor@{fish\_\-sound\_\-comment\_\-get\_\-vendor}!comments.h@{comments.h}}
124\subsubsection[{fish\_\-sound\_\-comment\_\-get\_\-vendor}]{\setlength{\rightskip}{0pt plus 5cm}const char$\ast$ fish\_\-sound\_\-comment\_\-get\_\-vendor ({\bf FishSound} $\ast$ {\em fsound})}\label{comments_8h_ecaa4422dade26c02553ba48697503ad}
125
126
127Retrieve the vendor string.
128
129\begin{Desc}
130\item[Parameters:]
131\begin{description}
132\item[{\em fsound}]A FishSound$\ast$ handle \end{description}
133\end{Desc}
134\begin{Desc}
135\item[Returns:]A read-only copy of the vendor string \end{Desc}
136\begin{Desc}
137\item[Return values:]
138\begin{description}
139\item[{\em NULL}]No vendor string is associated with {\em fsound\/}, or {\em fsound\/} is NULL. \end{description}
140\end{Desc}
141\index{comments.h@{comments.h}!fish\_\-sound\_\-comment\_\-next@{fish\_\-sound\_\-comment\_\-next}}
142\index{fish\_\-sound\_\-comment\_\-next@{fish\_\-sound\_\-comment\_\-next}!comments.h@{comments.h}}
143\subsubsection[{fish\_\-sound\_\-comment\_\-next}]{\setlength{\rightskip}{0pt plus 5cm}const {\bf FishSoundComment}$\ast$ fish\_\-sound\_\-comment\_\-next ({\bf FishSound} $\ast$ {\em fsound}, \/  const {\bf FishSoundComment} $\ast$ {\em comment})}\label{comments_8h_b68a529900d2546075193fa37cba76c8}
144
145
146Retrieve the next comment.
147
148\begin{Desc}
149\item[Parameters:]
150\begin{description}
151\item[{\em fsound}]A FishSound$\ast$ handle \item[{\em comment}]The previous comment. \end{description}
152\end{Desc}
153\begin{Desc}
154\item[Returns:]A read-only copy of the comment immediately following the given comment. \end{Desc}
155\index{comments.h@{comments.h}!fish\_\-sound\_\-comment\_\-next\_\-byname@{fish\_\-sound\_\-comment\_\-next\_\-byname}}
156\index{fish\_\-sound\_\-comment\_\-next\_\-byname@{fish\_\-sound\_\-comment\_\-next\_\-byname}!comments.h@{comments.h}}
157\subsubsection[{fish\_\-sound\_\-comment\_\-next\_\-byname}]{\setlength{\rightskip}{0pt plus 5cm}const {\bf FishSoundComment}$\ast$ fish\_\-sound\_\-comment\_\-next\_\-byname ({\bf FishSound} $\ast$ {\em fsound}, \/  const {\bf FishSoundComment} $\ast$ {\em comment})}\label{comments_8h_7a57c6059a0c2c8b10cf655d78977940}
158
159
160Retrieve the next comment following and with the same name as a given comment.
161
162\begin{Desc}
163\item[Parameters:]
164\begin{description}
165\item[{\em fsound}]A FishSound$\ast$ handle \item[{\em comment}]A comment \end{description}
166\end{Desc}
167\begin{Desc}
168\item[Returns:]A read-only copy of the next comment with the same name as {\em comment\/}. \end{Desc}
169\begin{Desc}
170\item[Return values:]
171\begin{description}
172\item[{\em NULL}]no further comments with the same name exist for this FishSound$\ast$ object. \end{description}
173\end{Desc}
174\index{comments.h@{comments.h}!fish\_\-sound\_\-comment\_\-remove@{fish\_\-sound\_\-comment\_\-remove}}
175\index{fish\_\-sound\_\-comment\_\-remove@{fish\_\-sound\_\-comment\_\-remove}!comments.h@{comments.h}}
176\subsubsection[{fish\_\-sound\_\-comment\_\-remove}]{\setlength{\rightskip}{0pt plus 5cm}int fish\_\-sound\_\-comment\_\-remove ({\bf FishSound} $\ast$ {\em fsound}, \/  {\bf FishSoundComment} $\ast$ {\em comment})}\label{comments_8h_d6c456b3c1f943966d1bac04452b2e84}
177
178
179Remove a comment.
180
181\begin{Desc}
182\item[Parameters:]
183\begin{description}
184\item[{\em fsound}]A FishSound$\ast$ handle (created with FISH\_\-SOUND\_\-ENCODE) \item[{\em comment}]The comment to remove. \end{description}
185\end{Desc}
186\begin{Desc}
187\item[Return values:]
188\begin{description}
189\item[{\em 1}]Success: comment removed \item[{\em 0}]No-op: comment not found, nothing to remove \item[{\em FISH\_\-SOUND\_\-ERR\_\-BAD}]{\em fsound\/} is not a valid FishSound$\ast$ handle \item[{\em FISH\_\-SOUND\_\-ERR\_\-INVALID}]Operation not suitable for this FishSound \end{description}
190\end{Desc}
191\index{comments.h@{comments.h}!fish\_\-sound\_\-comment\_\-remove\_\-byname@{fish\_\-sound\_\-comment\_\-remove\_\-byname}}
192\index{fish\_\-sound\_\-comment\_\-remove\_\-byname@{fish\_\-sound\_\-comment\_\-remove\_\-byname}!comments.h@{comments.h}}
193\subsubsection[{fish\_\-sound\_\-comment\_\-remove\_\-byname}]{\setlength{\rightskip}{0pt plus 5cm}int fish\_\-sound\_\-comment\_\-remove\_\-byname ({\bf FishSound} $\ast$ {\em fsound}, \/  char $\ast$ {\em name})}\label{comments_8h_5a84f90f4f3d61acd7682675b874a359}
194
195
196Remove all comments with a given name.
197
198\begin{Desc}
199\item[Parameters:]
200\begin{description}
201\item[{\em fsound}]A FishSound$\ast$ handle (created with FISH\_\-SOUND\_\-ENCODE) \item[{\em name}]The name of the comments to remove \end{description}
202\end{Desc}
203\begin{Desc}
204\item[Return values:]
205\begin{description}
206\item[{\em $>$= 0}]The number of comments removed \item[{\em FISH\_\-SOUND\_\-ERR\_\-BAD}]{\em fsound\/} is not a valid FishSound$\ast$ handle \item[{\em FISH\_\-SOUND\_\-ERR\_\-INVALID}]Operation not suitable for this FishSound \end{description}
207\end{Desc}
208