include/FLAC/stream_decoder.h

   1 /* libFLAC - Free Lossless Audio Codec library
   2  * Copyright (C) 2000,2001,2002,2003  Josh Coalson
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions
   6  * are met:
   7  *
   8  * - Redistributions of source code must retain the above copyright
   9  * notice, this list of conditions and the following disclaimer.
  10  *
  11  * - Redistributions in binary form must reproduce the above copyright
  12  * notice, this list of conditions and the following disclaimer in the
  13  * documentation and/or other materials provided with the distribution.
  14  *
  15  * - Neither the name of the Xiph.org Foundation nor the names of its
  16  * contributors may be used to endorse or promote products derived from
  17  * this software without specific prior written permission.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22  * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
  23  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  24  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  25  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  26  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  27  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  28  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  29  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30  */
  31
  32 #ifndef FLAC__STREAM_DECODER_H
  33 #define FLAC__STREAM_DECODER_H
  34
  35 #include "export.h"
  36 #include "format.h"
  37
  38 #ifdef __cplusplus
  39 extern "C" {
  40 #endif
  41
  42
  43 /** \file include/FLAC/stream_decoder.h
  44  *
  45  *  \brief
  46  *  This module contains the functions which implement the stream
  47  *  decoder.
  48  *
  49  *  See the detailed documentation in the
  50  *  \link flac_stream_decoder stream decoder \endlink module.
  51  */
  52
  53 /** \defgroup flac_decoder FLAC/ *_decoder.h: decoder interfaces
  54  *  \ingroup flac
  55  *
  56  *  \brief
  57  *  This module describes the three decoder layers provided by libFLAC.
  58  *
  59  * For decoding FLAC streams, libFLAC provides three layers of access.  The
  60  * lowest layer is non-seekable stream-level decoding, the next is seekable
  61  * stream-level decoding, and the highest layer is file-level decoding.  The
  62  * interfaces are described in the \link flac_stream_decoder stream decoder
  63  * \endlink, \link flac_seekable_stream_decoder seekable stream decoder
  64  * \endlink, and \link flac_file_decoder file decoder \endlink modules
  65  * respectively.  Typically you will choose the highest layer that your input
  66  * source will support.
  67  *
  68  * The stream decoder relies on callbacks for all input and output and has no
  69  * provisions for seeking.  The seekable stream decoder wraps the stream
  70  * decoder and exposes functions for seeking.  However, you must provide
  71  * extra callbacks for seek-related operations on your stream, like seek and
  72  * tell.  The file decoder wraps the seekable stream decoder and supplies
  73  * most of the callbacks internally, simplifying the processing of standard
  74  * files.
  75  */
  76
  77 /** \defgroup flac_stream_decoder FLAC/stream_decoder.h: stream decoder interface
  78  *  \ingroup flac_decoder
  79  *
  80  *  \brief
  81  *  This module contains the functions which implement the stream
  82  *  decoder.
  83  *
  84  * The basic usage of this decoder is as follows:
  85  * - The program creates an instance of a decoder using
  86  *   FLAC__stream_decoder_new().
  87  * - The program overrides the default settings and sets callbacks for
  88  *   reading, writing, error reporting, and metadata reporting using
  89  *   FLAC__stream_decoder_set_*() functions.
  90  * - The program initializes the instance to validate the settings and
  91  *   prepare for decoding using FLAC__stream_decoder_init().
  92  * - The program calls the FLAC__stream_decoder_process_*() functions
  93  *   to decode data, which subsequently calls the callbacks.
  94  * - The program finishes the decoding with FLAC__stream_decoder_finish(),
  95  *   which flushes the input and output and resets the decoder to the
  96  *   uninitialized state.
  97  * - The instance may be used again or deleted with
  98  *   FLAC__stream_decoder_delete().
  99  *
 100  * In more detail, the program will create a new instance by calling
 101  * FLAC__stream_decoder_new(), then call FLAC__stream_decoder_set_*()
 102  * functions to set the callbacks and client data, and call
 103  * FLAC__stream_decoder_init().  The required callbacks are:
 104  *
 105  * - Read callback - This function will be called when the decoder needs
 106  *   more input data.  The address of the buffer to be filled is supplied,
 107  *   along with the number of bytes the buffer can hold.  The callback may
 108  *   choose to supply less data and modify the byte count but must be careful
 109  *   not to overflow the buffer.  The callback then returns a status code
 110  *   chosen from FLAC__StreamDecoderReadStatus.
 111  * - Write callback - This function will be called when the decoder has
 112  *   decoded a single frame of data.  The decoder will pass the frame
 113  *   metadata as well as an array of pointers (one for each channel)
 114  *   pointing to the decoded audio.
 115  * - Metadata callback - This function will be called when the decoder has
 116  *   decoded a metadata block.  In a valid FLAC file there will always be
 117  *   one STREAMINFO block, followed by zero or more other metadata
 118  *   blocks.  These will be supplied by the decoder in the same order as
 119  *   they appear in the stream and always before the first audio frame
 120  *   (i.e. write callback).  The metadata block that is passed in must not
 121  *   be modified, and it doesn't live beyond the callback, so you should
 122  *   make a copy of it with FLAC__metadata_object_clone() if you will need
 123  *   it elsewhere.  Since metadata blocks can potentially be large, by
 124  *   default the decoder only calls the metadata callback for the STREAMINFO
 125  *   block; you can instruct the decoder to pass or filter other blocks with
 126  *   FLAC__stream_decoder_set_metadata_*() calls.
 127  * - Error callback - This function will be called whenever an error occurs
 128  *   during decoding.
 129  *
 130  * Once the decoder is initialized, your program will call one of several
 131  * functions to start the decoding process:
 132  *
 133  * - FLAC__stream_decoder_process_single() - Tells the decoder to process at
 134  *   most one metadata block or audio frame and return, calling either the
 135  *   metadata callback or write callback, respectively, once.  If the decoder
 136  *   loses sync it will return with only the error callback being called.
 137  * - FLAC__stream_decoder_process_until_end_of_metadata() - Tells the decoder
 138  *   to process the stream from the current location and stop upon reaching
 139  *   the first audio frame.  The user will get one metadata, write, or error
 140  *   callback per metadata block, audio frame, or sync error, respectively.
 141  * - FLAC__stream_decoder_process_until_end_of_stream() - Tells the decoder
 142  *   to process the stream from the current location until the read callback
 143  *   returns FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM or
 144  *   FLAC__STREAM_DECODER_READ_STATUS_ABORT.  The user will get one metadata,
 145  *   write, or error callback per metadata block, audio frame, or sync error,
 146  *   respectively.
 147  *
 148  * When the decoder has finished decoding (normally or through an abort),
 149  * the instance is finished by calling FLAC__stream_decoder_finish(), which
 150  * ensures the decoder is in the correct state and frees memory.  Then the
 151  * instance may be deleted with FLAC__stream_decoder_delete() or initialized
 152  * again to decode another stream.
 153  *
 154  * Note that the stream decoder has no real concept of stream position, it
 155  * just converts data.  To seek within a stream the callbacks have only to
 156  * flush the decoder using FLAC__stream_decoder_flush() and start feeding
 157  * data from the new position through the read callback.  The seekable
 158  * stream decoder does just this.
 159  *
 160  * The FLAC__stream_decoder_set_metadata_*() functions deserve special
 161  * attention.  By default, the decoder only calls the metadata_callback for
 162  * the STREAMINFO block.  These functions allow you to tell the decoder
 163  * explicitly which blocks to parse and return via the metadata_callback
 164  * and/or which to skip.  Use a FLAC__stream_decoder_set_metadata_respond_all(),
 165  * FLAC__stream_decoder_set_metadata_ignore() ... or FLAC__stream_decoder_set_metadata_ignore_all(),
 166  * FLAC__stream_decoder_set_metadata_respond() ... sequence to exactly specify which
 167  * blocks to return.  Remember that some metadata blocks can be big so
 168  * filtering out the ones you don't use can reduce the memory requirements
 169  * of the decoder.  Also note the special forms
 170  * FLAC__stream_decoder_set_metadata_respond_application(id) and
 171  * FLAC__stream_decoder_set_metadata_ignore_application(id) for filtering APPLICATION
 172  * blocks based on the application ID.
 173  *
 174  * STREAMINFO and SEEKTABLE blocks are always parsed and used internally, but
 175  * they still can legally be filtered from the metadata_callback.
 176  *
 177  * \note
 178  * The "set" functions may only be called when the decoder is in the
 179  * state FLAC__STREAM_DECODER_UNINITIALIZED, i.e. after
 180  * FLAC__stream_decoder_new() or FLAC__stream_decoder_finish(), but
 181  * before FLAC__stream_decoder_init().  If this is the case they will
 182  * return \c true, otherwise \c false.
 183  *
 184  * \note
 185  * FLAC__stream_decoder_finish() resets all settings to the constructor
 186  * defaults, including the callbacks.
 187  *
 188  * \{
 189  */
 190
 191
 192 /** State values for a FLAC__StreamDecoder
 193  *
 194  *  The decoder's state can be obtained by calling FLAC__stream_decoder_get_state().
 195  */
 196 typedef enum {
 197
 198         FLAC__STREAM_DECODER_SEARCH_FOR_METADATA = 0,
 199         /**< The decoder is ready to search for metadata. */
 200
 201         FLAC__STREAM_DECODER_READ_METADATA,
 202         /**< The decoder is ready to or is in the process of reading metadata. */
 203
 204         FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC,
 205         /**< The decoder is ready to or is in the process of searching for the frame sync code. */
 206
 207         FLAC__STREAM_DECODER_READ_FRAME,
 208         /**< The decoder is ready to or is in the process of reading a frame. */
 209
 210         FLAC__STREAM_DECODER_END_OF_STREAM,
 211         /**< The decoder has reached the end of the stream. */
 212
 213         FLAC__STREAM_DECODER_ABORTED,
 214         /**< The decoder was aborted by the read callback. */
 215
 216         FLAC__STREAM_DECODER_UNPARSEABLE_STREAM,
 217         /**< The decoder encountered reserved fields in use in the stream. */
 218
 219         FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
 220         /**< An error occurred allocating memory. */
 221
 222         FLAC__STREAM_DECODER_ALREADY_INITIALIZED,
 223         /**< FLAC__stream_decoder_init() was called when the decoder was
 224          * already initialized, usually because
 225          * FLAC__stream_decoder_finish() was not called.
 226          */
 227
 228         FLAC__STREAM_DECODER_INVALID_CALLBACK,
 229         /**< FLAC__stream_decoder_init() was called without all callbacks being set. */
 230
 231         FLAC__STREAM_DECODER_UNINITIALIZED
 232         /**< The decoder is in the uninitialized state. */
 233
 234 } FLAC__StreamDecoderState;
 235
 236 /** Maps a FLAC__StreamDecoderState to a C string.
 237  *
 238  *  Using a FLAC__StreamDecoderState as the index to this array
 239  *  will give the string equivalent.  The contents should not be modified.
 240  */
 241 extern FLAC_API const char * const FLAC__StreamDecoderStateString[];
 242
 243
 244 /** Return values for the FLAC__StreamDecoder read callback.
 245  */
 246 typedef enum {
 247
 248         FLAC__STREAM_DECODER_READ_STATUS_CONTINUE,
 249         /**< The read was OK and decoding can continue. */
 250
 251         FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM,
 252         /**< The read was attempted at the end of the stream. */
 253
 254         FLAC__STREAM_DECODER_READ_STATUS_ABORT
 255         /**< An unrecoverable error occurred.  The decoder will return from the process call. */
 256
 257 } FLAC__StreamDecoderReadStatus;
 258
 259 /** Maps a FLAC__StreamDecoderReadStatus to a C string.
 260  *
 261  *  Using a FLAC__StreamDecoderReadStatus as the index to this array
 262  *  will give the string equivalent.  The contents should not be modified.
 263  */
 264 extern FLAC_API const char * const FLAC__StreamDecoderReadStatusString[];
 265
 266
 267 /** Return values for the FLAC__StreamDecoder write callback.
 268  */
 269 typedef enum {
 270
 271         FLAC__STREAM_DECODER_WRITE_STATUS_CONTINUE,
 272         /**< The write was OK and decoding can continue. */
 273
 274         FLAC__STREAM_DECODER_WRITE_STATUS_ABORT
 275         /**< An unrecoverable error occurred.  The decoder will return from the process call. */
 276
 277 } FLAC__StreamDecoderWriteStatus;
 278
 279 /** Maps a FLAC__StreamDecoderWriteStatus to a C string.
 280  *
 281  *  Using a FLAC__StreamDecoderWriteStatus as the index to this array
 282  *  will give the string equivalent.  The contents should not be modified.
 283  */
 284 extern FLAC_API const char * const FLAC__StreamDecoderWriteStatusString[];
 285
 286
 287 /** Possible values passed in to the FLAC__StreamDecoder error callback.
 288  */
 289 typedef enum {
 290
 291         FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC,
 292         /**< An error in the stream caused the decoder to lose synchronization. */
 293
 294         FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER,
 295         /**< The decoder encountered a corrupted frame header. */
 296
 297         FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH
 298         /**< The frame's data did not match the CRC in the footer. */
 299
 300 } FLAC__StreamDecoderErrorStatus;
 301
 302 /** Maps a FLAC__StreamDecoderErrorStatus to a C string.
 303  *
 304  *  Using a FLAC__StreamDecoderErrorStatus as the index to this array
 305  *  will give the string equivalent.  The contents should not be modified.
 306  */
 307 extern FLAC_API const char * const FLAC__StreamDecoderErrorStatusString[];
 308
 309
 310 /***********************************************************************
 311  *
 312  * class FLAC__StreamDecoder
 313  *
 314  ***********************************************************************/
 315
 316 struct FLAC__StreamDecoderProtected;
 317 struct FLAC__StreamDecoderPrivate;
 318 /** The opaque structure definition for the stream decoder type.
 319  *  See the \link flac_stream_decoder stream decoder module \endlink
 320  *  for a detailed description.
 321  */
 322 typedef struct {
 323         struct FLAC__StreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
 324         struct FLAC__StreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
 325 } FLAC__StreamDecoder;
 326
 327 /** Signature for the read callback.
 328  *  See FLAC__stream_decoder_set_read_callback() for more info.
 329  *
 330  * \param  decoder  The decoder instance calling the callback.
 331  * \param  buffer   A pointer to a location for the callee to store
 332  *                  data to be decoded.
 333  * \param  bytes    A pointer to the size of the buffer.  On entry
 334  *                  to the callback, it contains the maximum number
 335  *                  of bytes that may be stored in \a buffer.  The
 336  *                  callee must set it to the actual number of bytes
 337  *                  stored (0 in case of error or end-of-stream) before
 338  *                  returning.
 339  * \param  client_data  The callee's client data set through
 340  *                      FLAC__stream_decoder_set_client_data().
 341  * \retval FLAC__StreamDecoderReadStatus
 342  *    The callee's return status.
 343  */
 344 typedef FLAC__StreamDecoderReadStatus (*FLAC__StreamDecoderReadCallback)(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
 345
 346 /** Signature for the write callback.
 347  *  See FLAC__stream_decoder_set_write_callback() for more info.
 348  *
 349  * \param  decoder  The decoder instance calling the callback.
 350  * \param  frame    The description of the decoded frame.  See
 351  *                  FLAC__Frame.
 352  * \param  buffer   An array of pointers to decoded channels of data.
 353  *                  Each pointer will point to an array of signed
 354  *                  samples of length \a frame->header.blocksize.
 355  *                  Currently, the channel order has no meaning
 356  *                  except for stereo streams; in this case channel
 357  *                  0 is left and 1 is right.
 358  * \param  client_data  The callee's client data set through
 359  *                      FLAC__stream_decoder_set_client_data().
 360  * \retval FLAC__StreamDecoderWriteStatus
 361  *    The callee's return status.
 362  */
 363 typedef FLAC__StreamDecoderWriteStatus (*FLAC__StreamDecoderWriteCallback)(const FLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
 364
 365 /** Signature for the metadata callback.
 366  *  See FLAC__stream_decoder_set_metadata_callback() for more info.
 367  *
 368  * \param  decoder  The decoder instance calling the callback.
 369  * \param  metadata The decoded metadata block.
 370  * \param  client_data  The callee's client data set through
 371  *                      FLAC__stream_decoder_set_client_data().
 372  */
 373 typedef void (*FLAC__StreamDecoderMetadataCallback)(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
 374
 375 /** Signature for the error callback.
 376  *  See FLAC__stream_decoder_set_error_callback() for more info.
 377  *
 378  * \param  decoder  The decoder instance calling the callback.
 379  * \param  status   The error encountered by the decoder.
 380  * \param  client_data  The callee's client data set through
 381  *                      FLAC__stream_decoder_set_client_data().
 382  */
 383 typedef void (*FLAC__StreamDecoderErrorCallback)(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
 384
 385
 386 /***********************************************************************
 387  *
 388  * Class constructor/destructor
 389  *
 390  ***********************************************************************/
 391
 392 /** Create a new stream decoder instance.  The instance is created with
 393  *  default settings; see the individual FLAC__stream_decoder_set_*()
 394  *  functions for each setting's default.
 395  *
 396  * \retval FLAC__StreamDecoder*
 397  *    \c NULL if there was an error allocating memory, else the new instance.
 398  */
 399 FLAC_API FLAC__StreamDecoder *FLAC__stream_decoder_new();
 400
 401 /** Free a decoder instance.  Deletes the object pointed to by \a decoder.
 402  *
 403  * \param decoder  A pointer to an existing decoder.
 404  * \assert
 405  *    \code decoder != NULL \endcode
 406  */
 407 FLAC_API void FLAC__stream_decoder_delete(FLAC__StreamDecoder *decoder);
 408
 409
 410 /***********************************************************************
 411  *
 412  * Public class method prototypes
 413  *
 414  ***********************************************************************/
 415
 416 /** Set the read callback.
 417  *  The supplied function will be called when the decoder needs more input
 418  *  data.  The address of the buffer to be filled is supplied, along with
 419  *  the number of bytes the buffer can hold.  The callback may choose to
 420  *  supply less data and modify the byte count but must be careful not to
 421  *  overflow the buffer.  The callback then returns a status code chosen
 422  *  from FLAC__StreamDecoderReadStatus.
 423  *
 424  * \note
 425  * The callback is mandatory and must be set before initialization.
 426  *
 427  * \default \c NULL
 428  * \param  decoder  A decoder instance to set.
 429  * \param  value    See above.
 430  * \assert
 431  *    \code decoder != NULL \endcode
 432  *    \code value != NULL \endcode
 433  * \retval FLAC__bool
 434  *    \c false if the decoder is already initialized, else \c true.
 435  */
 436 FLAC_API FLAC__bool FLAC__stream_decoder_set_read_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderReadCallback value);
 437
 438 /** Set the write callback.
 439  *  The supplied function will be called when the decoder has decoded a
 440  *  single frame of data.  The decoder will pass the frame metadata as
 441  *  well as an array of pointers (one for each channel) pointing to the
 442  *  decoded audio.
 443  *
 444  * \note
 445  * The callback is mandatory and must be set before initialization.
 446  *
 447  * \default \c NULL
 448  * \param  decoder  A decoder instance to set.
 449  * \param  value    See above.
 450  * \assert
 451  *    \code decoder != NULL \endcode
 452  *    \code value != NULL \endcode
 453  * \retval FLAC__bool
 454  *    \c false if the decoder is already initialized, else \c true.
 455  */
 456 FLAC_API FLAC__bool FLAC__stream_decoder_set_write_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderWriteCallback value);
 457
 458 /** Set the metadata callback.
 459  *  The supplied function will be called when the decoder has decoded a metadata
 460  *  block.  In a valid FLAC file there will always be one STREAMINFO block,
 461  *  followed by zero or more other metadata blocks.  These will be supplied
 462  *  by the decoder in the same order as they appear in the stream and always
 463  *  before the first audio frame (i.e. write callback).  The metadata block
 464  *  that is passed in must not be modified, and it doesn't live beyond the
 465  *  callback, so you should make a copy of it with
 466  *  FLAC__metadata_object_clone() if you will need it elsewhere.  Since
 467  *  metadata blocks can potentially be large, by default the decoder only
 468  *  calls the metadata callback for the STREAMINFO block; you can instruct
 469  *  the decoder to pass or filter other blocks with
 470  *  FLAC__stream_decoder_set_metadata_*() calls.
 471  *
 472  * \note
 473  * The callback is mandatory and must be set before initialization.
 474  *
 475  * \default \c NULL
 476  * \param  decoder  A decoder instance to set.
 477  * \param  value    See above.
 478  * \assert
 479  *    \code decoder != NULL \endcode
 480  *    \code value != NULL \endcode
 481  * \retval FLAC__bool
 482  *    \c false if the decoder is already initialized, else \c true.
 483  */
 484 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderMetadataCallback value);
 485
 486 /** Set the error callback.
 487  *  The supplied function will be called whenever an error occurs during
 488  *  decoding.
 489  *
 490  * \note
 491  * The callback is mandatory and must be set before initialization.
 492  *
 493  * \default \c NULL
 494  * \param  decoder  A decoder instance to set.
 495  * \param  value    See above.
 496  * \assert
 497  *    \code decoder != NULL \endcode
 498  *    \code value != NULL \endcode
 499  * \retval FLAC__bool
 500  *    \c false if the decoder is already initialized, else \c true.
 501  */
 502 FLAC_API FLAC__bool FLAC__stream_decoder_set_error_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorCallback value);
 503
 504 /** Set the client data to be passed back to callbacks.
 505  *  This value will be supplied to callbacks in their \a client_data
 506  *  argument.
 507  *
 508  * \default \c NULL
 509  * \param  decoder  A decoder instance to set.
 510  * \param  value    See above.
 511  * \assert
 512  *    \code decoder != NULL \endcode
 513  * \retval FLAC__bool
 514  *    \c false if the decoder is already initialized, else \c true.
 515  */
 516 FLAC_API FLAC__bool FLAC__stream_decoder_set_client_data(FLAC__StreamDecoder *decoder, void *value);
 517
 518 /** Direct the decoder to pass on all metadata blocks of type \a type.
 519  *
 520  * \default By default, only the \c STREAMINFO block is returned via the
 521  *          metadata callback.
 522  * \param  decoder  A decoder instance to set.
 523  * \param  type     See above.
 524  * \assert
 525  *    \code decoder != NULL \endcode
 526  *    \a type is valid
 527  * \retval FLAC__bool
 528  *    \c false if the decoder is already initialized, else \c true.
 529  */
 530 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
 531
 532 /** Direct the decoder to pass on all APPLICATION metadata blocks of the
 533  *  given \a id.
 534  *
 535  * \default By default, only the \c STREAMINFO block is returned via the
 536  *          metadata callback.
 537  * \param  decoder  A decoder instance to set.
 538  * \param  id       See above.
 539  * \assert
 540  *    \code decoder != NULL \endcode
 541  *    \code id != NULL \endcode
 542  * \retval FLAC__bool
 543  *    \c false if the decoder is already initialized, else \c true.
 544  */
 545 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
 546
 547 /** Direct the decoder to pass on all metadata blocks of any type.
 548  *
 549  * \default By default, only the \c STREAMINFO block is returned via the
 550  *          metadata callback.
 551  * \param  decoder  A decoder instance to set.
 552  * \assert
 553  *    \code decoder != NULL \endcode
 554  * \retval FLAC__bool
 555  *    \c false if the decoder is already initialized, else \c true.
 556  */
 557 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_all(FLAC__StreamDecoder *decoder);
 558
 559 /** Direct the decoder to filter out all metadata blocks of type \a type.
 560  *
 561  * \default By default, only the \c STREAMINFO block is returned via the
 562  *          metadata callback.
 563  * \param  decoder  A decoder instance to set.
 564  * \param  type     See above.
 565  * \assert
 566  *    \code decoder != NULL \endcode
 567  *    \a type is valid
 568  * \retval FLAC__bool
 569  *    \c false if the decoder is already initialized, else \c true.
 570  */
 571 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
 572
 573 /** Direct the decoder to filter out all APPLICATION metadata blocks of
 574  *  the given \a id.
 575  *
 576  * \default By default, only the \c STREAMINFO block is returned via the
 577  *          metadata callback.
 578  * \param  decoder  A decoder instance to set.
 579  * \param  id       See above.
 580  * \assert
 581  *    \code decoder != NULL \endcode
 582  *    \code id != NULL \endcode
 583  * \retval FLAC__bool
 584  *    \c false if the decoder is already initialized, else \c true.
 585  */
 586 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
 587
 588 /** Direct the decoder to filter out all metadata blocks of any type.
 589  *
 590  * \default By default, only the \c STREAMINFO block is returned via the
 591  *          metadata callback.
 592  * \param  decoder  A decoder instance to set.
 593  * \assert
 594  *    \code decoder != NULL \endcode
 595  * \retval FLAC__bool
 596  *    \c false if the decoder is already initialized, else \c true.
 597  */
 598 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_all(FLAC__StreamDecoder *decoder);
 599
 600 /** Get the current decoder state.
 601  *
 602  * \param  decoder  A decoder instance to query.
 603  * \assert
 604  *    \code decoder != NULL \endcode
 605  * \retval FLAC__StreamDecoderState
 606  *    The current decoder state.
 607  */
 608 FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_get_state(const FLAC__StreamDecoder *decoder);
 609
 610 /** Get the current decoder state as a C string.
 611  *
 612  * \param  decoder  A decoder instance to query.
 613  * \assert
 614  *    \code decoder != NULL \endcode
 615  * \retval const char *
 616  *    The decoder state as a C string.  Do not modify the contents.
 617  */
 618 FLAC_API const char *FLAC__stream_decoder_get_resolved_state_string(const FLAC__StreamDecoder *decoder);
 619
 620 /** Get the current number of channels in the stream being decoded.
 621  *  Will only be valid after decoding has started and will contain the
 622  *  value from the most recently decoded frame header.
 623  *
 624  * \param  decoder  A decoder instance to query.
 625  * \assert
 626  *    \code decoder != NULL \endcode
 627  * \retval unsigned
 628  *    See above.
 629  */
 630 FLAC_API unsigned FLAC__stream_decoder_get_channels(const FLAC__StreamDecoder *decoder);
 631
 632 /** Get the current channel assignment in the stream being decoded.
 633  *  Will only be valid after decoding has started and will contain the
 634  *  value from the most recently decoded frame header.
 635  *
 636  * \param  decoder  A decoder instance to query.
 637  * \assert
 638  *    \code decoder != NULL \endcode
 639  * \retval FLAC__ChannelAssignment
 640  *    See above.
 641  */
 642 FLAC_API FLAC__ChannelAssignment FLAC__stream_decoder_get_channel_assignment(const FLAC__StreamDecoder *decoder);
 643
 644 /** Get the current sample resolution in the stream being decoded.
 645  *  Will only be valid after decoding has started and will contain the
 646  *  value from the most recently decoded frame header.
 647  *
 648  * \param  decoder  A decoder instance to query.
 649  * \assert
 650  *    \code decoder != NULL \endcode
 651  * \retval unsigned
 652  *    See above.
 653  */
 654 FLAC_API unsigned FLAC__stream_decoder_get_bits_per_sample(const FLAC__StreamDecoder *decoder);
 655
 656 /** Get the current sample rate in Hz of the stream being decoded.
 657  *  Will only be valid after decoding has started and will contain the
 658  *  value from the most recently decoded frame header.
 659  *
 660  * \param  decoder  A decoder instance to query.
 661  * \assert
 662  *    \code decoder != NULL \endcode
 663  * \retval unsigned
 664  *    See above.
 665  */
 666 FLAC_API unsigned FLAC__stream_decoder_get_sample_rate(const FLAC__StreamDecoder *decoder);
 667
 668 /** Get the current blocksize of the stream being decoded.
 669  *  Will only be valid after decoding has started and will contain the
 670  *  value from the most recently decoded frame header.
 671  *
 672  * \param  decoder  A decoder instance to query.
 673  * \assert
 674  *    \code decoder != NULL \endcode
 675  * \retval unsigned
 676  *    See above.
 677  */
 678 FLAC_API unsigned FLAC__stream_decoder_get_blocksize(const FLAC__StreamDecoder *decoder);
 679
 680 /** Initialize the decoder instance.
 681  *  Should be called after FLAC__stream_decoder_new() and
 682  *  FLAC__stream_decoder_set_*() but before any of the
 683  *  FLAC__stream_decoder_process_*() functions.  Will set and return the
 684  *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
 685  *  if initialization succeeded.
 686  *
 687  * \param  decoder  An uninitialized decoder instance.
 688  * \assert
 689  *    \code decoder != NULL \endcode
 690  * \retval FLAC__StreamDecoderState
 691  *    \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA if initialization was
 692  *    successful; see FLAC__StreamDecoderState for the meanings of other
 693  *    return values.
 694  */
 695 FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_init(FLAC__StreamDecoder *decoder);
 696
 697 /** Finish the decoding process.
 698  *  Flushes the decoding buffer, releases resources, resets the decoder
 699  *  settings to their defaults, and returns the decoder state to
 700  *  FLAC__STREAM_DECODER_UNINITIALIZED.
 701  *
 702  *  In the event of a prematurely-terminated decode, it is not strictly
 703  *  necessary to call this immediately before FLAC__stream_decoder_delete()
 704  *  but it is good practice to match every FLAC__stream_decoder_init()
 705  *  with a FLAC__stream_decoder_finish().
 706  *
 707  * \param  decoder  An uninitialized decoder instance.
 708  * \assert
 709  *    \code decoder != NULL \endcode
 710  */
 711 FLAC_API void FLAC__stream_decoder_finish(FLAC__StreamDecoder *decoder);
 712
 713 /** Flush the stream input.
 714  *  The decoder's input buffer will be cleared and the state set to
 715  *  \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.
 716  *
 717  * \param  decoder  A decoder instance.
 718  * \assert
 719  *    \code decoder != NULL \endcode
 720  * \retval FLAC__bool
 721  *    \c true if successful, else \c false if a memory allocation
 722  *    error occurs.
 723  */
 724 FLAC_API FLAC__bool FLAC__stream_decoder_flush(FLAC__StreamDecoder *decoder);
 725
 726 /** Reset the decoding process.
 727  *  The decoder's input buffer will be cleared and the state set to
 728  *  \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.  This is similar to
 729  *  FLAC__stream_decoder_finish() except that the settings are
 730  *  preserved; there is no need to call FLAC__stream_decoder_init()
 731  *  before decoding again.
 732  *
 733  * \param  decoder  A decoder instance.
 734  * \assert
 735  *    \code decoder != NULL \endcode
 736  * \retval FLAC__bool
 737  *    \c true if successful, else \c false if a memory allocation
 738  *    error occurs.
 739  */
 740 FLAC_API FLAC__bool FLAC__stream_decoder_reset(FLAC__StreamDecoder *decoder);
 741
 742 /** Decode one metadata block or audio frame.
 743  *  This version instructs the decoder to decode a either a single metadata
 744  *  block or a single frame and stop, unless the callbacks return a fatal
 745  *  error or the read callback returns
 746  *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
 747  *
 748  *  As the decoder needs more input it will call the read callback.
 749  *  Depending on what was decoded, the metadata or write callback will be
 750  *  called with the decoded metadata block or audio frame, unless an error
 751  *  occurred.  If the decoder loses sync it will call the error callback
 752  *  instead.
 753  *
 754  * \param  decoder  An initialized decoder instance in the state
 755  *                  \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.
 756  * \assert
 757  *    \code decoder != NULL \endcode
 758  *    \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC \endcode
 759  * \retval FLAC__bool
 760  *    \c false if any read or write error occurred (except
 761  *    \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
 762  *    in any case, check the decoder state with
 763  *    FLAC__stream_decoder_get_state() to see what went wrong or to
 764  *    check for lost synchronization (a sign of stream corruption).
 765  */
 766 FLAC_API FLAC__bool FLAC__stream_decoder_process_single(FLAC__StreamDecoder *decoder);
 767
 768 /** Decode until the end of the metadata.
 769  *  This version instructs the decoder to decode from the current position
 770  *  and continue until all the metadata has been read, or until the
 771  *  callbacks return a fatal error or the read callback returns
 772  *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
 773  *
 774  *  As the decoder needs more input it will call the read callback.
 775  *  As each metadata block is decoded, the metadata callback will be called
 776  *  with the decoded metadata.  If the decoder loses sync it will call the
 777  *  error callback.
 778  *
 779  * \param  decoder  An initialized decoder instance in the state
 780  *                  \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.
 781  * \assert
 782  *    \code decoder != NULL \endcode
 783  *    \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_METADATA \endcode
 784  * \retval FLAC__bool
 785  *    \c false if any read or write error occurred (except
 786  *    \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
 787  *    in any case, check the decoder state with
 788  *    FLAC__stream_decoder_get_state() to see what went wrong or to
 789  *    check for lost synchronization (a sign of stream corruption).
 790  */
 791 FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_metadata(FLAC__StreamDecoder *decoder);
 792
 793 /** Decode until the end of the stream.
 794  *  This version instructs the decoder to decode from the current position
 795  *  and continue until the end of stream (the read callback returns
 796  *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM), or until the
 797  *  callbacks return a fatal error.
 798  *
 799  *  As the decoder needs more input it will call the read callback.
 800  *  As each metadata block and frame is decoded, the metadata or write
 801  *  callback will be called with the decoded metadata or frame.  If the
 802  *  decoder loses sync it will call the error callback.
 803  *
 804  * \param  decoder  An initialized decoder instance in the state
 805  *                  \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.
 806  * \assert
 807  *    \code decoder != NULL \endcode
 808  *    \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_METADATA \endcode
 809  * \retval FLAC__bool
 810  *    \c false if any read or write error occurred (except
 811  *    \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
 812  *    in any case, check the decoder state with
 813  *    FLAC__stream_decoder_get_state() to see what went wrong or to
 814  *    check for lost synchronization (a sign of stream corruption).
 815  */
 816 FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_stream(FLAC__StreamDecoder *decoder);
 817
 818 /* \} */
 819
 820 #ifdef __cplusplus
 821 }
 822 #endif
 823
 824 #endif