Main Page | Modules | File List | Globals

oggz.h File Reference


Detailed Description

The liboggz C API.

Generic semantics

All access is managed via an OGGZ handle. This can be instantiated in one of three ways:

To finish using an OGGZ handle, it should be closed with oggz_close().

Reading Ogg data

To read from Ogg files or streams you must instantiate an OGGZ handle with flags set to OGGZ_READ, and provide an OggzReadPacket callback with oggz_set_read_callback(). See the OGGZ Read API section for details.

Writing Ogg data

To write to Ogg files or streams you must instantiate an OGGZ handle with flags set to OGGZ_WRITE, and provide an OggzWritePacket callback with oggz_set_write_callback(). See the OGGZ Write API section for details.

Seeking on Ogg data

To seek while reading Ogg files or streams you must instantiate an OGGZ handle for reading, and ensure that an OggzMetric function is defined to translate packet positions into units such as time. See the OGGZ Seek API section for details.

Overriding the IO methods

When an OGGZ handle is instantiated by oggz_open() or oggz_open_stdio(), Oggz uses stdio functions internally to access the raw data. However for some applications, the raw data cannot be accessed via stdio -- this commonly occurs when integrating with media frameworks. For such applications, you can provide Oggz with custom IO methods that it should use to access the raw data. Oggz will then use these custom methods, rather than using stdio methods, to access the raw data internally.

For details, see <oggz/oggz_io.h> .

Headers

oggz.h provides direct access to libogg types such as ogg_packet, defined in <ogg/ogg.h>.

#include <stdio.h>
#include <sys/types.h>
#include <ogg/ogg.h>
#include <oggz/oggz_constants.h>
#include <oggz/oggz_table.h>
#include <oggz/oggz_io.h>

Go to the source code of this file.

Typedefs

typedef void OGGZ
 An opaque handle to an Ogg file.

typedef int(* OggzReadPacket )(OGGZ *oggz, ogg_packet *op, long serialno, void *user_data)
 This is the signature of a callback which you must provide for Oggz to call whenever it finds a new packet in the Ogg stream associated with oggz.

typedef int(* OggzWriteHungry )(OGGZ *oggz, int empty, void *user_data)
 This is the signature of a callback which Oggz will call when oggz is hungry .

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

OGGZoggz_new (int flags)
 Create a new OGGZ object.

OGGZoggz_open (char *filename, int flags)
 Open an Ogg file, creating an OGGZ handle for it.

OGGZoggz_open_stdio (FILE *file, int flags)
 Create an OGGZ handle associated with a stdio stream.

int oggz_flush (OGGZ *oggz)
 Ensure any associated io streams are flushed.

int oggz_close (OGGZ *oggz)
 Close an OGGZ handle.

int oggz_get_bos (OGGZ *oggz, long serialno)
 Determine if a given logical bitstream is at bos (beginning of stream).

int oggz_get_eos (OGGZ *oggz, long serialno)
 Determine if a given logical bitstream is at eos (end of stream).

int oggz_set_read_callback (OGGZ *oggz, long serialno, OggzReadPacket read_packet, void *user_data)
 Set a callback for Oggz to call when a new Ogg packet is found in the stream.

long oggz_read (OGGZ *oggz, long n)
 Read n bytes into oggz, calling any read callbacks on the fly.

long oggz_read_input (OGGZ *oggz, unsigned char *buf, long n)
 Input data into oggz.

int oggz_write_set_hungry_callback (OGGZ *oggz, OggzWriteHungry hungry, int only_when_empty, void *user_data)
 Set a callback for Oggz to call when oggz is hungry .

int oggz_write_feed (OGGZ *oggz, ogg_packet *op, long serialno, int flush, int *guard)
 Add a packet to oggz's packet queue.

long oggz_write_output (OGGZ *oggz, unsigned char *buf, long n)
 Output data from an OGGZ handle.

long oggz_write (OGGZ *oggz, long n)
 Write n bytes from an OGGZ handle.

long oggz_write_get_next_page_size (OGGZ *oggz)
 Query the number of bytes in the next page to be written.

int oggz_set_metric_linear (OGGZ *oggz, long serialno, ogg_int64_t granule_rate_numerator, ogg_int64_t granule_rate_denominator)
 Specify that a logical bitstream has a linear metric.

