<p>This function adds a complete page to the bitstream.
<p>In a typical decoding situation, this function would be called after using <ahref="ogg_sync_pageout.html">ogg_sync_pageout</a> to create a valid <ahref="ogg_page.html">ogg_page</a> struct.
<p>Internally, this function breaks the page into packet segments in preparation for outputting a valid packet to the codec decoding layer.
int ogg_stream_pagein(<ahref="ogg_stream_state.html">ogg_stream_state</a> *os, <ahref="ogg_page.html">ogg_page</a> *og);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>os</i></dt>
<dd>Pointer to a previously declared <ahref="ogg_stream_state.html">ogg_stream_state</a> struct, which represents the current logical bitstream.</dd>
<dt><i>og</i></dt>
<dd>Pointer to a page of data. The data inside this page is being submitted to the streaming layer in order to be allocated into packets.
</dl>
<h3>Return Values</h3>
<blockquote>
<li>-1 indicates failure. This means that the serial number of the page did not match the serial number of the bitstream, the page version was incorrect, or an internal error occurred.</li>
<li>
0 means that the page was successfully submitted to the bitstream.</li>
<p>This function is used to provide a properly-sized buffer for writing.
<p>Buffer space which has already been returned is cleared, and the buffer is extended as necessary by the size plus some additional bytes. Within the current implementation, an extra 4096 bytes are allocated, but applications should not rely on this additional buffer space.
<p>The buffer exposed by this function is empty internal storage from the <ahref="ogg_sync_state.html">ogg_sync_state</a> struct, beginning at the fill mark within the struct.
<p>A pointer to this buffer is returned to be used by the calling application.
<p>This function is used to check the error or readiness condition of an <ahref="ogg_sync_state.html">ogg_sync_state</a> structure.
<p>It is safe practice to ignore unrecoverable errors (such as an internal error caused by a malloc() failure) returned by ogg stream synchronization calls. Should an
internal error occur, the <ahref="ogg_sync_state.html">ogg_sync_state</a> structure will be cleared (equivalent to a
call to
<ahref="ogg_sync_clear.html">ogg_sync_clear</a>) and subsequent calls
using this <ahref="ogg_sync_state.html">ogg_sync_state</a> will be
noops. Error detection is then handled via a single call to
ogg_sync_check at the end of the operational block. </p>
int ogg_sync_check(<ahref="ogg_sync_state.html">ogg_sync_state</a> *oy);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>oy</i></dt>
<dd>Pointer to a previously declared <ahref="ogg_sync_state.html">ogg_sync_state</a> struct.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>
0 is returned if the <ahref="ogg_sync_state.html">ogg_sync_state</a> structure is initialized and ready.</li>
<li>
nonzero is returned if the structure was never initialized, or if an unrecoverable internal error occurred in a previous call using the passed in <ahref="ogg_sync_state.html">ogg_sync_state</a> struct.</li>
<p>This function is used to free the internal storage of an <ahref="ogg_sync_state.html">ogg_sync_state</a> struct and resets the struct to the initial state. To free the entire struct, <ahref="ogg_sync_destroy.html">ogg_sync_destroy</a> should be used instead. In situations where the struct needs to be reset but the internal storage does not need to be freed, <ahref="ogg_sync_reset.html">ogg_sync_reset</a> should be used.
<p>This function is used to initialize an <ahref="ogg_sync_state.html">ogg_sync_state</a> struct to a known initial value in preparation for manipulation of an Ogg bitstream.
<p>The ogg_sync struct is important when decoding, as it synchronizes retrieval and return of data.
int ogg_sync_init(<ahref="ogg_sync_state.html">ogg_sync_state</a> *oy);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>oy</i></dt>
<dd>Pointer to a previously declared <ahref="ogg_sync_state.html">ogg_sync_state</a> struct. After this function call, this struct has been initialized.</dd>
<p>This function takes the data stored in the buffer of the <ahref="ogg_sync_state.html">ogg_sync_state</a> struct and inserts them into an <ahref="ogg_page.html">ogg_page</a>.
<p>In an actual decoding loop, this function should be called first to ensure that the buffer is cleared. The example code below illustrates a clean reading loop which will fill and output pages.
<p><b>Caution:</b>This function should be called before reading into the buffer to ensure that data does not remain in the ogg_sync_state struct. Failing to do so may result in a memory leak. See the example code below for details.
int ogg_sync_pageout(<ahref="ogg_sync_state.html">ogg_sync_state</a> *oy, <ahref="ogg_page.html">ogg_page</a> *og);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>oy</i></dt>
<dd>Pointer to a previously declared <ahref="ogg_sync_state.html">ogg_sync_state</a> struct. Normally, the internal storage of this struct should be filled with newly read data and verified using <ahref="ogg_sync_wrote.html">ogg_sync_wrote</a>.</dd>
<dt><i>og</i></dt>
<dd>Pointer to page struct filled by this function.
</dl>
<h3>Return Values</h3>
<blockquote>
<li>-1 returned if stream has not yet captured sync (bytes were skipped).</li>
<li>0 returned if more data needed or an internal error occurred.</li>
<li>1 indicated a page was synced and returned.</li>
<p>This function synchronizes the ogg_sync_state struct to the next ogg_page.
<p>This is useful when seeking within a bitstream. ogg_sync_pageseek will synchronize to the next page in the bitstream and return information about how many bytes we advanced or skipped in order to do so.
The ogg_sync_state struct tracks the synchronization of the current page.
<p>It is used during decoding to track the status of data as it is read in, synchronized, verified, and parsed into pages belonging to the various logical bistreams in the current physical bitstream link.
int ogg_sync_wrote(<ahref="ogg_sync_state.html">ogg_sync_state</a> *oy, long bytes);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>oy</i></dt>
<dd>Pointer to a previously declared <ahref="ogg_sync_state.html">ogg_sync_state</a> struct.</dd>
<dt><i>bytes</i></dt>
<dd>Number of bytes of new data written.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>-1 if the number of bytes written overflows the internal storage of the <ahref="ogg_sync_state.html">ogg_sync_state</a> struct or an internal error occurred.
