\section{Oggz Read A\+PI}
\label{group__read__api}\index{Oggz Read A\+PI@{Oggz Read A\+PI}}


Oggz parses Ogg bitstreams, forming ogg\+\_\+packet structures, and calling your Oggz\+Read\+Packet callback(s).  


\subsection*{Typedefs}
\begin{DoxyCompactItemize}
\item 
typedef int($\ast$ \textbf{ Oggz\+Read\+Packet}) (\textbf{ O\+G\+GZ} $\ast$oggz, \textbf{ oggz\+\_\+packet} $\ast$packet, long serialno, void $\ast$user\+\_\+data)
\begin{DoxyCompactList}\small\item\em This is the signature of a callback which you must provide for Oggz to call whenever it finds a new packet in the Ogg stream associated with {\itshape oggz}. \end{DoxyCompactList}\item 
typedef int($\ast$ \textbf{ Oggz\+Read\+Page}) (\textbf{ O\+G\+GZ} $\ast$oggz, const ogg\+\_\+page $\ast$og, long serialno, void $\ast$user\+\_\+data)
\begin{DoxyCompactList}\small\item\em This is the signature of a callback which you must provide for Oggz to call whenever it finds a new page in the Ogg stream associated with {\itshape oggz}. \end{DoxyCompactList}\end{DoxyCompactItemize}
\subsection*{Functions}
\begin{DoxyCompactItemize}
\item 
int \textbf{ oggz\+\_\+set\+\_\+read\+\_\+callback} (\textbf{ O\+G\+GZ} $\ast$oggz, long serialno, \textbf{ Oggz\+Read\+Packet} read\+\_\+packet, void $\ast$user\+\_\+data)
\begin{DoxyCompactList}\small\item\em Set a callback for Oggz to call when a new Ogg packet is found in the stream. \end{DoxyCompactList}\item 
int \textbf{ oggz\+\_\+set\+\_\+read\+\_\+page} (\textbf{ O\+G\+GZ} $\ast$oggz, long serialno, \textbf{ Oggz\+Read\+Page} read\+\_\+page, void $\ast$user\+\_\+data)
\begin{DoxyCompactList}\small\item\em Set a callback for Oggz to call when a new Ogg page is found in the stream. \end{DoxyCompactList}\item 
long \textbf{ oggz\+\_\+read} (\textbf{ O\+G\+GZ} $\ast$oggz, long n)
\begin{DoxyCompactList}\small\item\em Read n bytes into {\itshape oggz}, calling any read callbacks on the fly. \end{DoxyCompactList}\item 
long \textbf{ oggz\+\_\+read\+\_\+input} (\textbf{ O\+G\+GZ} $\ast$oggz, unsigned char $\ast$buf, long n)
\begin{DoxyCompactList}\small\item\em Input data into {\itshape oggz}. \end{DoxyCompactList}\end{DoxyCompactItemize}


\subsection{Detailed Description}
Oggz parses Ogg bitstreams, forming ogg\+\_\+packet structures, and calling your Oggz\+Read\+Packet callback(s). 

You provide Ogg data to Oggz with \doxyref{oggz\+\_\+read()}{p.}{group__read__api_ga3ce7a31de5da56375057436c6b5108f2} or \doxyref{oggz\+\_\+read\+\_\+input()}{p.}{group__read__api_ga77d4158dd119f496f73311ace7f630d6}, and independently process it in Oggz\+Read\+Packet callbacks. It is possible to set a different callback per {\itshape serialno} (ie. for each logical bitstream in the Ogg bitstream -\/ see the \doxyref{Ogg basics}{p.}{group__basics} section for more detail).

When using an O\+G\+G\+Z$\ast$ opened with the O\+G\+G\+Z\+\_\+\+A\+U\+TO flag set, Oggz will internally calculate the granulepos for each packet, even though these are not all recorded in the file\+: only the last packet ending on a page will have its granulepos recorded in the page header. Within a Oggz\+Read\+Packet callback, calling \doxyref{oggz\+\_\+tell\+\_\+granulepos()}{p.}{group__seek__api_ga29181fb4e8f4e3629cb84810614acd30} will retrieve the calculated granulepos.

