Main Page | Modules | Data Structures | File List | Data Fields | Globals

oggz_seek.h File Reference


Detailed Description

Seeking within files.

Go to the source code of this file.

Typedefs

typedef ogg_int64_t(* OggzMetric )(OGGZ *oggz, long serialno, ogg_int64_t granulepos, void *user_data)
 This is the signature of a function to correlate Ogg streams.

Functions

ogg_int64_t oggz_tell_units (OGGZ *oggz)
 Query the current offset in milliseconds, or custom units as specified by a Metric function you have provided.
ogg_int64_t oggz_seek_units (OGGZ *oggz, ogg_int64_t units, int whence)
 Seek to an offset in milliseconds, or custom units as specified by a Metric function you have provided.
ogg_int64_t oggz_tell_granulepos (OGGZ *oggz)
 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.
oggz_off_t oggz_tell (OGGZ *oggz)
 Query the file offset in bytes corresponding to the data read.
oggz_off_t oggz_seek (OGGZ *oggz, oggz_off_t offset, int whence)
 Seek to a specific byte offset.
int oggz_get_preroll (OGGZ *oggz, long serialno)
 Retrieve the preroll of a logical bitstream.
int oggz_set_preroll (OGGZ *oggz, long serialno, int preroll)
 Specify the preroll of a logical bitstream.
int oggz_get_granuleshift (OGGZ *oggz, long serialno)
 Retrieve the granuleshift of a logical bitstream.
int oggz_set_granuleshift (OGGZ *oggz, long serialno, int granuleshift)
 Specify the granuleshift of a logical bitstream.
int oggz_get_granulerate (OGGZ *oggz, long serialno, ogg_int64_t *granulerate_n, ogg_int64_t *granulerate_d)
 Retrieve the granulerate of a logical bitstream.
int oggz_set_granulerate (OGGZ *oggz, long serialno, ogg_int64_t granule_rate_numerator, ogg_int64_t granule_rate_denominator)
 Specify the granulerate of a logical bitstream.
int oggz_set_metric (OGGZ *oggz, long serialno, OggzMetric metric, void *user_data)
 Set the OggzMetric to use for an OGGZ handle.
int oggz_set_data_start (OGGZ *oggz, oggz_off_t offset)
 Tell Oggz to remember the given offset as the start of data.
ogg_int64_t oggz_bounded_seek_set (OGGZ *oggz, ogg_int64_t unit_target, ogg_int64_t offset_begin, ogg_int64_t offset_end)
 Seeks Oggz to time unit_target, but with the bounds of the offset range [offset_begin, offset_end].


Typedef Documentation

typedef ogg_int64_t(* OggzMetric)(OGGZ *oggz, long serialno, ogg_int64_t granulepos, void *user_data)
 

This is the signature of a function to correlate Ogg streams.

If every position in an Ogg stream can be described by a metric (eg. time) then define this function that returns some arbitrary unit value. This is the normal use of Oggz for media streams. The meaning of units is arbitrary, but must be consistent across all logical bitstreams; for example a conversion of the time offset of a given packet into nanoseconds or a similar stream-specific subdivision may be appropriate.

Parameters:
oggz An OGGZ handle
serialno Identifies a logical bitstream within oggz
granulepos A granulepos within the logical bitstream identified by serialno
user_data Arbitrary data you wish to pass to your callback
Returns:
A conversion of the (serialno, granulepos) pair into a measure in units which is consistent across all logical bitstreams within oggz


Function Documentation

ogg_int64_t oggz_bounded_seek_set OGGZ oggz,
ogg_int64_t  unit_target,
ogg_int64_t  offset_begin,
ogg_int64_t  offset_end
 

Seeks Oggz to time unit_target, but with the bounds of the offset range [offset_begin, offset_end].

This is useful when seeking in network streams where only parts of a media are buffered, and retrieving unbuffered parts is expensive.

Parameters:
oggz An OGGZ handle previously opened for reading
unit_target The seek target, in milliseconds, or custom units
offset_begin Start of offset range to seek inside, in bytes
offset_end End of offset range to seek inside, in bytes, pass -1 for end of media
Returns:
The new position, in milliseconds or custom units
Return values:
-1 on failure (unit_target is not within range)

int oggz_get_granulerate OGGZ oggz,
long  serialno,
ogg_int64_t *  granulerate_n,
ogg_int64_t *  granulerate_d
 

Retrieve the granulerate of a logical bitstream.

Parameters:
oggz An OGGZ handle
serialno Identify the logical bitstream in oggz
granulerate_n Return location for the granulerate numerator
granulerate_d Return location for the granulerate denominator
Returns:
0 Success
Return values:
OGGZ_ERR_BAD_SERIALNO serialno does not identify an existing logical bitstream in oggz.
OGGZ_ERR_BAD_OGGZ oggz does not refer to an existing OGGZ

int oggz_get_granuleshift OGGZ oggz,
long  serialno
 

Retrieve the granuleshift of a logical bitstream.

Parameters:
oggz An OGGZ handle
serialno Identify the logical bitstream in oggz
Returns:
The granuleshift of the specified logical bitstream.
Return values:
OGGZ_ERR_BAD_SERIALNO serialno does not identify an existing logical bitstream in oggz.
OGGZ_ERR_BAD_OGGZ oggz does not refer to an existing OGGZ

