\section{Oggz Seek API}
\label{group__seek__api}\index{Oggz Seek API@{Oggz Seek API}}


Oggz can seek on multitrack, multicodec bitstreams.  


\subsection*{Functions}
\begin{DoxyCompactItemize}
\item 
ogg\_\-int64\_\-t {\bf oggz\_\-tell\_\-units} ({\bf OGGZ} $\ast$oggz)
\begin{DoxyCompactList}\small\item\em Query the current offset in milliseconds, or custom units as specified by a Metric function you have provided. \item\end{DoxyCompactList}\item 
ogg\_\-int64\_\-t {\bf oggz\_\-seek\_\-units} ({\bf OGGZ} $\ast$oggz, ogg\_\-int64\_\-t units, int whence)
\begin{DoxyCompactList}\small\item\em Seek to an offset in milliseconds, or custom units as specified by a Metric function you have provided. \item\end{DoxyCompactList}\item 
ogg\_\-int64\_\-t {\bf oggz\_\-tell\_\-granulepos} ({\bf OGGZ} $\ast$oggz)
\begin{DoxyCompactList}\small\item\em 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. \item\end{DoxyCompactList}\item 
oggz\_\-off\_\-t {\bf oggz\_\-tell} ({\bf OGGZ} $\ast$oggz)
\begin{DoxyCompactList}\small\item\em Query the file offset in bytes corresponding to the data read. \item\end{DoxyCompactList}\item 
oggz\_\-off\_\-t {\bf oggz\_\-seek} ({\bf OGGZ} $\ast$oggz, oggz\_\-off\_\-t offset, int whence)
\begin{DoxyCompactList}\small\item\em Seek to a specific byte offset. \item\end{DoxyCompactList}\end{DoxyCompactItemize}


\subsection{Detailed Description}
Oggz can seek on multitrack, multicodec bitstreams. \subsection{Time seeking}\label{group__seek__api_seek_time}
Support is built-\/in for seeking to time positions in {\tt CELT}, {\tt CMML}. {\tt FLAC}, {\tt OggPCM}, {\tt Speex}, {\tt Theora} and {\tt Vorbis}. Oggz is also compatible with {\tt Annodex} streams, and supports seeking on all tracks described in an {\tt Ogg Skeleton} track.

You need to open the file with the OGGZ\_\-AUTO flag set:


\begin{DoxyItemize}
\item Create an OGGZ handle for reading with {\itshape flags\/} = OGGZ\_\-READ $|$ OGGZ\_\-AUTO
\item Read data, ensuring that you have received all b\_\-o\_\-s pages before attempting to seek.
\end{DoxyItemize}

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 {\itshape b\_\-o\_\-s\/} == 0; see the \doxyref{Ogg basics }{p.}{group__basics} section for more details.

\begin{DoxyNote}{Note}
Oggz parses these codec headers internally, and so liboggz is {\bfseries not} linked to libspeex, libvorbis, libflac, libtheora, libcmml or libannodex.
\end{DoxyNote}
For other data streams, you will need to provide a metric function; see the section on \doxyref{Using OggzMetrics }{p.}{group__metric} for details of setting up and seeking with metrics.\subsection{Byte seeking}\label{group__seek__api_seek_bytes}
\doxyref{oggz\_\-seek()}{p.}{group__seek__api_gaeef4b261d443701207954e5a636d6817} provides low-\/level seeking to byte positions.\subsection{More detail}\label{group__seek__api_seek_info}
For a full description of the seeking methods possible in Ogg, see \doxyref{Semantics of seeking in Ogg bitstreams }{p.}{group__seek__semantics}. 

\subsection{Function Documentation}
\index{seek\_\-api@{seek\_\-api}!oggz\_\-seek@{oggz\_\-seek}}
\index{oggz\_\-seek@{oggz\_\-seek}!seek_api@{seek\_\-api}}
\subsubsection[{oggz\_\-seek}]{\setlength{\rightskip}{0pt plus 5cm}oggz\_\-off\_\-t oggz\_\-seek ({\bf OGGZ} $\ast$ {\em oggz}, \/  oggz\_\-off\_\-t {\em offset}, \/  int {\em whence})}\label{group__seek__api_gaeef4b261d443701207954e5a636d6817}


Seek to a specific byte offset. 


