FLAC/seekable_stream_decoder.h: seekable stream decoder interface

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

# FLAC/seekable_stream_decoder.h: seekable stream decoder interface
[FLAC/_decoder.h: decoder interfaces]

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

## Compounds

struct | FLAC__SeekableStreamDecoder

## Typedefs

typedef FLAC__SeekableStreamDecoderReadStatus(* | FLAC__SeekableStreamDecoderReadCallback )(const FLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data)
typedef FLAC__SeekableStreamDecoderSeekStatus(* | FLAC__SeekableStreamDecoderSeekCallback )(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data)
typedef FLAC__SeekableStreamDecoderTellStatus(* | FLAC__SeekableStreamDecoderTellCallback )(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data)
typedef FLAC__SeekableStreamDecoderLengthStatus(* | FLAC__SeekableStreamDecoderLengthCallback )(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data)
typedef FLAC__bool(* | FLAC__SeekableStreamDecoderEofCallback )(const FLAC__SeekableStreamDecoder *decoder, void *client_data)
typedef FLAC__StreamDecoderWriteStatus(* | FLAC__SeekableStreamDecoderWriteCallback )(const FLAC__SeekableStreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 *const buffer[], void *client_data)
typedef void(* | FLAC__SeekableStreamDecoderMetadataCallback )(const FLAC__SeekableStreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data)
typedef void(* | FLAC__SeekableStreamDecoderErrorCallback )(const FLAC__SeekableStreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data)

## Enumerations

enum

FLAC__SeekableStreamDecoderState {
FLAC__SEEKABLE_STREAM_DECODER_OK = 0, FLAC__SEEKABLE_STREAM_DECODER_SEEKING, FLAC__SEEKABLE_STREAM_DECODER_END_OF_STREAM, FLAC__SEEKABLE_STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR, FLAC__SEEKABLE_STREAM_DECODER_READ_ERROR, FLAC__SEEKABLE_STREAM_DECODER_SEEK_ERROR, FLAC__SEEKABLE_STREAM_DECODER_ALREADY_INITIALIZED,
FLAC__SEEKABLE_STREAM_DECODER_INVALID_CALLBACK, FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED
}

enum | FLAC__SeekableStreamDecoderReadStatus { FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_OK, FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_ERROR }
enum | FLAC__SeekableStreamDecoderSeekStatus { FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_OK, FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_ERROR }
enum | FLAC__SeekableStreamDecoderTellStatus { FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_OK, FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_ERROR }
enum | FLAC__SeekableStreamDecoderLengthStatus { FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_OK, FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_ERROR }

## Functions

