* 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
+ * \link flac_seekable_stream_decoder seekable stream decoder module \endlink
+ * and \link flac_stream_decoder stream decoder module \endlink
+ * 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
* The decoder's state can be obtained by calling FLAC__file_decoder_get_state().
*/
typedef enum {
+
FLAC__FILE_DECODER_OK = 0,
+ /**< 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. */
+
} FLAC__FileDecoderState;
+
+/** 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.
+ */
extern const char * const FLAC__FileDecoderStateString[];
+
/***********************************************************************
*
* class FLAC__FileDecoder : public FLAC__StreamDecoder
struct FLAC__FileDecoderProtected;
struct FLAC__FileDecoderPrivate;
+/** The opaque structure definition for the file decoder type. See the
+ * \link flac_file_decoder file decoder module \endlink for a detailed
+ * description.
+ */
typedef struct {
struct FLAC__FileDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
struct FLAC__FileDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
} FLAC__FileDecoder;
+
/***********************************************************************
*
* Class constructor/destructor
*
***********************************************************************/
-/*
- * Any parameters that are not set before FLAC__file_decoder_init()
- * will take on the defaults from the constructor, shown below.
- * For more on what the parameters mean, see the documentation.
+/** 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.
*
- * FLAC__bool md5_checking (DEFAULT: false) MD5 checking will be turned off if a seek is requested
- * (*write_callback)() (DEFAULT: NULL ) The callbacks are the only values that MUST be set before FLAC__file_decoder_init()
- * (*metadata_callback)() (DEFAULT: NULL )
- * (*error_callback)() (DEFAULT: NULL )
- * void* client_data (DEFAULT: NULL ) passed back through the callbacks
- * metadata_respond/ignore By default, only the STREAMINFO block is returned via metadata_callback()
+ * \retval FLAC__FileDecoder*
+ * \c NULL if there was an error allocating memory, else the new instance.
*/
FLAC__FileDecoder *FLAC__file_decoder_new();
+
+/** Free a decoder instance. Deletes the object pointed to by \a decoder.
+ *
+ * \param decoder A pointer to an existing decoder.
+ * \assert
+ * \code decoder != NULL \endcode
+ */
void FLAC__file_decoder_delete(FLAC__FileDecoder *);
+
/***********************************************************************
*
* Public class method prototypes
*
***********************************************************************/
-/*
- * Various "set" methods. These 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 that these functions do not validate the values as many are
- * interdependent. The FLAC__file_decoder_init() function will do
- * this, so make sure to pay attention to the state returned by
- * FLAC__file_decoder_init().
+/** Set the "MD5 signature checking" flag.
+ * This is inherited from FLAC__SeekableStreamDecoder; see
+ * FLAC__seekable_stream_decoder_set_md5_checking().
*
- * Any parameters that are not set before FLAC__file_decoder_init()
- * will take on the defaults from the constructor. NOTE that
- * FLAC__file_decoder_flush() or FLAC__file_decoder_reset() do
- * NOT reset the values to the constructor defaults.
+ * \default \c false
+ * \param decoder A decoder instance to set.
+ * \param value See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c true.
*/
FLAC__bool FLAC__file_decoder_set_md5_checking(FLAC__FileDecoder *decoder, FLAC__bool value);
+
+/** Set the input file name to decode.
+ *
+ * \default \c false
+ * \param decoder A decoder instance to set.
+ * \param value The input file name, or "-" for \c stdin.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \code value != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, or there was a memory
+ * allocation error, else \c true.
+ */
FLAC__bool FLAC__file_decoder_set_filename(FLAC__FileDecoder *decoder, const char *value); /* 'value' may not be 0; use "-" for stdin */
+
+/** 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 \c NULL
+ * \param decoder A decoder instance to set.
+ * \param value See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \code value != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c true.
+ */
FLAC__bool FLAC__file_decoder_set_write_callback(FLAC__FileDecoder *decoder, FLAC__StreamDecoderWriteStatus (*value)(const FLAC__FileDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data));
+
+/** 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 \c NULL
+ * \param decoder A decoder instance to set.
+ * \param value See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \code value != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c true.
+ */
FLAC__bool FLAC__file_decoder_set_metadata_callback(FLAC__FileDecoder *decoder, void (*value)(const FLAC__FileDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data));
+
+/** 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 \c NULL
+ * \param decoder A decoder instance to set.
+ * \param value See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \code value != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c true.
+ */
FLAC__bool FLAC__file_decoder_set_error_callback(FLAC__FileDecoder *decoder, void (*value)(const FLAC__FileDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data));
+
+/** Set the client data to be passed back to callbacks.
+ * This value will be supplied to callbacks in their \a client_data
+ * argument.
+ *
+ * \default \c NULL
+ * \param decoder An decoder instance to set.
+ * \param value See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c true.
+ */
FLAC__bool FLAC__file_decoder_set_client_data(FLAC__FileDecoder *decoder, void *value);
-/*
- * See the comments for the equivalent functions in stream_decoder.h
+
+/** This is inherited from FLAC__SeekableStreamDecoder; see
+ * FLAC__seekable_stream_decoder_set_metadata_respond().
+ *
+ * \default By default, only the \c STREAMINFO block is returned via the
+ * metadata callback.
+ * \param decoder A decoder instance to set.
+ * \param type See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \a type is valid
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c 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_application().
+ *
+ * \default By default, only the \c STREAMINFO block is returned via the
+ * metadata callback.
+ * \param decoder A decoder instance to set.
+ * \param id See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \code id != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c 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_all().
+ *
+ * \default By default, only the \c STREAMINFO block is returned via the
+ * metadata callback.
+ * \param decoder A decoder instance to set.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c 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_ignore().
+ *
+ * \default By default, only the \c STREAMINFO block is returned via the
+ * metadata callback.
+ * \param decoder A decoder instance to set.
+ * \param type See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \a type is valid
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c 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_application().
+ *
+ * \default By default, only the \c STREAMINFO block is returned via the
+ * metadata callback.
+ * \param decoder A decoder instance to set.
+ * \param id See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \code id != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c 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_all().
+ *
+ * \default By default, only the \c STREAMINFO block is returned via the
+ * metadata callback.
+ * \param decoder A decoder instance to set.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c true.
+ */
FLAC__bool FLAC__file_decoder_set_metadata_ignore_all(FLAC__FileDecoder *decoder);
-/*
- * Various "get" methods
+/** Get the current decoder state.
+ *
+ * \param decoder A decoder instance to query.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__FileDecoderState
+ * The current decoder state.
*/
FLAC__FileDecoderState FLAC__file_decoder_get_state(const FLAC__FileDecoder *decoder);
+
+/** Get the "MD5 signature checking" flag.
+ * This is inherited from FLAC__SeekableStreamDecoder; see
+ * FLAC__seekable_stream_decoder_get_md5_checking().
+ *
+ * \param decoder A decoder instance to query.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * See above.
+ */
FLAC__bool FLAC__file_decoder_get_md5_checking(const FLAC__FileDecoder *decoder);
-/*
- * Methods to return the current number of channels, channel assignment
- * bits-per-sample, sample rate in Hz, and blocksize in samples. These
- * will only be valid after decoding has started.
+
+/** This is inherited from FLAC__SeekableStreamDecoder; see
+ * FLAC__seekable_stream_decoder_get_channels().
+ *
+ * \param decoder A decoder instance to query.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval unsigned
+ * See above.
*/
unsigned FLAC__file_decoder_get_channels(const FLAC__FileDecoder *decoder);
+
+/** This is inherited from FLAC__SeekableStreamDecoder; see
+ * FLAC__seekable_stream_decoder_get_channel_assignment().
+ *
+ * \param decoder A decoder instance to query.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__ChannelAssignment
+ * 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_bits_per_sample().
+ *
+ * \param decoder A decoder instance to query.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval unsigned
+ * 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_sample_rate().
+ *
+ * \param decoder A decoder instance to query.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval 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_blocksize().
+ *
+ * \param decoder A decoder instance to query.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval unsigned
+ * See above.
+ */
unsigned FLAC__file_decoder_get_blocksize(const FLAC__FileDecoder *decoder);
-/*
- * Initialize the instance; should be called after construction and
- * 'set' calls but before any of the 'process' or 'seek' calls. Will
- * set and return the decoder state, which will be FLAC__FILE_DECODER_OK
- * if initialization succeeded.
+/** 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.
+ *
+ * \param decoder An uninitialized decoder instance.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__FileDecoderState
+ * \c FLAC__FILE_DECODER_OK if initialization was successful; see
+ * FLAC__FileDecoderState for the meanings of other return values.
*/
FLAC__FileDecoderState FLAC__file_decoder_init(FLAC__FileDecoder *decoder);
-/*
- * Flush the decoding buffer, release resources, and return the decoder
- * state to FLAC__FILE_DECODER_UNINITIALIZED. Only returns false if
- * md5_checking is set AND the stored MD5 sum is non-zero AND the stored
- * MD5 sum and computed MD5 sum do not match.
+/** 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().
+ *
+ * \param decoder An uninitialized decoder instance.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * \c 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
+ * \c true.
*/
FLAC__bool FLAC__file_decoder_finish(FLAC__FileDecoder *decoder);
-/*
- * Methods for decoding the data
+/** This is inherited from FLAC__SeekableStreamDecoder; see
+ * FLAC__seekable_stream_decoder_process_whole_stream().
+ *
+ * \param decoder A decoder instance.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * See above.
*/
FLAC__bool FLAC__file_decoder_process_whole_file(FLAC__FileDecoder *decoder);
+
+/** This is inherited from FLAC__SeekableStreamDecoder; see
+ * FLAC__seekable_stream_decoder_process_metadata().
+ *
+ * \param decoder A decoder instance.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * See above.
+ */
FLAC__bool FLAC__file_decoder_process_metadata(FLAC__FileDecoder *decoder);
+
+/** This is inherited from FLAC__SeekableStreamDecoder; see
+ * FLAC__seekable_stream_decoder_process_one_frame().
+ *
+ * \param decoder A decoder instance.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * See above.
+ */
FLAC__bool FLAC__file_decoder_process_one_frame(FLAC__FileDecoder *decoder);
+
+/** This is inherited from FLAC__SeekableStreamDecoder; see
+ * FLAC__seekable_stream_decoder_process_remaining_frames().
+ *
+ * \param decoder A decoder instance.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * See above.
+ */
FLAC__bool FLAC__file_decoder_process_remaining_frames(FLAC__FileDecoder *decoder);
+/** Flush the input and seek to an absolute sample.
+ * This is inherited from FLAC__SeekableStreamDecoder; see
+ * FLAC__seekable_stream_decoder_seek_absolute().
+ *
+ * \param decoder A decoder instance.
+ * \param sample The target sample number to seek to.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * \c true if successful, else \c false.
+ */
FLAC__bool FLAC__file_decoder_seek_absolute(FLAC__FileDecoder *decoder, FLAC__uint64 sample);
/* \} */
* 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
+ * \link flac_stream_decoder stream decoder module \endlink 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
/** State values for a FLAC__SeekableStreamDecoder
*
- * The decoder's state can be obtained by calling FLAC__seekable_tream_decoder_get_state().
+ * The decoder's state can be obtained by calling FLAC__seekable_stream_decoder_get_state().
*/
typedef enum {
+
FLAC__SEEKABLE_STREAM_DECODER_OK = 0,
+ /**< 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. */
+
} FLAC__SeekableStreamDecoderState;
+
+/** 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.
+ */
extern const char * const FLAC__SeekableStreamDecoderStateString[];
+
+/** Return values for the FLAC__SeekableStreamDecoder read callback.
+ */
typedef enum {
+
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. */
+
} FLAC__SeekableStreamDecoderReadStatus;
+
+/** 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.
+ */
extern const char * const FLAC__SeekableStreamDecoderReadStatusString[];
+
+/** Return values for the FLAC__SeekableStreamDecoder seek callback.
+ */
typedef enum {
+
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. */
+
} FLAC__SeekableStreamDecoderSeekStatus;
+
+/** 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.
+ */
extern const char * const FLAC__SeekableStreamDecoderSeekStatusString[];
+
+/** Return values for the FLAC__SeekableStreamDecoder tell callback.
+ */
typedef enum {
+
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. */
+
} FLAC__SeekableStreamDecoderTellStatus;
+
+/** 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.
+ */
extern const char * const FLAC__SeekableStreamDecoderTellStatusString[];
+
+/** Return values for the FLAC__SeekableStreamDecoder length callback.
+ */
typedef enum {
+
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. */
+
} FLAC__SeekableStreamDecoderLengthStatus;
+
+/** 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.
+ */
extern const char * const FLAC__SeekableStreamDecoderLengthStatusString[];
+
/***********************************************************************
*
* class FLAC__SeekableStreamDecoder : public FLAC__StreamDecoder
struct FLAC__SeekableStreamDecoderProtected;
struct FLAC__SeekableStreamDecoderPrivate;
+/** The opaque structure definition for the seekable stream decoder type.
+ * See the
+ * \link flac_seekable_stream_decoder seekable stream decoder module \endlink
+ * for a detailed description.
+ */
typedef struct {
struct FLAC__SeekableStreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
struct FLAC__SeekableStreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
} FLAC__SeekableStreamDecoder;
+
/***********************************************************************
*
* Class constructor/destructor
*
***********************************************************************/
-/*
- * Any parameters that are not set before FLAC__seekable_stream_decoder_init()
- * will take on the defaults from the constructor, shown below.
- * For more on what the parameters mean, see the documentation.
- *
- * FLAC__bool md5_checking (DEFAULT: false) MD5 checking will be turned off if a seek is requested
- * (*read_callback)() (DEFAULT: NULL ) The callbacks are the only values that MUST be set before FLAC__seekable_stream_decoder_init()
- * (*seek_callback)() (DEFAULT: NULL )
- * (*tell_callback)() (DEFAULT: NULL )
- * (*length_callback)() (DEFAULT: NULL )
- * (*eof_callback)() (DEFAULT: NULL )
- * (*write_callback)() (DEFAULT: NULL )
- * (*metadata_callback)() (DEFAULT: NULL )
- * (*error_callback)() (DEFAULT: NULL )
- * void* client_data (DEFAULT: NULL ) passed back through the callbacks
- * metadata_respond/ignore By default, only the STREAMINFO block is returned via metadata_callback()
+/** 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.
+ *
+ * \retval FLAC__SeekableStreamDecoder*
+ * \c NULL if there was an error allocating memory, else the new instance.
*/
FLAC__SeekableStreamDecoder *FLAC__seekable_stream_decoder_new();
-void FLAC__seekable_stream_decoder_delete(FLAC__SeekableStreamDecoder *);
+
+/** Free a decoder instance. Deletes the object pointed to by \a decoder.
+ *
+ * \param decoder A pointer to an existing decoder.
+ * \assert
+ * \code decoder != NULL \endcode
+ */
+void FLAC__seekable_stream_decoder_delete(FLAC__SeekableStreamDecoder *decoder);
+
/***********************************************************************
*
*
***********************************************************************/
-/*
- * Various "set" methods. These 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.
+/** Set the "MD5 signature checking" flag. If \c 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().
*
- * NOTE that these functions do not validate the values as many are
- * interdependent. The FLAC__seekable_stream_decoder_init() function will
- * do this, so make sure to pay attention to the state returned by
- * FLAC__seekable_stream_decoder_init().
+ * 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.
*
- * Any parameters that are not set before FLAC__seekable_stream_decoder_init()
- * will take on the defaults from the constructor. NOTE that
- * FLAC__seekable_stream_decoder_flush() or FLAC__seekable_stream_decoder_reset()
- * do NOT reset the values to the constructor defaults.
+ * \default \c false
+ * \param decoder A decoder instance to set.
+ * \param value Flag value (see above).
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c true.
*/
FLAC__bool FLAC__seekable_stream_decoder_set_md5_checking(FLAC__SeekableStreamDecoder *decoder, FLAC__bool 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 \c NULL
+ * \param decoder A decoder instance to set.
+ * \param value See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \code value != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c true.
+ */
FLAC__bool FLAC__seekable_stream_decoder_set_read_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderReadStatus (*value)(const FLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data));
+
+/** 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 \c NULL
+ * \param decoder An decoder instance to set.
+ * \param value See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \code value != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c true.
+ */
FLAC__bool FLAC__seekable_stream_decoder_set_seek_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderSeekStatus (*value)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data));
+
+/** 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 \c NULL
+ * \param decoder An decoder instance to set.
+ * \param value See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \code value != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c true.
+ */
FLAC__bool FLAC__seekable_stream_decoder_set_tell_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderTellStatus (*value)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data));
+
+/** 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 \c NULL
+ * \param decoder An decoder instance to set.
+ * \param value See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \code value != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c true.
+ */
FLAC__bool FLAC__seekable_stream_decoder_set_length_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderLengthStatus (*value)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data));
+
+/** 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 \c NULL
+ * \param decoder An decoder instance to set.
+ * \param value See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \code value != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c true.
+ */
FLAC__bool FLAC__seekable_stream_decoder_set_eof_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__bool (*value)(const FLAC__SeekableStreamDecoder *decoder, void *client_data));
+
+/** 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 \c NULL
+ * \param decoder A decoder instance to set.
+ * \param value See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \code value != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c true.
+ */
FLAC__bool FLAC__seekable_stream_decoder_set_write_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__StreamDecoderWriteStatus (*value)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data));
+
+/** 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 \c NULL
+ * \param decoder A decoder instance to set.
+ * \param value See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \code value != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c true.
+ */
FLAC__bool FLAC__seekable_stream_decoder_set_metadata_callback(FLAC__SeekableStreamDecoder *decoder, void (*value)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data));
+
+/** 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 \c NULL
+ * \param decoder A decoder instance to set.
+ * \param value See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \code value != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c true.
+ */
FLAC__bool FLAC__seekable_stream_decoder_set_error_callback(FLAC__SeekableStreamDecoder *decoder, void (*value)(const FLAC__SeekableStreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data));
+
+/** Set the client data to be passed back to callbacks.
+ * This value will be supplied to callbacks in their \a client_data
+ * argument.
+ *
+ * \default \c NULL
+ * \param decoder An decoder instance to set.
+ * \param value See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c true.
+ */
FLAC__bool FLAC__seekable_stream_decoder_set_client_data(FLAC__SeekableStreamDecoder *decoder, void *value);
-/*
- * See the comments for the equivalent functions in stream_decoder.h
+
+/** This is inherited from FLAC__StreamDecoder; see
+ * FLAC__stream_decoder_set_metadata_respond().
+ *
+ * \default By default, only the \c STREAMINFO block is returned via the
+ * metadata callback.
+ * \param decoder A decoder instance to set.
+ * \param type See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \a type is valid
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c 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_application().
+ *
+ * \default By default, only the \c STREAMINFO block is returned via the
+ * metadata callback.
+ * \param decoder A decoder instance to set.
+ * \param id See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \code id != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c 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_all().
+ *
+ * \default By default, only the \c STREAMINFO block is returned via the
+ * metadata callback.
+ * \param decoder A decoder instance to set.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c 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_ignore().
+ *
+ * \default By default, only the \c STREAMINFO block is returned via the
+ * metadata callback.
+ * \param decoder A decoder instance to set.
+ * \param type See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \a type is valid
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c 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_application().
+ *
+ * \default By default, only the \c STREAMINFO block is returned via the
+ * metadata callback.
+ * \param decoder A decoder instance to set.
+ * \param id See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \code id != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c 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_all().
+ *
+ * \default By default, only the \c STREAMINFO block is returned via the
+ * metadata callback.
+ * \param decoder A decoder instance to set.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c true.
+ */
FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore_all(FLAC__SeekableStreamDecoder *decoder);
-/*
- * Various "get" methods
+/** Get the current decoder state.
+ *
+ * \param decoder A decoder instance to query.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__SeekableStreamDecoderState
+ * The current decoder state.
*/
FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_get_state(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.
+ *
+ * \param decoder A decoder instance to query.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * See above.
+ */
FLAC__bool FLAC__seekable_stream_decoder_get_md5_checking(const FLAC__SeekableStreamDecoder *decoder);
-/*
- * Methods to return the current number of channels, channel assignment
- * bits-per-sample, sample rate in Hz, and blocksize in samples. These
- * will only be valid after decoding has started.
+
+/** This is inherited from FLAC__StreamDecoder; see
+ * FLAC__stream_decoder_get_channels().
+ *
+ * \param decoder A decoder instance to query.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval unsigned
+ * See above.
*/
unsigned FLAC__seekable_stream_decoder_get_channels(const FLAC__SeekableStreamDecoder *decoder);
+
+/** This is inherited from FLAC__StreamDecoder; see
+ * FLAC__stream_decoder_get_channel_assignment().
+ *
+ * \param decoder A decoder instance to query.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__ChannelAssignment
+ * 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_bits_per_sample().
+ *
+ * \param decoder A decoder instance to query.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval unsigned
+ * 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_sample_rate().
+ *
+ * \param decoder A decoder instance to query.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval 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_blocksize().
+ *
+ * \param decoder A decoder instance to query.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval unsigned
+ * See above.
+ */
unsigned FLAC__seekable_stream_decoder_get_blocksize(const FLAC__SeekableStreamDecoder *decoder);
-/*
- * Initialize the instance; should be called after construction and
- * 'set' calls but before any of the 'process' or 'seek' calls. Will
- * set and return the decoder state, which will be
- * FLAC__SEEKABLE_STREAM_DECODER_OK if initialization succeeded.
+/** 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.
+ *
+ * \param decoder An uninitialized decoder instance.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__SeekableStreamDecoderState
+ * \c FLAC__SEEKABLE_STREAM_DECODER_OK if initialization was
+ * successful; see FLAC__SeekableStreamDecoderState for the meanings
+ * of other return values.
*/
FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_init(FLAC__SeekableStreamDecoder *decoder);
-/*
- * Flush the decoding buffer, release resources, and return the decoder
- * state to FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED. Only returns false if
- * md5_checking is set AND the stored MD5 sum is non-zero AND the stored
- * MD5 sum and computed MD5 sum do not match.
+/** 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().
+ *
+ * \param decoder An uninitialized decoder instance.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * \c 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
+ * \c true.
*/
FLAC__bool FLAC__seekable_stream_decoder_finish(FLAC__SeekableStreamDecoder *decoder);
-/*
- * state control methods
+/** Flush the stream input.
+ * The decoder's input buffer will be cleared and the state set to
+ * \c FLAC__SEEKABLE_STREAM_DECODER_OK. This will also turn off MD5
+ * checking.
+ *
+ * \param decoder A decoder instance.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * \c true if successful, else \c false if a memory allocation
+ * or stream decoder error occurs.
*/
FLAC__bool FLAC__seekable_stream_decoder_flush(FLAC__SeekableStreamDecoder *decoder);
+
+/** Reset the decoding process.
+ * The decoder's input buffer will be cleared and the state set to
+ * \c 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.
+ *
+ * \param decoder A decoder instance.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * \c true if successful, else \c false if a memory allocation
+ * or stream decoder error occurs.
+ */
FLAC__bool FLAC__seekable_stream_decoder_reset(FLAC__SeekableStreamDecoder *decoder);
-/*
- * Methods for decoding the data
+/** This is inherited from FLAC__StreamDecoder; see
+ * FLAC__stream_decoder_process_whole_stream().
+ *
+ * \param decoder A decoder instance.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * See above.
*/
FLAC__bool FLAC__seekable_stream_decoder_process_whole_stream(FLAC__SeekableStreamDecoder *decoder);
+
+/** This is inherited from FLAC__StreamDecoder; see
+ * FLAC__stream_decoder_process_metadata().
+ *
+ * \param decoder A decoder instance.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * See above.
+ */
FLAC__bool FLAC__seekable_stream_decoder_process_metadata(FLAC__SeekableStreamDecoder *decoder);
+
+/** This is inherited from FLAC__StreamDecoder; see
+ * FLAC__stream_decoder_process_one_frame().
+ *
+ * \param decoder A decoder instance.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * See above.
+ */
FLAC__bool FLAC__seekable_stream_decoder_process_one_frame(FLAC__SeekableStreamDecoder *decoder);
+
+/** This is inherited from FLAC__StreamDecoder; see
+ * FLAC__stream_decoder_process_remaining_frames().
+ *
+ * \param decoder A decoder instance.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * See above.
+ */
FLAC__bool FLAC__seekable_stream_decoder_process_remaining_frames(FLAC__SeekableStreamDecoder *decoder);
+/** 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.
+ *
+ * \param decoder A decoder instance.
+ * \param sample The target sample number to seek to.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * \c true if successful, else \c false.
+ */
FLAC__bool FLAC__seekable_stream_decoder_seek_absolute(FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 sample);
/* \} */
*
* - FLAC__stream_decoder_process_whole_stream() - Tells the decoder to
* start and continue processing the stream until the read callback
- * returns FLAC__STREAM_DECODER_READ_END_OF_STREAM or
- * FLAC__STREAM_DECODER_READ_ABORT.
+ * returns FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM or
+ * FLAC__STREAM_DECODER_READ_STATUS_ABORT.
* - FLAC__stream_decoder_process_metadata() - Tells the decoder to start
* processing the stream and stop upon reaching the first audio frame.
* - FLAC__stream_decoder_process_one_frame() - Tells the decoder to
* data from the new position through the read callback. The seekable
* stream decoder does just this.
*
+ * The FLAC__stream_decoder_set_metadata_*() functions deserve special
+ * attention. By default, the decoder only calls the metadata_callback for
+ * the STREAMINFO block. These functions allow you to tell the decoder
+ * explicitly which blocks to parse and return via the metadata_callback
+ * and/or which to skip. Use a FLAC__stream_decoder_respond_all(),
+ * FLAC__stream_decoder_ignore() ... or FLAC__stream_decoder_ignore_all(),
+ * FLAC__stream_decoder_respond() ... sequence to exactly specify which
+ * blocks to return. Remember that some metadata blocks can be big so
+ * filtering out the ones you don't use can reduce the memory requirements
+ * of the decoder. Also note the special forms
+ * FLAC__stream_decoder_respond_application(id) and
+ * FLAC__stream_decoder_ignore_application(id) for filtering APPLICATION
+ * blocks based on the application ID.
+ *
+ * STREAMINFO and SEEKTABLE blocks are always parsed and used internally, but
+ * they still can legally be filtered from the metadata_callback.
+ *
* \note
* The "set" functions may only be called when the decoder is in the
* state FLAC__STREAM_DECODER_UNINITIALIZED, i.e. after
*/
FLAC__StreamDecoder *FLAC__stream_decoder_new();
-/** Free an decoder instance. Deletes the object pointed to by \a decoder.
+/** Free a decoder instance. Deletes the object pointed to by \a decoder.
*
* \param decoder A pointer to an existing decoder.
* \assert
* \code decoder != NULL \endcode
*/
-void FLAC__stream_decoder_delete(FLAC__StreamDecoder *);
+void FLAC__stream_decoder_delete(FLAC__StreamDecoder *decoder);
/***********************************************************************
*/
FLAC__bool FLAC__stream_decoder_set_client_data(FLAC__StreamDecoder *decoder, void *value);
-/*
- * These deserve special attention. By default, the decoder only calls the
- * metadata_callback for the STREAMINFO block. These functions allow you to
- * tell the decoder explicitly which blocks to parse and return via the
- * metadata_callback and/or which to skip. Use a _respond_all(), _ignore() ...
- * or _ignore_all(), _respond() ... sequence to exactly specify which blocks
- * to return. Remember that some metadata blocks can be big so filtering out
- * the ones you don't use can reduce the memory requirements of the decoder.
- * Also note the special forms _respond/_ignore_application(id) for filtering
- * APPLICATION blocks based on the application ID.
+/** Direct the decoder to pass on all metadata blocks of type \a type.
*
- * STREAMINFO and SEEKTABLE blocks are always parsed and used internally, but
- * they still can legally be filtered from the metadata_callback here.
- */
-/*
- * metadata_respond/ignore By default, only the STREAMINFO block is returned via metadata_callback()
+ * \default By default, only the \c STREAMINFO block is returned via the
+ * metadata callback.
+ * \param decoder A decoder instance to set.
+ * \param type See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \a type is valid
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c true.
*/
FLAC__bool FLAC__stream_decoder_set_metadata_respond(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
+
+/** Direct the decoder to pass on all APPLICATION metadata blocks of the
+ * given \a id.
+ *
+ * \default By default, only the \c STREAMINFO block is returned via the
+ * metadata callback.
+ * \param decoder A decoder instance to set.
+ * \param id See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \code id != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c true.
+ */
FLAC__bool FLAC__stream_decoder_set_metadata_respond_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
+
+/** Direct the decoder to pass on all metadata blocks of any type.
+ *
+ * \default By default, only the \c STREAMINFO block is returned via the
+ * metadata callback.
+ * \param decoder A decoder instance to set.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c true.
+ */
FLAC__bool FLAC__stream_decoder_set_metadata_respond_all(FLAC__StreamDecoder *decoder);
+
+/** Direct the decoder to filter out all metadata blocks of type \a type.
+ *
+ * \default By default, only the \c STREAMINFO block is returned via the
+ * metadata callback.
+ * \param decoder A decoder instance to set.
+ * \param type See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \a type is valid
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c true.
+ */
FLAC__bool FLAC__stream_decoder_set_metadata_ignore(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
+
+/** Direct the decoder to filter out all APPLICATION metadata blocks of
+ * the given \a id.
+ *
+ * \default By default, only the \c STREAMINFO block is returned via the
+ * metadata callback.
+ * \param decoder A decoder instance to set.
+ * \param id See above.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \code id != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c true.
+ */
FLAC__bool FLAC__stream_decoder_set_metadata_ignore_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
+
+/** Direct the decoder to filter out all metadata blocks of any type.
+ *
+ * \default By default, only the \c STREAMINFO block is returned via the
+ * metadata callback.
+ * \param decoder A decoder instance to set.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * \c false if the decoder is already initialized, else \c true.
+ */
FLAC__bool FLAC__stream_decoder_set_metadata_ignore_all(FLAC__StreamDecoder *decoder);
-/*
- * Methods to return the current stream decoder state, number
- * of channels, channel assignment, bits-per-sample, sample
- * rate in Hz, and blocksize in samples. All but the decoder
- * state will only be valid after decoding has started.
+/** Get the current decoder state.
+ *
+ * \param decoder A decoder instance to query.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__StreamDecoderState
+ * The current decoder state.
*/
FLAC__StreamDecoderState FLAC__stream_decoder_get_state(const FLAC__StreamDecoder *decoder);
+
+/** Get the current number of channels in the stream being decoded.
+ * Will only be valid after decoding has started and will contain the
+ * value from the most recently decoded frame header.
+ *
+ * \param decoder A decoder instance to query.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval unsigned
+ * See above.
+ */
unsigned FLAC__stream_decoder_get_channels(const FLAC__StreamDecoder *decoder);
+
+/** Get the current channel assignment in the stream being decoded.
+ * Will only be valid after decoding has started and will contain the
+ * value from the most recently decoded frame header.
+ *
+ * \param decoder A decoder instance to query.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__ChannelAssignment
+ * See above.
+ */
FLAC__ChannelAssignment FLAC__stream_decoder_get_channel_assignment(const FLAC__StreamDecoder *decoder);
+
+/** Get the current sample resolution in the stream being decoded.
+ * Will only be valid after decoding has started and will contain the
+ * value from the most recently decoded frame header.
+ *
+ * \param decoder A decoder instance to query.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval unsigned
+ * See above.
+ */
unsigned FLAC__stream_decoder_get_bits_per_sample(const FLAC__StreamDecoder *decoder);
+
+/** Get the current sample rate in Hz of the stream being decoded.
+ * Will only be valid after decoding has started and will contain the
+ * value from the most recently decoded frame header.
+ *
+ * \param decoder A decoder instance to query.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval unsigned
+ * See above.
+ */
unsigned FLAC__stream_decoder_get_sample_rate(const FLAC__StreamDecoder *decoder);
+
+/** Get the current blocksize of the stream being decoded.
+ * Will only be valid after decoding has started and will contain the
+ * value from the most recently decoded frame header.
+ *
+ * \param decoder A decoder instance to query.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval unsigned
+ * See above.
+ */
unsigned FLAC__stream_decoder_get_blocksize(const FLAC__StreamDecoder *decoder);
-/*
- * Initialize the instance; should be called after construction and
- * 'set' calls but before any of the 'process' calls. Will set and
- * return the decoder state, which will be
- * FLAC__STREAM_DECODER_SEARCH_FOR_METADATA if initialization
- * succeeded.
+/** Initialize the decoder instance.
+ * Should be called after FLAC__stream_decoder_new() and
+ * FLAC__stream_decoder_set_*() but before any of the
+ * FLAC__stream_decoder_process_*() functions. Will set and return the
+ * decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
+ * if initialization succeeded.
+ *
+ * \param decoder An uninitialized decoder instance.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__StreamDecoderState
+ * \c FLAC__STREAM_DECODER_SEARCH_FOR_MEATADATA if initialization was
+ * successful; see FLAC__StreamDecoderState for the meanings of other
+ * return values.
*/
FLAC__StreamDecoderState FLAC__stream_decoder_init(FLAC__StreamDecoder *decoder);
-/*
- * Flush the decoding buffer, release resources, and return the decoder
- * state to FLAC__STREAM_DECODER_UNINITIALIZED.
+/** Finish the decoding process.
+ * Flushes the decoding buffer, releases resources, resets the decoder
+ * settings to their defaults, and returns the decoder state to
+ * FLAC__STREAM_DECODER_UNINITIALIZED.
+ *
+ * In the event of a prematurely-terminated decode, it is not strictly
+ * necessary to call this immediately before FLAC__stream_decoder_delete()
+ * but it is good practice to match every FLAC__stream_decoder_init()
+ * with a FLAC__stream_decoder_finish().
+ *
+ * \param decoder An uninitialized decoder instance.
+ * \assert
+ * \code decoder != NULL \endcode
*/
void FLAC__stream_decoder_finish(FLAC__StreamDecoder *decoder);
-/*
- * state control methods
+/** Flush the stream input.
+ * The decoder's input buffer will be cleared and the state set to
+ * \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.
+ *
+ * \param decoder A decoder instance.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * \c true if successful, else \c false if a memory allocation
+ * error occurs.
*/
FLAC__bool FLAC__stream_decoder_flush(FLAC__StreamDecoder *decoder);
+
+/** Reset the decoding process.
+ * The decoder's input buffer will be cleared and the state set to
+ * \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA. This is similar to
+ * FLAC__stream_decoder_finish() except that the settings are
+ * preserved; there is no need to call FLAC__stream_decoder_init()
+ * before decoding again.
+ *
+ * \param decoder A decoder instance.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ * \c true if successful, else \c false if a memory allocation
+ * error occurs.
+ */
FLAC__bool FLAC__stream_decoder_reset(FLAC__StreamDecoder *decoder);
-/*
- * Methods for decoding the data
+/** Decode the entire stream.
+ * This version instructs the decoder to start and continue decoding
+ * the entire stream until the callbacks return a fatal error or the
+ * read callback returns \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
+ *
+ * As the decoder needs more input it will call the read callback.
+ * As each metadata block and frame is decoded, the metadata or write
+ * callback will be called with the decoded metadata or frame.
+ *
+ * \param decoder An initialized decoder instance in the state
+ * \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_METADATA \endcode
+ * \retval FLAC__bool
+ * \c false if any read or write error occurred (except
+ * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c false;
+ * in any case, check the decoder state with
+ * FLAC__stream_decoder_get_state() to see what went wrong or to
+ * check for lost synchronization (a sign of stream corruption).
*/
FLAC__bool FLAC__stream_decoder_process_whole_stream(FLAC__StreamDecoder *decoder);
+
+/** Decode just the metadata.
+ * This version instructs the decoder to start decoding and stop after
+ * all the metadata has been read, or until the callbacks return a fatal
+ * error or the read callback returns
+ * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
+ *
+ * As the decoder needs more input it will call the read callback.
+ * As each metadata block is decoded, the metadata callback will be called
+ * with the decoded metadata.
+ *
+ * \param decoder An initialized decoder instance in the state
+ * \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_METADATA \endcode
+ * \retval FLAC__bool
+ * \c false if any read or write error occurred (except
+ * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c false;
+ * in any case, check the decoder state with
+ * FLAC__stream_decoder_get_state() to see what went wrong or to
+ * check for lost synchronization (a sign of stream corruption).
+ */
FLAC__bool FLAC__stream_decoder_process_metadata(FLAC__StreamDecoder *decoder);
+
+/** Decode one frame.
+ * This version instructs the decoder to decode a single frame and stop,
+ * or until the callbacks return a fatal error or the read callback returns
+ * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
+ *
+ * As the decoder needs more input it will call the read callback.
+ * The write callback will be called with the decoded frame.
+ *
+ * \param decoder An initialized decoder instance in the state
+ * \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC \endcode
+ * \retval FLAC__bool
+ * \c false if any read or write error occurred (except
+ * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c false;
+ * in any case, check the decoder state with
+ * FLAC__stream_decoder_get_state() to see what went wrong or to
+ * check for lost synchronization (a sign of stream corruption).
+ */
FLAC__bool FLAC__stream_decoder_process_one_frame(FLAC__StreamDecoder *decoder);
+
+/** Decode the remaining frames until end of stream.
+ * This version instructs the decoder to decode all remaining frames,
+ * until the callbacks return a fatal error or the read callback returns
+ * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
+ *
+ * As the decoder needs more input it will call the read callback.
+ * As each frame is decoded, the write callback will be called with the
+ * decoded frame.
+ *
+ * \param decoder An initialized decoder instance in the state
+ * \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.
+ * \assert
+ * \code decoder != NULL \endcode
+ * \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC \endcode
+ * \retval FLAC__bool
+ * \c false if any read or write error occurred (except
+ * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c false;
+ * in any case, check the decoder state with
+ * FLAC__stream_decoder_get_state() to see what went wrong or to
+ * check for lost synchronization (a sign of stream corruption).
+ */
FLAC__bool FLAC__stream_decoder_process_remaining_frames(FLAC__StreamDecoder *decoder);
/* \} */
* occur in the supplied array.
*
* \default \c NULL, 0
- * \param encoder An encoder instance to set.
- * \param value See above.
+ * \param encoder An encoder instance to set.
+ * \param metadata See above.
+ * \param num_blocks See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
FLAC__StreamEncoderState FLAC__stream_encoder_init(FLAC__StreamEncoder *encoder);
/** Finish the encoding process.
- * Flushes the encoding buffer, releases resources, and returns the encoder
- * state to FLAC__STREAM_ENCODER_UNINITIALIZED. Note that this can
- * generate one or more write callbacks before returning, and will
- * generate a metadata callback.
+ * Flushes the encoding buffer, releases resources, resets the encoder
+ * settings to their defaults, and returns the encoder state to
+ * FLAC__STREAM_ENCODER_UNINITIALIZED. Note that this can generate
+ * one or more write callbacks before returning, and will generate
+ * a metadata callback.
*
* In the event of a prematurely-terminated encode, it is not strictly
* necessary to call this immediately before FLAC__stream_encoder_delete()
projects / platform / upstream / flac.git / commitdiff