Main Page Modules Class Hierarchy Alphabetical List Compound List File List Compound Members File Members

# OggFLAC/stream_decoder.h: stream decoder interface
[OggFLAC/_decoder.h: decoder interfaces]

This module contains the functions which implement the stream decoder. More...

## Compounds
struct | OggFLAC__StreamDecoder
## Typedefs
typedef FLAC__StreamDecoderReadStatus(* | OggFLAC__StreamDecoderReadCallback )(const OggFLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data)
typedef FLAC__StreamDecoderWriteStatus(* | OggFLAC__StreamDecoderWriteCallback )(const OggFLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 *const buffer[], void *client_data)
typedef void(* | OggFLAC__StreamDecoderMetadataCallback )(const OggFLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data)
typedef void(* | OggFLAC__StreamDecoderErrorCallback )(const OggFLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data)
## Enumerations
enum | OggFLAC__StreamDecoderState { OggFLAC__STREAM_DECODER_OK = 0, OggFLAC__STREAM_DECODER_OGG_ERROR, OggFLAC__STREAM_DECODER_READ_ERROR, OggFLAC__STREAM_DECODER_FLAC_STREAM_DECODER_ERROR, OggFLAC__STREAM_DECODER_INVALID_CALLBACK, OggFLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR, OggFLAC__STREAM_DECODER_ALREADY_INITIALIZED, OggFLAC__STREAM_DECODER_UNINITIALIZED }
## Functions
OggFLAC__StreamDecoder * | OggFLAC__stream_decoder_new ()
void | OggFLAC__stream_decoder_delete (OggFLAC__StreamDecoder *decoder)
FLAC__bool | OggFLAC__stream_decoder_set_read_callback (OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderReadCallback value)
FLAC__bool | OggFLAC__stream_decoder_set_write_callback (OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderWriteCallback value)
FLAC__bool | OggFLAC__stream_decoder_set_metadata_callback (OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderMetadataCallback value)
FLAC__bool | OggFLAC__stream_decoder_set_error_callback (OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderErrorCallback value)
FLAC__bool | OggFLAC__stream_decoder_set_client_data (OggFLAC__StreamDecoder *decoder, void *value)
FLAC__bool | OggFLAC__stream_decoder_set_serial_number (OggFLAC__StreamDecoder *decoder, long serial_number)
FLAC__bool | OggFLAC__stream_decoder_set_metadata_respond (OggFLAC__StreamDecoder *decoder, FLAC__MetadataType type)
FLAC__bool | OggFLAC__stream_decoder_set_metadata_respond_application (OggFLAC__StreamDecoder *decoder, const FLAC__byte id[4])
FLAC__bool | OggFLAC__stream_decoder_set_metadata_respond_all (OggFLAC__StreamDecoder *decoder)
FLAC__bool | OggFLAC__stream_decoder_set_metadata_ignore (OggFLAC__StreamDecoder *decoder, FLAC__MetadataType type)
FLAC__bool | OggFLAC__stream_decoder_set_metadata_ignore_application (OggFLAC__StreamDecoder *decoder, const FLAC__byte id[4])
FLAC__bool | OggFLAC__stream_decoder_set_metadata_ignore_all (OggFLAC__StreamDecoder *decoder)
OggFLAC__StreamDecoderState | OggFLAC__stream_decoder_get_state (const OggFLAC__StreamDecoder *decoder)
FLAC__StreamDecoderState | OggFLAC__stream_decoder_get_FLAC_stream_decoder_state (const OggFLAC__StreamDecoder *decoder)
unsigned | OggFLAC__stream_decoder_get_channels (const OggFLAC__StreamDecoder *decoder)
FLAC__ChannelAssignment | OggFLAC__stream_decoder_get_channel_assignment (const OggFLAC__StreamDecoder *decoder)
unsigned | OggFLAC__stream_decoder_get_bits_per_sample (const OggFLAC__StreamDecoder *decoder)
unsigned | OggFLAC__stream_decoder_get_sample_rate (const OggFLAC__StreamDecoder *decoder)
unsigned | OggFLAC__stream_decoder_get_blocksize (const OggFLAC__StreamDecoder *decoder)
OggFLAC__StreamDecoderState | OggFLAC__stream_decoder_init (OggFLAC__StreamDecoder *decoder)
void | OggFLAC__stream_decoder_finish (OggFLAC__StreamDecoder *decoder)
FLAC__bool | OggFLAC__stream_decoder_flush (OggFLAC__StreamDecoder *decoder)
FLAC__bool | OggFLAC__stream_decoder_reset (OggFLAC__StreamDecoder *decoder)
FLAC__bool | OggFLAC__stream_decoder_process_single (OggFLAC__StreamDecoder *decoder)
FLAC__bool | OggFLAC__stream_decoder_process_until_end_of_metadata (OggFLAC__StreamDecoder *decoder)
FLAC__bool | OggFLAC__stream_decoder_process_until_end_of_stream (OggFLAC__StreamDecoder *decoder)
## Variables
const char *const | OggFLAC__StreamDecoderStateString []

