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

# FLAC/file_decoder.h: file decoder interface
[FLAC/_decoder.h: decoder interfaces]

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

## Compounds
struct | FLAC__FileDecoder
## Typedefs
typedef FLAC__StreamDecoderWriteStatus(* | FLAC__FileDecoderWriteCallback )(const FLAC__FileDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 *const buffer[], void *client_data)
typedef void(* | FLAC__FileDecoderMetadataCallback )(const FLAC__FileDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data)
typedef void(* | FLAC__FileDecoderErrorCallback )(const FLAC__FileDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data)
## Enumerations
enum | FLAC__FileDecoderState { FLAC__FILE_DECODER_OK = 0, FLAC__FILE_DECODER_END_OF_FILE, FLAC__FILE_DECODER_ERROR_OPENING_FILE, FLAC__FILE_DECODER_MEMORY_ALLOCATION_ERROR, FLAC__FILE_DECODER_SEEK_ERROR, FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR, FLAC__FILE_DECODER_ALREADY_INITIALIZED, FLAC__FILE_DECODER_INVALID_CALLBACK, FLAC__FILE_DECODER_UNINITIALIZED }
## Functions
FLAC__FileDecoder * | FLAC__file_decoder_new ()
void | FLAC__file_decoder_delete (FLAC__FileDecoder *decoder)
FLAC__bool | FLAC__file_decoder_set_md5_checking (FLAC__FileDecoder *decoder, FLAC__bool value)
FLAC__bool | FLAC__file_decoder_set_filename (FLAC__FileDecoder *decoder, const char *value)
FLAC__bool | FLAC__file_decoder_set_write_callback (FLAC__FileDecoder *decoder, FLAC__FileDecoderWriteCallback value)
FLAC__bool | FLAC__file_decoder_set_metadata_callback (FLAC__FileDecoder *decoder, FLAC__FileDecoderMetadataCallback value)
FLAC__bool | FLAC__file_decoder_set_error_callback (FLAC__FileDecoder *decoder, FLAC__FileDecoderErrorCallback value)
FLAC__bool | FLAC__file_decoder_set_client_data (FLAC__FileDecoder *decoder, void *value)
FLAC__bool | FLAC__file_decoder_set_metadata_respond (FLAC__FileDecoder *decoder, FLAC__MetadataType type)
FLAC__bool | FLAC__file_decoder_set_metadata_respond_application (FLAC__FileDecoder *decoder, const FLAC__byte id[4])
FLAC__bool | FLAC__file_decoder_set_metadata_respond_all (FLAC__FileDecoder *decoder)
FLAC__bool | FLAC__file_decoder_set_metadata_ignore (FLAC__FileDecoder *decoder, FLAC__MetadataType type)
FLAC__bool | FLAC__file_decoder_set_metadata_ignore_application (FLAC__FileDecoder *decoder, const FLAC__byte id[4])
FLAC__bool | FLAC__file_decoder_set_metadata_ignore_all (FLAC__FileDecoder *decoder)
FLAC__FileDecoderState | FLAC__file_decoder_get_state (const FLAC__FileDecoder *decoder)
FLAC__SeekableStreamDecoderState | FLAC__file_decoder_get_seekable_stream_decoder_state (const FLAC__FileDecoder *decoder)
FLAC__StreamDecoderState | FLAC__file_decoder_get_stream_decoder_state (const FLAC__FileDecoder *decoder)
FLAC__bool | FLAC__file_decoder_get_md5_checking (const FLAC__FileDecoder *decoder)
unsigned | FLAC__file_decoder_get_channels (const FLAC__FileDecoder *decoder)
FLAC__ChannelAssignment | FLAC__file_decoder_get_channel_assignment (const FLAC__FileDecoder *decoder)
unsigned | FLAC__file_decoder_get_bits_per_sample (const FLAC__FileDecoder *decoder)
unsigned | FLAC__file_decoder_get_sample_rate (const FLAC__FileDecoder *decoder)
unsigned | FLAC__file_decoder_get_blocksize (const FLAC__FileDecoder *decoder)
FLAC__FileDecoderState | FLAC__file_decoder_init (FLAC__FileDecoder *decoder)
FLAC__bool | FLAC__file_decoder_finish (FLAC__FileDecoder *decoder)
FLAC__bool | FLAC__file_decoder_process_single (FLAC__FileDecoder *decoder)
FLAC__bool | FLAC__file_decoder_process_until_end_of_metadata (FLAC__FileDecoder *decoder)
FLAC__bool | FLAC__file_decoder_process_until_end_of_file (FLAC__FileDecoder *decoder)
FLAC__bool | FLAC__file_decoder_process_remaining_frames (FLAC__FileDecoder *decoder)
FLAC__bool | FLAC__file_decoder_seek_absolute (FLAC__FileDecoder *decoder, FLAC__uint64 sample)
## Variables
const char *const | FLAC__FileDecoderStateString []

