\doxysection{Oggz Read API}
\label{group__read__api}\index{Oggz Read API@{Oggz Read API}}


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


\doxysubsubsection*{Typedefs}
\begin{DoxyCompactItemize}
\item 
typedef int($\ast$ \textbf{ Oggz\+Read\+Packet}) (\textbf{ OGGZ} $\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{ OGGZ} $\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}
\doxysubsubsection*{Functions}
\begin{DoxyCompactItemize}
\item 
int \textbf{ oggz\+\_\+set\+\_\+read\+\_\+callback} (\textbf{ OGGZ} $\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{ OGGZ} $\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{ OGGZ} $\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{ OGGZ} $\ast$oggz, unsigned char $\ast$buf, long n)
\begin{DoxyCompactList}\small\item\em Input data into {\itshape oggz}. \end{DoxyCompactList}\end{DoxyCompactItemize}


\doxysubsection{Detailed Description}
Oggz parses Ogg bitstreams, forming ogg\+\_\+packet structures, and calling your \doxyref{Oggz\+Read\+Packet}{p.}{group__read__api_ga81d64edc03ec1dac12dfbf3e1c0f97e9} 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 \doxyref{Oggz\+Read\+Packet}{p.}{group__read__api_ga81d64edc03ec1dac12dfbf3e1c0f97e9} 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 OGGZ$\ast$ opened with the OGGZ\+\_\+\+AUTO 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 \doxyref{Oggz\+Read\+Packet}{p.}{group__read__api_ga81d64edc03ec1dac12dfbf3e1c0f97e9} callback, calling \doxyref{oggz\+\_\+tell\+\_\+granulepos()}{p.}{group__seek__api_ga29181fb4e8f4e3629cb84810614acd30} will retrieve the calculated granulepos.

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

\doxysubsection{Typedef Documentation}
\index{Oggz Read API@{Oggz Read API}!OggzReadPacket@{OggzReadPacket}}
\index{OggzReadPacket@{OggzReadPacket}!Oggz Read API@{Oggz Read API}}
\doxysubsubsection{OggzReadPacket}
{\footnotesize\ttfamily \label{group__read__api_ga81d64edc03ec1dac12dfbf3e1c0f97e9} 
typedef int($\ast$ Oggz\+Read\+Packet) (\textbf{ OGGZ} $\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 \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} 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}
\index{Oggz Read API@{Oggz Read API}!OggzReadPage@{OggzReadPage}}
\index{OggzReadPage@{OggzReadPage}!Oggz Read API@{Oggz Read API}}
\doxysubsubsection{OggzReadPage}
{\footnotesize\ttfamily \label{group__read__api_ga33c666508e417bb8cc66895d49e97248} 
typedef int($\ast$ Oggz\+Read\+Page) (\textbf{ OGGZ} $\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 \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} 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}


\doxysubsection{Function Documentation}
\index{Oggz Read API@{Oggz Read API}!oggz\_read@{oggz\_read}}
\index{oggz\_read@{oggz\_read}!Oggz Read API@{Oggz Read API}}
\doxysubsubsection{oggz\_read()}
{\footnotesize\ttfamily \label{group__read__api_ga3ce7a31de5da56375057436c6b5108f2} 
long oggz\+\_\+read (\begin{DoxyParamCaption}\item[{\textbf{ OGGZ} $\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 \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} 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 OGGZ\+\_\+\+ERR\+\_\+\+BAD\+\_\+\+OGGZ} & {\itshape oggz} does not refer to an existing \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+INVALID} & Operation not suitable for this \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+SYSTEM} & System error; check errno for details \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+STOP\+\_\+\+OK} & Reading was stopped by a user callback returning OGGZ\+\_\+\+STOP\+\_\+\+OK \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+STOP\+\_\+\+ERR} & Reading was stopped by a user callback returning OGGZ\+\_\+\+STOP\+\_\+\+ERR \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+HOLE\+\_\+\+IN\+\_\+\+DATA} & Hole (sequence number gap) detected in input data \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+OUT\+\_\+\+OF\+\_\+\+MEMORY} & Out of memory \\
\hline
\end{DoxyRetVals}
\index{Oggz Read API@{Oggz Read API}!oggz\_read\_input@{oggz\_read\_input}}
\index{oggz\_read\_input@{oggz\_read\_input}!Oggz Read API@{Oggz Read API}}
\doxysubsubsection{oggz\_read\_input()}
{\footnotesize\ttfamily \label{group__read__api_ga77d4158dd119f496f73311ace7f630d6} 
long oggz\+\_\+read\+\_\+input (\begin{DoxyParamCaption}\item[{\textbf{ OGGZ} $\ast$}]{oggz}{, }\item[{unsigned char $\ast$}]{buf}{, }\item[{long}]{n}{}\end{DoxyParamCaption})}