## Detailed Description

This module contains the functions which implement the stream decoder.

The interface here is identical to FLAC's stream decoder, including the callbacks. See the FLAC stream decoder module for full documentation.

## Typedef Documentation

typedef FLAC__StreamDecoderReadStatus(* OggFLAC__StreamDecoderReadCallback)(const OggFLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data)

  | Signature for the read callback. See OggFLAC__stream_decoder_set_read_callback() and FLAC__StreamDecoderReadCallback for more info. Parameters:
  decoder | The decoder instance calling the callback.
  buffer | A pointer to a location for the callee to store data to be decoded.
  bytes | A pointer to the size of the buffer.
  client_data | The callee's client data set through OggFLAC__stream_decoder_set_client_data().
  Return values:
  FLAC__StreamDecoderReadStatus | The callee's return status.

typedef FLAC__StreamDecoderWriteStatus(* OggFLAC__StreamDecoderWriteCallback)(const OggFLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data)

  | Signature for the write callback. See OggFLAC__stream_decoder_set_write_callback() and FLAC__StreamDecoderWriteCallback for more info. Parameters:
  decoder | The decoder instance calling the callback.
  frame | The description of the decoded frame.
  buffer | An array of pointers to decoded channels of data.
  client_data | The callee's client data set through OggFLAC__stream_decoder_set_client_data().
  Return values:
  FLAC__StreamDecoderWriteStatus | The callee's return status.

typedef void(* OggFLAC__StreamDecoderMetadataCallback)(const OggFLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data)

  | Signature for the metadata callback. See OggFLAC__stream_decoder_set_metadata_callback() and FLAC__StreamDecoderMetadataCallback for more info. Parameters:
  decoder | The decoder instance calling the callback.
  metadata | The decoded metadata block.
  client_data | The callee's client data set through OggFLAC__stream_decoder_set_client_data().

typedef void(* OggFLAC__StreamDecoderErrorCallback)(const OggFLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data)

  | Signature for the error callback. See OggFLAC__stream_decoder_set_error_callback() and FLAC__StreamDecoderErrorCallback for more info. Parameters:
  decoder | The decoder instance calling the callback.
  status | The error encountered by the decoder.
  client_data | The callee's client data set through OggFLAC__stream_decoder_set_client_data().

## Enumeration Type Documentation

enum OggFLAC__StreamDecoderState

  | State values for an OggFLAC__StreamDecoder The decoder's state can be obtained by calling OggFLAC__stream_decoder_get_state(). Enumeration values:
  OggFLAC__STREAM_DECODER_OK | The decoder is in the normal OK state.
  OggFLAC__STREAM_DECODER_OGG_ERROR | An error occurred in the underlying Ogg layer.
  OggFLAC__STREAM_DECODER_READ_ERROR | The read callback returned an error.
  OggFLAC__STREAM_DECODER_FLAC_STREAM_DECODER_ERROR | An error occurred in the underlying FLAC stream decoder; check OggFLAC__stream_decoder_get_FLAC_stream_decoder_state().
  OggFLAC__STREAM_DECODER_INVALID_CALLBACK | The decoder was initialized before setting all the required callbacks.
  OggFLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR | Memory allocation failed.
  OggFLAC__STREAM_DECODER_ALREADY_INITIALIZED | OggFLAC__stream_decoder_init() was called when the decoder was already initialized, usually because OggFLAC__stream_decoder_finish() was not called.
  OggFLAC__STREAM_DECODER_UNINITIALIZED | The decoder is in the uninitialized state.

## Function Documentation

OggFLAC__StreamDecoder* OggFLAC__stream_decoder_new | ( |  | ) |

  | Create a new stream decoder instance. The instance is created with default settings; see the individual OggFLAC__stream_decoder_set_*() functions for each setting's default. Return values:
  OggFLAC__StreamDecoder | * `NULL` if there was an error allocating memory, else the new instance.

