\doxysection{Oggz Write API}
\label{group__write__api}\index{Oggz Write API@{Oggz Write API}}


Oggz maintains a packet queue, such that you can independently add packets to the queue and write an Ogg bitstream.  


\doxysubsubsection*{Typedefs}
\begin{DoxyCompactItemize}
\item 
typedef int($\ast$ \textbf{ Oggz\+Write\+Hungry}) (\textbf{ OGGZ} $\ast$oggz, int empty, void $\ast$user\+\_\+data)
\begin{DoxyCompactList}\small\item\em This is the signature of a callback which Oggz will call when {\itshape oggz} is \doxyref{hungry }{p.}{group__hungry}. \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsubsection*{Functions}
\begin{DoxyCompactItemize}
\item 
int \textbf{ oggz\+\_\+write\+\_\+set\+\_\+hungry\+\_\+callback} (\textbf{ OGGZ} $\ast$oggz, \textbf{ Oggz\+Write\+Hungry} hungry, int only\+\_\+when\+\_\+empty, void $\ast$user\+\_\+data)
\begin{DoxyCompactList}\small\item\em Set a callback for Oggz to call when {\itshape oggz} is \doxyref{hungry }{p.}{group__hungry}. \end{DoxyCompactList}\item 
int \textbf{ oggz\+\_\+write\+\_\+feed} (\textbf{ OGGZ} $\ast$oggz, ogg\+\_\+packet $\ast$op, long serialno, int flush, int $\ast$guard)
\begin{DoxyCompactList}\small\item\em Add a packet to {\itshape oggz\textquotesingle{}s} packet queue. \end{DoxyCompactList}\item 
long \textbf{ oggz\+\_\+write\+\_\+output} (\textbf{ OGGZ} $\ast$oggz, unsigned char $\ast$buf, long n)
\begin{DoxyCompactList}\small\item\em Output data from an \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} handle. \end{DoxyCompactList}\item 
long \textbf{ oggz\+\_\+write} (\textbf{ OGGZ} $\ast$oggz, long n)
\begin{DoxyCompactList}\small\item\em Write n bytes from an \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} handle. \end{DoxyCompactList}\item 
long \textbf{ oggz\+\_\+write\+\_\+get\+\_\+next\+\_\+page\+\_\+size} (\textbf{ OGGZ} $\ast$oggz)
\begin{DoxyCompactList}\small\item\em Query the number of bytes in the next page to be written. \end{DoxyCompactList}\end{DoxyCompactItemize}


\doxysubsection{Detailed Description}
Oggz maintains a packet queue, such that you can independently add packets to the queue and write an Ogg bitstream. 

There are two complementary methods for adding packets to the packet queue.


\begin{DoxyItemize}
\item by \doxyref{force feeding Oggz }{p.}{group__force__feed}
\item by using \doxyref{Oggz\+Hungry }{p.}{group__hungry} callbacks
\end{DoxyItemize}

As each packet is enqueued, its validity is checked against the framing constraints outlined in the \doxyref{Ogg basics }{p.}{group__basics} section. If it does not pass these constraints, \doxyref{oggz\+\_\+write\+\_\+feed()}{p.}{group__write__api_ga6ccaceb107db1fd2eae047dbdbaa5889} will fail with an appropriate error code.

\begin{DoxyNote}{Note}

