diff --git a/include/FLAC/file_decoder.h b/include/FLAC/file_decoder.h index 9fa4cfa4..c9d415d9 100644 --- a/include/FLAC/file_decoder.h +++ b/include/FLAC/file_decoder.h @@ -81,6 +81,11 @@ extern "C" { * 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 @@ -101,18 +106,49 @@ extern "C" { * 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 @@ -121,111 +157,397 @@ extern const char * const FLAC__FileDecoderStateString[]; 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. +/** Set the "MD5 signature checking" flag. + * This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_set_md5_checking(). * - * 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(). - * - * 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); /* \} */ diff --git a/include/FLAC/seekable_stream_decoder.h b/include/FLAC/seekable_stream_decoder.h index 60080ff1..26c5bc98 100644 --- a/include/FLAC/seekable_stream_decoder.h +++ b/include/FLAC/seekable_stream_decoder.h @@ -92,6 +92,10 @@ extern "C" { * 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 @@ -110,46 +114,137 @@ extern "C" { /** 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 @@ -158,36 +253,41 @@ extern const char * const FLAC__SeekableStreamDecoderLengthStatusString[]; 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. +/** 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. * - * 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() + * \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); + /*********************************************************************** * @@ -195,89 +295,475 @@ void FLAC__seekable_stream_decoder_delete(FLAC__SeekableStreamDecoder *); * ***********************************************************************/ -/* - * 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); /* \} */ diff --git a/include/FLAC/stream_decoder.h b/include/FLAC/stream_decoder.h index 7788a470..f43edfee 100644 --- a/include/FLAC/stream_decoder.h +++ b/include/FLAC/stream_decoder.h @@ -119,8 +119,8 @@ extern "C" { * * - 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 @@ -143,6 +143,23 @@ extern "C" { * 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 @@ -309,13 +326,13 @@ typedef struct { */ 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); /*********************************************************************** @@ -426,70 +443,310 @@ FLAC__bool FLAC__stream_decoder_set_error_callback(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); /* \} */ diff --git a/include/FLAC/stream_encoder.h b/include/FLAC/stream_encoder.h index 679eaef3..6380e9a0 100644 --- a/include/FLAC/stream_encoder.h +++ b/include/FLAC/stream_encoder.h @@ -563,8 +563,9 @@ FLAC__bool FLAC__stream_encoder_set_total_samples_estimate(FLAC__StreamEncoder * * 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 @@ -808,10 +809,11 @@ unsigned FLAC__stream_encoder_get_rice_parameter_search_dist(const FLAC__StreamE 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()