void OggFLAC__stream_decoder_delete | ( | OggFLAC__StreamDecoder * | decoder | ) |

  | Free a decoder instance. Deletes the object pointed to by decoder. Parameters:
  decoder | A pointer to an existing decoder.
  Assertions:
      decoder != NULL

FLAC__bool OggFLAC__stream_decoder_set_read_callback | ( | OggFLAC__StreamDecoder * | decoder,
|  | OggFLAC__StreamDecoderReadCallback | value
| ) |

  | Set the read callback. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_read_callback() Note: The callback is mandatory and must be set before initialization. Default Value: `NULL` Parameters:
  decoder | A decoder instance to set.
  value | See above.
  Assertions:
      decoder != NULL
      value != NULL
  Return values:
  FLAC__bool | `false` if the decoder is already initialized, else `true`.

FLAC__bool OggFLAC__stream_decoder_set_write_callback | ( | OggFLAC__StreamDecoder * | decoder,
|  | OggFLAC__StreamDecoderWriteCallback | value
| ) |

  | Set the write callback. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_write_callback() Note: The callback is mandatory and must be set before initialization. Default Value: `NULL` Parameters:
  decoder | A decoder instance to set.
  value | See above.
  Assertions:
      decoder != NULL
      value != NULL
  Return values:
  FLAC__bool | `false` if the decoder is already initialized, else `true`.

FLAC__bool OggFLAC__stream_decoder_set_metadata_callback | ( | OggFLAC__StreamDecoder * | decoder,
|  | OggFLAC__StreamDecoderMetadataCallback | value
| ) |

  | Set the metadata callback. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_callback() Note: The callback is mandatory and must be set before initialization. Default Value: `NULL` Parameters:
  decoder | A decoder instance to set.
  value | See above.
  Assertions:
      decoder != NULL
      value != NULL
  Return values:
  FLAC__bool | `false` if the decoder is already initialized, else `true`.

FLAC__bool OggFLAC__stream_decoder_set_error_callback | ( | OggFLAC__StreamDecoder * | decoder,
|  | OggFLAC__StreamDecoderErrorCallback | value
| ) |

  | Set the error callback. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_error_callback() Note: The callback is mandatory and must be set before initialization. Default Value: `NULL` Parameters:
  decoder | A decoder instance to set.
  value | See above.
  Assertions:
      decoder != NULL
      value != NULL
  Return values:
  FLAC__bool | `false` if the decoder is already initialized, else `true`.

FLAC__bool OggFLAC__stream_decoder_set_client_data | ( | OggFLAC__StreamDecoder * | decoder,
|  | void * | value
| ) |

  | Set the client data to be passed back to callbacks. This value will be supplied to callbacks in their client_data argument. Default Value: `NULL` Parameters:
  decoder | A decoder instance to set.
  value | See above.
  Assertions:
      decoder != NULL
  Return values:
  FLAC__bool | `false` if the decoder is already initialized, else `true`.

FLAC__bool OggFLAC__stream_decoder_set_serial_number | ( | OggFLAC__StreamDecoder * | decoder,
|  | long | serial_number
| ) |

  | Set the serial number for the Ogg stream. The default behavior is to use the serial number of the first Ogg page. Setting a serial number here will explicitly define which stream is to be decoded. Default Value: `use` serial number of first page Parameters:
  decoder | A decoder instance to set.
  serial_number | See above.
  Assertions:
      decoder != NULL
  Return values:
  FLAC__bool | `false` if the decoder is already initialized, else `true`.

FLAC__bool OggFLAC__stream_decoder_set_metadata_respond | ( | OggFLAC__StreamDecoder * | decoder,
|  | FLAC__MetadataType | type
| ) |

  | Direct the decoder to pass on all metadata blocks of type type. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_respond() Default Value: By default, only the `STREAMINFO` block is returned via the metadata callback. Parameters:
  decoder | A decoder instance to set.
  type | See above.
  Assertions:
      decoder != NULL
  type is valid Return values:
  FLAC__bool | `false` if the decoder is already initialized, else `true`.

FLAC__bool OggFLAC__stream_decoder_set_metadata_respond_application | ( | OggFLAC__StreamDecoder * | decoder,
|  | const FLAC__byte | id[4]
| ) |

  | Direct the decoder to pass on all APPLICATION metadata blocks of the given id. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_respond_application() Default Value: By default, only the `STREAMINFO` block is returned via the metadata callback. Parameters:
  decoder | A decoder instance to set.
  id | See above.
  Assertions:
      decoder != NULL
      id != NULL
  Return values:
  FLAC__bool | `false` if the decoder is already initialized, else `true`.