\begin{DoxyItemize}
\item When writing, you can ensure that a packet starts on a new page by setting the {\itshape flush} parameter of \doxyref{oggz\+\_\+write\+\_\+feed()}{p.}{group__write__api_ga6ccaceb107db1fd2eae047dbdbaa5889} to {\itshape OGGZ\+\_\+\+FLUSH\+\_\+\+BEFORE} when enqueuing it. Similarly you can ensure that the last page a packet is written into won\textquotesingle{}t contain any following packets by setting the {\itshape flush} parameter of \doxyref{oggz\+\_\+write\+\_\+feed()}{p.}{group__write__api_ga6ccaceb107db1fd2eae047dbdbaa5889} to {\itshape OGGZ\+\_\+\+FLUSH\+\_\+\+AFTER}.
\item The {\itshape OGGZ\+\_\+\+FLUSH\+\_\+\+BEFORE} and {\itshape OGGZ\+\_\+\+FLUSH\+\_\+\+AFTER} flags can be bitwise OR\textquotesingle{}d together to ensure that the packet will not share any pages with any other packets, either before or after. 
\end{DoxyItemize}
\end{DoxyNote}


\doxysubsection{Typedef Documentation}
\index{Oggz Write API@{Oggz Write API}!OggzWriteHungry@{OggzWriteHungry}}
\index{OggzWriteHungry@{OggzWriteHungry}!Oggz Write API@{Oggz Write API}}
\doxysubsubsection{OggzWriteHungry}
{\footnotesize\ttfamily \label{group__write__api_ga028c64d6c9dbf0be14b9d1644b4e31c0} 
typedef int($\ast$ Oggz\+Write\+Hungry) (\textbf{ OGGZ} $\ast$oggz, int empty, void $\ast$user\+\_\+data)}



This is the signature of a callback which Oggz will call when {\itshape oggz} is \doxyref{hungry }{p.}{group__hungry}. 


\begin{DoxyParams}{Parameters}
{\em oggz} & The \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} handle \\
\hline
{\em empty} & A value of 1 indicates that the packet queue is currently empty. A value of 0 indicates that the packet queue is not empty. \\
\hline
{\em user\+\_\+data} & A generic pointer you have provided earlier \\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 0} & Continue \\
\hline
{\em non-\/zero} & Instruct Oggz to stop. \\
\hline
\end{DoxyRetVals}


\doxysubsection{Function Documentation}
\index{Oggz Write API@{Oggz Write API}!oggz\_write@{oggz\_write}}
\index{oggz\_write@{oggz\_write}!Oggz Write API@{Oggz Write API}}
\doxysubsubsection{oggz\_write()}
{\footnotesize\ttfamily \label{group__write__api_ga3c97d94ea425d64546adf9c368b71904} 
long oggz\+\_\+write (\begin{DoxyParamCaption}\item[{\textbf{ OGGZ} $\ast$}]{oggz}{, }\item[{long}]{n}{}\end{DoxyParamCaption})}



Write n bytes from an \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} handle. 

Oggz will call your write callback as needed.


\begin{DoxyParams}{Parameters}
{\em oggz} & An \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} handle previously opened for writing \\
\hline
{\em n} & A count of bytes to be written \\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em $>$ 0} & The number of bytes successfully output \\
\hline
{\em 0} & End of stream \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+RECURSIVE\+\_\+\+WRITE} & Attempt to initiate writing from within an Oggz\+Hungry callback \\
\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} & Writing was stopped by an Oggz\+Hungry callback returning OGGZ\+\_\+\+STOP\+\_\+\+OK \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+STOP\+\_\+\+ERR} & Reading was stopped by an Oggz\+Hungry callback returning OGGZ\+\_\+\+STOP\+\_\+\+ERR \\
\hline
\end{DoxyRetVals}
\index{Oggz Write API@{Oggz Write API}!oggz\_write\_feed@{oggz\_write\_feed}}
\index{oggz\_write\_feed@{oggz\_write\_feed}!Oggz Write API@{Oggz Write API}}
\doxysubsubsection{oggz\_write\_feed()}
{\footnotesize\ttfamily \label{group__write__api_ga6ccaceb107db1fd2eae047dbdbaa5889} 
int oggz\+\_\+write\+\_\+feed (\begin{DoxyParamCaption}\item[{\textbf{ OGGZ} $\ast$}]{oggz}{, }\item[{ogg\+\_\+packet $\ast$}]{op}{, }\item[{long}]{serialno}{, }\item[{int}]{flush}{, }\item[{int $\ast$}]{guard}{}\end{DoxyParamCaption})}



