---

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)
const char *	FLAC__file_decoder_get_resolved_state_string (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__bool	FLAC__file_decoder_get_decode_position (const FLAC__FileDecoder *decoder, FLAC__uint64 *position)
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.

const char* FLAC__file_decoder_get_resolved_state_string (  const FLAC__FileDecoder *    decoder )

Get the current decoder state as a C string. This version automatically resolves FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR by getting the seekable 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__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__bool FLAC__file_decoder_get_decode_position (  const FLAC__FileDecoder *    decoder, FLAC__uint64 *    position )

This is inherited from FLAC__SeekableStreamDecoder; see FLAC__seekable_stream_decoder_get_decode_position(). 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__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.

---