FLAC__bool OggFLAC__stream_decoder_set_metadata_respond_all | ( | OggFLAC__StreamDecoder * | decoder | ) |

  | Direct the decoder to pass on all metadata blocks of any type. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_respond_all() Default Value: By default, only the `STREAMINFO` block is returned via the metadata callback. Parameters:
  decoder | A decoder instance to set.
  Assertions:
      decoder != NULL
  Return values:
  FLAC__bool | `false` if the decoder is already initialized, else `true`.

FLAC__bool OggFLAC__stream_decoder_set_metadata_ignore | ( | OggFLAC__StreamDecoder * | decoder,
|  | FLAC__MetadataType | type
| ) |

  | Direct the decoder to filter out all metadata blocks of type type. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_ignore() Default Value: By default, only the `STREAMINFO` block is returned via the metadata callback. Parameters:
  decoder | A decoder instance to set.
  type | See above.
  Assertions:
      decoder != NULL
  type is valid Return values:
  FLAC__bool | `false` if the decoder is already initialized, else `true`.

FLAC__bool OggFLAC__stream_decoder_set_metadata_ignore_application | ( | OggFLAC__StreamDecoder * | decoder,
|  | const FLAC__byte | id[4]
| ) |

  | Direct the decoder to filter out all APPLICATION metadata blocks of the given id. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_ignore_application() Default Value: By default, only the `STREAMINFO` block is returned via the metadata callback. Parameters:
  decoder | A decoder instance to set.
  id | See above.
  Assertions:
      decoder != NULL
      id != NULL
  Return values:
  FLAC__bool | `false` if the decoder is already initialized, else `true`.

FLAC__bool OggFLAC__stream_decoder_set_metadata_ignore_all | ( | OggFLAC__StreamDecoder * | decoder | ) |

  | Direct the decoder to filter out all metadata blocks of any type. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_ignore_all() Default Value: By default, only the `STREAMINFO` block is returned via the metadata callback. Parameters:
  decoder | A decoder instance to set.
  Assertions:
      decoder != NULL
  Return values:
  FLAC__bool | `false` if the decoder is already initialized, else `true`.

OggFLAC__StreamDecoderState OggFLAC__stream_decoder_get_state | ( | const OggFLAC__StreamDecoder * | decoder | ) |

  | Get the current decoder state. Parameters:
  decoder | A decoder instance to query.
  Assertions:
      decoder != NULL
  Return values:
  OggFLAC__StreamDecoderState | The current decoder state.

FLAC__StreamDecoderState OggFLAC__stream_decoder_get_FLAC_stream_decoder_state | ( | const OggFLAC__StreamDecoder * | decoder | ) |

  | Get the state of the underlying FLAC stream decoder. Useful when the stream decoder state is `OggFLAC__STREAM_DECODER_FLAC_STREAM_DECODER_ERROR`. Parameters:
  decoder | A decoder instance to query.
  Assertions:
      decoder != NULL
  Return values:
  FLAC__StreamDecoderState | The FLAC stream decoder state.

unsigned OggFLAC__stream_decoder_get_channels | ( | const OggFLAC__StreamDecoder * | decoder | ) |

  | This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_channels() Parameters:
  decoder | A decoder instance to query.
  Assertions:
      decoder != NULL
  Return values:
  unsigned | See above.

FLAC__ChannelAssignment OggFLAC__stream_decoder_get_channel_assignment | ( | const OggFLAC__StreamDecoder * | decoder | ) |

  | This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_channel_assignment() Parameters:
  decoder | A decoder instance to query.
  Assertions:
      decoder != NULL
  Return values:
  OggFLAC__ChannelAssignment | See above.

unsigned OggFLAC__stream_decoder_get_bits_per_sample | ( | const OggFLAC__StreamDecoder * | decoder | ) |

  | This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_bits_per_sample() Parameters:
  decoder | A decoder instance to query.
  Assertions:
      decoder != NULL
  Return values:
  unsigned | See above.

unsigned OggFLAC__stream_decoder_get_sample_rate | ( | const OggFLAC__StreamDecoder * | decoder | ) |

  | This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_sample_rate() Parameters:
  decoder | A decoder instance to query.
  Assertions:
      decoder != NULL
  Return values:
  unsigned | See above.