Add a packet to {\itshape oggz\textquotesingle{}s} packet queue. 


\begin{DoxyParams}{Parameters}
{\em oggz} & An \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} handle previously opened for writing \\
\hline
{\em op} & An ogg\+\_\+packet with all fields filled in \\
\hline
{\em serialno} & Identify the logical bitstream in {\itshape oggz} to add the packet to \\
\hline
{\em flush} & Bitmask of OGGZ\+\_\+\+FLUSH\+\_\+\+BEFORE, OGGZ\+\_\+\+FLUSH\+\_\+\+AFTER \\
\hline
{\em guard} & A guard for nocopy, NULL otherwise \\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 0} & Success \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+BAD\+\_\+\+GUARD} & {\itshape guard} specified has non-\/zero initialization \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+BOS} & Packet would be bos packet of a new logical bitstream, but oggz has already written one or more non-\/bos packets in other logical bitstreams, and {\itshape oggz} is not flagged OGGZ\+\_\+\+NONSTRICT \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+EOS} & The logical bitstream identified by {\itshape serialno} is already at eos, and {\itshape oggz} is not flagged OGGZ\+\_\+\+NONSTRICT \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+BAD\+\_\+\+BYTES} & {\itshape op-\/$>$bytes} is invalid, and {\itshape oggz} is not flagged OGGZ\+\_\+\+NONSTRICT \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+BAD\+\_\+\+B\+\_\+\+O\+\_\+S} & {\itshape op-\/$>$b\+\_\+o\+\_\+s} is invalid, and {\itshape oggz} is not flagged OGGZ\+\_\+\+NONSTRICT \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+BAD\+\_\+\+GRANULEPOS} & {\itshape op-\/$>$granulepos} is less than that of an earlier packet within this logical bitstream, and {\itshape oggz} is not flagged OGGZ\+\_\+\+NONSTRICT \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+BAD\+\_\+\+PACKETNO} & {\itshape op-\/$>$packetno} is less than that of an earlier packet within this logical bitstream, and {\itshape oggz} is not flagged OGGZ\+\_\+\+NONSTRICT \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+BAD\+\_\+\+SERIALNO} & {\itshape serialno} does not identify an existing logical bitstream in {\itshape oggz}, and {\itshape oggz} is not flagged OGGZ\+\_\+\+NONSTRICT or {\itshape serialno} is equal to -\/1, or {\itshape serialno} does not fit in 32 bits, ie. within the range (-\/(2$^\wedge$31), (2$^\wedge$31)-\/1) \\
\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} & Unable to allocate memory to queue packet\\
\hline
\end{DoxyRetVals}
\begin{DoxyNote}{Note}
If {\itshape op-\/$>$b\+\_\+o\+\_\+s} is initialized to {\itshape -\/1} before calling \doxyref{oggz\+\_\+write\+\_\+feed()}{p.}{group__write__api_ga6ccaceb107db1fd2eae047dbdbaa5889}, Oggz will fill it in with the appropriate value; ie. 1 for the first packet of a new stream, and 0 otherwise. 
\end{DoxyNote}
\index{Oggz Write API@{Oggz Write API}!oggz\_write\_get\_next\_page\_size@{oggz\_write\_get\_next\_page\_size}}
\index{oggz\_write\_get\_next\_page\_size@{oggz\_write\_get\_next\_page\_size}!Oggz Write API@{Oggz Write API}}
\doxysubsubsection{oggz\_write\_get\_next\_page\_size()}
{\footnotesize\ttfamily \label{group__write__api_gab25da7d2cbf39585357f2a426d3dba2f} 
long oggz\+\_\+write\+\_\+get\+\_\+next\+\_\+page\+\_\+size (\begin{DoxyParamCaption}\item[{\textbf{ OGGZ} $\ast$}]{oggz}{}\end{DoxyParamCaption})}



