\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{CompactItemize}
\item 
typedef int($\ast$ {\bf OggzWriteHungry} )({\bf OGGZ} $\ast$oggz, int empty, void $\ast$user\_\-data)
\begin{CompactList}\small\item\em This is the signature of a callback which Oggz will call when {\em oggz\/} is \doxyref{hungry }{p.}{group__hungry}. \item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
int {\bf oggz\_\-write\_\-set\_\-hungry\_\-callback} ({\bf OGGZ} $\ast$oggz, {\bf OggzWriteHungry} hungry, int only\_\-when\_\-empty, void $\ast$user\_\-data)
\begin{CompactList}\small\item\em Set a callback for Oggz to call when {\em oggz\/} is \doxyref{hungry }{p.}{group__hungry}. \item\end{CompactList}\item 
int {\bf oggz\_\-write\_\-feed} ({\bf OGGZ} $\ast$oggz, ogg\_\-packet $\ast$op, long serialno, int flush, int $\ast$guard)
\begin{CompactList}\small\item\em Add a packet to {\em oggz's\/} packet queue. \item\end{CompactList}\item 
long {\bf oggz\_\-write\_\-output} ({\bf OGGZ} $\ast$oggz, unsigned char $\ast$buf, long n)
\begin{CompactList}\small\item\em Output data from an OGGZ handle. \item\end{CompactList}\item 
long {\bf oggz\_\-write} ({\bf OGGZ} $\ast$oggz, long n)
\begin{CompactList}\small\item\em Write n bytes from an OGGZ handle. \item\end{CompactList}\item 
long {\bf oggz\_\-write\_\-get\_\-next\_\-page\_\-size} ({\bf OGGZ} $\ast$oggz)
\begin{CompactList}\small\item\em Query the number of bytes in the next page to be written. \item\end{CompactList}\end{CompactItemize}


\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{itemize}
\item by \doxyref{force feeding Oggz }{p.}{group__force__feed}\item by using \doxyref{OggzHungry }{p.}{group__hungry} callbacks\end{itemize}


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_g6ccaceb107db1fd2eae047dbdbaa5889} will fail with an appropriate error code.

\begin{Desc}
\item[Note:]\begin{itemize}
\item When writing, you can ensure that a packet starts on a new page by setting the {\em flush\/} parameter of \doxyref{oggz\_\-write\_\-feed()}{p.}{group__write__api_g6ccaceb107db1fd2eae047dbdbaa5889} to {\em 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 {\em flush\/} parameter of \doxyref{oggz\_\-write\_\-feed()}{p.}{group__write__api_g6ccaceb107db1fd2eae047dbdbaa5889} to {\em OGGZ\_\-FLUSH\_\-AFTER\/}.\item The {\em OGGZ\_\-FLUSH\_\-BEFORE\/} and {\em 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{itemize}
\end{Desc}


\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_g27ef9f56078d3c015431b1a67b2c1812}


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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em oggz}]The OGGZ handle \item[{\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. \item[{\em user\_\-data}]A generic pointer you have provided earlier \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]Continue \item[{\em non-zero}]Instruct Oggz to stop. \end{description}
\end{Desc}


\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 ({\bf OGGZ} $\ast$ {\em oggz}, \/  long {\em n})}\label{group__write__api_g3c97d94ea425d64546adf9c368b71904}


Write n bytes from an OGGZ handle. 

