Main Page | Modules | Directories | File List | Globals

OGGZ Read API


Detailed Description

OGGZ parses Ogg bitstreams, forming ogg_packet structures, and calling your OggzReadPacket callback(s).

You provide Ogg data to OGGZ with oggz_read() or oggz_read_input(), and independently process it in OggzReadPacket callbacks. It is possible to set a different callback per serialno (ie. for each logical bitstream in the Ogg bitstream - see the Ogg basics section for more detail).

See OGGZ Seek API for information on seeking on interleaved Ogg data.


Typedefs

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(* OggzReadPage )(OGGZ *oggz, const ogg_page *og, 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 page in the Ogg stream associated with oggz.

Functions

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.
int oggz_set_read_page (OGGZ *oggz, long serialno, OggzReadPage read_page, void *user_data)
 Set a callback for Oggz to call when a new Ogg page 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.


Typedef Documentation

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.

Parameters:
oggz The OGGZ handle
op The full ogg_packet (see <ogg/ogg.h>)
serialno Identify the logical bistream in oggz that contains op
user_data A generic pointer you have provided earlier
Returns:
0 to continue, non-zero to instruct OGGZ to stop.
Note:
It is possible to provide different callbacks per logical bitstream -- see oggz_set_read_callback() for more information.

typedef int(* OggzReadPage)(OGGZ *oggz, const ogg_page *og, 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 page in the Ogg stream associated with oggz.

Parameters:
oggz The OGGZ handle
op The full ogg_page (see <ogg/ogg.h>)
user_data A generic pointer you have provided earlier
Returns:
0 to continue, non-zero to instruct OGGZ to stop.


Function Documentation

long oggz_read OGGZ oggz,
long  n
 

Read n bytes into oggz, calling any read callbacks on the fly.

Parameters:
oggz An OGGZ handle previously opened for reading
n A count of bytes to ingest
Return values:
> 0 The number of bytes successfully ingested.
0 End of file
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
OGGZ_ERR_USER_STOPPED Reading was stopped by a user callback returning OGGZ_STOP_OK or OGGZ_STOP_ERR before any input bytes were consumed. This will occur when a packet is read from a previously buffered page of input data, and stopping is immediately requested.

long oggz_read_input OGGZ oggz,
unsigned char *  buf,
long  n
 

Input data into oggz.

Parameters:
oggz An OGGZ handle previously opened for reading
buf A memory buffer
n A count of bytes to input
Return values:
> 0 The number of bytes successfully ingested.
OGGZ_ERR_BAD_OGGZ oggz does not refer to an existing OGGZ
OGGZ_ERR_INVALID Operation not suitable for this OGGZ
OGGZ_ERR_USER_STOPPED Reading was stopped by a user callback returning OGGZ_STOP_OK or OGGZ_STOP_ERR before any input bytes were consumed. This will occur when a packet is read from a previously buffered page of input data, and stopping is immediately requested.

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.

Parameters:
oggz An OGGZ handle previously opened for reading
serialno Identify the logical bitstream in oggz to attach this callback to, or -1 to attach this callback to all unattached logical bitstreams in oggz.
read_packet Your callback function
user_data Arbitrary data you wish to pass to your callback
Return values:
0 Success
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_ERR_INVALID Operation not suitable for this OGGZ
Note:
Values of serialno other than -1 allows you to specify different callback functions for each logical bitstream.

It is safe to call this callback from within an OggzReadPacket function, in order to specify that subsequent packets should be handled by a different OggzReadPacket function.

int oggz_set_read_page OGGZ oggz,
long  serialno,
OggzReadPage  read_page,
void *  user_data
 

Set a callback for Oggz to call when a new Ogg page is found in the stream.

Parameters:
oggz An OGGZ handle previously opened for reading
serialno Identify the logical bitstream in oggz to attach this callback to, or -1 to attach this callback to all unattached logical bitstreams in oggz.
read_page Your OggzReadPage callback function
user_data Arbitrary data you wish to pass to your callback
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
Note:
Values of serialno other than -1 allows you to specify different callback functions for each logical bitstream.

It is safe to call this callback from within an OggzReadPage function, in order to specify that subsequent pages should be handled by a different OggzReadPage function.


Generated on Mon Feb 14 18:00:08 2005 for liboggz by  doxygen 1.4.0