\section{comments.h File Reference}
\label{comments_8h}\index{comments.h@{comments.h}}
Encoding and decoding of comments.
{\tt \#include $<$fishsound/fishsound.h$>$}\par
\subsection*{Data Structures}
\begin{CompactItemize}
\item
struct {\bf FishSoundComment}
\begin{CompactList}\small\item\em A comment. \item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item
const char $\ast$ {\bf fish\_\-sound\_\-comment\_\-get\_\-vendor} ({\bf FishSound} $\ast$fsound)
\begin{CompactList}\small\item\em Retrieve the vendor string. \item\end{CompactList}\item
const {\bf FishSoundComment} $\ast$ {\bf fish\_\-sound\_\-comment\_\-first} ({\bf FishSound} $\ast$fsound)
\begin{CompactList}\small\item\em Retrieve the first comment. \item\end{CompactList}\item
const {\bf FishSoundComment} $\ast$ {\bf fish\_\-sound\_\-comment\_\-next} ({\bf FishSound} $\ast$fsound, const {\bf FishSoundComment} $\ast$comment)
\begin{CompactList}\small\item\em Retrieve the next comment. \item\end{CompactList}\item
const {\bf FishSoundComment} $\ast$ {\bf fish\_\-sound\_\-comment\_\-first\_\-byname} ({\bf FishSound} $\ast$fsound, char $\ast$name)
\begin{CompactList}\small\item\em Retrieve the first comment with a given name. \item\end{CompactList}\item
const {\bf FishSoundComment} $\ast$ {\bf fish\_\-sound\_\-comment\_\-next\_\-byname} ({\bf FishSound} $\ast$fsound, const {\bf FishSoundComment} $\ast$comment)
\begin{CompactList}\small\item\em Retrieve the next comment following and with the same name as a given comment. \item\end{CompactList}\item
int {\bf fish\_\-sound\_\-comment\_\-add} ({\bf FishSound} $\ast$fsound, {\bf FishSoundComment} $\ast$comment)
\begin{CompactList}\small\item\em Add a comment. \item\end{CompactList}\item
int {\bf fish\_\-sound\_\-comment\_\-add\_\-byname} ({\bf FishSound} $\ast$fsound, const char $\ast$name, const char $\ast$value)
\begin{CompactList}\small\item\em Add a comment by name and value. \item\end{CompactList}\item
int {\bf fish\_\-sound\_\-comment\_\-remove} ({\bf FishSound} $\ast$fsound, {\bf FishSoundComment} $\ast$comment)
\begin{CompactList}\small\item\em Remove a comment. \item\end{CompactList}\item
int {\bf fish\_\-sound\_\-comment\_\-remove\_\-byname} ({\bf FishSound} $\ast$fsound, char $\ast$name)
\begin{CompactList}\small\item\em Remove all comments with a given name. \item\end{CompactList}\end{CompactItemize}
\subsection{Detailed Description}
Encoding and decoding of comments.
Vorbis 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.
The following general features of Vorbiscomment are relevant to this API:\begin{itemize}
\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}
Each 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.
The rest of a comment block consists of {\em name\/} = {\em value\/} pairs, with the following restrictions:\begin{itemize}
\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}
\subsection{Retrieving comments}\label{comments_8h_comments_get}
FishSound 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}
For 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}).
\subsection{Function Documentation}
\index{comments.h@{comments.h}!fish\_\-sound\_\-comment\_\-add@{fish\_\-sound\_\-comment\_\-add}}
\index{fish\_\-sound\_\-comment\_\-add@{fish\_\-sound\_\-comment\_\-add}!comments.h@{comments.h}}
\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}
Add a comment.
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em fsound}]A FishSound$\ast$ handle (created with mode FISH\_\-SOUND\_\-ENCODE) \item[{\em comment}]The comment to add \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\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}
\end{Desc}
\index{comments.h@{comments.h}!fish\_\-sound\_\-comment\_\-add\_\-byname@{fish\_\-sound\_\-comment\_\-add\_\-byname}}
\index{fish\_\-sound\_\-comment\_\-add\_\-byname@{fish\_\-sound\_\-comment\_\-add\_\-byname}!comments.h@{comments.h}}
\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}
Add a comment by name and value.
\begin{Desc}
\item[Parameters:]
\begin{description}
\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}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\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}
\end{Desc}
\index{comments.h@{comments.h}!fish\_\-sound\_\-comment\_\-first@{fish\_\-sound\_\-comment\_\-first}}
\index{fish\_\-sound\_\-comment\_\-first@{fish\_\-sound\_\-comment\_\-first}!comments.h@{comments.h}}
\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}
Retrieve the first comment.
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em fsound}]A FishSound$\ast$ handle \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A read-only copy of the first comment, or NULL if no comments exist for this FishSound$\ast$ object. \end{Desc}
\index{comments.h@{comments.h}!fish\_\-sound\_\-comment\_\-first\_\-byname@{fish\_\-sound\_\-comment\_\-first\_\-byname}}
\index{fish\_\-sound\_\-comment\_\-first\_\-byname@{fish\_\-sound\_\-comment\_\-first\_\-byname}!comments.h@{comments.h}}
\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}
Retrieve the first comment with a given name.
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em fsound}]A FishSound$\ast$ handle \item[{\em name}]the name of the comment to retrieve. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A read-only copy of the first comment matching the given {\em name\/}. \end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em NULL}]no match was found. \end{description}
\end{Desc}
\begin{Desc}
\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}
\index{comments.h@{comments.h}!fish\_\-sound\_\-comment\_\-get\_\-vendor@{fish\_\-sound\_\-comment\_\-get\_\-vendor}}
\index{fish\_\-sound\_\-comment\_\-get\_\-vendor@{fish\_\-sound\_\-comment\_\-get\_\-vendor}!comments.h@{comments.h}}
\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}
Retrieve the vendor string.
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em fsound}]A FishSound$\ast$ handle \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A read-only copy of the vendor string \end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em NULL}]No vendor string is associated with {\em fsound\/}, or {\em fsound\/} is NULL. \end{description}
\end{Desc}
\index{comments.h@{comments.h}!fish\_\-sound\_\-comment\_\-next@{fish\_\-sound\_\-comment\_\-next}}
\index{fish\_\-sound\_\-comment\_\-next@{fish\_\-sound\_\-comment\_\-next}!comments.h@{comments.h}}
\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}
Retrieve the next comment.
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em fsound}]A FishSound$\ast$ handle \item[{\em comment}]The previous comment. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A read-only copy of the comment immediately following the given comment. \end{Desc}
\index{comments.h@{comments.h}!fish\_\-sound\_\-comment\_\-next\_\-byname@{fish\_\-sound\_\-comment\_\-next\_\-byname}}
\index{fish\_\-sound\_\-comment\_\-next\_\-byname@{fish\_\-sound\_\-comment\_\-next\_\-byname}!comments.h@{comments.h}}
\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}
Retrieve the next comment following and with the same name as a given comment.
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em fsound}]A FishSound$\ast$ handle \item[{\em comment}]A comment \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A read-only copy of the next comment with the same name as {\em comment\/}. \end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em NULL}]no further comments with the same name exist for this FishSound$\ast$ object. \end{description}
\end{Desc}
\index{comments.h@{comments.h}!fish\_\-sound\_\-comment\_\-remove@{fish\_\-sound\_\-comment\_\-remove}}
\index{fish\_\-sound\_\-comment\_\-remove@{fish\_\-sound\_\-comment\_\-remove}!comments.h@{comments.h}}
\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}
Remove a comment.
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em fsound}]A FishSound$\ast$ handle (created with FISH\_\-SOUND\_\-ENCODE) \item[{\em comment}]The comment to remove. \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\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}
\end{Desc}
\index{comments.h@{comments.h}!fish\_\-sound\_\-comment\_\-remove\_\-byname@{fish\_\-sound\_\-comment\_\-remove\_\-byname}}
\index{fish\_\-sound\_\-comment\_\-remove\_\-byname@{fish\_\-sound\_\-comment\_\-remove\_\-byname}!comments.h@{comments.h}}
\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}
Remove all comments with a given name.
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em fsound}]A FishSound$\ast$ handle (created with FISH\_\-SOUND\_\-ENCODE) \item[{\em name}]The name of the comments to remove \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\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}
\end{Desc}
