\doxysection{Oggz Seek A\+PI}
\label{group__seek__api}\index{Oggz Seek API@{Oggz Seek API}}


Oggz can seek on multitrack, multicodec bitstreams.  


\doxysubsection*{Functions}
\begin{DoxyCompactItemize}
\item 
ogg\+\_\+int64\+\_\+t \textbf{ oggz\+\_\+tell\+\_\+units} (\textbf{ O\+G\+GZ} $\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. \end{DoxyCompactList}\item 
ogg\+\_\+int64\+\_\+t \textbf{ oggz\+\_\+seek\+\_\+units} (\textbf{ O\+G\+GZ} $\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. \end{DoxyCompactList}\item 
ogg\+\_\+int64\+\_\+t \textbf{ oggz\+\_\+tell\+\_\+granulepos} (\textbf{ O\+G\+GZ} $\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. \end{DoxyCompactList}\item 
\textbf{ oggz\+\_\+off\+\_\+t} \textbf{ oggz\+\_\+tell} (\textbf{ O\+G\+GZ} $\ast$oggz)
\begin{DoxyCompactList}\small\item\em Query the file offset in bytes corresponding to the data read. \end{DoxyCompactList}\item 
\textbf{ oggz\+\_\+off\+\_\+t} \textbf{ oggz\+\_\+seek} (\textbf{ O\+G\+GZ} $\ast$oggz, \textbf{ oggz\+\_\+off\+\_\+t} offset, int whence)
\begin{DoxyCompactList}\small\item\em Seek to a specific byte offset. \end{DoxyCompactList}\end{DoxyCompactItemize}


\doxysubsection{Detailed Description}
Oggz can seek on multitrack, multicodec bitstreams. 

\doxysubsection{Time seeking}\label{group__seek__api_seek_time}
Support is built-\/in for seeking to time positions in {\texttt{ C\+E\+LT}}, {\texttt{ C\+M\+ML}}. {\texttt{ F\+L\+AC}}, {\texttt{ Ogg\+P\+CM}}, {\texttt{ Speex}}, {\texttt{ Theora}} and {\texttt{ Vorbis}}. Oggz is also compatible with {\texttt{ Annodex}} streams, and supports seeking on all tracks described in an {\texttt{ Ogg Skeleton}} track.

You need to open the file with the O\+G\+G\+Z\+\_\+\+A\+U\+TO flag set\+:


\begin{DoxyItemize}
\item Create an O\+G\+GZ handle for reading with {\itshape flags} = O\+G\+G\+Z\+\_\+\+R\+E\+AD $\vert$ O\+G\+G\+Z\+\_\+\+A\+U\+TO
\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 Oggz\+Metrics }{p.}{group__metric} for details of setting up and seeking with metrics.\doxysubsection{Byte seeking}\label{group__seek__api_seek_bytes}
\doxyref{oggz\+\_\+seek()}{p.}{group__seek__api_gaeef4b261d443701207954e5a636d6817} provides low-\/level seeking to byte positions.\doxysubsection{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}. 

\doxysubsection{Function Documentation}
\mbox{\label{group__seek__api_gaeef4b261d443701207954e5a636d6817}} 
\index{Oggz Seek API@{Oggz Seek API}!oggz\_seek@{oggz\_seek}}
\index{oggz\_seek@{oggz\_seek}!Oggz Seek API@{Oggz Seek API}}
\doxysubsubsection{oggz\_seek()}
{\footnotesize\ttfamily \textbf{ oggz\+\_\+off\+\_\+t} oggz\+\_\+seek (\begin{DoxyParamCaption}\item[{\textbf{ O\+G\+GZ} $\ast$}]{oggz,  }\item[{\textbf{ oggz\+\_\+off\+\_\+t}}]{offset,  }\item[{int}]{whence }\end{DoxyParamCaption})}



Seek to a specific byte offset. 


\begin{DoxyParams}{Parameters}
{\em oggz} & An O\+G\+GZ handle \\
\hline
{\em offset} & a byte offset \\
\hline
{\em whence} & As defined in $<$stdio.\+h$>$\+: S\+E\+E\+K\+\_\+\+S\+ET, S\+E\+E\+K\+\_\+\+C\+UR or S\+E\+E\+K\+\_\+\+E\+ND \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the new file offset, or -\/1 on failure. 
\end{DoxyReturn}
\mbox{\label{group__seek__api_ga60bac88ef3695629efacec43a21927e5}} 
\index{Oggz Seek API@{Oggz Seek API}!oggz\_seek\_units@{oggz\_seek\_units}}
\index{oggz\_seek\_units@{oggz\_seek\_units}!Oggz Seek API@{Oggz Seek API}}
\doxysubsubsection{oggz\_seek\_units()}
{\footnotesize\ttfamily ogg\+\_\+int64\+\_\+t oggz\+\_\+seek\+\_\+units (\begin{DoxyParamCaption}\item[{\textbf{ O\+G\+GZ} $\ast$}]{oggz,  }\item[{ogg\+\_\+int64\+\_\+t}]{units,  }\item[{int}]{whence }\end{DoxyParamCaption})}



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


\begin{DoxyParams}{Parameters}
{\em oggz} & An O\+G\+GZ handle \\
\hline
{\em units} & A number of milliseconds, or custom units \\
\hline
{\em whence} & As defined in $<$stdio.\+h$>$\+: S\+E\+E\+K\+\_\+\+S\+ET, S\+E\+E\+K\+\_\+\+C\+UR or S\+E\+E\+K\+\_\+\+E\+ND \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the new file offset, or -\/1 on failure. 
\end{DoxyReturn}
\mbox{\label{group__seek__api_ga553fabfa03553669f79e37b28eb07ec6}} 
\index{Oggz Seek API@{Oggz Seek API}!oggz\_tell@{oggz\_tell}}
\index{oggz\_tell@{oggz\_tell}!Oggz Seek API@{Oggz Seek API}}
\doxysubsubsection{oggz\_tell()}
{\footnotesize\ttfamily \textbf{ oggz\+\_\+off\+\_\+t} oggz\+\_\+tell (\begin{DoxyParamCaption}\item[{\textbf{ O\+G\+GZ} $\ast$}]{oggz }\end{DoxyParamCaption})}



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


\begin{DoxyParams}{Parameters}
{\em oggz} & An O\+G\+GZ handle \\
\hline
\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 Oggz\+Read\+Packet 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}
\mbox{\label{group__seek__api_ga29181fb4e8f4e3629cb84810614acd30}} 
\index{Oggz Seek API@{Oggz Seek API}!oggz\_tell\_granulepos@{oggz\_tell\_granulepos}}
\index{oggz\_tell\_granulepos@{oggz\_tell\_granulepos}!Oggz Seek API@{Oggz Seek API}}
\doxysubsubsection{oggz\_tell\_granulepos()}
{\footnotesize\ttfamily ogg\+\_\+int64\+\_\+t oggz\+\_\+tell\+\_\+granulepos (\begin{DoxyParamCaption}\item[{\textbf{ O\+G\+GZ} $\ast$}]{oggz }\end{DoxyParamCaption})}



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}
{\em oggz} & An O\+G\+GZ handle \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the granulepos of the {\itshape current} packet (if available) 
\end{DoxyReturn}
\mbox{\label{group__seek__api_ga2ec088fc5541ce9749ce63ccc162761f}} 
\index{Oggz Seek API@{Oggz Seek API}!oggz\_tell\_units@{oggz\_tell\_units}}
\index{oggz\_tell\_units@{oggz\_tell\_units}!Oggz Seek API@{Oggz Seek API}}
\doxysubsubsection{oggz\_tell\_units()}
{\footnotesize\ttfamily ogg\+\_\+int64\+\_\+t oggz\+\_\+tell\+\_\+units (\begin{DoxyParamCaption}\item[{\textbf{ O\+G\+GZ} $\ast$}]{oggz }\end{DoxyParamCaption})}



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


\begin{DoxyParams}{Parameters}
{\em oggz} & An O\+G\+GZ handle \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the offset in milliseconds, or custom units 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+B\+A\+D\+\_\+\+O\+G\+GZ} & {\itshape oggz} does not refer to an existing O\+G\+GZ \\
\hline
{\em O\+G\+G\+Z\+\_\+\+E\+R\+R\+\_\+\+I\+N\+V\+A\+L\+ID} & Operation not suitable for this O\+G\+GZ \\
\hline
\end{DoxyRetVals}
