\doxysection{Oggz Write A\+PI}
\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. There are two complementary methods for adding packets to the packet queue.  


\doxysubsection*{Typedefs}
\begin{DoxyCompactItemize}
\item 
typedef int($\ast$ \textbf{ Oggz\+Write\+Hungry}) (\textbf{ O\+G\+GZ} $\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}
\doxysubsection*{Functions}
\begin{DoxyCompactItemize}
\item 
int \textbf{ oggz\+\_\+write\+\_\+set\+\_\+hungry\+\_\+callback} (\textbf{ O\+G\+GZ} $\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{ O\+G\+GZ} $\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{ O\+G\+GZ} $\ast$oggz, unsigned char $\ast$buf, long n)
\begin{DoxyCompactList}\small\item\em Output data from an O\+G\+GZ handle. \end{DoxyCompactList}\item 
long \textbf{ oggz\+\_\+write} (\textbf{ O\+G\+GZ} $\ast$oggz, long n)
\begin{DoxyCompactList}\small\item\em Write n bytes from an O\+G\+GZ handle. \end{DoxyCompactList}\item 
long \textbf{ oggz\+\_\+write\+\_\+get\+\_\+next\+\_\+page\+\_\+size} (\textbf{ O\+G\+GZ} $\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 O\+G\+G\+Z\+\_\+\+F\+L\+U\+S\+H\+\_\+\+B\+E\+F\+O\+RE} 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 O\+G\+G\+Z\+\_\+\+F\+L\+U\+S\+H\+\_\+\+A\+F\+T\+ER}.
\item The {\itshape O\+G\+G\+Z\+\_\+\+F\+L\+U\+S\+H\+\_\+\+B\+E\+F\+O\+RE} and {\itshape O\+G\+G\+Z\+\_\+\+F\+L\+U\+S\+H\+\_\+\+A\+F\+T\+ER} 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}
\mbox{\label{group__write__api_ga028c64d6c9dbf0be14b9d1644b4e31c0}} 
\index{Oggz Write API@{Oggz Write API}!OggzWriteHungry@{OggzWriteHungry}}
\index{OggzWriteHungry@{OggzWriteHungry}!Oggz Write API@{Oggz Write API}}
\doxysubsubsection{OggzWriteHungry}
{\footnotesize\ttfamily typedef int($\ast$ Oggz\+Write\+Hungry) (\textbf{ O\+G\+GZ} $\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 O\+G\+GZ 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}
\mbox{\label{group__write__api_ga3c97d94ea425d64546adf9c368b71904}} 
\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 long oggz\+\_\+write (\begin{DoxyParamCaption}\item[{\textbf{ O\+G\+GZ} $\ast$}]{oggz,  }\item[{long}]{n }\end{DoxyParamCaption})}



Write n bytes from an O\+G\+GZ handle. 

Oggz will call your write callback as needed.