FLAC__SeekableStreamDecoder * | FLAC__seekable_stream_decoder_new ()
void | FLAC__seekable_stream_decoder_delete (FLAC__SeekableStreamDecoder *decoder)
FLAC__bool | FLAC__seekable_stream_decoder_set_md5_checking (FLAC__SeekableStreamDecoder *decoder, FLAC__bool value)
FLAC__bool | FLAC__seekable_stream_decoder_set_read_callback (FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderReadCallback value)
FLAC__bool | FLAC__seekable_stream_decoder_set_seek_callback (FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderSeekCallback value)
FLAC__bool | FLAC__seekable_stream_decoder_set_tell_callback (FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderTellCallback value)
FLAC__bool | FLAC__seekable_stream_decoder_set_length_callback (FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderLengthCallback value)
FLAC__bool | FLAC__seekable_stream_decoder_set_eof_callback (FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderEofCallback value)
FLAC__bool | FLAC__seekable_stream_decoder_set_write_callback (FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderWriteCallback value)
FLAC__bool | FLAC__seekable_stream_decoder_set_metadata_callback (FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderMetadataCallback value)
FLAC__bool | FLAC__seekable_stream_decoder_set_error_callback (FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderErrorCallback value)
FLAC__bool | FLAC__seekable_stream_decoder_set_client_data (FLAC__SeekableStreamDecoder *decoder, void *value)
FLAC__bool | FLAC__seekable_stream_decoder_set_metadata_respond (FLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type)
FLAC__bool | FLAC__seekable_stream_decoder_set_metadata_respond_application (FLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4])
FLAC__bool | FLAC__seekable_stream_decoder_set_metadata_respond_all (FLAC__SeekableStreamDecoder *decoder)
FLAC__bool | FLAC__seekable_stream_decoder_set_metadata_ignore (FLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type)
FLAC__bool | FLAC__seekable_stream_decoder_set_metadata_ignore_application (FLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4])
FLAC__bool | FLAC__seekable_stream_decoder_set_metadata_ignore_all (FLAC__SeekableStreamDecoder *decoder)
FLAC__SeekableStreamDecoderState | FLAC__seekable_stream_decoder_get_state (const FLAC__SeekableStreamDecoder *decoder)
FLAC__StreamDecoderState | FLAC__seekable_stream_decoder_get_stream_decoder_state (const FLAC__SeekableStreamDecoder *decoder)
const char * | FLAC__seekable_stream_decoder_get_resolved_state_string (const FLAC__SeekableStreamDecoder *decoder)
FLAC__bool | FLAC__seekable_stream_decoder_get_md5_checking (const FLAC__SeekableStreamDecoder *decoder)
unsigned | FLAC__seekable_stream_decoder_get_channels (const FLAC__SeekableStreamDecoder *decoder)
FLAC__ChannelAssignment | FLAC__seekable_stream_decoder_get_channel_assignment (const FLAC__SeekableStreamDecoder *decoder)
unsigned | FLAC__seekable_stream_decoder_get_bits_per_sample (const FLAC__SeekableStreamDecoder *decoder)
unsigned | FLAC__seekable_stream_decoder_get_sample_rate (const FLAC__SeekableStreamDecoder *decoder)
unsigned | FLAC__seekable_stream_decoder_get_blocksize (const FLAC__SeekableStreamDecoder *decoder)
FLAC__bool | FLAC__seekable_stream_decoder_get_decode_position (const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *position)
FLAC__SeekableStreamDecoderState | FLAC__seekable_stream_decoder_init (FLAC__SeekableStreamDecoder *decoder)
FLAC__bool | FLAC__seekable_stream_decoder_finish (FLAC__SeekableStreamDecoder *decoder)
FLAC__bool | FLAC__seekable_stream_decoder_flush (FLAC__SeekableStreamDecoder *decoder)
FLAC__bool | FLAC__seekable_stream_decoder_reset (FLAC__SeekableStreamDecoder *decoder)
FLAC__bool | FLAC__seekable_stream_decoder_process_single (FLAC__SeekableStreamDecoder *decoder)
FLAC__bool | FLAC__seekable_stream_decoder_process_until_end_of_metadata (FLAC__SeekableStreamDecoder *decoder)
FLAC__bool | FLAC__seekable_stream_decoder_process_until_end_of_stream (FLAC__SeekableStreamDecoder *decoder)
FLAC__bool | FLAC__seekable_stream_decoder_skip_single_frame (FLAC__SeekableStreamDecoder *decoder)
FLAC__bool | FLAC__seekable_stream_decoder_seek_absolute (FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 sample)

## Variables

const char *const | FLAC__SeekableStreamDecoderStateString []
const char *const | FLAC__SeekableStreamDecoderReadStatusString []
const char *const | FLAC__SeekableStreamDecoderSeekStatusString []
const char *const | FLAC__SeekableStreamDecoderTellStatusString []
const char *const | FLAC__SeekableStreamDecoderLengthStatusString []

## Detailed Description

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

The basic usage of this decoder is as follows:

- The program creates an instance of a decoder using FLAC__seekable_stream_decoder_new().
- The program overrides the default settings and sets callbacks for reading, writing, seeking, error reporting, and metadata reporting using FLAC__seekable_stream_decoder_set_*() functions.
- The program initializes the instance to validate the settings and prepare for decoding using FLAC__seekable_stream_decoder_init().
- The program calls the FLAC__seekable_stream_decoder_process_*() functions to decode data, which subsequently calls the callbacks.
- The program finishes the decoding with FLAC__seekable_stream_decoder_finish(), which flushes the input and output and resets the decoder to the uninitialized state.
- The instance may be used again or deleted with FLAC__seekable_stream_decoder_delete().