Query the number of bytes in the next page to be written. 


\begin{DoxyParams}{Parameters}
{\em oggz} & An \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} handle previously opened for writing \\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em $>$= 0} & The number of bytes in the next page \\
\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
\end{DoxyRetVals}
\index{Oggz Write API@{Oggz Write API}!oggz\_write\_output@{oggz\_write\_output}}
\index{oggz\_write\_output@{oggz\_write\_output}!Oggz Write API@{Oggz Write API}}
\doxysubsubsection{oggz\_write\_output()}
{\footnotesize\ttfamily \label{group__write__api_ga5606dff01964caec4582eb172fde0c1c} 
long oggz\+\_\+write\+\_\+output (\begin{DoxyParamCaption}\item[{\textbf{ OGGZ} $\ast$}]{oggz}{, }\item[{unsigned char $\ast$}]{buf}{, }\item[{long}]{n}{}\end{DoxyParamCaption})}



Output data from an \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} handle. 

Oggz will call your write callback as needed.


\begin{DoxyParams}{Parameters}
{\em oggz} & An \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} handle previously opened for writing \\
\hline
{\em buf} & A memory buffer \\
\hline
{\em n} & A count of bytes to output \\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em $>$ 0} & The number of bytes successfully output \\
\hline
{\em 0} & End of stream \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+RECURSIVE\+\_\+\+WRITE} & Attempt to initiate writing from within an Oggz\+Hungry callback \\
\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} & Writing was stopped by an Oggz\+Hungry callback returning OGGZ\+\_\+\+STOP\+\_\+\+OK \\
\hline
{\em OGGZ\+\_\+\+ERR\+\_\+\+STOP\+\_\+\+ERR} & Reading was stopped by an Oggz\+Hungry callback returning OGGZ\+\_\+\+STOP\+\_\+\+ERR \\
\hline
\end{DoxyRetVals}
\index{Oggz Write API@{Oggz Write API}!oggz\_write\_set\_hungry\_callback@{oggz\_write\_set\_hungry\_callback}}
\index{oggz\_write\_set\_hungry\_callback@{oggz\_write\_set\_hungry\_callback}!Oggz Write API@{Oggz Write API}}
\doxysubsubsection{oggz\_write\_set\_hungry\_callback()}
{\footnotesize\ttfamily \label{group__write__api_gaf362c030bc7a7f57cb23f2b863a59389} 
int oggz\+\_\+write\+\_\+set\+\_\+hungry\+\_\+callback (\begin{DoxyParamCaption}\item[{\textbf{ OGGZ} $\ast$}]{oggz}{, }\item[{\textbf{ Oggz\+Write\+Hungry}}]{hungry}{, }\item[{int}]{only\+\_\+when\+\_\+empty}{, }\item[{void $\ast$}]{user\+\_\+data}{}\end{DoxyParamCaption})}



Set a callback for Oggz to call when {\itshape oggz} is \doxyref{hungry }{p.}{group__hungry}. 


\begin{DoxyParams}{Parameters}
{\em oggz} & An \doxyref{OGGZ}{p.}{oggz_8h_a672d218df13da45a4b41d5366211bfee} handle previously opened for writing \\
\hline
{\em hungry} & Your callback function \\
\hline
{\em only\+\_\+when\+\_\+empty} & When to call\+: a value of 0 indicates that Oggz should call {\itshape hungry()} after each and every packet is written; a value of 1 indicates that Oggz should call {\itshape hungry()} only when its packet queue is empty \\
\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
\end{DoxyRetVals}
\begin{DoxyNote}{Note}
Passing a value of 0 for {\itshape only\+\_\+when\+\_\+empty} allows you to feed new packets into {\itshape oggz\textquotesingle{}s} packet queue on the fly. 
\end{DoxyNote}