## Detailed Description

This module contains the functions which implement the file decoder.

The basic usage of this decoder is as follows:

- The program creates an instance of a decoder using FLAC__file_decoder_new().
- The program overrides the default settings and sets callbacks for writing, error reporting, and metadata reporting using FLAC__file_decoder_set_*() functions.
- The program initializes the instance to validate the settings and prepare for decoding using FLAC__file_decoder_init().
- The program calls the FLAC__file_decoder_process_*() functions to decode data, which subsequently calls the callbacks.
- The program finishes the decoding with FLAC__file_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__file_decoder_delete().

The file decoder is a trivial wrapper around the seekable stream decoder meant to simplfy the process of decoding from a standard file. The file decoder supplies all but the Write/Metadata/Error callbacks. The user needs only to provide the path to the file and the file decoder handles the rest.

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

The file decoder also inherits MD5 signature checking from the seekable stream decoder. If this is turned on before initialization, FLAC__file_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 if there is no signature in the STREAMINFO block or when a seek is attempted.

Make sure to read the detailed descriptions of the seekable stream decoder module and stream decoder module since the file decoder inherits much of its behavior from them.

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

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

## Typedef Documentation

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

  | Signature for the write callback. See FLAC__file_decoder_set_write_callback() and FLAC__SeekableStreamDecoderWriteCallback 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__file_decoder_set_client_data().
  Return values:
  FLAC__StreamDecoderWriteStatus | The callee's return status.

typedef void(* FLAC__FileDecoderMetadataCallback)(const FLAC__FileDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data)

  | Signature for the metadata callback. See FLAC__file_decoder_set_metadata_callback() and FLAC__SeekableStreamDecoderMetadataCallback 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__file_decoder_set_client_data().

typedef void(* FLAC__FileDecoderErrorCallback)(const FLAC__FileDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data)

  | Signature for the error callback. See FLAC__file_decoder_set_error_callback() and FLAC__SeekableStreamDecoderErrorCallback 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__file_decoder_set_client_data().

## Enumeration Type Documentation

enum FLAC__FileDecoderState

  | State values for a FLAC__FileDecoder The decoder's state can be obtained by calling FLAC__file_decoder_get_state(). Enumeration values:
  FLAC__FILE_DECODER_OK | The decoder is in the normal OK state.
  FLAC__FILE_DECODER_END_OF_FILE | The decoder has reached the end of the file.
  FLAC__FILE_DECODER_ERROR_OPENING_FILE | An error occurred opening the input file.
  FLAC__FILE_DECODER_MEMORY_ALLOCATION_ERROR | An error occurred allocating memory.
  FLAC__FILE_DECODER_SEEK_ERROR | An error occurred while seeking.
  FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR | An error occurred in the underlying seekable stream decoder.
  FLAC__FILE_DECODER_ALREADY_INITIALIZED | FLAC__file_decoder_init() was called when the decoder was already initialized, usually because FLAC__file_decoder_finish() was not called.
  FLAC__FILE_DECODER_INVALID_CALLBACK | FLAC__file_decoder_init() was called without all callbacks being set.
  FLAC__FILE_DECODER_UNINITIALIZED | The decoder is in the uninitialized state.