int oggz_get_preroll OGGZ oggz,
long  serialno
 

Retrieve the preroll of a logical bitstream.

Parameters:
oggz An OGGZ handle
serialno Identify the logical bitstream in oggz
Returns:
The preroll of the specified logical bitstream.
Return values:
OGGZ_ERR_BAD_SERIALNO serialno does not identify an existing logical bitstream in oggz.
OGGZ_ERR_BAD_OGGZ oggz does not refer to an existing OGGZ

oggz_off_t oggz_seek OGGZ oggz,
oggz_off_t  offset,
int  whence
 

Seek to a specific byte offset.

Parameters:
oggz An OGGZ handle
offset a byte offset
whence As defined in <stdio.h>: SEEK_SET, SEEK_CUR or SEEK_END
Returns:
the new file offset, or -1 on failure.

ogg_int64_t oggz_seek_units OGGZ oggz,
ogg_int64_t  units,
int  whence
 

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

Parameters:
oggz An OGGZ handle
units A number of milliseconds, or custom units
whence As defined in <stdio.h>: SEEK_SET, SEEK_CUR or SEEK_END
Returns:
the new file offset, or -1 on failure.

int oggz_set_data_start OGGZ oggz,
oggz_off_t  offset
 

Tell Oggz to remember the given offset as the start of data.

This informs the seeking mechanism that when seeking back to unit 0, go to the given offset, not to the start of the file, which is usually codec headers. The usual usage is:

    oggz_set_data_start (oggz, oggz_tell (oggz));
Parameters:
oggz An OGGZ handle previously opened for reading
offset The offset of the start of data
Returns:
0 on success, -1 on failure.

int oggz_set_granulerate OGGZ oggz,
long  serialno,
ogg_int64_t  granule_rate_numerator,
ogg_int64_t  granule_rate_denominator
 

Specify the granulerate of a logical bitstream.

Parameters:
oggz An OGGZ handle
serialno Identify the logical bitstream in oggz to attach this linear metric to. A value of -1 indicates that the metric should be attached to all unattached logical bitstreams in oggz.
granule_rate_numerator The numerator of the granule rate
granule_rate_denominator The denominator of the granule rate
Returns:
0 Success
Return values:
OGGZ_ERR_BAD_SERIALNO serialno does not identify an existing logical bitstream in oggz.
OGGZ_ERR_BAD_OGGZ oggz does not refer to an existing OGGZ

int oggz_set_granuleshift OGGZ oggz,
long  serialno,
int  granuleshift
 

Specify the granuleshift of a logical bitstream.

Parameters:
oggz An OGGZ handle
serialno Identify the logical bitstream in oggz to attach this granuleshift metric to. A value of -1 indicates that the metric should be attached to all unattached logical bitstreams in oggz.
granuleshift The granuleshift
Returns:
0 Success
Return values:
OGGZ_ERR_BAD_SERIALNO serialno does not identify an existing logical bitstream in oggz.
OGGZ_ERR_BAD_OGGZ oggz does not refer to an existing OGGZ

int oggz_set_metric OGGZ oggz,
long  serialno,
OggzMetric  metric,
void *  user_data
 

Set the OggzMetric to use for an OGGZ handle.

Parameters:
oggz An OGGZ handle
serialno Identify the logical bitstream in oggz to attach this metric to. A value of -1 indicates that this metric should be attached to all unattached logical bitstreams in oggz.
metric An OggzMetric callback
user_data arbitrary data to pass to the metric callback
Returns:
0 Success
Return values:
OGGZ_ERR_BAD_SERIALNO serialno does not identify an existing logical bitstream in oggz, and is not -1
OGGZ_ERR_BAD_OGGZ oggz does not refer to an existing OGGZ
Note:
Specifying values of serialno other than -1 allows you to pass logical bitstream specific user_data to the same metric.

Alternatively, you may use a different metric for each serialno, but all metrics used must return mutually consistent unit measurements.

int oggz_set_preroll OGGZ oggz,
long  serialno,
int  preroll
 

Specify the preroll of a logical bitstream.

Parameters:
oggz An OGGZ handle
serialno Identify the logical bitstream in oggz to attach this preroll to.
preroll The preroll
Returns:
0 Success
Return values:
OGGZ_ERR_BAD_SERIALNO serialno does not identify an existing logical bitstream in oggz.
OGGZ_ERR_BAD_OGGZ oggz does not refer to an existing OGGZ

oggz_off_t oggz_tell OGGZ oggz  ) 
 

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

Parameters:
oggz An OGGZ handle
Returns:
The current offset of oggz.
Note:
When reading, the value returned by oggz_tell() 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.

ogg_int64_t oggz_tell_granulepos OGGZ oggz  ) 
 

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.

Parameters:
oggz An OGGZ handle
Returns:
the granulepos of the current packet (if available)

ogg_int64_t oggz_tell_units OGGZ oggz  ) 
 

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

Parameters:
oggz An OGGZ handle
Returns:
the offset in milliseconds, or custom units
Return values:
OGGZ_ERR_BAD_OGGZ oggz does not refer to an existing OGGZ
OGGZ_ERR_INVALID Operation not suitable for this OGGZ


Generated on Wed Nov 17 09:47:45 2010 for liboggz by  doxygen 1.3.9.1