liboggz: Oggz Read API

liboggz 1.1.1

Typedefs | Functions
Oggz Read API

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

## Typedefs
typedef int(* | OggzReadPacket) (OGGZ *oggz, oggz_packet *packet, 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. More...
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. More...

## 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. More...
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. More...
long | oggz_read (OGGZ *oggz, long n)
| Read n bytes into oggz, calling any read callbacks on the fly. More...
long | oggz_read_input (OGGZ *oggz, unsigned char *buf, long n)
| Input data into oggz. More...

## 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).

When using an OGGZ* opened with the OGGZ_AUTO flag set, Oggz will internally calculate the granulepos for each packet, even though these are not all recorded in the file: only the last packet ending on a page will have its granulepos recorded in the page header. Within a OggzReadPacket callback, calling oggz_tell_granulepos() will retrieve the calculated granulepos.

See Oggz Seek API for information on seeking on interleaved Ogg data, and for working with calculated granulepos values.

## Typedef Documentation

## ◆ OggzReadPacket

typedef int(* OggzReadPacket) (OGGZ *oggz, oggz_packet *packet, 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
  packet | The packet, including its position in the stream.
  serialno | Identify the logical bistream in oggz that contains packet
  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.

## ◆ OggzReadPage

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

## ◆ oggz_read()

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_STOP_OK | Reading was stopped by a user callback returning OGGZ_STOP_OK
  OGGZ_ERR_STOP_ERR | Reading was stopped by a user callback returning OGGZ_STOP_ERR
  OGGZ_ERR_HOLE_IN_DATA | Hole (sequence number gap) detected in input data
  OGGZ_ERR_OUT_OF_MEMORY | Out of memory

## ◆ oggz_read_input()

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_STOP_OK | Reading was stopped by a user callback returning OGGZ_STOP_OK
  OGGZ_ERR_STOP_ERR | Reading was stopped by a user callback returning OGGZ_STOP_ERR
  OGGZ_ERR_HOLE_IN_DATA | Hole (sequence number gap) detected in input data
  OGGZ_ERR_OUT_OF_MEMORY | Out of memory

## ◆ oggz_set_read_callback()

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
  OGGZ_ERR_OUT_OF_MEMORY | Out of memory

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.

## ◆ oggz_set_read_page()

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
  OGGZ_ERR_OUT_OF_MEMORY | Out of memory

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.