See \doxyref{Oggz Seek A\+PI}{p.}{group__seek__api} for information on seeking on interleaved Ogg data, and for working with calculated granulepos values. 

\subsection{Typedef Documentation}
\mbox{\label{group__read__api_ga81d64edc03ec1dac12dfbf3e1c0f97e9}} 
\index{Oggz Read A\+PI@{Oggz Read A\+PI}!Oggz\+Read\+Packet@{Oggz\+Read\+Packet}}
\index{Oggz\+Read\+Packet@{Oggz\+Read\+Packet}!Oggz Read A\+PI@{Oggz Read A\+PI}}
\subsubsection{Oggz\+Read\+Packet}
{\footnotesize\ttfamily typedef int($\ast$ Oggz\+Read\+Packet) (\textbf{ O\+G\+GZ} $\ast$oggz, \textbf{ oggz\+\_\+packet} $\ast$packet, long serialno, void $\ast$user\+\_\+data)}



This is the signature of a callback which you must provide for Oggz to call whenever it finds a new packet in the Ogg stream associated with {\itshape oggz}. 


\begin{DoxyParams}{Parameters}
{\em oggz} & The O\+G\+GZ handle \\
\hline
{\em packet} & The packet, including its position in the stream. \\
\hline
{\em serialno} & Identify the logical bistream in {\itshape oggz} that contains {\itshape packet} \\
\hline
{\em user\+\_\+data} & A generic pointer you have provided earlier \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
0 to continue, non-\/zero to instruct Oggz to stop.
\end{DoxyReturn}
\begin{DoxyNote}{Note}
It is possible to provide different callbacks per logical bitstream -- see \doxyref{oggz\+\_\+set\+\_\+read\+\_\+callback()}{p.}{group__read__api_ga6d5aae4f7f186fffe19d4fd3cd63148d} for more information. 
\end{DoxyNote}
\mbox{\label{group__read__api_ga33c666508e417bb8cc66895d49e97248}} 
\index{Oggz Read A\+PI@{Oggz Read A\+PI}!Oggz\+Read\+Page@{Oggz\+Read\+Page}}
\index{Oggz\+Read\+Page@{Oggz\+Read\+Page}!Oggz Read A\+PI@{Oggz Read A\+PI}}
\subsubsection{Oggz\+Read\+Page}
{\footnotesize\ttfamily typedef int($\ast$ Oggz\+Read\+Page) (\textbf{ O\+G\+GZ} $\ast$oggz, const ogg\+\_\+page $\ast$og, long serialno, void $\ast$user\+\_\+data)}



This is the signature of a callback which you must provide for Oggz to call whenever it finds a new page in the Ogg stream associated with {\itshape oggz}. 


\begin{DoxyParams}{Parameters}
{\em oggz} & The O\+G\+GZ handle \\
\hline
{\em op} & The full ogg\+\_\+page (see $<$ogg/ogg.\+h$>$) \\
\hline
{\em user\+\_\+data} & A generic pointer you have provided earlier \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
0 to continue, non-\/zero to instruct Oggz to stop. 
\end{DoxyReturn}


\subsection{Function Documentation}
\mbox{\label{group__read__api_ga3ce7a31de5da56375057436c6b5108f2}} 
\index{Oggz Read A\+PI@{Oggz Read A\+PI}!oggz\+\_\+read@{oggz\+\_\+read}}
\index{oggz\+\_\+read@{oggz\+\_\+read}!Oggz Read A\+PI@{Oggz Read A\+PI}}
\subsubsection{oggz\+\_\+read()}
{\footnotesize\ttfamily long oggz\+\_\+read (\begin{DoxyParamCaption}\item[{\textbf{ O\+G\+GZ} $\ast$}]{oggz,  }\item[{long}]{n }\end{DoxyParamCaption})}



Read n bytes into {\itshape oggz}, calling any read callbacks on the fly. 