unsigned OggFLAC__stream_decoder_get_blocksize | ( | const OggFLAC__StreamDecoder * | decoder | ) |

  | This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_blocksize() Parameters:
  decoder | A decoder instance to query.
  Assertions:
      decoder != NULL
  Return values:
  unsigned | See above.

OggFLAC__StreamDecoderState OggFLAC__stream_decoder_init | ( | OggFLAC__StreamDecoder * | decoder | ) |

  | Initialize the decoder instance. Should be called after OggFLAC__stream_decoder_new() and OggFLAC__stream_decoder_set_*() but before any of the OggFLAC__stream_decoder_process_*() functions. Will set and return the decoder state, which will be OggFLAC__STREAM_DECODER_OK if initialization succeeded. Parameters:
  decoder | An uninitialized decoder instance.
  Assertions:
      decoder != NULL
  Return values:
  OggFLAC__StreamDecoderState | `OggFLAC__STREAM_DECODER_OK` if initialization was successful; see OggFLAC__StreamDecoderState for the meanings of other return values.

void OggFLAC__stream_decoder_finish | ( | OggFLAC__StreamDecoder * | decoder | ) |

  | Finish the decoding process. Flushes the decoding buffer, releases resources, resets the decoder settings to their defaults, and returns the decoder state to OggFLAC__STREAM_DECODER_UNINITIALIZED. In the event of a prematurely-terminated decode, it is not strictly necessary to call this immediately before OggFLAC__stream_decoder_delete() but it is good practice to match every OggFLAC__stream_decoder_init() with an OggFLAC__stream_decoder_finish(). Parameters:
  decoder | An uninitialized decoder instance.
  Assertions:
      decoder != NULL

FLAC__bool OggFLAC__stream_decoder_flush | ( | OggFLAC__StreamDecoder * | decoder | ) |

  | This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_flush() Parameters:
  decoder | A decoder instance.
  Assertions:
      decoder != NULL
  Return values:
  FLAC__bool | `true` if successful, else `false` if a memory allocation error occurs.

FLAC__bool OggFLAC__stream_decoder_reset | ( | OggFLAC__StreamDecoder * | decoder | ) |

  | This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_reset() Parameters:
  decoder | A decoder instance.
  Assertions:
      decoder != NULL
  Return values:
  FLAC__bool | `true` if successful, else `false` if a memory allocation error occurs.

FLAC__bool OggFLAC__stream_decoder_process_single | ( | OggFLAC__StreamDecoder * | decoder | ) |

  | Decode one metadata block or audio frame. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_process_single() Parameters:
  decoder | An initialized decoder instance in the state `OggFLAC__STREAM_DECODER_OK`.
  Assertions:
      decoder != NULL
      OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_OK
  Return values:
  FLAC__bool | `false` if any read or write error occurred (except `FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC)`, else `true`; in any case, check the decoder state with OggFLAC__stream_decoder_get_state() to see what went wrong or to check for lost synchronization (a sign of stream corruption).

FLAC__bool OggFLAC__stream_decoder_process_until_end_of_metadata | ( | OggFLAC__StreamDecoder * | decoder | ) |

  | Decode until the end of the metadata. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_process_until_end_of_metadata() Parameters:
  decoder | An initialized decoder instance in the state `OggFLAC__STREAM_DECODER_OK`.
  Assertions:
      decoder != NULL
      OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_OK
  Return values:
  FLAC__bool | `false` if any read or write error occurred (except `OggFLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC)`, else `true`; in any case, check the decoder state with OggFLAC__stream_decoder_get_state() to see what went wrong or to check for lost synchronization (a sign of stream corruption).

FLAC__bool OggFLAC__stream_decoder_process_until_end_of_stream | ( | OggFLAC__StreamDecoder * | decoder | ) |

  | Decode until the end of the stream. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_process_until_end_of_stream() Parameters:
  decoder | An initialized decoder instance in the state `OggFLAC__STREAM_DECODER_OK`.
  Assertions:
      decoder != NULL
      OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_OK
  Return values:
  FLAC__bool | `false` if any read or write error occurred (except `OggFLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC)`, else `true`; in any case, check the decoder state with OggFLAC__stream_decoder_get_state() to see what went wrong or to check for lost synchronization (a sign of stream corruption).

## Variable Documentation

const char* const OggFLAC__StreamDecoderStateString[]

| Maps an OggFLAC__StreamDecoderState to a C string. Using an OggFLAC__StreamDecoderState as the index to this array will give the string equivalent. The contents should not be modified.