## Function Documentation

FLAC__FileDecoder* FLAC__file_decoder_new | ( |  | ) |

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

void FLAC__file_decoder_delete | ( | FLAC__FileDecoder * | 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__file_decoder_set_md5_checking | ( | FLAC__FileDecoder * | decoder,
|  | FLAC__bool | value
| ) |

  | Set the "MD5 signature checking" flag. This is inherited from FLAC__SeekableStreamDecoder; see FLAC__seekable_stream_decoder_set_md5_checking(). Default Value: `false` 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__file_decoder_set_filename | ( | FLAC__FileDecoder * | decoder,
|  | const char * | value
| ) |

  | Set the input file name to decode. Default Value: `"-"` Parameters:
  decoder | A decoder instance to set.
  value | The input file name, or "-" for `stdin`.
  Assertions:
      decoder != NULL
      value != NULL
  Return values:
  FLAC__bool | `false` if the decoder is already initialized, or there was a memory allocation error, else `true`.

FLAC__bool FLAC__file_decoder_set_write_callback | ( | FLAC__FileDecoder * | decoder,
|  | FLAC__FileDecoderWriteCallback | value
| ) |

  | Set the write callback. This is inherited from FLAC__SeekableStreamDecoder; see FLAC__seekable_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__file_decoder_set_metadata_callback | ( | FLAC__FileDecoder * | decoder,
|  | FLAC__FileDecoderMetadataCallback | value
| ) |

  | Set the metadata callback. This is inherited from FLAC__SeekableStreamDecoder; see FLAC__seekable_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__file_decoder_set_error_callback | ( | FLAC__FileDecoder * | decoder,
|  | FLAC__FileDecoderErrorCallback | value
| ) |

  | Set the error callback. This is inherited from FLAC__SeekableStreamDecoder; see FLAC__seekable_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__file_decoder_set_client_data | ( | FLAC__FileDecoder * | 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__file_decoder_set_metadata_respond | ( | FLAC__FileDecoder * | decoder,
|  | FLAC__MetadataType | type
| ) |

  | This is inherited from FLAC__SeekableStreamDecoder; see FLAC__seekable_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__file_decoder_set_metadata_respond_application | ( | FLAC__FileDecoder * | decoder,
|  | const FLAC__byte | id[4]
| ) |

  | This is inherited from FLAC__SeekableStreamDecoder; see FLAC__seekable_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__file_decoder_set_metadata_respond_all | ( | FLAC__FileDecoder * | decoder | ) |

  | This is inherited from FLAC__SeekableStreamDecoder; see FLAC__seekable_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__file_decoder_set_metadata_ignore | ( | FLAC__FileDecoder * | decoder,
|  | FLAC__MetadataType | type
| ) |

  | This is inherited from FLAC__SeekableStreamDecoder; see FLAC__seekable_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__file_decoder_set_metadata_ignore_application | ( | FLAC__FileDecoder * | decoder,
|  | const FLAC__byte | id[4]
| ) |

  | This is inherited from FLAC__SeekableStreamDecoder; see FLAC__seekable_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__file_decoder_set_metadata_ignore_all | ( | FLAC__FileDecoder * | decoder | ) |

  | This is inherited from FLAC__SeekableStreamDecoder; see FLAC__seekable_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__FileDecoderState FLAC__file_decoder_get_state | ( | const FLAC__FileDecoder * | decoder | ) |

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

FLAC__SeekableStreamDecoderState FLAC__file_decoder_get_seekable_stream_decoder_state | ( | const FLAC__FileDecoder * | decoder | ) |

  | Get the state of the underlying seekable stream decoder. Useful when the file decoder state is `FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR`. Parameters:
  decoder | A decoder instance to query.
  Assertions:
      decoder != NULL
  Return values:
  FLAC__SeekableStreamDecoderState | The seekable stream decoder state.

FLAC__StreamDecoderState FLAC__file_decoder_get_stream_decoder_state | ( | const FLAC__FileDecoder * | decoder | ) |

  | Get the state of the underlying stream decoder. Useful when the file decoder state is `FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR` and 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 seekable stream decoder state.

FLAC__bool FLAC__file_decoder_get_md5_checking | ( | const FLAC__FileDecoder * | decoder | ) |

  | Get the "MD5 signature checking" flag. This is inherited from FLAC__SeekableStreamDecoder; see FLAC__seekable_stream_decoder_get_md5_checking(). Parameters:
  decoder | A decoder instance to query.
  Assertions:
      decoder != NULL
  Return values:
  FLAC__bool | See above.

unsigned FLAC__file_decoder_get_channels | ( | const FLAC__FileDecoder * | decoder | ) |

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

FLAC__ChannelAssignment FLAC__file_decoder_get_channel_assignment | ( | const FLAC__FileDecoder * | decoder | ) |

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

unsigned FLAC__file_decoder_get_bits_per_sample | ( | const FLAC__FileDecoder * | decoder | ) |

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

unsigned FLAC__file_decoder_get_sample_rate | ( | const FLAC__FileDecoder * | decoder | ) |

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

unsigned FLAC__file_decoder_get_blocksize | ( | const FLAC__FileDecoder * | decoder | ) |

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

FLAC__FileDecoderState FLAC__file_decoder_init | ( | FLAC__FileDecoder * | decoder | ) |

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

FLAC__bool FLAC__file_decoder_finish | ( | FLAC__FileDecoder * | 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__FILE_DECODER_UNINITIALIZED. In the event of a prematurely-terminated decode, it is not strictly necessary to call this immediately before FLAC__file_decoder_delete() but it is good practice to match every FLAC__file_decoder_init() with a FLAC__file_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__file_decoder_process_single | ( | FLAC__FileDecoder * | decoder | ) |

  | This is inherited from FLAC__SeekableStreamDecoder; see FLAC__seekable_stream_decoder_process_single(). Parameters:
  decoder | A decoder instance.
  Assertions:
      decoder != NULL
  Return values:
  FLAC__bool | See above.

FLAC__bool FLAC__file_decoder_process_until_end_of_metadata | ( | FLAC__FileDecoder * | decoder | ) |

  | This is inherited from FLAC__SeekableStreamDecoder; see FLAC__seekable_stream_decoder_process_until_end_of_metadata(). Parameters:
  decoder | A decoder instance.
  Assertions:
      decoder != NULL
  Return values:
  FLAC__bool | See above.

FLAC__bool FLAC__file_decoder_process_until_end_of_file | ( | FLAC__FileDecoder * | decoder | ) |

  | This is inherited from FLAC__SeekableStreamDecoder; see FLAC__seekable_stream_decoder_process_until_end_of_stream(). Parameters:
  decoder | A decoder instance.
  Assertions:
      decoder != NULL
  Return values:
  FLAC__bool | See above.

FLAC__bool FLAC__file_decoder_process_remaining_frames | ( | FLAC__FileDecoder * | decoder | ) |

  | This is inherited from FLAC__SeekableStreamDecoder; see FLAC__seekable_stream_decoder_process_remaining_frames(). Parameters:
  decoder | A decoder instance.
  Assertions:
      decoder != NULL
  Return values:
  FLAC__bool | See above.

FLAC__bool FLAC__file_decoder_seek_absolute | ( | FLAC__FileDecoder * | decoder,
|  | FLAC__uint64 | sample
| ) |

  | Flush the input and seek to an absolute sample. This is inherited from FLAC__SeekableStreamDecoder; see FLAC__seekable_stream_decoder_seek_absolute(). 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__FileDecoderStateString[]

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