\begin{DoxyParams}{Parameters}
{\em oggz} & An O\+G\+GZ handle previously opened for reading \\
\hline
{\em n} & A count of bytes to ingest \\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em $>$  0} & The number of bytes successfully ingested. \\
\hline
{\em 0} & End of file \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+B\+A\+D\+\_\+\+O\+G\+GZ} & {\itshape oggz} does not refer to an existing O\+G\+GZ \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+I\+N\+V\+A\+L\+ID} & Operation not suitable for this O\+G\+GZ \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+S\+Y\+S\+T\+EM} & System error; check errno for details \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+S\+T\+O\+P\+\_\+\+OK} & Reading was stopped by a user callback returning O\+G\+G\+Z\+\_\+\+S\+T\+O\+P\+\_\+\+OK \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+S\+T\+O\+P\+\_\+\+E\+RR} & Reading was stopped by a user callback returning O\+G\+G\+Z\+\_\+\+S\+T\+O\+P\+\_\+\+E\+RR \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+H\+O\+L\+E\+\_\+\+I\+N\+\_\+\+D\+A\+TA} & Hole (sequence number gap) detected in input data \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+O\+U\+T\+\_\+\+O\+F\+\_\+\+M\+E\+M\+O\+RY} & Out of memory \\
\hline
\end{DoxyRetVals}
\mbox{\label{group__read__api_ga77d4158dd119f496f73311ace7f630d6}} 
\index{Oggz Read A\+PI@{Oggz Read A\+PI}!oggz\+\_\+read\+\_\+input@{oggz\+\_\+read\+\_\+input}}
\index{oggz\+\_\+read\+\_\+input@{oggz\+\_\+read\+\_\+input}!Oggz Read A\+PI@{Oggz Read A\+PI}}
\subsubsection{oggz\+\_\+read\+\_\+input()}
{\footnotesize\ttfamily long oggz\+\_\+read\+\_\+input (\begin{DoxyParamCaption}\item[{\textbf{ O\+G\+GZ} $\ast$}]{oggz,  }\item[{unsigned char $\ast$}]{buf,  }\item[{long}]{n }\end{DoxyParamCaption})}



Input data into {\itshape oggz}. 


\begin{DoxyParams}{Parameters}
{\em oggz} & An O\+G\+GZ handle previously opened for reading \\
\hline
{\em buf} & A memory buffer \\
\hline
{\em n} & A count of bytes to input \\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em $>$  0} & The number of bytes successfully ingested. \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+B\+A\+D\+\_\+\+O\+G\+GZ} & {\itshape oggz} does not refer to an existing O\+G\+GZ \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+I\+N\+V\+A\+L\+ID} & Operation not suitable for this O\+G\+GZ \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+S\+T\+O\+P\+\_\+\+OK} & Reading was stopped by a user callback returning O\+G\+G\+Z\+\_\+\+S\+T\+O\+P\+\_\+\+OK \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+S\+T\+O\+P\+\_\+\+E\+RR} & Reading was stopped by a user callback returning O\+G\+G\+Z\+\_\+\+S\+T\+O\+P\+\_\+\+E\+RR \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+H\+O\+L\+E\+\_\+\+I\+N\+\_\+\+D\+A\+TA} & Hole (sequence number gap) detected in input data \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+O\+U\+T\+\_\+\+O\+F\+\_\+\+M\+E\+M\+O\+RY} & Out of memory \\
\hline
\end{DoxyRetVals}
\mbox{\label{group__read__api_ga6d5aae4f7f186fffe19d4fd3cd63148d}} 
\index{Oggz Read A\+PI@{Oggz Read A\+PI}!oggz\+\_\+set\+\_\+read\+\_\+callback@{oggz\+\_\+set\+\_\+read\+\_\+callback}}
\index{oggz\+\_\+set\+\_\+read\+\_\+callback@{oggz\+\_\+set\+\_\+read\+\_\+callback}!Oggz Read A\+PI@{Oggz Read A\+PI}}
\subsubsection{oggz\+\_\+set\+\_\+read\+\_\+callback()}
{\footnotesize\ttfamily int oggz\+\_\+set\+\_\+read\+\_\+callback (\begin{DoxyParamCaption}\item[{\textbf{ O\+G\+GZ} $\ast$}]{oggz,  }\item[{long}]{serialno,  }\item[{\textbf{ Oggz\+Read\+Packet}}]{read\+\_\+packet,  }\item[{void $\ast$}]{user\+\_\+data }\end{DoxyParamCaption})}



