<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>liboggz: Oggz Seek API</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.7.3 -->
<div id="top">
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">liboggz <span id="projectnumber">1.1.1</span></div>
</td>
</tr>
</tbody>
</table>
</div>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div>
<div class="header">
<div class="summary">
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<h1>Oggz Seek API</h1> </div>
</div>
<div class="contents">
<p>Oggz can seek on multitrack, multicodec bitstreams.
<a href="#_details">More...</a></p>
<table class="memberdecls">
<tr><td colspan="2"><h2><a name="func-members"></a>
Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">ogg_int64_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__seek__api.html#ga2ec088fc5541ce9749ce63ccc162761f">oggz_tell_units</a> (<a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> *oggz)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Query the current offset in milliseconds, or custom units as specified by a Metric function you have provided. <a href="#ga2ec088fc5541ce9749ce63ccc162761f"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">ogg_int64_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__seek__api.html#ga60bac88ef3695629efacec43a21927e5">oggz_seek_units</a> (<a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> *oggz, ogg_int64_t units, int whence)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Seek to an offset in milliseconds, or custom units as specified by a Metric function you have provided. <a href="#ga60bac88ef3695629efacec43a21927e5"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">ogg_int64_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__seek__api.html#ga29181fb4e8f4e3629cb84810614acd30">oggz_tell_granulepos</a> (<a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> *oggz)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Provide the exact stored granulepos (from the page header) if relevant to the current packet, or a constructed granulepos if the stored granulepos does not belong to this packet, or -1 if this codec does not have support for granulepos interpolation. <a href="#ga29181fb4e8f4e3629cb84810614acd30"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="oggz__off__t__generated_8h.html#ae4d9c2528ce26af562d8ad958d738050">oggz_off_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__seek__api.html#ga553fabfa03553669f79e37b28eb07ec6">oggz_tell</a> (<a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> *oggz)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Query the file offset in bytes corresponding to the data read. <a href="#ga553fabfa03553669f79e37b28eb07ec6"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="oggz__off__t__generated_8h.html#ae4d9c2528ce26af562d8ad958d738050">oggz_off_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__seek__api.html#gaeef4b261d443701207954e5a636d6817">oggz_seek</a> (<a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> *oggz, <a class="el" href="oggz__off__t__generated_8h.html#ae4d9c2528ce26af562d8ad958d738050">oggz_off_t</a> offset, int whence)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Seek to a specific byte offset. <a href="#gaeef4b261d443701207954e5a636d6817"></a><br/></td></tr>
</table>
<hr/><a name="_details"></a><h2>Detailed Description</h2>
<p>Oggz can seek on multitrack, multicodec bitstreams. </p>
<h2><a class="anchor" id="seek_time"></a>
Time seeking</h2>
<p>Support is built-in for seeking to time positions in <a href="http://www.celt-codec.org/">CELT</a>, <a href="http://www.annodex.net/">CMML</a>. <a href="http://flac.sourceforge.net/">FLAC</a>, <a href="http://wiki.xiph.org/OggPCM">OggPCM</a>, <a href="http://www.speex.org/">Speex</a>, <a href="http://www.theora.org/">Theora</a> and <a href="http://www.vorbis.com/">Vorbis</a>. Oggz is also compatible with <a href="http://www.annodex.net/">Annodex</a> streams, and supports seeking on all tracks described in an <a href="http://wiki.xiph.org/OggSkeleton">Ogg Skeleton</a> track.</p>
<p>You need to open the file with the OGGZ_AUTO flag set:</p>
<ul>
<li>Create an OGGZ handle for reading with <em>flags</em> = OGGZ_READ | OGGZ_AUTO</li>
<li>Read data, ensuring that you have received all b_o_s pages before attempting to seek.</li>
</ul>
<p>Oggz will silently parse known codec headers and associate metrics appropriately; if you attempt to seek before you have received all b_o_s pages, Oggz will not have had a chance to parse the codec headers and associate metrics. It is safe to seek once you have received a packet with <em>b_o_s</em> == 0; see the <a class="el" href="group__basics.html">Ogg basics </a> section for more details.</p>
<dl class="note"><dt><b>Note:</b></dt><dd>Oggz parses these codec headers internally, and so liboggz is <b>not</b> linked to libspeex, libvorbis, libflac, libtheora, libcmml or libannodex.</dd></dl>
<p>For other data streams, you will need to provide a metric function; see the section on <a class="el" href="group__metric.html">Using OggzMetrics </a> for details of setting up and seeking with metrics.</p>
<h2><a class="anchor" id="seek_bytes"></a>
Byte seeking</h2>
<p><a class="el" href="group__seek__api.html#gaeef4b261d443701207954e5a636d6817" title="Seek to a specific byte offset.">oggz_seek()</a> provides low-level seeking to byte positions.</p>
<h2><a class="anchor" id="seek_info"></a>
More detail</h2>
<p>For a full description of the seeking methods possible in Ogg, see <a class="el" href="group__seek__semantics.html">Semantics of seeking in Ogg bitstreams </a>. </p>
<hr/><h2>Function Documentation</h2>
<a class="anchor" id="gaeef4b261d443701207954e5a636d6817"></a><!-- doxytag: member="oggz_seek.h::oggz_seek" ref="gaeef4b261d443701207954e5a636d6817" args="(OGGZ *oggz, oggz_off_t offset, int whence)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="oggz__off__t__generated_8h.html#ae4d9c2528ce26af562d8ad958d738050">oggz_off_t</a> oggz_seek </td>
<td>(</td>
<td class="paramtype"><a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> * </td>
<td class="paramname"><em>oggz</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="oggz__off__t__generated_8h.html#ae4d9c2528ce26af562d8ad958d738050">oggz_off_t</a> </td>
<td class="paramname"><em>offset</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>whence</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Seek to a specific byte offset. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">oggz</td><td>An OGGZ handle </td></tr>
<tr><td class="paramname">offset</td><td>a byte offset </td></tr>
<tr><td class="paramname">whence</td><td>As defined in <stdio.h>: SEEK_SET, SEEK_CUR or SEEK_END </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the new file offset, or -1 on failure. </dd></dl>
</div>
</div>
<a class="anchor" id="ga60bac88ef3695629efacec43a21927e5"></a><!-- doxytag: member="oggz_seek.h::oggz_seek_units" ref="ga60bac88ef3695629efacec43a21927e5" args="(OGGZ *oggz, ogg_int64_t units, int whence)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ogg_int64_t oggz_seek_units </td>
<td>(</td>
<td class="paramtype"><a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> * </td>
<td class="paramname"><em>oggz</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">ogg_int64_t </td>
<td class="paramname"><em>units</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>whence</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Seek to an offset in milliseconds, or custom units as specified by a Metric function you have provided. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">oggz</td><td>An OGGZ handle </td></tr>
<tr><td class="paramname">units</td><td>A number of milliseconds, or custom units </td></tr>
<tr><td class="paramname">whence</td><td>As defined in <stdio.h>: SEEK_SET, SEEK_CUR or SEEK_END </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the new file offset, or -1 on failure. </dd></dl>
</div>
</div>
<a class="anchor" id="ga553fabfa03553669f79e37b28eb07ec6"></a><!-- doxytag: member="oggz_seek.h::oggz_tell" ref="ga553fabfa03553669f79e37b28eb07ec6" args="(OGGZ *oggz)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="oggz__off__t__generated_8h.html#ae4d9c2528ce26af562d8ad958d738050">oggz_off_t</a> oggz_tell </td>
<td>(</td>
<td class="paramtype"><a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> * </td>
<td class="paramname"><em>oggz</em></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Query the file offset in bytes corresponding to the data read. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">oggz</td><td>An OGGZ handle </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>The current offset of oggz.</dd></dl>
<dl class="note"><dt><b>Note:</b></dt><dd>When reading, the value returned by <a class="el" href="group__seek__api.html#ga553fabfa03553669f79e37b28eb07ec6" title="Query the file offset in bytes corresponding to the data read.">oggz_tell()</a> reflects the data offset of the start of the most recent packet processed, so that when called from an OggzReadPacket callback it reflects the byte offset of the start of the packet. As Oggz may have internally read ahead, this may differ from the current offset of the associated file descriptor. </dd></dl>
</div>
</div>
<a class="anchor" id="ga29181fb4e8f4e3629cb84810614acd30"></a><!-- doxytag: member="oggz_seek.h::oggz_tell_granulepos" ref="ga29181fb4e8f4e3629cb84810614acd30" args="(OGGZ *oggz)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ogg_int64_t oggz_tell_granulepos </td>
<td>(</td>
<td class="paramtype"><a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> * </td>
<td class="paramname"><em>oggz</em></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Provide the exact stored granulepos (from the page header) if relevant to the current packet, or a constructed granulepos if the stored granulepos does not belong to this packet, or -1 if this codec does not have support for granulepos interpolation. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">oggz</td><td>An OGGZ handle </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the granulepos of the <em>current</em> packet (if available) </dd></dl>
</div>
</div>
<a class="anchor" id="ga2ec088fc5541ce9749ce63ccc162761f"></a><!-- doxytag: member="oggz_seek.h::oggz_tell_units" ref="ga2ec088fc5541ce9749ce63ccc162761f" args="(OGGZ *oggz)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ogg_int64_t oggz_tell_units </td>
<td>(</td>
<td class="paramtype"><a class="el" href="oggz_8h.html#a672d218df13da45a4b41d5366211bfee">OGGZ</a> * </td>
<td class="paramname"><em>oggz</em></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Query the current offset in milliseconds, or custom units as specified by a Metric function you have provided. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">oggz</td><td>An OGGZ handle </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the offset in milliseconds, or custom units </dd></dl>
<dl><dt><b>Return values:</b></dt><dd>
<table class="retval">
<tr><td class="paramname">OGGZ_ERR_BAD_OGGZ</td><td><em>oggz</em> does not refer to an existing OGGZ </td></tr>
<tr><td class="paramname">OGGZ_ERR_INVALID</td><td>Operation not suitable for this OGGZ </td></tr>
</table>
</dd>
</dl>
</div>
</div>
</div>
<hr class="footer"/><address class="footer"><small>Generated on Tue Feb 8 2011 for liboggz by 
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.3 </small></address>
</body>
</html>