Oggz will call your write callback as needed.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em oggz}]An OGGZ handle previously opened for writing \item[{\em n}]A count of bytes to be written \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em $>$ 0}]The number of bytes successfully output \item[{\em 0}]End of stream \item[{\em OGGZ\_\-ERR\_\-RECURSIVE\_\-WRITE}]Attempt to initiate writing from within an OggzHungry callback \item[{\em OGGZ\_\-ERR\_\-BAD\_\-OGGZ}]{\em oggz\/} does not refer to an existing OGGZ \item[{\em OGGZ\_\-ERR\_\-INVALID}]Operation not suitable for this OGGZ \item[{\em OGGZ\_\-ERR\_\-STOP\_\-OK}]Writing was stopped by an OggzHungry callback returning OGGZ\_\-STOP\_\-OK \item[{\em OGGZ\_\-ERR\_\-STOP\_\-ERR}]Reading was stopped by an OggzHungry callback returning OGGZ\_\-STOP\_\-ERR \end{description}
\end{Desc}
\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 ({\bf OGGZ} $\ast$ {\em oggz}, \/  ogg\_\-packet $\ast$ {\em op}, \/  long {\em serialno}, \/  int {\em flush}, \/  int $\ast$ {\em guard})}\label{group__write__api_g6ccaceb107db1fd2eae047dbdbaa5889}


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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em oggz}]An OGGZ handle previously opened for writing \item[{\em op}]An ogg\_\-packet with all fields filled in \item[{\em serialno}]Identify the logical bitstream in {\em oggz\/} to add the packet to \item[{\em flush}]Bitmask of OGGZ\_\-FLUSH\_\-BEFORE, OGGZ\_\-FLUSH\_\-AFTER \item[{\em guard}]A guard for nocopy, NULL otherwise \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]Success \item[{\em OGGZ\_\-ERR\_\-BAD\_\-GUARD}]{\em guard\/} specified has non-zero initialization \item[{\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 {\em oggz\/} is not flagged OGGZ\_\-NONSTRICT \item[{\em OGGZ\_\-ERR\_\-EOS}]The logical bitstream identified by {\em serialno\/} is already at eos, and {\em oggz\/} is not flagged OGGZ\_\-NONSTRICT \item[{\em OGGZ\_\-ERR\_\-BAD\_\-BYTES}]{\em op-$>$bytes\/} is invalid, and {\em oggz\/} is not flagged OGGZ\_\-NONSTRICT \item[{\em OGGZ\_\-ERR\_\-BAD\_\-B\_\-O\_\-S}]{\em op-$>$b\_\-o\_\-s\/} is invalid, and {\em oggz\/} is not flagged OGGZ\_\-NONSTRICT \item[{\em OGGZ\_\-ERR\_\-BAD\_\-GRANULEPOS}]{\em op-$>$granulepos\/} is less than that of an earlier packet within this logical bitstream, and {\em oggz\/} is not flagged OGGZ\_\-NONSTRICT \item[{\em OGGZ\_\-ERR\_\-BAD\_\-PACKETNO}]{\em op-$>$packetno\/} is less than that of an earlier packet within this logical bitstream, and {\em oggz\/} is not flagged OGGZ\_\-NONSTRICT \item[{\em OGGZ\_\-ERR\_\-BAD\_\-SERIALNO}]{\em serialno\/} does not identify an existing logical bitstream in {\em oggz\/}, and {\em oggz\/} is not flagged OGGZ\_\-NONSTRICT or {\em serialno\/} is equal to -1, or {\em serialno\/} does not fit in 32 bits, ie. within the range (-(2$^\wedge$31), (2$^\wedge$31)-1) \item[{\em OGGZ\_\-ERR\_\-BAD\_\-OGGZ}]{\em oggz\/} does not refer to an existing OGGZ \item[{\em OGGZ\_\-ERR\_\-INVALID}]Operation not suitable for this OGGZ \item[{\em OGGZ\_\-ERR\_\-OUT\_\-OF\_\-MEMORY}]Unable to allocate memory to queue packet\end{description}
\end{Desc}
\begin{Desc}
\item[Note:]If {\em op-$>$b\_\-o\_\-s\/} is initialized to {\em -1\/} before calling \doxyref{oggz\_\-write\_\-feed()}{p.}{group__write__api_g6ccaceb107db1fd2eae047dbdbaa5889}, Oggz will fill it in with the appropriate value; ie. 1 for the first packet of a new stream, and 0 otherwise. \end{Desc}
\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 ({\bf OGGZ} $\ast$ {\em oggz})}\label{group__write__api_gb25da7d2cbf39585357f2a426d3dba2f}


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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em oggz}]An OGGZ handle previously opened for writing \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em $>$= 0}]The number of bytes in the next page \item[{\em OGGZ\_\-ERR\_\-BAD\_\-OGGZ}]{\em oggz\/} does not refer to an existing OGGZ \item[{\em OGGZ\_\-ERR\_\-INVALID}]Operation not suitable for this OGGZ \end{description}
\end{Desc}
\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 ({\bf OGGZ} $\ast$ {\em oggz}, \/  unsigned char $\ast$ {\em buf}, \/  long {\em n})}\label{group__write__api_g5606dff01964caec4582eb172fde0c1c}


Output data from an OGGZ handle. 

Oggz will call your write callback as needed.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em oggz}]An OGGZ handle previously opened for writing \item[{\em buf}]A memory buffer \item[{\em n}]A count of bytes to output \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em $>$ 0}]The number of bytes successfully output \item[{\em 0}]End of stream \item[{\em OGGZ\_\-ERR\_\-RECURSIVE\_\-WRITE}]Attempt to initiate writing from within an OggzHungry callback \item[{\em OGGZ\_\-ERR\_\-BAD\_\-OGGZ}]{\em oggz\/} does not refer to an existing OGGZ \item[{\em OGGZ\_\-ERR\_\-INVALID}]Operation not suitable for this OGGZ \item[{\em OGGZ\_\-ERR\_\-STOP\_\-OK}]Writing was stopped by an OggzHungry callback returning OGGZ\_\-STOP\_\-OK \item[{\em OGGZ\_\-ERR\_\-STOP\_\-ERR}]Reading was stopped by an OggzHungry callback returning OGGZ\_\-STOP\_\-ERR \end{description}
\end{Desc}
\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 ({\bf OGGZ} $\ast$ {\em oggz}, \/  {\bf OggzWriteHungry} {\em hungry}, \/  int {\em only\_\-when\_\-empty}, \/  void $\ast$ {\em user\_\-data})}\label{group__write__api_gf362c030bc7a7f57cb23f2b863a59389}


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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em oggz}]An OGGZ handle previously opened for writing \item[{\em hungry}]Your callback function \item[{\em only\_\-when\_\-empty}]When to call: a value of 0 indicates that Oggz should call {\em hungry()\/} after each and every packet is written; a value of 1 indicates that Oggz should call {\em hungry()\/} only when its packet queue is empty \item[{\em user\_\-data}]Arbitrary data you wish to pass to your callback \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]Success \item[{\em OGGZ\_\-ERR\_\-BAD\_\-OGGZ}]{\em oggz\/} does not refer to an existing OGGZ \item[{\em OGGZ\_\-ERR\_\-INVALID}]Operation not suitable for this OGGZ \end{description}
\end{Desc}
\begin{Desc}
\item[Note:]Passing a value of 0 for {\em only\_\-when\_\-empty\/} allows you to feed new packets into {\em oggz's\/} packet queue on the fly. \end{Desc}