Set a callback for Oggz to call when a new Ogg packet is found in the stream. 


\begin{DoxyParams}{Parameters}
{\em oggz} & An O\+G\+GZ handle previously opened for reading \\
\hline
{\em serialno} & Identify the logical bitstream in {\itshape oggz} to attach this callback to, or -\/1 to attach this callback to all unattached logical bitstreams in {\itshape oggz}. \\
\hline
{\em read\+\_\+packet} & Your callback function \\
\hline
{\em user\+\_\+data} & Arbitrary data you wish to pass to your callback \\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 0} & Success \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+B\+A\+D\+\_\+\+S\+E\+R\+I\+A\+L\+NO} & {\itshape serialno} does not identify an existing logical bitstream in {\itshape oggz}. \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+B\+A\+D\+\_\+\+O\+G\+GZ} & {\itshape oggz} does not refer to an existing O\+G\+GZ \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+I\+N\+V\+A\+L\+ID} & Operation not suitable for this O\+G\+GZ \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+O\+U\+T\+\_\+\+O\+F\+\_\+\+M\+E\+M\+O\+RY} & Out of memory\\
\hline
\end{DoxyRetVals}
\begin{DoxyNote}{Note}
Values of {\itshape serialno} other than -\/1 allows you to specify different callback functions for each logical bitstream.

It is safe to call this callback from within an Oggz\+Read\+Packet function, in order to specify that subsequent packets should be handled by a different Oggz\+Read\+Packet function. 
\end{DoxyNote}
\mbox{\label{group__read__api_gafe738d4fdd4b00b1280f5978be19b2d5}} 
\index{Oggz Read A\+PI@{Oggz Read A\+PI}!oggz\+\_\+set\+\_\+read\+\_\+page@{oggz\+\_\+set\+\_\+read\+\_\+page}}
\index{oggz\+\_\+set\+\_\+read\+\_\+page@{oggz\+\_\+set\+\_\+read\+\_\+page}!Oggz Read A\+PI@{Oggz Read A\+PI}}
\subsubsection{oggz\+\_\+set\+\_\+read\+\_\+page()}
{\footnotesize\ttfamily int oggz\+\_\+set\+\_\+read\+\_\+page (\begin{DoxyParamCaption}\item[{\textbf{ O\+G\+GZ} $\ast$}]{oggz,  }\item[{long}]{serialno,  }\item[{\textbf{ Oggz\+Read\+Page}}]{read\+\_\+page,  }\item[{void $\ast$}]{user\+\_\+data }\end{DoxyParamCaption})}



Set a callback for Oggz to call when a new Ogg page is found in the stream. 


\begin{DoxyParams}{Parameters}
{\em oggz} & An O\+G\+GZ handle previously opened for reading \\
\hline
{\em serialno} & Identify the logical bitstream in {\itshape oggz} to attach this callback to, or -\/1 to attach this callback to all unattached logical bitstreams in {\itshape oggz}. \\
\hline
{\em read\+\_\+page} & Your Oggz\+Read\+Page callback function \\
\hline
{\em user\+\_\+data} & Arbitrary data you wish to pass to your callback \\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 0} & Success \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+B\+A\+D\+\_\+\+O\+G\+GZ} & {\itshape oggz} does not refer to an existing O\+G\+GZ \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+I\+N\+V\+A\+L\+ID} & Operation not suitable for this O\+G\+GZ \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+O\+U\+T\+\_\+\+O\+F\+\_\+\+M\+E\+M\+O\+RY} & Out of memory\\
\hline
\end{DoxyRetVals}
\begin{DoxyNote}{Note}
Values of {\itshape serialno} other than -\/1 allows you to specify different callback functions for each logical bitstream.

It is safe to call this callback from within an Oggz\+Read\+Page function, in order to specify that subsequent pages should be handled by a different Oggz\+Read\+Page function. 
\end{DoxyNote}