The seekable stream decoder is a wrapper around the stream decoder which also provides seeking capability. In addition to the Read/Write/Metadata/Error callbacks of the stream decoder, the user must also provide the following:

- Seek callback - This function will be called when the decoder wants to seek to an absolute position in the stream.
- Tell callback - This function will be called when the decoder wants to know the current absolute position of the stream.
- Length callback - This function will be called when the decoder wants to know length of the stream. The seeking algorithm currently requires that the overall stream length be known.
- EOF callback - This function will be called when the decoder wants to know if it is at the end of the stream. This could be synthesized from the tell and length callbacks but it may be more expensive that way, so there is a separate callback for it.

Seeking is exposed through the FLAC__seekable_stream_decoder_seek_absolute() method. At any point after the seekable stream decoder has been initialized, the user can call this function to seek to an exact sample within the stream. Subsequently, the first time the write callback is called it will be passed a (possibly partial) block starting at that sample.

The seekable stream decoder also provides MD5 signature checking. If this is turned on before initialization, FLAC__seekable_stream_decoder_finish() will report when the decoded MD5 signature does not match the one stored in the STREAMINFO block. MD5 checking is automatically turned off (until the next FLAC__seekable_stream_decoder_reset()) if there is no signature in the STREAMINFO block or when a seek is attempted.

Make sure to read the detailed description of the stream decoder module since the seekable stream decoder inherits much of its behavior.

Note:
  The "set" functions may only be called when the decoder is in the state FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED, i.e. after FLAC__seekable_stream_decoder_new() or FLAC__seekable_stream_decoder_finish(), but before FLAC__seekable_stream_decoder_init(). If this is the case they will return `true`, otherwise `false`.

Note:
  FLAC__stream_decoder_finish() resets all settings to the constructor defaults, including the callbacks.

## Typedef Documentation

typedef FLAC__SeekableStreamDecoderReadStatus(* FLAC__SeekableStreamDecoderReadCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data)

Signature for the read callback. See FLAC__seekable_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 FLAC__seekable_stream_decoder_set_client_data().

Return values:

  FLAC__SeekableStreamDecoderReadStatus | The callee's return status.

typedef FLAC__SeekableStreamDecoderSeekStatus(* FLAC__SeekableStreamDecoderSeekCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data)

Signature for the seek callback. See FLAC__seekable_stream_decoder_set_seek_callback() for more info.

Parameters:

  decoder | The decoder instance calling the callback.
  absolute_byte_offset | The offset from the beginning of the stream to seek to.
  client_data | The callee's client data set through FLAC__seekable_stream_decoder_set_client_data().

Return values:

  FLAC__SeekableStreamDecoderSeekStatus | The callee's return status.

typedef FLAC__SeekableStreamDecoderTellStatus(* FLAC__SeekableStreamDecoderTellCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data)

Signature for the tell callback. See FLAC__seekable_stream_decoder_set_tell_callback() for more info.

Parameters:

  decoder | The decoder instance calling the callback.
  absolute_byte_offset | A pointer to storage for the current offset from the beginning of the stream.
  client_data | The callee's client data set through FLAC__seekable_stream_decoder_set_client_data().

Return values:

  FLAC__SeekableStreamDecoderTellStatus | The callee's return status.

typedef FLAC__SeekableStreamDecoderLengthStatus(* FLAC__SeekableStreamDecoderLengthCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data)

Signature for the length callback. See FLAC__seekable_stream_decoder_set_length_callback() for more info.

Parameters:

  decoder | The decoder instance calling the callback.
  stream_length | A pointer to storage for the length of the stream in bytes.
  client_data | The callee's client data set through FLAC__seekable_stream_decoder_set_client_data().

Return values:

  FLAC__SeekableStreamDecoderLengthStatus | The callee's return status.