\begin{DoxyParams}{Parameters}
\item[{\em oggz}]An OGGZ handle \item[{\em offset}]a byte offset \item[{\em whence}]As defined in $<$stdio.h$>$: SEEK\_\-SET, SEEK\_\-CUR or SEEK\_\-END \end{DoxyParams}
\begin{DoxyReturn}{Returns}
the new file offset, or -\/1 on failure. 
\end{DoxyReturn}
\index{seek\_\-api@{seek\_\-api}!oggz\_\-seek\_\-units@{oggz\_\-seek\_\-units}}
\index{oggz\_\-seek\_\-units@{oggz\_\-seek\_\-units}!seek_api@{seek\_\-api}}
\subsubsection[{oggz\_\-seek\_\-units}]{\setlength{\rightskip}{0pt plus 5cm}ogg\_\-int64\_\-t oggz\_\-seek\_\-units ({\bf OGGZ} $\ast$ {\em oggz}, \/  ogg\_\-int64\_\-t {\em units}, \/  int {\em whence})}\label{group__seek__api_ga60bac88ef3695629efacec43a21927e5}


Seek to an offset in milliseconds, or custom units as specified by a Metric function you have provided. 


\begin{DoxyParams}{Parameters}
\item[{\em oggz}]An OGGZ handle \item[{\em units}]A number of milliseconds, or custom units \item[{\em whence}]As defined in $<$stdio.h$>$: SEEK\_\-SET, SEEK\_\-CUR or SEEK\_\-END \end{DoxyParams}
\begin{DoxyReturn}{Returns}
the new file offset, or -\/1 on failure. 
\end{DoxyReturn}
\index{seek\_\-api@{seek\_\-api}!oggz\_\-tell@{oggz\_\-tell}}
\index{oggz\_\-tell@{oggz\_\-tell}!seek_api@{seek\_\-api}}
\subsubsection[{oggz\_\-tell}]{\setlength{\rightskip}{0pt plus 5cm}oggz\_\-off\_\-t oggz\_\-tell ({\bf OGGZ} $\ast$ {\em oggz})}\label{group__seek__api_ga553fabfa03553669f79e37b28eb07ec6}


Query the file offset in bytes corresponding to the data read. 


\begin{DoxyParams}{Parameters}
\item[{\em oggz}]An OGGZ handle \end{DoxyParams}
\begin{DoxyReturn}{Returns}
The current offset of oggz.
\end{DoxyReturn}
\begin{DoxyNote}{Note}
When reading, the value returned by \doxyref{oggz\_\-tell()}{p.}{group__seek__api_ga553fabfa03553669f79e37b28eb07ec6} 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. 
\end{DoxyNote}
\index{seek\_\-api@{seek\_\-api}!oggz\_\-tell\_\-granulepos@{oggz\_\-tell\_\-granulepos}}
\index{oggz\_\-tell\_\-granulepos@{oggz\_\-tell\_\-granulepos}!seek_api@{seek\_\-api}}
\subsubsection[{oggz\_\-tell\_\-granulepos}]{\setlength{\rightskip}{0pt plus 5cm}ogg\_\-int64\_\-t oggz\_\-tell\_\-granulepos ({\bf OGGZ} $\ast$ {\em oggz})}\label{group__seek__api_ga29181fb4e8f4e3629cb84810614acd30}


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. 


\begin{DoxyParams}{Parameters}
\item[{\em oggz}]An OGGZ handle \end{DoxyParams}
\begin{DoxyReturn}{Returns}
the granulepos of the {\itshape current\/} packet (if available) 
\end{DoxyReturn}
\index{seek\_\-api@{seek\_\-api}!oggz\_\-tell\_\-units@{oggz\_\-tell\_\-units}}
\index{oggz\_\-tell\_\-units@{oggz\_\-tell\_\-units}!seek_api@{seek\_\-api}}
\subsubsection[{oggz\_\-tell\_\-units}]{\setlength{\rightskip}{0pt plus 5cm}ogg\_\-int64\_\-t oggz\_\-tell\_\-units ({\bf OGGZ} $\ast$ {\em oggz})}\label{group__seek__api_ga2ec088fc5541ce9749ce63ccc162761f}


Query the current offset in milliseconds, or custom units as specified by a Metric function you have provided. 


\begin{DoxyParams}{Parameters}
\item[{\em oggz}]An OGGZ handle \end{DoxyParams}
\begin{DoxyReturn}{Returns}
the offset in milliseconds, or custom units 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
\item[{\em OGGZ\_\-ERR\_\-BAD\_\-OGGZ}]{\itshape oggz\/} does not refer to an existing OGGZ \item[{\em OGGZ\_\-ERR\_\-INVALID}]Operation not suitable for this OGGZ \end{DoxyRetVals}