\section{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.  


\subsection*{Typedefs}
\begin{DoxyCompactItemize}
\item 
typedef int($\ast$ {\bf OggzWriteHungry} )({\bf 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}. \item\end{DoxyCompactList}\end{DoxyCompactItemize}
\subsection*{Functions}
\begin{DoxyCompactItemize}
\item 
int {\bf oggz\_\-write\_\-set\_\-hungry\_\-callback} ({\bf OGGZ} $\ast$oggz, {\bf OggzWriteHungry} 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}. \item\end{DoxyCompactList}\item 
int {\bf oggz\_\-write\_\-feed} ({\bf 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's\/} packet queue. \item\end{DoxyCompactList}\item 
long {\bf oggz\_\-write\_\-output} ({\bf OGGZ} $\ast$oggz, unsigned char $\ast$buf, long n)
\begin{DoxyCompactList}\small\item\em Output data from an OGGZ handle. \item\end{DoxyCompactList}\item 
long {\bf oggz\_\-write} ({\bf OGGZ} $\ast$oggz, long n)
\begin{DoxyCompactList}\small\item\em Write n bytes from an OGGZ handle. \item\end{DoxyCompactList}\item 
long {\bf oggz\_\-write\_\-get\_\-next\_\-page\_\-size} ({\bf OGGZ} $\ast$oggz)
\begin{DoxyCompactList}\small\item\em Query the number of bytes in the next page to be written. \item\end{DoxyCompactList}\end{DoxyCompactItemize}


\subsection{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{OggzHungry }{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'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'd together to ensure that the packet will not share any pages with any other packets, either before or after. 
\end{DoxyItemize}
\end{DoxyNote}


\subsection{Typedef Documentation}
\index{write\_\-api@{write\_\-api}!OggzWriteHungry@{OggzWriteHungry}}
\index{OggzWriteHungry@{OggzWriteHungry}!write_api@{write\_\-api}}
\subsubsection[{OggzWriteHungry}]{\setlength{\rightskip}{0pt plus 5cm}typedef int($\ast$ {\bf OggzWriteHungry})({\bf OGGZ} $\ast$oggz, int empty, void $\ast$user\_\-data)}\label{group__write__api_ga27ef9f56078d3c015431b1a67b2c1812}


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 OGGZ 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}


\subsection{Function Documentation}
\index{write\_\-api@{write\_\-api}!oggz\_\-write@{oggz\_\-write}}
\index{oggz\_\-write@{oggz\_\-write}!write_api@{write\_\-api}}
\subsubsection[{oggz\_\-write}]{\setlength{\rightskip}{0pt plus 5cm}long oggz\_\-write (
\begin{DoxyParamCaption}
\item[{{\bf OGGZ} $\ast$}]{oggz, }
\item[{long}]{n}
\end{DoxyParamCaption}
)}\label{group__write__api_ga3c97d94ea425d64546adf9c368b71904}


Write n bytes from an OGGZ handle. 

Oggz will call your write callback as needed.


\begin{DoxyParams}{Parameters}
{\em oggz} & An OGGZ 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 OggzHungry callback \\
\hline
{\em OGGZ\_\-ERR\_\-BAD\_\-OGGZ} & {\itshape oggz\/} does not refer to an existing OGGZ \\
\hline
{\em OGGZ\_\-ERR\_\-INVALID} & Operation not suitable for this OGGZ \\
\hline
{\em OGGZ\_\-ERR\_\-STOP\_\-OK} & Writing was stopped by an OggzHungry callback returning OGGZ\_\-STOP\_\-OK \\
\hline
{\em OGGZ\_\-ERR\_\-STOP\_\-ERR} & Reading was stopped by an OggzHungry callback returning OGGZ\_\-STOP\_\-ERR \\
\hline
\end{DoxyRetVals}
\index{write\_\-api@{write\_\-api}!oggz\_\-write\_\-feed@{oggz\_\-write\_\-feed}}
\index{oggz\_\-write\_\-feed@{oggz\_\-write\_\-feed}!write_api@{write\_\-api}}
\subsubsection[{oggz\_\-write\_\-feed}]{\setlength{\rightskip}{0pt plus 5cm}int oggz\_\-write\_\-feed (
\begin{DoxyParamCaption}
\item[{{\bf OGGZ} $\ast$}]{oggz, }
\item[{ogg\_\-packet $\ast$}]{op, }
\item[{long}]{serialno, }
\item[{int}]{flush, }
\item[{int $\ast$}]{guard}
\end{DoxyParamCaption}
)}\label{group__write__api_ga6ccaceb107db1fd2eae047dbdbaa5889}


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


\begin{DoxyParams}{Parameters}
{\em oggz} & An OGGZ 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 OGGZ \\
\hline
{\em OGGZ\_\-ERR\_\-INVALID} & Operation not suitable for this OGGZ \\
\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{write\_\-api@{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}!write_api@{write\_\-api}}
\subsubsection[{oggz\_\-write\_\-get\_\-next\_\-page\_\-size}]{\setlength{\rightskip}{0pt plus 5cm}long oggz\_\-write\_\-get\_\-next\_\-page\_\-size (
\begin{DoxyParamCaption}
\item[{{\bf OGGZ} $\ast$}]{oggz}
\end{DoxyParamCaption}
)}\label{group__write__api_gab25da7d2cbf39585357f2a426d3dba2f}


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


\begin{DoxyParams}{Parameters}
{\em oggz} & An OGGZ 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 OGGZ \\
\hline
{\em OGGZ\_\-ERR\_\-INVALID} & Operation not suitable for this OGGZ \\
\hline
\end{DoxyRetVals}
\index{write\_\-api@{write\_\-api}!oggz\_\-write\_\-output@{oggz\_\-write\_\-output}}
\index{oggz\_\-write\_\-output@{oggz\_\-write\_\-output}!write_api@{write\_\-api}}
\subsubsection[{oggz\_\-write\_\-output}]{\setlength{\rightskip}{0pt plus 5cm}long oggz\_\-write\_\-output (
\begin{DoxyParamCaption}
\item[{{\bf OGGZ} $\ast$}]{oggz, }
\item[{unsigned char $\ast$}]{buf, }
\item[{long}]{n}
\end{DoxyParamCaption}
)}\label{group__write__api_ga5606dff01964caec4582eb172fde0c1c}


Output data from an OGGZ handle. 

Oggz will call your write callback as needed.


\begin{DoxyParams}{Parameters}
{\em oggz} & An OGGZ 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 OggzHungry callback \\
\hline
{\em OGGZ\_\-ERR\_\-BAD\_\-OGGZ} & {\itshape oggz\/} does not refer to an existing OGGZ \\
\hline
{\em OGGZ\_\-ERR\_\-INVALID} & Operation not suitable for this OGGZ \\
\hline
{\em OGGZ\_\-ERR\_\-STOP\_\-OK} & Writing was stopped by an OggzHungry callback returning OGGZ\_\-STOP\_\-OK \\
\hline
{\em OGGZ\_\-ERR\_\-STOP\_\-ERR} & Reading was stopped by an OggzHungry callback returning OGGZ\_\-STOP\_\-ERR \\
\hline
\end{DoxyRetVals}
\index{write\_\-api@{write\_\-api}!oggz\_\-write\_\-set\_\-hungry\_\-callback@{oggz\_\-write\_\-set\_\-hungry\_\-callback}}
\index{oggz\_\-write\_\-set\_\-hungry\_\-callback@{oggz\_\-write\_\-set\_\-hungry\_\-callback}!write_api@{write\_\-api}}
\subsubsection[{oggz\_\-write\_\-set\_\-hungry\_\-callback}]{\setlength{\rightskip}{0pt plus 5cm}int oggz\_\-write\_\-set\_\-hungry\_\-callback (
\begin{DoxyParamCaption}
\item[{{\bf OGGZ} $\ast$}]{oggz, }
\item[{{\bf OggzWriteHungry}}]{hungry, }
\item[{int}]{only\_\-when\_\-empty, }
\item[{void $\ast$}]{user\_\-data}
\end{DoxyParamCaption}
)}\label{group__write__api_gaf362c030bc7a7f57cb23f2b863a59389}


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


\begin{DoxyParams}{Parameters}
{\em oggz} & An OGGZ 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 OGGZ \\
\hline
{\em OGGZ\_\-ERR\_\-INVALID} & Operation not suitable for this OGGZ \\
\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's\/} packet queue on the fly. 
\end{DoxyNote}