typedef FLAC__bool(* FLAC__SeekableStreamDecoderEofCallback)(const FLAC__SeekableStreamDecoder *decoder, void *client_data)

Signature for the EOF callback. See FLAC__seekable_stream_decoder_set_eof_callback() for more info.

Parameters:

  decoder | The decoder instance calling the callback.
  client_data | The callee's client data set through FLAC__seekable_stream_decoder_set_client_data().

Return values:

  FLAC__bool | `true` if the currently at the end of the stream, else `false`.

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

Signature for the write callback. See FLAC__seekable_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 FLAC__seekable_stream_decoder_set_client_data().

Return values:

  FLAC__StreamDecoderWriteStatus | The callee's return status.

typedef void(* FLAC__SeekableStreamDecoderMetadataCallback)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data)

Signature for the metadata callback. See FLAC__seekable_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 FLAC__seekable_stream_decoder_set_client_data().

typedef void(* FLAC__SeekableStreamDecoderErrorCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data)

Signature for the error callback. See FLAC__seekable_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 FLAC__seekable_stream_decoder_set_client_data().

## Enumeration Type Documentation

enum FLAC__SeekableStreamDecoderState

State values for a FLAC__SeekableStreamDecoder

The decoder's state can be obtained by calling FLAC__seekable_stream_decoder_get_state().

Enumeration values:

  FLAC__SEEKABLE_STREAM_DECODER_OK | The decoder is in the normal OK state.
  FLAC__SEEKABLE_STREAM_DECODER_SEEKING | The decoder is in the process of seeking.
  FLAC__SEEKABLE_STREAM_DECODER_END_OF_STREAM | The decoder has reached the end of the stream.
  FLAC__SEEKABLE_STREAM_DECODER_MEMORY_ALLOCATION_ERROR | An error occurred allocating memory.
  FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR | An error occurred in the underlying stream decoder.
  FLAC__SEEKABLE_STREAM_DECODER_READ_ERROR | The read callback returned an error.
  FLAC__SEEKABLE_STREAM_DECODER_SEEK_ERROR | An error occurred while seeking or the seek or tell callback returned an error.
  FLAC__SEEKABLE_STREAM_DECODER_ALREADY_INITIALIZED | FLAC__seekable_stream_decoder_init() was called when the decoder was already initialized, usually because FLAC__seekable_stream_decoder_finish() was not called.
  FLAC__SEEKABLE_STREAM_DECODER_INVALID_CALLBACK | FLAC__seekable_stream_decoder_init() was called without all callbacks being set.
  FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED | The decoder is in the uninitialized state.

enum FLAC__SeekableStreamDecoderReadStatus

Return values for the FLAC__SeekableStreamDecoder read callback.

Enumeration values:

  FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_OK | The read was OK and decoding can continue.
  FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_ERROR | An unrecoverable error occurred. The decoder will return from the process call.

enum FLAC__SeekableStreamDecoderSeekStatus

Return values for the FLAC__SeekableStreamDecoder seek callback.

Enumeration values:

  FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_OK | The seek was OK and decoding can continue.
  FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_ERROR | An unrecoverable error occurred. The decoder will return from the process call.

enum FLAC__SeekableStreamDecoderTellStatus

Return values for the FLAC__SeekableStreamDecoder tell callback.

Enumeration values:

  FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_OK | The tell was OK and decoding can continue.
  FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_ERROR | An unrecoverable error occurred. The decoder will return from the process call.

enum FLAC__SeekableStreamDecoderLengthStatus

Return values for the FLAC__SeekableStreamDecoder length callback.

Enumeration values:

  FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_OK | The length call was OK and decoding can continue.
  FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_ERROR | An unrecoverable error occurred. The decoder will return from the process call.

## Function Documentation

FLAC__SeekableStreamDecoder* FLAC__seekable_stream_decoder_new | ( |  | ) |

Create a new seekable stream decoder instance. The instance is created with default settings; see the individual FLAC__seekable_stream_decoder_set_*() functions for each setting's default.

