Home | History | Annotate | Download | only in FLAC
      1 /* libFLAC - Free Lossless Audio Codec library
      2  * Copyright (C) 2000-2009  Josh Coalson
      3  * Copyright (C) 2011-2014  Xiph.Org Foundation
      4  *
      5  * Redistribution and use in source and binary forms, with or without
      6  * modification, are permitted provided that the following conditions
      7  * are met:
      8  *
      9  * - Redistributions of source code must retain the above copyright
     10  * notice, this list of conditions and the following disclaimer.
     11  *
     12  * - Redistributions in binary form must reproduce the above copyright
     13  * notice, this list of conditions and the following disclaimer in the
     14  * documentation and/or other materials provided with the distribution.
     15  *
     16  * - Neither the name of the Xiph.org Foundation nor the names of its
     17  * contributors may be used to endorse or promote products derived from
     18  * this software without specific prior written permission.
     19  *
     20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
     21  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
     22  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
     23  * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
     24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
     25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
     26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
     27  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
     28  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
     29  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
     30  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     31  */
     32 
     33 #ifndef FLAC__STREAM_DECODER_H
     34 #define FLAC__STREAM_DECODER_H
     35 
     36 #include <stdio.h> /* for FILE */
     37 #include "export.h"
     38 #include "format.h"
     39 
     40 #ifdef __cplusplus
     41 extern "C" {
     42 #endif
     43 
     44 
     45 /** \file include/FLAC/stream_decoder.h
     46  *
     47  *  \brief
     48  *  This module contains the functions which implement the stream
     49  *  decoder.
     50  *
     51  *  See the detailed documentation in the
     52  *  \link flac_stream_decoder stream decoder \endlink module.
     53  */
     54 
     55 /** \defgroup flac_decoder FLAC/ \*_decoder.h: decoder interfaces
     56  *  \ingroup flac
     57  *
     58  *  \brief
     59  *  This module describes the decoder layers provided by libFLAC.
     60  *
     61  * The stream decoder can be used to decode complete streams either from
     62  * the client via callbacks, or directly from a file, depending on how
     63  * it is initialized.  When decoding via callbacks, the client provides
     64  * callbacks for reading FLAC data and writing decoded samples, and
     65  * handling metadata and errors.  If the client also supplies seek-related
     66  * callback, the decoder function for sample-accurate seeking within the
     67  * FLAC input is also available.  When decoding from a file, the client
     68  * needs only supply a filename or open \c FILE* and write/metadata/error
     69  * callbacks; the rest of the callbacks are supplied internally.  For more
     70  * info see the \link flac_stream_decoder stream decoder \endlink module.
     71  */
     72 
     73 /** \defgroup flac_stream_decoder FLAC/stream_decoder.h: stream decoder interface
     74  *  \ingroup flac_decoder
     75  *
     76  *  \brief
     77  *  This module contains the functions which implement the stream
     78  *  decoder.
     79  *
     80  * The stream decoder can decode native FLAC, and optionally Ogg FLAC
     81  * (check FLAC_API_SUPPORTS_OGG_FLAC) streams and files.
     82  *
     83  * The basic usage of this decoder is as follows:
     84  * - The program creates an instance of a decoder using
     85  *   FLAC__stream_decoder_new().
     86  * - The program overrides the default settings using
     87  *   FLAC__stream_decoder_set_*() functions.
     88  * - The program initializes the instance to validate the settings and
     89  *   prepare for decoding using
     90  *   - FLAC__stream_decoder_init_stream() or FLAC__stream_decoder_init_FILE()
     91  *     or FLAC__stream_decoder_init_file() for native FLAC,
     92  *   - FLAC__stream_decoder_init_ogg_stream() or FLAC__stream_decoder_init_ogg_FILE()
     93  *     or FLAC__stream_decoder_init_ogg_file() for Ogg FLAC
     94  * - The program calls the FLAC__stream_decoder_process_*() functions
     95  *   to decode data, which subsequently calls the callbacks.
     96  * - The program finishes the decoding with FLAC__stream_decoder_finish(),
     97  *   which flushes the input and output and resets the decoder to the
     98  *   uninitialized state.
     99  * - The instance may be used again or deleted with
    100  *   FLAC__stream_decoder_delete().
    101  *
    102  * In more detail, the program will create a new instance by calling
    103  * FLAC__stream_decoder_new(), then call FLAC__stream_decoder_set_*()
    104  * functions to override the default decoder options, and call
    105  * one of the FLAC__stream_decoder_init_*() functions.
    106  *
    107  * There are three initialization functions for native FLAC, one for
    108  * setting up the decoder to decode FLAC data from the client via
    109  * callbacks, and two for decoding directly from a FLAC file.
    110  *
    111  * For decoding via callbacks, use FLAC__stream_decoder_init_stream().
    112  * You must also supply several callbacks for handling I/O.  Some (like
    113  * seeking) are optional, depending on the capabilities of the input.
    114  *
    115  * For decoding directly from a file, use FLAC__stream_decoder_init_FILE()
    116  * or FLAC__stream_decoder_init_file().  Then you must only supply an open
    117  * \c FILE* or filename and fewer callbacks; the decoder will handle
    118  * the other callbacks internally.
    119  *
    120  * There are three similarly-named init functions for decoding from Ogg
    121  * FLAC streams.  Check \c FLAC_API_SUPPORTS_OGG_FLAC to find out if the
    122  * library has been built with Ogg support.
    123  *
    124  * Once the decoder is initialized, your program will call one of several
    125  * functions to start the decoding process:
    126  *
    127  * - FLAC__stream_decoder_process_single() - Tells the decoder to process at
    128  *   most one metadata block or audio frame and return, calling either the
    129  *   metadata callback or write callback, respectively, once.  If the decoder
    130  *   loses sync it will return with only the error callback being called.
    131  * - FLAC__stream_decoder_process_until_end_of_metadata() - Tells the decoder
    132  *   to process the stream from the current location and stop upon reaching
    133  *   the first audio frame.  The client will get one metadata, write, or error
    134  *   callback per metadata block, audio frame, or sync error, respectively.
    135  * - FLAC__stream_decoder_process_until_end_of_stream() - Tells the decoder
    136  *   to process the stream from the current location until the read callback
    137  *   returns FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM or
    138  *   FLAC__STREAM_DECODER_READ_STATUS_ABORT.  The client will get one metadata,
    139  *   write, or error callback per metadata block, audio frame, or sync error,
    140  *   respectively.
    141  *
    142  * When the decoder has finished decoding (normally or through an abort),
    143  * the instance is finished by calling FLAC__stream_decoder_finish(), which
    144  * ensures the decoder is in the correct state and frees memory.  Then the
    145  * instance may be deleted with FLAC__stream_decoder_delete() or initialized
    146  * again to decode another stream.
    147  *
    148  * Seeking is exposed through the FLAC__stream_decoder_seek_absolute() method.
    149  * At any point after the stream decoder has been initialized, the client can
    150  * call this function to seek to an exact sample within the stream.
    151  * Subsequently, the first time the write callback is called it will be
    152  * passed a (possibly partial) block starting at that sample.
    153  *
    154  * If the client cannot seek via the callback interface provided, but still
    155  * has another way of seeking, it can flush the decoder using
    156  * FLAC__stream_decoder_flush() and start feeding data from the new position
    157  * through the read callback.
    158  *
    159  * The stream decoder also provides MD5 signature checking.  If this is
    160  * turned on before initialization, FLAC__stream_decoder_finish() will
    161  * report when the decoded MD5 signature does not match the one stored
    162  * in the STREAMINFO block.  MD5 checking is automatically turned off
    163  * (until the next FLAC__stream_decoder_reset()) if there is no signature
    164  * in the STREAMINFO block or when a seek is attempted.
    165  *
    166  * The FLAC__stream_decoder_set_metadata_*() functions deserve special
    167  * attention.  By default, the decoder only calls the metadata_callback for
    168  * the STREAMINFO block.  These functions allow you to tell the decoder
    169  * explicitly which blocks to parse and return via the metadata_callback
    170  * and/or which to skip.  Use a FLAC__stream_decoder_set_metadata_respond_all(),
    171  * FLAC__stream_decoder_set_metadata_ignore() ... or FLAC__stream_decoder_set_metadata_ignore_all(),
    172  * FLAC__stream_decoder_set_metadata_respond() ... sequence to exactly specify
    173  * which blocks to return.  Remember that metadata blocks can potentially
    174  * be big (for example, cover art) so filtering out the ones you don't
    175  * use can reduce the memory requirements of the decoder.  Also note the
    176  * special forms FLAC__stream_decoder_set_metadata_respond_application(id)
    177  * and FLAC__stream_decoder_set_metadata_ignore_application(id) for
    178  * filtering APPLICATION blocks based on the application ID.
    179  *
    180  * STREAMINFO and SEEKTABLE blocks are always parsed and used internally, but
    181  * they still can legally be filtered from the metadata_callback.
    182  *
    183  * \note
    184  * The "set" functions may only be called when the decoder is in the
    185  * state FLAC__STREAM_DECODER_UNINITIALIZED, i.e. after
    186  * FLAC__stream_decoder_new() or FLAC__stream_decoder_finish(), but
    187  * before FLAC__stream_decoder_init_*().  If this is the case they will
    188  * return \c true, otherwise \c false.
    189  *
    190  * \note
    191  * FLAC__stream_decoder_finish() resets all settings to the constructor
    192  * defaults, including the callbacks.
    193  *
    194  * \{
    195  */
    196 
    197 
    198 /** State values for a FLAC__StreamDecoder
    199  *
    200  * The decoder's state can be obtained by calling FLAC__stream_decoder_get_state().
    201  */
    202 typedef enum {
    203 
    204 	FLAC__STREAM_DECODER_SEARCH_FOR_METADATA = 0,
    205 	/**< The decoder is ready to search for metadata. */
    206 
    207 	FLAC__STREAM_DECODER_READ_METADATA,
    208 	/**< The decoder is ready to or is in the process of reading metadata. */
    209 
    210 	FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC,
    211 	/**< The decoder is ready to or is in the process of searching for the
    212 	 * frame sync code.
    213 	 */
    214 
    215 	FLAC__STREAM_DECODER_READ_FRAME,
    216 	/**< The decoder is ready to or is in the process of reading a frame. */
    217 
    218 	FLAC__STREAM_DECODER_END_OF_STREAM,
    219 	/**< The decoder has reached the end of the stream. */
    220 
    221 	FLAC__STREAM_DECODER_OGG_ERROR,
    222 	/**< An error occurred in the underlying Ogg layer.  */
    223 
    224 	FLAC__STREAM_DECODER_SEEK_ERROR,
    225 	/**< An error occurred while seeking.  The decoder must be flushed
    226 	 * with FLAC__stream_decoder_flush() or reset with
    227 	 * FLAC__stream_decoder_reset() before decoding can continue.
    228 	 */
    229 
    230 	FLAC__STREAM_DECODER_ABORTED,
    231 	/**< The decoder was aborted by the read callback. */
    232 
    233 	FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
    234 	/**< An error occurred allocating memory.  The decoder is in an invalid
    235 	 * state and can no longer be used.
    236 	 */
    237 
    238 	FLAC__STREAM_DECODER_UNINITIALIZED
    239 	/**< The decoder is in the uninitialized state; one of the
    240 	 * FLAC__stream_decoder_init_*() functions must be called before samples
    241 	 * can be processed.
    242 	 */
    243 
    244 } FLAC__StreamDecoderState;
    245 
    246 /** Maps a FLAC__StreamDecoderState to a C string.
    247  *
    248  *  Using a FLAC__StreamDecoderState as the index to this array
    249  *  will give the string equivalent.  The contents should not be modified.
    250  */
    251 extern FLAC_API const char * const FLAC__StreamDecoderStateString[];
    252 
    253 
    254 /** Possible return values for the FLAC__stream_decoder_init_*() functions.
    255  */
    256 typedef enum {
    257 
    258 	FLAC__STREAM_DECODER_INIT_STATUS_OK = 0,
    259 	/**< Initialization was successful. */
    260 
    261 	FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER,
    262 	/**< The library was not compiled with support for the given container
    263 	 * format.
    264 	 */
    265 
    266 	FLAC__STREAM_DECODER_INIT_STATUS_INVALID_CALLBACKS,
    267 	/**< A required callback was not supplied. */
    268 
    269 	FLAC__STREAM_DECODER_INIT_STATUS_MEMORY_ALLOCATION_ERROR,
    270 	/**< An error occurred allocating memory. */
    271 
    272 	FLAC__STREAM_DECODER_INIT_STATUS_ERROR_OPENING_FILE,
    273 	/**< fopen() failed in FLAC__stream_decoder_init_file() or
    274 	 * FLAC__stream_decoder_init_ogg_file(). */
    275 
    276 	FLAC__STREAM_DECODER_INIT_STATUS_ALREADY_INITIALIZED
    277 	/**< FLAC__stream_decoder_init_*() was called when the decoder was
    278 	 * already initialized, usually because
    279 	 * FLAC__stream_decoder_finish() was not called.
    280 	 */
    281 
    282 } FLAC__StreamDecoderInitStatus;
    283 
    284 /** Maps a FLAC__StreamDecoderInitStatus to a C string.
    285  *
    286  *  Using a FLAC__StreamDecoderInitStatus as the index to this array
    287  *  will give the string equivalent.  The contents should not be modified.
    288  */
    289 extern FLAC_API const char * const FLAC__StreamDecoderInitStatusString[];
    290 
    291 
    292 /** Return values for the FLAC__StreamDecoder read callback.
    293  */
    294 typedef enum {
    295 
    296 	FLAC__STREAM_DECODER_READ_STATUS_CONTINUE,
    297 	/**< The read was OK and decoding can continue. */
    298 
    299 	FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM,
    300 	/**< The read was attempted while at the end of the stream.  Note that
    301 	 * the client must only return this value when the read callback was
    302 	 * called when already at the end of the stream.  Otherwise, if the read
    303 	 * itself moves to the end of the stream, the client should still return
    304 	 * the data and \c FLAC__STREAM_DECODER_READ_STATUS_CONTINUE, and then on
    305 	 * the next read callback it should return
    306 	 * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM with a byte count
    307 	 * of \c 0.
    308 	 */
    309 
    310 	FLAC__STREAM_DECODER_READ_STATUS_ABORT
    311 	/**< An unrecoverable error occurred.  The decoder will return from the process call. */
    312 
    313 } FLAC__StreamDecoderReadStatus;
    314 
    315 /** Maps a FLAC__StreamDecoderReadStatus to a C string.
    316  *
    317  *  Using a FLAC__StreamDecoderReadStatus as the index to this array
    318  *  will give the string equivalent.  The contents should not be modified.
    319  */
    320 extern FLAC_API const char * const FLAC__StreamDecoderReadStatusString[];
    321 
    322 
    323 /** Return values for the FLAC__StreamDecoder seek callback.
    324  */
    325 typedef enum {
    326 
    327 	FLAC__STREAM_DECODER_SEEK_STATUS_OK,
    328 	/**< The seek was OK and decoding can continue. */
    329 
    330 	FLAC__STREAM_DECODER_SEEK_STATUS_ERROR,
    331 	/**< An unrecoverable error occurred.  The decoder will return from the process call. */
    332 
    333 	FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
    334 	/**< Client does not support seeking. */
    335 
    336 } FLAC__StreamDecoderSeekStatus;
    337 
    338 /** Maps a FLAC__StreamDecoderSeekStatus to a C string.
    339  *
    340  *  Using a FLAC__StreamDecoderSeekStatus as the index to this array
    341  *  will give the string equivalent.  The contents should not be modified.
    342  */
    343 extern FLAC_API const char * const FLAC__StreamDecoderSeekStatusString[];
    344 
    345 
    346 /** Return values for the FLAC__StreamDecoder tell callback.
    347  */
    348 typedef enum {
    349 
    350 	FLAC__STREAM_DECODER_TELL_STATUS_OK,
    351 	/**< The tell was OK and decoding can continue. */
    352 
    353 	FLAC__STREAM_DECODER_TELL_STATUS_ERROR,
    354 	/**< An unrecoverable error occurred.  The decoder will return from the process call. */
    355 
    356 	FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
    357 	/**< Client does not support telling the position. */
    358 
    359 } FLAC__StreamDecoderTellStatus;
    360 
    361 /** Maps a FLAC__StreamDecoderTellStatus to a C string.
    362  *
    363  *  Using a FLAC__StreamDecoderTellStatus as the index to this array
    364  *  will give the string equivalent.  The contents should not be modified.
    365  */
    366 extern FLAC_API const char * const FLAC__StreamDecoderTellStatusString[];
    367 
    368 
    369 /** Return values for the FLAC__StreamDecoder length callback.
    370  */
    371 typedef enum {
    372 
    373 	FLAC__STREAM_DECODER_LENGTH_STATUS_OK,
    374 	/**< The length call was OK and decoding can continue. */
    375 
    376 	FLAC__STREAM_DECODER_LENGTH_STATUS_ERROR,
    377 	/**< An unrecoverable error occurred.  The decoder will return from the process call. */
    378 
    379 	FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
    380 	/**< Client does not support reporting the length. */
    381 
    382 } FLAC__StreamDecoderLengthStatus;
    383 
    384 /** Maps a FLAC__StreamDecoderLengthStatus to a C string.
    385  *
    386  *  Using a FLAC__StreamDecoderLengthStatus as the index to this array
    387  *  will give the string equivalent.  The contents should not be modified.
    388  */
    389 extern FLAC_API const char * const FLAC__StreamDecoderLengthStatusString[];
    390 
    391 
    392 /** Return values for the FLAC__StreamDecoder write callback.
    393  */
    394 typedef enum {
    395 
    396 	FLAC__STREAM_DECODER_WRITE_STATUS_CONTINUE,
    397 	/**< The write was OK and decoding can continue. */
    398 
    399 	FLAC__STREAM_DECODER_WRITE_STATUS_ABORT
    400 	/**< An unrecoverable error occurred.  The decoder will return from the process call. */
    401 
    402 } FLAC__StreamDecoderWriteStatus;
    403 
    404 /** Maps a FLAC__StreamDecoderWriteStatus to a C string.
    405  *
    406  *  Using a FLAC__StreamDecoderWriteStatus as the index to this array
    407  *  will give the string equivalent.  The contents should not be modified.
    408  */
    409 extern FLAC_API const char * const FLAC__StreamDecoderWriteStatusString[];
    410 
    411 
    412 /** Possible values passed back to the FLAC__StreamDecoder error callback.
    413  *  \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC is the generic catch-
    414  *  all.  The rest could be caused by bad sync (false synchronization on
    415  *  data that is not the start of a frame) or corrupted data.  The error
    416  *  itself is the decoder's best guess at what happened assuming a correct
    417  *  sync.  For example \c FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER
    418  *  could be caused by a correct sync on the start of a frame, but some
    419  *  data in the frame header was corrupted.  Or it could be the result of
    420  *  syncing on a point the stream that looked like the starting of a frame
    421  *  but was not.  \c FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM
    422  *  could be because the decoder encountered a valid frame made by a future
    423  *  version of the encoder which it cannot parse, or because of a false
    424  *  sync making it appear as though an encountered frame was generated by
    425  *  a future encoder.
    426  */
    427 typedef enum {
    428 
    429 	FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC,
    430 	/**< An error in the stream caused the decoder to lose synchronization. */
    431 
    432 	FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER,
    433 	/**< The decoder encountered a corrupted frame header. */
    434 
    435 	FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH,
    436 	/**< The frame's data did not match the CRC in the footer. */
    437 
    438 	FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM
    439 	/**< The decoder encountered reserved fields in use in the stream. */
    440 
    441 } FLAC__StreamDecoderErrorStatus;
    442 
    443 /** Maps a FLAC__StreamDecoderErrorStatus to a C string.
    444  *
    445  *  Using a FLAC__StreamDecoderErrorStatus as the index to this array
    446  *  will give the string equivalent.  The contents should not be modified.
    447  */
    448 extern FLAC_API const char * const FLAC__StreamDecoderErrorStatusString[];
    449 
    450 
    451 /***********************************************************************
    452  *
    453  * class FLAC__StreamDecoder
    454  *
    455  ***********************************************************************/
    456 
    457 struct FLAC__StreamDecoderProtected;
    458 struct FLAC__StreamDecoderPrivate;
    459 /** The opaque structure definition for the stream decoder type.
    460  *  See the \link flac_stream_decoder stream decoder module \endlink
    461  *  for a detailed description.
    462  */
    463 typedef struct {
    464 	struct FLAC__StreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
    465 	struct FLAC__StreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
    466 } FLAC__StreamDecoder;
    467 
    468 /** Signature for the read callback.
    469  *
    470  *  A function pointer matching this signature must be passed to
    471  *  FLAC__stream_decoder_init*_stream(). The supplied function will be
    472  *  called when the decoder needs more input data.  The address of the
    473  *  buffer to be filled is supplied, along with the number of bytes the
    474  *  buffer can hold.  The callback may choose to supply less data and
    475  *  modify the byte count but must be careful not to overflow the buffer.
    476  *  The callback then returns a status code chosen from
    477  *  FLAC__StreamDecoderReadStatus.
    478  *
    479  * Here is an example of a read callback for stdio streams:
    480  * \code
    481  * FLAC__StreamDecoderReadStatus read_cb(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], size_t *bytes, void *client_data)
    482  * {
    483  *   FILE *file = ((MyClientData*)client_data)->file;
    484  *   if(*bytes > 0) {
    485  *     *bytes = fread(buffer, sizeof(FLAC__byte), *bytes, file);
    486  *     if(ferror(file))
    487  *       return FLAC__STREAM_DECODER_READ_STATUS_ABORT;
    488  *     else if(*bytes == 0)
    489  *       return FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM;
    490  *     else
    491  *       return FLAC__STREAM_DECODER_READ_STATUS_CONTINUE;
    492  *   }
    493  *   else
    494  *     return FLAC__STREAM_DECODER_READ_STATUS_ABORT;
    495  * }
    496  * \endcode
    497  *
    498  * \note In general, FLAC__StreamDecoder functions which change the
    499  * state should not be called on the \a decoder while in the callback.
    500  *
    501  * \param  decoder  The decoder instance calling the callback.
    502  * \param  buffer   A pointer to a location for the callee to store
    503  *                  data to be decoded.
    504  * \param  bytes    A pointer to the size of the buffer.  On entry
    505  *                  to the callback, it contains the maximum number
    506  *                  of bytes that may be stored in \a buffer.  The
    507  *                  callee must set it to the actual number of bytes
    508  *                  stored (0 in case of error or end-of-stream) before
    509  *                  returning.
    510  * \param  client_data  The callee's client data set through
    511  *                      FLAC__stream_decoder_init_*().
    512  * \retval FLAC__StreamDecoderReadStatus
    513  *    The callee's return status.  Note that the callback should return
    514  *    \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM if and only if
    515  *    zero bytes were read and there is no more data to be read.
    516  */
    517 typedef FLAC__StreamDecoderReadStatus (*FLAC__StreamDecoderReadCallback)(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], size_t *bytes, void *client_data);
    518 
    519 /** Signature for the seek callback.
    520  *
    521  *  A function pointer matching this signature may be passed to
    522  *  FLAC__stream_decoder_init*_stream().  The supplied function will be
    523  *  called when the decoder needs to seek the input stream.  The decoder
    524  *  will pass the absolute byte offset to seek to, 0 meaning the
    525  *  beginning of the stream.
    526  *
    527  * Here is an example of a seek callback for stdio streams:
    528  * \code
    529  * FLAC__StreamDecoderSeekStatus seek_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data)
    530  * {
    531  *   FILE *file = ((MyClientData*)client_data)->file;
    532  *   if(file == stdin)
    533  *     return FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED;
    534  *   else if(fseeko(file, (off_t)absolute_byte_offset, SEEK_SET) < 0)
    535  *     return FLAC__STREAM_DECODER_SEEK_STATUS_ERROR;
    536  *   else
    537  *     return FLAC__STREAM_DECODER_SEEK_STATUS_OK;
    538  * }
    539  * \endcode
    540  *
    541  * \note In general, FLAC__StreamDecoder functions which change the
    542  * state should not be called on the \a decoder while in the callback.
    543  *
    544  * \param  decoder  The decoder instance calling the callback.
    545  * \param  absolute_byte_offset  The offset from the beginning of the stream
    546  *                               to seek to.
    547  * \param  client_data  The callee's client data set through
    548  *                      FLAC__stream_decoder_init_*().
    549  * \retval FLAC__StreamDecoderSeekStatus
    550  *    The callee's return status.
    551  */
    552 typedef FLAC__StreamDecoderSeekStatus (*FLAC__StreamDecoderSeekCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
    553 
    554 /** Signature for the tell callback.
    555  *
    556  *  A function pointer matching this signature may be passed to
    557  *  FLAC__stream_decoder_init*_stream().  The supplied function will be
    558  *  called when the decoder wants to know the current position of the
    559  *  stream.  The callback should return the byte offset from the
    560  *  beginning of the stream.
    561  *
    562  * Here is an example of a tell callback for stdio streams:
    563  * \code
    564  * FLAC__StreamDecoderTellStatus tell_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data)
    565  * {
    566  *   FILE *file = ((MyClientData*)client_data)->file;
    567  *   off_t pos;
    568  *   if(file == stdin)
    569  *     return FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED;
    570  *   else if((pos = ftello(file)) < 0)
    571  *     return FLAC__STREAM_DECODER_TELL_STATUS_ERROR;
    572  *   else {
    573  *     *absolute_byte_offset = (FLAC__uint64)pos;
    574  *     return FLAC__STREAM_DECODER_TELL_STATUS_OK;
    575  *   }
    576  * }
    577  * \endcode
    578  *
    579  * \note In general, FLAC__StreamDecoder functions which change the
    580  * state should not be called on the \a decoder while in the callback.
    581  *
    582  * \param  decoder  The decoder instance calling the callback.
    583  * \param  absolute_byte_offset  A pointer to storage for the current offset
    584  *                               from the beginning of the stream.
    585  * \param  client_data  The callee's client data set through
    586  *                      FLAC__stream_decoder_init_*().
    587  * \retval FLAC__StreamDecoderTellStatus
    588  *    The callee's return status.
    589  */
    590 typedef FLAC__StreamDecoderTellStatus (*FLAC__StreamDecoderTellCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
    591 
    592 /** Signature for the length callback.
    593  *
    594  *  A function pointer matching this signature may be passed to
    595  *  FLAC__stream_decoder_init*_stream().  The supplied function will be
    596  *  called when the decoder wants to know the total length of the stream
    597  *  in bytes.
    598  *
    599  * Here is an example of a length callback for stdio streams:
    600  * \code
    601  * FLAC__StreamDecoderLengthStatus length_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data)
    602  * {
    603  *   FILE *file = ((MyClientData*)client_data)->file;
    604  *   struct stat filestats;
    605  *
    606  *   if(file == stdin)
    607  *     return FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED;
    608  *   else if(fstat(fileno(file), &filestats) != 0)
    609  *     return FLAC__STREAM_DECODER_LENGTH_STATUS_ERROR;
    610  *   else {
    611  *     *stream_length = (FLAC__uint64)filestats.st_size;
    612  *     return FLAC__STREAM_DECODER_LENGTH_STATUS_OK;
    613  *   }
    614  * }
    615  * \endcode
    616  *
    617  * \note In general, FLAC__StreamDecoder functions which change the
    618  * state should not be called on the \a decoder while in the callback.
    619  *
    620  * \param  decoder  The decoder instance calling the callback.
    621  * \param  stream_length  A pointer to storage for the length of the stream
    622  *                        in bytes.
    623  * \param  client_data  The callee's client data set through
    624  *                      FLAC__stream_decoder_init_*().
    625  * \retval FLAC__StreamDecoderLengthStatus
    626  *    The callee's return status.
    627  */
    628 typedef FLAC__StreamDecoderLengthStatus (*FLAC__StreamDecoderLengthCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
    629 
    630 /** Signature for the EOF callback.
    631  *
    632  *  A function pointer matching this signature may be passed to
    633  *  FLAC__stream_decoder_init*_stream().  The supplied function will be
    634  *  called when the decoder needs to know if the end of the stream has
    635  *  been reached.
    636  *
    637  * Here is an example of a EOF callback for stdio streams:
    638  * FLAC__bool eof_cb(const FLAC__StreamDecoder *decoder, void *client_data)
    639  * \code
    640  * {
    641  *   FILE *file = ((MyClientData*)client_data)->file;
    642  *   return feof(file)? true : false;
    643  * }
    644  * \endcode
    645  *
    646  * \note In general, FLAC__StreamDecoder functions which change the
    647  * state should not be called on the \a decoder while in the callback.
    648  *
    649  * \param  decoder  The decoder instance calling the callback.
    650  * \param  client_data  The callee's client data set through
    651  *                      FLAC__stream_decoder_init_*().
    652  * \retval FLAC__bool
    653  *    \c true if the currently at the end of the stream, else \c false.
    654  */
    655 typedef FLAC__bool (*FLAC__StreamDecoderEofCallback)(const FLAC__StreamDecoder *decoder, void *client_data);
    656 
    657 /** Signature for the write callback.
    658  *
    659  *  A function pointer matching this signature must be passed to one of
    660  *  the FLAC__stream_decoder_init_*() functions.
    661  *  The supplied function will be called when the decoder has decoded a
    662  *  single audio frame.  The decoder will pass the frame metadata as well
    663  *  as an array of pointers (one for each channel) pointing to the
    664  *  decoded audio.
    665  *
    666  * \note In general, FLAC__StreamDecoder functions which change the
    667  * state should not be called on the \a decoder while in the callback.
    668  *
    669  * \param  decoder  The decoder instance calling the callback.
    670  * \param  frame    The description of the decoded frame.  See
    671  *                  FLAC__Frame.
    672  * \param  buffer   An array of pointers to decoded channels of data.
    673  *                  Each pointer will point to an array of signed
    674  *                  samples of length \a frame->header.blocksize.
    675  *                  Channels will be ordered according to the FLAC
    676  *                  specification; see the documentation for the
    677  *                  <A HREF="../format.html#frame_header">frame header</A>.
    678  * \param  client_data  The callee's client data set through
    679  *                      FLAC__stream_decoder_init_*().
    680  * \retval FLAC__StreamDecoderWriteStatus
    681  *    The callee's return status.
    682  */
    683 typedef FLAC__StreamDecoderWriteStatus (*FLAC__StreamDecoderWriteCallback)(const FLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
    684 
    685 /** Signature for the metadata callback.
    686  *
    687  *  A function pointer matching this signature must be passed to one of
    688  *  the FLAC__stream_decoder_init_*() functions.
    689  *  The supplied function will be called when the decoder has decoded a
    690  *  metadata block.  In a valid FLAC file there will always be one
    691  *  \c STREAMINFO block, followed by zero or more other metadata blocks.
    692  *  These will be supplied by the decoder in the same order as they
    693  *  appear in the stream and always before the first audio frame (i.e.
    694  *  write callback).  The metadata block that is passed in must not be
    695  *  modified, and it doesn't live beyond the callback, so you should make
    696  *  a copy of it with FLAC__metadata_object_clone() if you will need it
    697  *  elsewhere.  Since metadata blocks can potentially be large, by
    698  *  default the decoder only calls the metadata callback for the
    699  *  \c STREAMINFO block; you can instruct the decoder to pass or filter
    700  *  other blocks with FLAC__stream_decoder_set_metadata_*() calls.
    701  *
    702  * \note In general, FLAC__StreamDecoder functions which change the
    703  * state should not be called on the \a decoder while in the callback.
    704  *
    705  * \param  decoder  The decoder instance calling the callback.
    706  * \param  metadata The decoded metadata block.
    707  * \param  client_data  The callee's client data set through
    708  *                      FLAC__stream_decoder_init_*().
    709  */
    710 typedef void (*FLAC__StreamDecoderMetadataCallback)(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
    711 
    712 /** Signature for the error callback.
    713  *
    714  *  A function pointer matching this signature must be passed to one of
    715  *  the FLAC__stream_decoder_init_*() functions.
    716  *  The supplied function will be called whenever an error occurs during
    717  *  decoding.
    718  *
    719  * \note In general, FLAC__StreamDecoder functions which change the
    720  * state should not be called on the \a decoder while in the callback.
    721  *
    722  * \param  decoder  The decoder instance calling the callback.
    723  * \param  status   The error encountered by the decoder.
    724  * \param  client_data  The callee's client data set through
    725  *                      FLAC__stream_decoder_init_*().
    726  */
    727 typedef void (*FLAC__StreamDecoderErrorCallback)(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
    728 
    729 
    730 /***********************************************************************
    731  *
    732  * Class constructor/destructor
    733  *
    734  ***********************************************************************/
    735 
    736 /** Create a new stream decoder instance.  The instance is created with
    737  *  default settings; see the individual FLAC__stream_decoder_set_*()
    738  *  functions for each setting's default.
    739  *
    740  * \retval FLAC__StreamDecoder*
    741  *    \c NULL if there was an error allocating memory, else the new instance.
    742  */
    743 FLAC_API FLAC__StreamDecoder *FLAC__stream_decoder_new(void);
    744 
    745 /** Free a decoder instance.  Deletes the object pointed to by \a decoder.
    746  *
    747  * \param decoder  A pointer to an existing decoder.
    748  * \assert
    749  *    \code decoder != NULL \endcode
    750  */
    751 FLAC_API void FLAC__stream_decoder_delete(FLAC__StreamDecoder *decoder);
    752 
    753 
    754 /***********************************************************************
    755  *
    756  * Public class method prototypes
    757  *
    758  ***********************************************************************/
    759 
    760 /** Set the serial number for the FLAC stream within the Ogg container.
    761  *  The default behavior is to use the serial number of the first Ogg
    762  *  page.  Setting a serial number here will explicitly specify which
    763  *  stream is to be decoded.
    764  *
    765  * \note
    766  * This does not need to be set for native FLAC decoding.
    767  *
    768  * \default \c use serial number of first page
    769  * \param  decoder        A decoder instance to set.
    770  * \param  serial_number  See above.
    771  * \assert
    772  *    \code decoder != NULL \endcode
    773  * \retval FLAC__bool
    774  *    \c false if the decoder is already initialized, else \c true.
    775  */
    776 FLAC_API FLAC__bool FLAC__stream_decoder_set_ogg_serial_number(FLAC__StreamDecoder *decoder, long serial_number);
    777 
    778 /** Set the "MD5 signature checking" flag.  If \c true, the decoder will
    779  *  compute the MD5 signature of the unencoded audio data while decoding
    780  *  and compare it to the signature from the STREAMINFO block, if it
    781  *  exists, during FLAC__stream_decoder_finish().
    782  *
    783  *  MD5 signature checking will be turned off (until the next
    784  *  FLAC__stream_decoder_reset()) if there is no signature in the
    785  *  STREAMINFO block or when a seek is attempted.
    786  *
    787  *  Clients that do not use the MD5 check should leave this off to speed
    788  *  up decoding.
    789  *
    790  * \default \c false
    791  * \param  decoder  A decoder instance to set.
    792  * \param  value    Flag value (see above).
    793  * \assert
    794  *    \code decoder != NULL \endcode
    795  * \retval FLAC__bool
    796  *    \c false if the decoder is already initialized, else \c true.
    797  */
    798 FLAC_API FLAC__bool FLAC__stream_decoder_set_md5_checking(FLAC__StreamDecoder *decoder, FLAC__bool value);
    799 
    800 /** Direct the decoder to pass on all metadata blocks of type \a type.
    801  *
    802  * \default By default, only the \c STREAMINFO block is returned via the
    803  *          metadata callback.
    804  * \param  decoder  A decoder instance to set.
    805  * \param  type     See above.
    806  * \assert
    807  *    \code decoder != NULL \endcode
    808  *    \a type is valid
    809  * \retval FLAC__bool
    810  *    \c false if the decoder is already initialized, else \c true.
    811  */
    812 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
    813 
    814 /** Direct the decoder to pass on all APPLICATION metadata blocks of the
    815  *  given \a id.
    816  *
    817  * \default By default, only the \c STREAMINFO block is returned via the
    818  *          metadata callback.
    819  * \param  decoder  A decoder instance to set.
    820  * \param  id       See above.
    821  * \assert
    822  *    \code decoder != NULL \endcode
    823  *    \code id != NULL \endcode
    824  * \retval FLAC__bool
    825  *    \c false if the decoder is already initialized, else \c true.
    826  */
    827 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
    828 
    829 /** Direct the decoder to pass on all metadata blocks of any type.
    830  *
    831  * \default By default, only the \c STREAMINFO block is returned via the
    832  *          metadata callback.
    833  * \param  decoder  A decoder instance to set.
    834  * \assert
    835  *    \code decoder != NULL \endcode
    836  * \retval FLAC__bool
    837  *    \c false if the decoder is already initialized, else \c true.
    838  */
    839 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_all(FLAC__StreamDecoder *decoder);
    840 
    841 /** Direct the decoder to filter out all metadata blocks of type \a type.
    842  *
    843  * \default By default, only the \c STREAMINFO block is returned via the
    844  *          metadata callback.
    845  * \param  decoder  A decoder instance to set.
    846  * \param  type     See above.
    847  * \assert
    848  *    \code decoder != NULL \endcode
    849  *    \a type is valid
    850  * \retval FLAC__bool
    851  *    \c false if the decoder is already initialized, else \c true.
    852  */
    853 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
    854 
    855 /** Direct the decoder to filter out all APPLICATION metadata blocks of
    856  *  the given \a id.
    857  *
    858  * \default By default, only the \c STREAMINFO block is returned via the
    859  *          metadata callback.
    860  * \param  decoder  A decoder instance to set.
    861  * \param  id       See above.
    862  * \assert
    863  *    \code decoder != NULL \endcode
    864  *    \code id != NULL \endcode
    865  * \retval FLAC__bool
    866  *    \c false if the decoder is already initialized, else \c true.
    867  */
    868 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
    869 
    870 /** Direct the decoder to filter out all metadata blocks of any type.
    871  *
    872  * \default By default, only the \c STREAMINFO block is returned via the
    873  *          metadata callback.
    874  * \param  decoder  A decoder instance to set.
    875  * \assert
    876  *    \code decoder != NULL \endcode
    877  * \retval FLAC__bool
    878  *    \c false if the decoder is already initialized, else \c true.
    879  */
    880 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_all(FLAC__StreamDecoder *decoder);
    881 
    882 /** Get the current decoder state.
    883  *
    884  * \param  decoder  A decoder instance to query.
    885  * \assert
    886  *    \code decoder != NULL \endcode
    887  * \retval FLAC__StreamDecoderState
    888  *    The current decoder state.
    889  */
    890 FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_get_state(const FLAC__StreamDecoder *decoder);
    891 
    892 /** Get the current decoder state as a C string.
    893  *
    894  * \param  decoder  A decoder instance to query.
    895  * \assert
    896  *    \code decoder != NULL \endcode
    897  * \retval const char *
    898  *    The decoder state as a C string.  Do not modify the contents.
    899  */
    900 FLAC_API const char *FLAC__stream_decoder_get_resolved_state_string(const FLAC__StreamDecoder *decoder);
    901 
    902 /** Get the "MD5 signature checking" flag.
    903  *  This is the value of the setting, not whether or not the decoder is
    904  *  currently checking the MD5 (remember, it can be turned off automatically
    905  *  by a seek).  When the decoder is reset the flag will be restored to the
    906  *  value returned by this function.
    907  *
    908  * \param  decoder  A decoder instance to query.
    909  * \assert
    910  *    \code decoder != NULL \endcode
    911  * \retval FLAC__bool
    912  *    See above.
    913  */
    914 FLAC_API FLAC__bool FLAC__stream_decoder_get_md5_checking(const FLAC__StreamDecoder *decoder);
    915 
    916 /** Get the total number of samples in the stream being decoded.
    917  *  Will only be valid after decoding has started and will contain the
    918  *  value from the \c STREAMINFO block.  A value of \c 0 means "unknown".
    919  *
    920  * \param  decoder  A decoder instance to query.
    921  * \assert
    922  *    \code decoder != NULL \endcode
    923  * \retval unsigned
    924  *    See above.
    925  */
    926 FLAC_API FLAC__uint64 FLAC__stream_decoder_get_total_samples(const FLAC__StreamDecoder *decoder);
    927 
    928 /** Get the current number of channels in the stream being decoded.
    929  *  Will only be valid after decoding has started and will contain the
    930  *  value from the most recently decoded frame header.
    931  *
    932  * \param  decoder  A decoder instance to query.
    933  * \assert
    934  *    \code decoder != NULL \endcode
    935  * \retval unsigned
    936  *    See above.
    937  */
    938 FLAC_API unsigned FLAC__stream_decoder_get_channels(const FLAC__StreamDecoder *decoder);
    939 
    940 /** Get the current channel assignment in the stream being decoded.
    941  *  Will only be valid after decoding has started and will contain the
    942  *  value from the most recently decoded frame header.
    943  *
    944  * \param  decoder  A decoder instance to query.
    945  * \assert
    946  *    \code decoder != NULL \endcode
    947  * \retval FLAC__ChannelAssignment
    948  *    See above.
    949  */
    950 FLAC_API FLAC__ChannelAssignment FLAC__stream_decoder_get_channel_assignment(const FLAC__StreamDecoder *decoder);
    951 
    952 /** Get the current sample resolution in the stream being decoded.
    953  *  Will only be valid after decoding has started and will contain the
    954  *  value from the most recently decoded frame header.
    955  *
    956  * \param  decoder  A decoder instance to query.
    957  * \assert
    958  *    \code decoder != NULL \endcode
    959  * \retval unsigned
    960  *    See above.
    961  */
    962 FLAC_API unsigned FLAC__stream_decoder_get_bits_per_sample(const FLAC__StreamDecoder *decoder);
    963 
    964 /** Get the current sample rate in Hz of the stream being decoded.
    965  *  Will only be valid after decoding has started and will contain the
    966  *  value from the most recently decoded frame header.
    967  *
    968  * \param  decoder  A decoder instance to query.
    969  * \assert
    970  *    \code decoder != NULL \endcode
    971  * \retval unsigned
    972  *    See above.
    973  */
    974 FLAC_API unsigned FLAC__stream_decoder_get_sample_rate(const FLAC__StreamDecoder *decoder);
    975 
    976 /** Get the current blocksize of the stream being decoded.
    977  *  Will only be valid after decoding has started and will contain the
    978  *  value from the most recently decoded frame header.
    979  *
    980  * \param  decoder  A decoder instance to query.
    981  * \assert
    982  *    \code decoder != NULL \endcode
    983  * \retval unsigned
    984  *    See above.
    985  */
    986 FLAC_API unsigned FLAC__stream_decoder_get_blocksize(const FLAC__StreamDecoder *decoder);
    987 
    988 /** Returns the decoder's current read position within the stream.
    989  *  The position is the byte offset from the start of the stream.
    990  *  Bytes before this position have been fully decoded.  Note that
    991  *  there may still be undecoded bytes in the decoder's read FIFO.
    992  *  The returned position is correct even after a seek.
    993  *
    994  *  \warning This function currently only works for native FLAC,
    995  *           not Ogg FLAC streams.
    996  *
    997  * \param  decoder   A decoder instance to query.
    998  * \param  position  Address at which to return the desired position.
    999  * \assert
   1000  *    \code decoder != NULL \endcode
   1001  *    \code position != NULL \endcode
   1002  * \retval FLAC__bool
   1003  *    \c true if successful, \c false if the stream is not native FLAC,
   1004  *    or there was an error from the 'tell' callback or it returned
   1005  *    \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED.
   1006  */
   1007 FLAC_API FLAC__bool FLAC__stream_decoder_get_decode_position(const FLAC__StreamDecoder *decoder, FLAC__uint64 *position);
   1008 
   1009 /** Initialize the decoder instance to decode native FLAC streams.
   1010  *
   1011  *  This flavor of initialization sets up the decoder to decode from a
   1012  *  native FLAC stream. I/O is performed via callbacks to the client.
   1013  *  For decoding from a plain file via filename or open FILE*,
   1014  *  FLAC__stream_decoder_init_file() and FLAC__stream_decoder_init_FILE()
   1015  *  provide a simpler interface.
   1016  *
   1017  *  This function should be called after FLAC__stream_decoder_new() and
   1018  *  FLAC__stream_decoder_set_*() but before any of the
   1019  *  FLAC__stream_decoder_process_*() functions.  Will set and return the
   1020  *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
   1021  *  if initialization succeeded.
   1022  *
   1023  * \param  decoder            An uninitialized decoder instance.
   1024  * \param  read_callback      See FLAC__StreamDecoderReadCallback.  This
   1025  *                            pointer must not be \c NULL.
   1026  * \param  seek_callback      See FLAC__StreamDecoderSeekCallback.  This
   1027  *                            pointer may be \c NULL if seeking is not
   1028  *                            supported.  If \a seek_callback is not \c NULL then a
   1029  *                            \a tell_callback, \a length_callback, and \a eof_callback must also be supplied.
   1030  *                            Alternatively, a dummy seek callback that just
   1031  *                            returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
   1032  *                            may also be supplied, all though this is slightly
   1033  *                            less efficient for the decoder.
   1034  * \param  tell_callback      See FLAC__StreamDecoderTellCallback.  This
   1035  *                            pointer may be \c NULL if not supported by the client.  If
   1036  *                            \a seek_callback is not \c NULL then a
   1037  *                            \a tell_callback must also be supplied.
   1038  *                            Alternatively, a dummy tell callback that just
   1039  *                            returns \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
   1040  *                            may also be supplied, all though this is slightly
   1041  *                            less efficient for the decoder.
   1042  * \param  length_callback    See FLAC__StreamDecoderLengthCallback.  This
   1043  *                            pointer may be \c NULL if not supported by the client.  If
   1044  *                            \a seek_callback is not \c NULL then a
   1045  *                            \a length_callback must also be supplied.
   1046  *                            Alternatively, a dummy length callback that just
   1047  *                            returns \c FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
   1048  *                            may also be supplied, all though this is slightly
   1049  *                            less efficient for the decoder.
   1050  * \param  eof_callback       See FLAC__StreamDecoderEofCallback.  This
   1051  *                            pointer may be \c NULL if not supported by the client.  If
   1052  *                            \a seek_callback is not \c NULL then a
   1053  *                            \a eof_callback must also be supplied.
   1054  *                            Alternatively, a dummy length callback that just
   1055  *                            returns \c false
   1056  *                            may also be supplied, all though this is slightly
   1057  *                            less efficient for the decoder.
   1058  * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
   1059  *                            pointer must not be \c NULL.
   1060  * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
   1061  *                            pointer may be \c NULL if the callback is not
   1062  *                            desired.
   1063  * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
   1064  *                            pointer must not be \c NULL.
   1065  * \param  client_data        This value will be supplied to callbacks in their
   1066  *                            \a client_data argument.
   1067  * \assert
   1068  *    \code decoder != NULL \endcode
   1069  * \retval FLAC__StreamDecoderInitStatus
   1070  *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
   1071  *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
   1072  */
   1073 FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_stream(
   1074 	FLAC__StreamDecoder *decoder,
   1075 	FLAC__StreamDecoderReadCallback read_callback,
   1076 	FLAC__StreamDecoderSeekCallback seek_callback,
   1077 	FLAC__StreamDecoderTellCallback tell_callback,
   1078 	FLAC__StreamDecoderLengthCallback length_callback,
   1079 	FLAC__StreamDecoderEofCallback eof_callback,
   1080 	FLAC__StreamDecoderWriteCallback write_callback,
   1081 	FLAC__StreamDecoderMetadataCallback metadata_callback,
   1082 	FLAC__StreamDecoderErrorCallback error_callback,
   1083 	void *client_data
   1084 );
   1085 
   1086 /** Initialize the decoder instance to decode Ogg FLAC streams.
   1087  *
   1088  *  This flavor of initialization sets up the decoder to decode from a
   1089  *  FLAC stream in an Ogg container. I/O is performed via callbacks to the
   1090  *  client.  For decoding from a plain file via filename or open FILE*,
   1091  *  FLAC__stream_decoder_init_ogg_file() and FLAC__stream_decoder_init_ogg_FILE()
   1092  *  provide a simpler interface.
   1093  *
   1094  *  This function should be called after FLAC__stream_decoder_new() and
   1095  *  FLAC__stream_decoder_set_*() but before any of the
   1096  *  FLAC__stream_decoder_process_*() functions.  Will set and return the
   1097  *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
   1098  *  if initialization succeeded.
   1099  *
   1100  *  \note Support for Ogg FLAC in the library is optional.  If this
   1101  *  library has been built without support for Ogg FLAC, this function
   1102  *  will return \c FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER.
   1103  *
   1104  * \param  decoder            An uninitialized decoder instance.
   1105  * \param  read_callback      See FLAC__StreamDecoderReadCallback.  This
   1106  *                            pointer must not be \c NULL.
   1107  * \param  seek_callback      See FLAC__StreamDecoderSeekCallback.  This
   1108  *                            pointer may be \c NULL if seeking is not
   1109  *                            supported.  If \a seek_callback is not \c NULL then a
   1110  *                            \a tell_callback, \a length_callback, and \a eof_callback must also be supplied.
   1111  *                            Alternatively, a dummy seek callback that just
   1112  *                            returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
   1113  *                            may also be supplied, all though this is slightly
   1114  *                            less efficient for the decoder.
   1115  * \param  tell_callback      See FLAC__StreamDecoderTellCallback.  This
   1116  *                            pointer may be \c NULL if not supported by the client.  If
   1117  *                            \a seek_callback is not \c NULL then a
   1118  *                            \a tell_callback must also be supplied.
   1119  *                            Alternatively, a dummy tell callback that just
   1120  *                            returns \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
   1121  *                            may also be supplied, all though this is slightly
   1122  *                            less efficient for the decoder.
   1123  * \param  length_callback    See FLAC__StreamDecoderLengthCallback.  This
   1124  *                            pointer may be \c NULL if not supported by the client.  If
   1125  *                            \a seek_callback is not \c NULL then a
   1126  *                            \a length_callback must also be supplied.
   1127  *                            Alternatively, a dummy length callback that just
   1128  *                            returns \c FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
   1129  *                            may also be supplied, all though this is slightly
   1130  *                            less efficient for the decoder.
   1131  * \param  eof_callback       See FLAC__StreamDecoderEofCallback.  This
   1132  *                            pointer may be \c NULL if not supported by the client.  If
   1133  *                            \a seek_callback is not \c NULL then a
   1134  *                            \a eof_callback must also be supplied.
   1135  *                            Alternatively, a dummy length callback that just
   1136  *                            returns \c false
   1137  *                            may also be supplied, all though this is slightly
   1138  *                            less efficient for the decoder.
   1139  * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
   1140  *                            pointer must not be \c NULL.
   1141  * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
   1142  *                            pointer may be \c NULL if the callback is not
   1143  *                            desired.
   1144  * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
   1145  *                            pointer must not be \c NULL.
   1146  * \param  client_data        This value will be supplied to callbacks in their
   1147  *                            \a client_data argument.
   1148  * \assert
   1149  *    \code decoder != NULL \endcode
   1150  * \retval FLAC__StreamDecoderInitStatus
   1151  *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
   1152  *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
   1153  */
   1154 FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_stream(
   1155 	FLAC__StreamDecoder *decoder,
   1156 	FLAC__StreamDecoderReadCallback read_callback,
   1157 	FLAC__StreamDecoderSeekCallback seek_callback,
   1158 	FLAC__StreamDecoderTellCallback tell_callback,
   1159 	FLAC__StreamDecoderLengthCallback length_callback,
   1160 	FLAC__StreamDecoderEofCallback eof_callback,
   1161 	FLAC__StreamDecoderWriteCallback write_callback,
   1162 	FLAC__StreamDecoderMetadataCallback metadata_callback,
   1163 	FLAC__StreamDecoderErrorCallback error_callback,
   1164 	void *client_data
   1165 );
   1166 
   1167 /** Initialize the decoder instance to decode native FLAC files.
   1168  *
   1169  *  This flavor of initialization sets up the decoder to decode from a
   1170  *  plain native FLAC file.  For non-stdio streams, you must use
   1171  *  FLAC__stream_decoder_init_stream() and provide callbacks for the I/O.
   1172  *
   1173  *  This function should be called after FLAC__stream_decoder_new() and
   1174  *  FLAC__stream_decoder_set_*() but before any of the
   1175  *  FLAC__stream_decoder_process_*() functions.  Will set and return the
   1176  *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
   1177  *  if initialization succeeded.
   1178  *
   1179  * \param  decoder            An uninitialized decoder instance.
   1180  * \param  file               An open FLAC file.  The file should have been
   1181  *                            opened with mode \c "rb" and rewound.  The file
   1182  *                            becomes owned by the decoder and should not be
   1183  *                            manipulated by the client while decoding.
   1184  *                            Unless \a file is \c stdin, it will be closed
   1185  *                            when FLAC__stream_decoder_finish() is called.
   1186  *                            Note however that seeking will not work when
   1187  *                            decoding from \c stdout since it is not seekable.
   1188  * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
   1189  *                            pointer must not be \c NULL.
   1190  * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
   1191  *                            pointer may be \c NULL if the callback is not
   1192  *                            desired.
   1193  * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
   1194  *                            pointer must not be \c NULL.
   1195  * \param  client_data        This value will be supplied to callbacks in their
   1196  *                            \a client_data argument.
   1197  * \assert
   1198  *    \code decoder != NULL \endcode
   1199  *    \code file != NULL \endcode
   1200  * \retval FLAC__StreamDecoderInitStatus
   1201  *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
   1202  *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
   1203  */
   1204 FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_FILE(
   1205 	FLAC__StreamDecoder *decoder,
   1206 	FILE *file,
   1207 	FLAC__StreamDecoderWriteCallback write_callback,
   1208 	FLAC__StreamDecoderMetadataCallback metadata_callback,
   1209 	FLAC__StreamDecoderErrorCallback error_callback,
   1210 	void *client_data
   1211 );
   1212 
   1213 /** Initialize the decoder instance to decode Ogg FLAC files.
   1214  *
   1215  *  This flavor of initialization sets up the decoder to decode from a
   1216  *  plain Ogg FLAC file.  For non-stdio streams, you must use
   1217  *  FLAC__stream_decoder_init_ogg_stream() and provide callbacks for the I/O.
   1218  *
   1219  *  This function should be called after FLAC__stream_decoder_new() and
   1220  *  FLAC__stream_decoder_set_*() but before any of the
   1221  *  FLAC__stream_decoder_process_*() functions.  Will set and return the
   1222  *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
   1223  *  if initialization succeeded.
   1224  *
   1225  *  \note Support for Ogg FLAC in the library is optional.  If this
   1226  *  library has been built without support for Ogg FLAC, this function
   1227  *  will return \c FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER.
   1228  *
   1229  * \param  decoder            An uninitialized decoder instance.
   1230  * \param  file               An open FLAC file.  The file should have been
   1231  *                            opened with mode \c "rb" and rewound.  The file
   1232  *                            becomes owned by the decoder and should not be
   1233  *                            manipulated by the client while decoding.
   1234  *                            Unless \a file is \c stdin, it will be closed
   1235  *                            when FLAC__stream_decoder_finish() is called.
   1236  *                            Note however that seeking will not work when
   1237  *                            decoding from \c stdout since it is not seekable.
   1238  * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
   1239  *                            pointer must not be \c NULL.
   1240  * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
   1241  *                            pointer may be \c NULL if the callback is not
   1242  *                            desired.
   1243  * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
   1244  *                            pointer must not be \c NULL.
   1245  * \param  client_data        This value will be supplied to callbacks in their
   1246  *                            \a client_data argument.
   1247  * \assert
   1248  *    \code decoder != NULL \endcode
   1249  *    \code file != NULL \endcode
   1250  * \retval FLAC__StreamDecoderInitStatus
   1251  *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
   1252  *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
   1253  */
   1254 FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_FILE(
   1255 	FLAC__StreamDecoder *decoder,
   1256 	FILE *file,
   1257 	FLAC__StreamDecoderWriteCallback write_callback,
   1258 	FLAC__StreamDecoderMetadataCallback metadata_callback,
   1259 	FLAC__StreamDecoderErrorCallback error_callback,
   1260 	void *client_data
   1261 );
   1262 
   1263 /** Initialize the decoder instance to decode native FLAC files.
   1264  *
   1265  *  This flavor of initialization sets up the decoder to decode from a plain
   1266  *  native FLAC file.  If POSIX fopen() semantics are not sufficient, (for
   1267  *  example, with Unicode filenames on Windows), you must use
   1268  *  FLAC__stream_decoder_init_FILE(), or FLAC__stream_decoder_init_stream()
   1269  *  and provide callbacks for the I/O.
   1270  *
   1271  *  This function should be called after FLAC__stream_decoder_new() and
   1272  *  FLAC__stream_decoder_set_*() but before any of the
   1273  *  FLAC__stream_decoder_process_*() functions.  Will set and return the
   1274  *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
   1275  *  if initialization succeeded.
   1276  *
   1277  * \param  decoder            An uninitialized decoder instance.
   1278  * \param  filename           The name of the file to decode from.  The file will
   1279  *                            be opened with fopen().  Use \c NULL to decode from
   1280  *                            \c stdin.  Note that \c stdin is not seekable.
   1281  * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
   1282  *                            pointer must not be \c NULL.
   1283  * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
   1284  *                            pointer may be \c NULL if the callback is not
   1285  *                            desired.
   1286  * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
   1287  *                            pointer must not be \c NULL.
   1288  * \param  client_data        This value will be supplied to callbacks in their
   1289  *                            \a client_data argument.
   1290  * \assert
   1291  *    \code decoder != NULL \endcode
   1292  * \retval FLAC__StreamDecoderInitStatus
   1293  *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
   1294  *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
   1295  */
   1296 FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_file(
   1297 	FLAC__StreamDecoder *decoder,
   1298 	const char *filename,
   1299 	FLAC__StreamDecoderWriteCallback write_callback,
   1300 	FLAC__StreamDecoderMetadataCallback metadata_callback,
   1301 	FLAC__StreamDecoderErrorCallback error_callback,
   1302 	void *client_data
   1303 );
   1304 
   1305 /** Initialize the decoder instance to decode Ogg FLAC files.
   1306  *
   1307  *  This flavor of initialization sets up the decoder to decode from a plain
   1308  *  Ogg FLAC file.  If POSIX fopen() semantics are not sufficient, (for
   1309  *  example, with Unicode filenames on Windows), you must use
   1310  *  FLAC__stream_decoder_init_ogg_FILE(), or FLAC__stream_decoder_init_ogg_stream()
   1311  *  and provide callbacks for the I/O.
   1312  *
   1313  *  This function should be called after FLAC__stream_decoder_new() and
   1314  *  FLAC__stream_decoder_set_*() but before any of the
   1315  *  FLAC__stream_decoder_process_*() functions.  Will set and return the
   1316  *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
   1317  *  if initialization succeeded.
   1318  *
   1319  *  \note Support for Ogg FLAC in the library is optional.  If this
   1320  *  library has been built without support for Ogg FLAC, this function
   1321  *  will return \c FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER.
   1322  *
   1323  * \param  decoder            An uninitialized decoder instance.
   1324  * \param  filename           The name of the file to decode from.  The file will
   1325  *                            be opened with fopen().  Use \c NULL to decode from
   1326  *                            \c stdin.  Note that \c stdin is not seekable.
   1327  * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
   1328  *                            pointer must not be \c NULL.
   1329  * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
   1330  *                            pointer may be \c NULL if the callback is not
   1331  *                            desired.
   1332  * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
   1333  *                            pointer must not be \c NULL.
   1334  * \param  client_data        This value will be supplied to callbacks in their
   1335  *                            \a client_data argument.
   1336  * \assert
   1337  *    \code decoder != NULL \endcode
   1338  * \retval FLAC__StreamDecoderInitStatus
   1339  *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
   1340  *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
   1341  */
   1342 FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_file(
   1343 	FLAC__StreamDecoder *decoder,
   1344 	const char *filename,
   1345 	FLAC__StreamDecoderWriteCallback write_callback,
   1346 	FLAC__StreamDecoderMetadataCallback metadata_callback,
   1347 	FLAC__StreamDecoderErrorCallback error_callback,
   1348 	void *client_data
   1349 );
   1350 
   1351 /** Finish the decoding process.
   1352  *  Flushes the decoding buffer, releases resources, resets the decoder
   1353  *  settings to their defaults, and returns the decoder state to
   1354  *  FLAC__STREAM_DECODER_UNINITIALIZED.
   1355  *
   1356  *  In the event of a prematurely-terminated decode, it is not strictly
   1357  *  necessary to call this immediately before FLAC__stream_decoder_delete()
   1358  *  but it is good practice to match every FLAC__stream_decoder_init_*()
   1359  *  with a FLAC__stream_decoder_finish().
   1360  *
   1361  * \param  decoder  An uninitialized decoder instance.
   1362  * \assert
   1363  *    \code decoder != NULL \endcode
   1364  * \retval FLAC__bool
   1365  *    \c false if MD5 checking is on AND a STREAMINFO block was available
   1366  *    AND the MD5 signature in the STREAMINFO block was non-zero AND the
   1367  *    signature does not match the one computed by the decoder; else
   1368  *    \c true.
   1369  */
   1370 FLAC_API FLAC__bool FLAC__stream_decoder_finish(FLAC__StreamDecoder *decoder);
   1371 
   1372 /** Flush the stream input.
   1373  *  The decoder's input buffer will be cleared and the state set to
   1374  *  \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.  This will also turn
   1375  *  off MD5 checking.
   1376  *
   1377  * \param  decoder  A decoder instance.
   1378  * \assert
   1379  *    \code decoder != NULL \endcode
   1380  * \retval FLAC__bool
   1381  *    \c true if successful, else \c false if a memory allocation
   1382  *    error occurs (in which case the state will be set to
   1383  *    \c FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR).
   1384  */
   1385 FLAC_API FLAC__bool FLAC__stream_decoder_flush(FLAC__StreamDecoder *decoder);
   1386 
   1387 /** Reset the decoding process.
   1388  *  The decoder's input buffer will be cleared and the state set to
   1389  *  \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.  This is similar to
   1390  *  FLAC__stream_decoder_finish() except that the settings are
   1391  *  preserved; there is no need to call FLAC__stream_decoder_init_*()
   1392  *  before decoding again.  MD5 checking will be restored to its original
   1393  *  setting.
   1394  *
   1395  *  If the decoder is seekable, or was initialized with
   1396  *  FLAC__stream_decoder_init*_FILE() or FLAC__stream_decoder_init*_file(),
   1397  *  the decoder will also attempt to seek to the beginning of the file.
   1398  *  If this rewind fails, this function will return \c false.  It follows
   1399  *  that FLAC__stream_decoder_reset() cannot be used when decoding from
   1400  *  \c stdin.
   1401  *
   1402  *  If the decoder was initialized with FLAC__stream_encoder_init*_stream()
   1403  *  and is not seekable (i.e. no seek callback was provided or the seek
   1404  *  callback returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED), it
   1405  *  is the duty of the client to start feeding data from the beginning of
   1406  *  the stream on the next FLAC__stream_decoder_process() or
   1407  *  FLAC__stream_decoder_process_interleaved() call.
   1408  *
   1409  * \param  decoder  A decoder instance.
   1410  * \assert
   1411  *    \code decoder != NULL \endcode
   1412  * \retval FLAC__bool
   1413  *    \c true if successful, else \c false if a memory allocation occurs
   1414  *    (in which case the state will be set to
   1415  *    \c FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR) or a seek error
   1416  *    occurs (the state will be unchanged).
   1417  */
   1418 FLAC_API FLAC__bool FLAC__stream_decoder_reset(FLAC__StreamDecoder *decoder);
   1419 
   1420 /** Decode one metadata block or audio frame.
   1421  *  This version instructs the decoder to decode a either a single metadata
   1422  *  block or a single frame and stop, unless the callbacks return a fatal
   1423  *  error or the read callback returns
   1424  *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
   1425  *
   1426  *  As the decoder needs more input it will call the read callback.
   1427  *  Depending on what was decoded, the metadata or write callback will be
   1428  *  called with the decoded metadata block or audio frame.
   1429  *
   1430  *  Unless there is a fatal read error or end of stream, this function
   1431  *  will return once one whole frame is decoded.  In other words, if the
   1432  *  stream is not synchronized or points to a corrupt frame header, the
   1433  *  decoder will continue to try and resync until it gets to a valid
   1434  *  frame, then decode one frame, then return.  If the decoder points to
   1435  *  a frame whose frame CRC in the frame footer does not match the
   1436  *  computed frame CRC, this function will issue a
   1437  *  FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH error to the
   1438  *  error callback, and return, having decoded one complete, although
   1439  *  corrupt, frame.  (Such corrupted frames are sent as silence of the
   1440  *  correct length to the write callback.)
   1441  *
   1442  * \param  decoder  An initialized decoder instance.
   1443  * \assert
   1444  *    \code decoder != NULL \endcode
   1445  * \retval FLAC__bool
   1446  *    \c false if any fatal read, write, or memory allocation error
   1447  *    occurred (meaning decoding must stop), else \c true; for more
   1448  *    information about the decoder, check the decoder state with
   1449  *    FLAC__stream_decoder_get_state().
   1450  */
   1451 FLAC_API FLAC__bool FLAC__stream_decoder_process_single(FLAC__StreamDecoder *decoder);
   1452 
   1453 /** Decode until the end of the metadata.
   1454  *  This version instructs the decoder to decode from the current position
   1455  *  and continue until all the metadata has been read, or until the
   1456  *  callbacks return a fatal error or the read callback returns
   1457  *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
   1458  *
   1459  *  As the decoder needs more input it will call the read callback.
   1460  *  As each metadata block is decoded, the metadata callback will be called
   1461  *  with the decoded metadata.
   1462  *
   1463  * \param  decoder  An initialized decoder instance.
   1464  * \assert
   1465  *    \code decoder != NULL \endcode
   1466  * \retval FLAC__bool
   1467  *    \c false if any fatal read, write, or memory allocation error
   1468  *    occurred (meaning decoding must stop), else \c true; for more
   1469  *    information about the decoder, check the decoder state with
   1470  *    FLAC__stream_decoder_get_state().
   1471  */
   1472 FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_metadata(FLAC__StreamDecoder *decoder);
   1473 
   1474 /** Decode until the end of the stream.
   1475  *  This version instructs the decoder to decode from the current position
   1476  *  and continue until the end of stream (the read callback returns
   1477  *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM), or until the
   1478  *  callbacks return a fatal error.
   1479  *
   1480  *  As the decoder needs more input it will call the read callback.
   1481  *  As each metadata block and frame is decoded, the metadata or write
   1482  *  callback will be called with the decoded metadata or frame.
   1483  *
   1484  * \param  decoder  An initialized decoder instance.
   1485  * \assert
   1486  *    \code decoder != NULL \endcode
   1487  * \retval FLAC__bool
   1488  *    \c false if any fatal read, write, or memory allocation error
   1489  *    occurred (meaning decoding must stop), else \c true; for more
   1490  *    information about the decoder, check the decoder state with
   1491  *    FLAC__stream_decoder_get_state().
   1492  */
   1493 FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_stream(FLAC__StreamDecoder *decoder);
   1494 
   1495 /** Skip one audio frame.
   1496  *  This version instructs the decoder to 'skip' a single frame and stop,
   1497  *  unless the callbacks return a fatal error or the read callback returns
   1498  *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
   1499  *
   1500  *  The decoding flow is the same as what occurs when
   1501  *  FLAC__stream_decoder_process_single() is called to process an audio
   1502  *  frame, except that this function does not decode the parsed data into
   1503  *  PCM or call the write callback.  The integrity of the frame is still
   1504  *  checked the same way as in the other process functions.
   1505  *
   1506  *  This function will return once one whole frame is skipped, in the
   1507  *  same way that FLAC__stream_decoder_process_single() will return once
   1508  *  one whole frame is decoded.
   1509  *
   1510  *  This function can be used in more quickly determining FLAC frame
   1511  *  boundaries when decoding of the actual data is not needed, for
   1512  *  example when an application is separating a FLAC stream into frames
   1513  *  for editing or storing in a container.  To do this, the application
   1514  *  can use FLAC__stream_decoder_skip_single_frame() to quickly advance
   1515  *  to the next frame, then use
   1516  *  FLAC__stream_decoder_get_decode_position() to find the new frame
   1517  *  boundary.
   1518  *
   1519  *  This function should only be called when the stream has advanced
   1520  *  past all the metadata, otherwise it will return \c false.
   1521  *
   1522  * \param  decoder  An initialized decoder instance not in a metadata
   1523  *                  state.
   1524  * \assert
   1525  *    \code decoder != NULL \endcode
   1526  * \retval FLAC__bool
   1527  *    \c false if any fatal read, write, or memory allocation error
   1528  *    occurred (meaning decoding must stop), or if the decoder
   1529  *    is in the FLAC__STREAM_DECODER_SEARCH_FOR_METADATA or
   1530  *    FLAC__STREAM_DECODER_READ_METADATA state, else \c true; for more
   1531  *    information about the decoder, check the decoder state with
   1532  *    FLAC__stream_decoder_get_state().
   1533  */
   1534 FLAC_API FLAC__bool FLAC__stream_decoder_skip_single_frame(FLAC__StreamDecoder *decoder);
   1535 
   1536 /** Flush the input and seek to an absolute sample.
   1537  *  Decoding will resume at the given sample.  Note that because of
   1538  *  this, the next write callback may contain a partial block.  The
   1539  *  client must support seeking the input or this function will fail
   1540  *  and return \c false.  Furthermore, if the decoder state is
   1541  *  \c FLAC__STREAM_DECODER_SEEK_ERROR, then the decoder must be flushed
   1542  *  with FLAC__stream_decoder_flush() or reset with
   1543  *  FLAC__stream_decoder_reset() before decoding can continue.
   1544  *
   1545  * \param  decoder  A decoder instance.
   1546  * \param  sample   The target sample number to seek to.
   1547  * \assert
   1548  *    \code decoder != NULL \endcode
   1549  * \retval FLAC__bool
   1550  *    \c true if successful, else \c false.
   1551  */
   1552 FLAC_API FLAC__bool FLAC__stream_decoder_seek_absolute(FLAC__StreamDecoder *decoder, FLAC__uint64 sample);
   1553 
   1554 /* \} */
   1555 
   1556 #ifdef __cplusplus
   1557 }
   1558 #endif
   1559 
   1560 #endif
   1561