\begin{DoxyParams}{Parameters}
{\em oggz} & An O\+G\+GZ 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 O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+R\+E\+C\+U\+R\+S\+I\+V\+E\+\_\+\+W\+R\+I\+TE} & Attempt to initiate writing from within an Oggz\+Hungry callback \\
\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} & Writing was stopped by an Oggz\+Hungry 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 an Oggz\+Hungry callback returning O\+G\+G\+Z\+\_\+\+S\+T\+O\+P\+\_\+\+E\+RR \\
\hline
\end{DoxyRetVals}
\mbox{\label{group__write__api_ga6ccaceb107db1fd2eae047dbdbaa5889}} 
\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 int oggz\+\_\+write\+\_\+feed (\begin{DoxyParamCaption}\item[{\textbf{ O\+G\+GZ} $\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 O\+G\+GZ 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 O\+G\+G\+Z\+\_\+\+F\+L\+U\+S\+H\+\_\+\+B\+E\+F\+O\+RE, O\+G\+G\+Z\+\_\+\+F\+L\+U\+S\+H\+\_\+\+A\+F\+T\+ER \\
\hline
{\em guard} & A guard for nocopy, N\+U\+LL otherwise \\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 0} & Success \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+B\+A\+D\+\_\+\+G\+U\+A\+RD} & {\itshape guard} specified has non-\/zero initialization \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+B\+OS} & 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 O\+G\+G\+Z\+\_\+\+N\+O\+N\+S\+T\+R\+I\+CT \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+E\+OS} & The logical bitstream identified by {\itshape serialno} is already at eos, and {\itshape oggz} is not flagged O\+G\+G\+Z\+\_\+\+N\+O\+N\+S\+T\+R\+I\+CT \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+B\+A\+D\+\_\+\+B\+Y\+T\+ES} & {\itshape op-\/$>$bytes} is invalid, and {\itshape oggz} is not flagged O\+G\+G\+Z\+\_\+\+N\+O\+N\+S\+T\+R\+I\+CT \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+B\+A\+D\+\_\+\+B\+\_\+\+O\+\_\+S} & {\itshape op-\/$>$b\+\_\+o\+\_\+s} is invalid, and {\itshape oggz} is not flagged O\+G\+G\+Z\+\_\+\+N\+O\+N\+S\+T\+R\+I\+CT \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+B\+A\+D\+\_\+\+G\+R\+A\+N\+U\+L\+E\+P\+OS} & {\itshape op-\/$>$granulepos} is less than that of an earlier packet within this logical bitstream, and {\itshape oggz} is not flagged O\+G\+G\+Z\+\_\+\+N\+O\+N\+S\+T\+R\+I\+CT \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+B\+A\+D\+\_\+\+P\+A\+C\+K\+E\+T\+NO} & {\itshape op-\/$>$packetno} is less than that of an earlier packet within this logical bitstream, and {\itshape oggz} is not flagged O\+G\+G\+Z\+\_\+\+N\+O\+N\+S\+T\+R\+I\+CT \\
\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}, and {\itshape oggz} is not flagged O\+G\+G\+Z\+\_\+\+N\+O\+N\+S\+T\+R\+I\+CT 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 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} & 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}
\mbox{\label{group__write__api_gab25da7d2cbf39585357f2a426d3dba2f}} 
\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 long oggz\+\_\+write\+\_\+get\+\_\+next\+\_\+page\+\_\+size (\begin{DoxyParamCaption}\item[{\textbf{ O\+G\+GZ} $\ast$}]{oggz }\end{DoxyParamCaption})}



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


\begin{DoxyParams}{Parameters}
{\em oggz} & An O\+G\+GZ handle previously opened for writing \\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em $>$= 0} & The number of bytes in the next page \\
\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
\end{DoxyRetVals}
\mbox{\label{group__write__api_ga5606dff01964caec4582eb172fde0c1c}} 
\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 long oggz\+\_\+write\+\_\+output (\begin{DoxyParamCaption}\item[{\textbf{ O\+G\+GZ} $\ast$}]{oggz,  }\item[{unsigned char $\ast$}]{buf,  }\item[{long}]{n }\end{DoxyParamCaption})}



Output data from an O\+G\+GZ handle. 

Oggz will call your write callback as needed.


\begin{DoxyParams}{Parameters}
{\em oggz} & An O\+G\+GZ 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 O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+R\+E\+C\+U\+R\+S\+I\+V\+E\+\_\+\+W\+R\+I\+TE} & Attempt to initiate writing from within an Oggz\+Hungry callback \\
\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} & Writing was stopped by an Oggz\+Hungry 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 an Oggz\+Hungry callback returning O\+G\+G\+Z\+\_\+\+S\+T\+O\+P\+\_\+\+E\+RR \\
\hline
\end{DoxyRetVals}
\mbox{\label{group__write__api_gaf362c030bc7a7f57cb23f2b863a59389}} 
\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 int oggz\+\_\+write\+\_\+set\+\_\+hungry\+\_\+callback (\begin{DoxyParamCaption}\item[{\textbf{ O\+G\+GZ} $\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 O\+G\+GZ 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 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
\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}