Return values:

  FLAC__SeekableStreamDecoder | * `NULL` if there was an error allocating memory, else the new instance.

void FLAC__seekable_stream_decoder_delete | ( | FLAC__SeekableStreamDecoder * | 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 FLAC__seekable_stream_decoder_set_md5_checking | ( | FLAC__SeekableStreamDecoder * | decoder,
|  | FLAC__bool | value
| ) |

Set the "MD5 signature checking" flag. If `true`, the decoder will compute the MD5 signature of the unencoded audio data while decoding and compare it to the signature from the STREAMINFO block, if it exists, during FLAC__seekable_stream_decoder_finish().

MD5 signature checking will be turned off (until the next FLAC__seekable_stream_decoder_reset()) if there is no signature in the STREAMINFO block or when a seek is attempted.

Default Value:
  `false`

Parameters:

  decoder | A decoder instance to set.
  value | Flag value (see above).

Assertions:

      decoder != NULL

Return values:

  FLAC__bool | `false` if the decoder is already initialized, else `true`.

FLAC__bool FLAC__seekable_stream_decoder_set_read_callback | ( | FLAC__SeekableStreamDecoder * | decoder,
|  | FLAC__SeekableStreamDecoderReadCallback | 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 FLAC__seekable_stream_decoder_set_seek_callback | ( | FLAC__SeekableStreamDecoder * | decoder,
|  | FLAC__SeekableStreamDecoderSeekCallback | value
| ) |

Set the seek callback. The supplied function will be called when the decoder needs to seek the input stream. The decoder will pass the absolute byte offset to seek to, 0 meaning the beginning of the stream.

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 FLAC__seekable_stream_decoder_set_tell_callback | ( | FLAC__SeekableStreamDecoder * | decoder,
|  | FLAC__SeekableStreamDecoderTellCallback | value
| ) |

Set the tell callback. The supplied function will be called when the decoder wants to know the current position of the stream. The callback should return the byte offset from the beginning of the stream.

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 FLAC__seekable_stream_decoder_set_length_callback | ( | FLAC__SeekableStreamDecoder * | decoder,
|  | FLAC__SeekableStreamDecoderLengthCallback | value
| ) |

Set the length callback. The supplied function will be called when the decoder wants to know the total length of the stream in bytes.

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 FLAC__seekable_stream_decoder_set_eof_callback | ( | FLAC__SeekableStreamDecoder * | decoder,
|  | FLAC__SeekableStreamDecoderEofCallback | value
| ) |

Set the eof callback. The supplied function will be called when the decoder needs to know if the end of the stream has been reached.

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 FLAC__seekable_stream_decoder_set_write_callback | ( | FLAC__SeekableStreamDecoder * | decoder,
|  | FLAC__SeekableStreamDecoderWriteCallback | 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 FLAC__seekable_stream_decoder_set_metadata_callback | ( | FLAC__SeekableStreamDecoder * | decoder,
|  | FLAC__SeekableStreamDecoderMetadataCallback | 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 FLAC__seekable_stream_decoder_set_error_callback | ( | FLAC__SeekableStreamDecoder * | decoder,
|  | FLAC__SeekableStreamDecoderErrorCallback | 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 FLAC__seekable_stream_decoder_set_client_data | ( | FLAC__SeekableStreamDecoder * | 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 FLAC__seekable_stream_decoder_set_metadata_respond | ( | FLAC__SeekableStreamDecoder * | decoder,
|  | FLAC__MetadataType | 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 FLAC__seekable_stream_decoder_set_metadata_respond_application | ( | FLAC__SeekableStreamDecoder * | decoder,
|  | const FLAC__byte | id[4]
| ) |

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 FLAC__seekable_stream_decoder_set_metadata_respond_all | ( | FLAC__SeekableStreamDecoder * | decoder | ) |

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 FLAC__seekable_stream_decoder_set_metadata_ignore | ( | FLAC__SeekableStreamDecoder * | decoder,
|  | FLAC__MetadataType | 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 FLAC__seekable_stream_decoder_set_metadata_ignore_application | ( | FLAC__SeekableStreamDecoder * | decoder,
|  | const FLAC__byte | id[4]
| ) |

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 FLAC__seekable_stream_decoder_set_metadata_ignore_all | ( | FLAC__SeekableStreamDecoder * | decoder | ) |

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

FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_get_state | ( | const FLAC__SeekableStreamDecoder * | decoder | ) |

Get the current decoder state.

Parameters:

  decoder | A decoder instance to query.

Assertions:

      decoder != NULL

Return values:

  FLAC__SeekableStreamDecoderState | The current decoder state.

FLAC__StreamDecoderState FLAC__seekable_stream_decoder_get_stream_decoder_state | ( | const FLAC__SeekableStreamDecoder * | decoder | ) |

Get the state of the underlying stream decoder. Useful when the seekable stream decoder state is `FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR`.

Parameters:

  decoder | A decoder instance to query.

Assertions:

      decoder != NULL

Return values:

  FLAC__StreamDecoderState | The stream decoder state.

const char* FLAC__seekable_stream_decoder_get_resolved_state_string | ( | const FLAC__SeekableStreamDecoder * | decoder | ) |

Get the current decoder state as a C string. This version automatically resolves `FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR` by getting the stream decoder's state.

Parameters:

  decoder | A decoder instance to query.

Assertions:

      decoder != NULL

Return values:

  const | char * The decoder state as a C string. Do not modify the contents.

FLAC__bool FLAC__seekable_stream_decoder_get_md5_checking | ( | const FLAC__SeekableStreamDecoder * | decoder | ) |

Get the "MD5 signature checking" flag. This is the value of the setting, not whether or not the decoder is currently checking the MD5 (remember, it can be turned off automatically by a seek). When the decoder is reset the flag will be restored to the value returned by this function.

Parameters:

  decoder | A decoder instance to query.

Assertions:

      decoder != NULL

Return values:

  FLAC__bool | See above.

unsigned FLAC__seekable_stream_decoder_get_channels | ( | const FLAC__SeekableStreamDecoder * | 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 FLAC__seekable_stream_decoder_get_channel_assignment | ( | const FLAC__SeekableStreamDecoder * | 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:

  FLAC__ChannelAssignment | See above.

unsigned FLAC__seekable_stream_decoder_get_bits_per_sample | ( | const FLAC__SeekableStreamDecoder * | 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 FLAC__seekable_stream_decoder_get_sample_rate | ( | const FLAC__SeekableStreamDecoder * | 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 FLAC__seekable_stream_decoder_get_blocksize | ( | const FLAC__SeekableStreamDecoder * | 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.

FLAC__bool FLAC__seekable_stream_decoder_get_decode_position | ( | const FLAC__SeekableStreamDecoder * | decoder,
|  | FLAC__uint64 * | position
| ) |

Returns the decoder's current read position within the stream. The position is the byte offset from the start of the stream. Bytes before this position have been fully decoded. Note that there may still be undecoded bytes in the decoder's read FIFO. The returned position is correct even after a seek.

Parameters:

  decoder | A decoder instance to query.
  position | Address at which to return the desired position.

Assertions:

      decoder != NULL

      position != NULL

Return values:

  FLAC__bool | `true` if successful, `false` if there was an error from the 'tell' callback.

FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_init | ( | FLAC__SeekableStreamDecoder * | decoder | ) |

Initialize the decoder instance. Should be called after FLAC__seekable_stream_decoder_new() and FLAC__seekable_stream_decoder_set_*() but before any of the FLAC__seekable_stream_decoder_process_*() functions. Will set and return the decoder state, which will be FLAC__SEEKABLE_STREAM_DECODER_OK if initialization succeeded.

Parameters:

  decoder | An uninitialized decoder instance.

Assertions:

      decoder != NULL

Return values:

  FLAC__SeekableStreamDecoderState | `FLAC__SEEKABLE_STREAM_DECODER_OK` if initialization was successful; see FLAC__SeekableStreamDecoderState for the meanings of other return values.

FLAC__bool FLAC__seekable_stream_decoder_finish | ( | FLAC__SeekableStreamDecoder * | decoder | ) |

Finish the decoding process. Flushes the decoding buffer, releases resources, resets the decoder settings to their defaults, and returns the decoder state to FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED.

In the event of a prematurely-terminated decode, it is not strictly necessary to call this immediately before FLAC__seekable_stream_decoder_delete() but it is good practice to match every FLAC__seekable_stream_decoder_init() with a FLAC__seekable_stream_decoder_finish().

Parameters:

  decoder | An uninitialized decoder instance.

Assertions:

      decoder != NULL

Return values:

  FLAC__bool | `false` if MD5 checking is on AND a STREAMINFO block was available AND the MD5 signature in the STREAMINFO block was non-zero AND the signature does not match the one computed by the decoder; else `true`.

FLAC__bool FLAC__seekable_stream_decoder_flush | ( | FLAC__SeekableStreamDecoder * | decoder | ) |

Flush the stream input. The decoder's input buffer will be cleared and the state set to `FLAC__SEEKABLE_STREAM_DECODER_OK`. This will also turn off MD5 checking.

Parameters:

  decoder | A decoder instance.

Assertions:

      decoder != NULL

Return values:

  FLAC__bool | `true` if successful, else `false` if a memory allocation or stream decoder error occurs.

FLAC__bool FLAC__seekable_stream_decoder_reset | ( | FLAC__SeekableStreamDecoder * | decoder | ) |

Reset the decoding process. The decoder's input buffer will be cleared and the state set to `FLAC__SEEKABLE_STREAM_DECODER_OK`. This is similar to FLAC__seekable_stream_decoder_finish() except that the settings are preserved; there is no need to call FLAC__seekable_stream_decoder_init() before decoding again. MD5 checking will be restored to its original setting.

Parameters:

  decoder | A decoder instance.

Assertions:

      decoder != NULL

Return values:

  FLAC__bool | `true` if successful, else `false` if a memory allocation or stream decoder error occurs.

FLAC__bool FLAC__seekable_stream_decoder_process_single | ( | FLAC__SeekableStreamDecoder * | decoder | ) |

This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_process_single().

Parameters:

  decoder | A decoder instance.

Assertions:

      decoder != NULL

Return values:

  FLAC__bool | See above.

FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_metadata | ( | FLAC__SeekableStreamDecoder * | decoder | ) |

This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_process_until_end_of_metadata().

Parameters:

  decoder | A decoder instance.

Assertions:

      decoder != NULL

Return values:

  FLAC__bool | See above.

FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_stream | ( | FLAC__SeekableStreamDecoder * | decoder | ) |

This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_process_until_end_of_stream().

Parameters:

  decoder | A decoder instance.

Assertions:

      decoder != NULL

Return values:

  FLAC__bool | See above.

FLAC__bool FLAC__seekable_stream_decoder_skip_single_frame | ( | FLAC__SeekableStreamDecoder * | decoder | ) |

This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_skip_single_frame().

Parameters:

  decoder | A decoder instance.

Assertions:

      decoder != NULL

Return values:

  FLAC__bool | See above.

FLAC__bool FLAC__seekable_stream_decoder_seek_absolute | ( | FLAC__SeekableStreamDecoder * | decoder,
|  | FLAC__uint64 | sample
| ) |

Flush the input and seek to an absolute sample. Decoding will resume at the given sample. Note that because of this, the next write callback may contain a partial block.

Parameters:

  decoder | A decoder instance.
  sample | The target sample number to seek to.

Assertions:

      decoder != NULL

Return values:

  FLAC__bool | `true` if successful, else `false`.

## Variable Documentation

const char* const FLAC__SeekableStreamDecoderStateString[]

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

const char* const FLAC__SeekableStreamDecoderReadStatusString[]

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

const char* const FLAC__SeekableStreamDecoderSeekStatusString[]

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

const char* const FLAC__SeekableStreamDecoderTellStatusString[]

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

const char* const FLAC__SeekableStreamDecoderLengthStatusString[]

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