Input data into {\itshape oggz}. 


\begin{DoxyParams}{Parameters}
{\em oggz} & An \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} 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 OGGZ\+\_\+\+ERR\+\_\+\+BAD\+\_\+\+OGGZ} & {\itshape oggz} does not refer to an existing \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+INVALID} & Operation not suitable for this \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+STOP\+\_\+\+OK} & Reading was stopped by a user callback returning OGGZ\+\_\+\+STOP\+\_\+\+OK \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+STOP\+\_\+\+ERR} & Reading was stopped by a user callback returning OGGZ\+\_\+\+STOP\+\_\+\+ERR \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+HOLE\+\_\+\+IN\+\_\+\+DATA} & Hole (sequence number gap) detected in input data \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+OUT\+\_\+\+OF\+\_\+\+MEMORY} & Out of memory \\
\hline
\end{DoxyRetVals}
\index{Oggz Read API@{Oggz Read API}!oggz\_set\_read\_callback@{oggz\_set\_read\_callback}}
\index{oggz\_set\_read\_callback@{oggz\_set\_read\_callback}!Oggz Read API@{Oggz Read API}}
\doxysubsubsection{oggz\_set\_read\_callback()}
{\footnotesize\ttfamily \label{group__read__api_ga6d5aae4f7f186fffe19d4fd3cd63148d} 
int oggz\+\_\+set\+\_\+read\+\_\+callback (\begin{DoxyParamCaption}\item[{\textbf{ OGGZ} $\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 \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} 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 OGGZ\+\_\+\+ERR\+\_\+\+BAD\+\_\+\+SERIALNO} & {\itshape serialno} does not identify an existing logical bitstream in {\itshape oggz}. \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+BAD\+\_\+\+OGGZ} & {\itshape oggz} does not refer to an existing \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+INVALID} & Operation not suitable for this \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+OUT\+\_\+\+OF\+\_\+\+MEMORY} & 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 \doxyref{Oggz\+Read\+Packet}{p.}{group__read__api_ga81d64edc03ec1dac12dfbf3e1c0f97e9} function, in order to specify that subsequent packets should be handled by a different \doxyref{Oggz\+Read\+Packet}{p.}{group__read__api_ga81d64edc03ec1dac12dfbf3e1c0f97e9} function. 
\end{DoxyNote}
\index{Oggz Read API@{Oggz Read API}!oggz\_set\_read\_page@{oggz\_set\_read\_page}}
\index{oggz\_set\_read\_page@{oggz\_set\_read\_page}!Oggz Read API@{Oggz Read API}}
\doxysubsubsection{oggz\_set\_read\_page()}
{\footnotesize\ttfamily \label{group__read__api_gafe738d4fdd4b00b1280f5978be19b2d5} 
int oggz\+\_\+set\+\_\+read\+\_\+page (\begin{DoxyParamCaption}\item[{\textbf{ OGGZ} $\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 \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} 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 \doxyref{Oggz\+Read\+Page}{p.}{group__read__api_ga33c666508e417bb8cc66895d49e97248} 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 OGGZ\+\_\+\+ERR\+\_\+\+BAD\+\_\+\+OGGZ} & {\itshape oggz} does not refer to an existing \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+INVALID} & Operation not suitable for this \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+OUT\+\_\+\+OF\+\_\+\+MEMORY} & 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 \doxyref{Oggz\+Read\+Page}{p.}{group__read__api_ga33c666508e417bb8cc66895d49e97248} function, in order to specify that subsequent pages should be handled by a different \doxyref{Oggz\+Read\+Page}{p.}{group__read__api_ga33c666508e417bb8cc66895d49e97248} function. 
\end{DoxyNote}