int oggz_set_metric (OGGZ *oggz, long serialno, OggzMetric metric, void *user_data)
 Set the OggzMetric to use for an OGGZ handle.

ogg_int64_t oggz_tell_units (OGGZ *oggz)
 Query the current offset in units corresponding to the Metric function.

ogg_int64_t oggz_seek_units (OGGZ *oggz, ogg_int64_t units, int whence)
 Seek to a number of units corresponding to the Metric function.

int oggz_purge (OGGZ *oggz)
 Erase any input buffered in OGGZ.

int oggz_set_data_start (OGGZ *oggz, off_t offset)
 Tell OGGZ to remember the given offset as the start of data.

off_t oggz_tell (OGGZ *oggz)
 Provide the file offset in bytes corresponding to the data read.

off_t oggz_seek (OGGZ *oggz, off_t offset, int whence)
 Seek to a specific byte offset.

long oggz_serialno_new (OGGZ *oggz)
 Request a new serialno, as required for a new stream, ensuring the serialno is not yet used for any other streams managed by this OGGZ.


Typedef Documentation

typedef void OGGZ
 

An opaque handle to an Ogg file.

This is returned by oggz_open() or oggz_new(), and is passed to all other oggz_* functions.


Function Documentation

int oggz_close OGGZ oggz  ) 
 

Close an OGGZ handle.

Parameters:
oggz An OGGZ handle
Return values:
0 Success
OGGZ_ERR_BAD_OGGZ oggz does not refer to an existing OGGZ
OGGZ_ERR_SYSTEM System error; check errno for details

int oggz_flush OGGZ oggz  ) 
 

Ensure any associated io streams are flushed.

Parameters:
oggz An OGGZ handle
Return values:
0 Success
OGGZ_ERR_BAD_OGGZ oggz does not refer to an existing OGGZ
OGGZ_ERR_INVALID Operation not suitable for this OGGZ
OGGZ_ERR_SYSTEM System error; check errno for details

int oggz_get_bos OGGZ oggz,
long  serialno
 

Determine if a given logical bitstream is at bos (beginning of stream).

Parameters:
oggz An OGGZ handle
serialno Identify a logical bitstream within oggz, or -1 to query if all logical bitstreams in oggz are at bos
Return values:
1 The given stream is at bos
0 The given stream is not at bos
OGGZ_ERR_BAD_SERIALNO serialno does not identify an existing logical bitstream in oggz.

int oggz_get_eos OGGZ oggz,
long  serialno
 

Determine if a given logical bitstream is at eos (end of stream).

Parameters:
oggz An OGGZ handle
serialno Identify a logical bitstream within oggz, or -1 to query if all logical bitstreams in oggz are at eos
Return values:
1 The given stream is at eos
0 The given stream is not at eos
OGGZ_ERR_BAD_SERIALNO serialno does not identify an existing logical bitstream in oggz.

OGGZ* oggz_new int  flags  ) 
 

Create a new OGGZ object.

Parameters:
flags OGGZ_READ or OGGZ_WRITE
Returns:
A new OGGZ object
Return values:
NULL on system error; check errno for details

OGGZ* oggz_open char *  filename,
int  flags
 

Open an Ogg file, creating an OGGZ handle for it.

Parameters:
filename The file to open
flags OGGZ_READ or OGGZ_WRITE
Returns:
A new OGGZ handle
Return values:
NULL System error; check errno for details

OGGZ* oggz_open_stdio FILE *  file,
int  flags
 

Create an OGGZ handle associated with a stdio stream.

Parameters:
file An open FILE handle
flags OGGZ_READ or OGGZ_WRITE
Returns:
A new OGGZ handle
Return values:
NULL System error; check errno for details

long oggz_serialno_new OGGZ oggz  ) 
 

Request a new serialno, as required for a new stream, ensuring the serialno is not yet used for any other streams managed by this OGGZ.

Parameters:
oggz An OGGZ handle
Returns:
A new serialno, not already occuring in any logical bitstreams in oggz.


Generated on Fri May 21 16:55:00 2004 for liboggz by doxygen 1.3.5