liboggz: oggz.h File Reference

liboggz 1.1.3

Typedefs | Functions
oggz.h File Reference

The liboggz C API. More...

`#include <stdio.h>`
`#include <sys/types.h>`
`#include <ogg/ogg.h>`
`#include <oggz/oggz_constants.h>`
`#include <oggz/oggz_table.h>`
`#include <oggz/oggz_off_t.h>`
`#include <oggz/oggz_read.h>`
`#include <oggz/oggz_stream.h>`
`#include <oggz/oggz_seek.h>`
`#include <oggz/oggz_write.h>`
`#include <oggz/oggz_io.h>`
`#include <oggz/oggz_comments.h>`
`#include <oggz/oggz_deprecated.h>`

Go to the source code of this file.

## Typedefs
typedef void | OGGZ
| An opaque handle to an Ogg file.

## Functions
OGGZ * | oggz_new (int flags)
| Create a new OGGZ object.
OGGZ * | oggz_open (const char *filename, int flags)
| Open an Ogg file, creating an OGGZ handle for it.
OGGZ * | oggz_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.
long | oggz_run (OGGZ *oggz)
| Run an OGGZ until completion, or error.
int | oggz_run_set_blocksize (OGGZ *oggz, long blocksize)
| Set the blocksize to use internally for oggz_run()
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_get_numtracks (OGGZ *oggz)
| Query the number of tracks (logical bitstreams).
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.
const char * | oggz_content_type (OggzStreamContent content)
| Return human-readable string representation of a content type.

## 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:

- oggz_open() - Open a full pathname
- oggz_open_stdio() - Use an already opened FILE *
- oggz_new() - Create an anonymous OGGZ object, which you can later handle via memory buffers

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

## Typedef Documentation

## ◆ OGGZ

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

## ◆ oggz_close()

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

## ◆ oggz_content_type()

const char * oggz_content_type | ( | OggzStreamContent | content | ) |

Return human-readable string representation of a content type.

Return values

  string | the name of the content type
  NULL | content invalid

## ◆ oggz_flush()

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

## ◆ oggz_get_bos()

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.

## ◆ oggz_get_eos()

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_get_numtracks()

int oggz_get_numtracks | ( | OGGZ * | oggz | ) |

Query the number of tracks (logical bitstreams).

When reading, this number is incremented every time a new track is found, so the returned value is only correct once the OGGZ is no longer at bos (beginning of stream): see oggz_get_bos() for determining this.

Parameters

  oggz | An OGGZ handle

Returns
  The number of tracks in OGGZ

Return values

  OGGZ_ERR_BAD_SERIALNO | serialno does not identify an existing logical bitstream in oggz.

## ◆ oggz_new()

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_open()

OGGZ * oggz_open | ( | const 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_open_stdio()

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

## ◆ oggz_run()

long oggz_run | ( | OGGZ * | oggz | ) |

Run an OGGZ until completion, or error.

This is a convenience function which repeatedly calls oggz_read() or oggz_write() as appropriate. For an OGGZ opened for reading, an OggzReadPacket or OggzReadPage callback should have been set before calling this function. For an OGGZ opened for writing, either an OggzHungry callback should have been set before calling this function, or you can use this function to write out all unwritten Ogg pages which are pending.

Parameters

  oggz | An OGGZ handle previously opened for either reading or writing

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
  OGGZ_ERR_STOP_OK | Operation was stopped by a user callback returning OGGZ_STOP_OK
  OGGZ_ERR_STOP_ERR | Operation was stopped by a user callback returning OGGZ_STOP_ERR
  OGGZ_ERR_RECURSIVE_WRITE | Attempt to initiate writing from within an OggzHungry callback

## ◆ oggz_run_set_blocksize()

int oggz_run_set_blocksize | ( | OGGZ * | oggz,
|  | long | blocksize )

Set the blocksize to use internally for oggz_run()

Parameters

  oggz | An OGGZ handle previously opened for either reading or writing
  blocksize | The blocksize to use within oggz_run()

Return values

  0 | Success
  OGGZ_ERR_BAD_OGGZ | oggz does not refer to an existing OGGZ
  OGGZ_ERR_INVALID | Invalid blocksize (run_blocksize <= 0)

## ◆ oggz_serialno_new()

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.