include/FLAC/file_decoder.h

   1 /* libFLAC - Free Lossless Audio Codec library
   2  * Copyright (C) 2000,2001,2002,2003,2004  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__FILE_DECODER_H
  33 #define FLAC__FILE_DECODER_H
  34
  35 #include "export.h"
  36 #include "seekable_stream_decoder.h"
  37
  38 #ifdef __cplusplus
  39 extern "C" {
  40 #endif
  41
  42
  43 /** \file include/FLAC/file_decoder.h
  44  *
  45  *  \brief
  46  *  This module contains the functions which implement the file
  47  *  decoder.
  48  *
  49  *  See the detailed documentation in the
  50  *  \link flac_file_decoder file decoder \endlink module.
  51  */
  52
  53 /** \defgroup flac_file_decoder FLAC/file_decoder.h: file decoder interface
  54  *  \ingroup flac_decoder
  55  *
  56  *  \brief
  57  *  This module contains the functions which implement the file
  58  *  decoder.
  59  *
  60  * The basic usage of this decoder is as follows:
  61  * - The program creates an instance of a decoder using
  62  *   FLAC__file_decoder_new().
  63  * - The program overrides the default settings and sets callbacks for
  64  *   writing, error reporting, and metadata reporting using
  65  *   FLAC__file_decoder_set_*() functions.
  66  * - The program initializes the instance to validate the settings and
  67  *   prepare for decoding using FLAC__file_decoder_init().
  68  * - The program calls the FLAC__file_decoder_process_*() functions
  69  *   to decode data, which subsequently calls the callbacks.
  70  * - The program finishes the decoding with FLAC__file_decoder_finish(),
  71  *   which flushes the input and output and resets the decoder to the
  72  *   uninitialized state.
  73  * - The instance may be used again or deleted with
  74  *   FLAC__file_decoder_delete().
  75  *
  76  * The file decoder is a trivial wrapper around the
  77  * \link flac_seekable_stream_decoder seekable stream decoder \endlink
  78  * meant to simplfy the process of decoding from a standard file.  The
  79  * file decoder supplies all but the Write/Metadata/Error callbacks.
  80  * The user needs only to provide the path to the file and the file
  81  * decoder handles the rest.
  82  *
  83  * Like the seekable stream decoder, seeking is exposed through the
  84  * FLAC__file_decoder_seek_absolute() method.  At any point after the file
  85  * decoder has been initialized, the user can call this function to seek to
  86  * an exact sample within the file.  Subsequently, the first time the write
  87  * callback is called it will be passed a (possibly partial) block starting
  88  * at that sample.
  89  *
  90  * The file decoder also inherits MD5 signature checking from the seekable
  91  * stream decoder.  If this is turned on before initialization,
  92  * FLAC__file_decoder_finish() will report when the decoded MD5 signature
  93  * does not match the one stored in the STREAMINFO block.  MD5 checking is
  94  * automatically turned off if there is no signature in the STREAMINFO
  95  * block or when a seek is attempted.
  96  *
  97  * Make sure to read the detailed descriptions of the
  98  * \link flac_seekable_stream_decoder seekable stream decoder module \endlink
  99  * and \link flac_stream_decoder stream decoder module \endlink
 100  * since the file decoder inherits much of its behavior from them.
 101  *
 102  * \note
 103  * The "set" functions may only be called when the decoder is in the
 104  * state FLAC__FILE_DECODER_UNINITIALIZED, i.e. after
 105  * FLAC__file_decoder_new() or FLAC__file_decoder_finish(), but
 106  * before FLAC__file_decoder_init().  If this is the case they will
 107  * return \c true, otherwise \c false.
 108  *
 109  * \note
 110  * FLAC__file_decoder_finish() resets all settings to the constructor
 111  * defaults, including the callbacks.
 112  *
 113  * \{
 114  */
 115
 116
 117 /** State values for a FLAC__FileDecoder
 118  *
 119  *  The decoder's state can be obtained by calling FLAC__file_decoder_get_state().
 120  */
 121 typedef enum {
 122
 123         FLAC__FILE_DECODER_OK = 0,
 124         /**< The decoder is in the normal OK state. */
 125
 126         FLAC__FILE_DECODER_END_OF_FILE,
 127         /**< The decoder has reached the end of the file. */
 128
 129         FLAC__FILE_DECODER_ERROR_OPENING_FILE,
 130         /**< An error occurred opening the input file. */
 131
 132         FLAC__FILE_DECODER_MEMORY_ALLOCATION_ERROR,
 133         /**< An error occurred allocating memory. */
 134
 135         FLAC__FILE_DECODER_SEEK_ERROR,
 136         /**< An error occurred while seeking. */
 137
 138         FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR,
 139         /**< An error occurred in the underlying seekable stream decoder. */
 140
 141         FLAC__FILE_DECODER_ALREADY_INITIALIZED,
 142         /**< FLAC__file_decoder_init() was called when the decoder was already
 143          * initialized, usually because FLAC__file_decoder_finish() was not
 144          * called.
 145          */
 146
 147         FLAC__FILE_DECODER_INVALID_CALLBACK,
 148         /**< FLAC__file_decoder_init() was called without all callbacks
 149          * being set.
 150          */
 151
 152         FLAC__FILE_DECODER_UNINITIALIZED
 153         /**< The decoder is in the uninitialized state. */
 154
 155 } FLAC__FileDecoderState;
 156
 157 /** Maps a FLAC__FileDecoderState to a C string.
 158  *
 159  *  Using a FLAC__FileDecoderState as the index to this array
 160  *  will give the string equivalent.  The contents should not be modified.
 161  */
 162 extern FLAC_API const char * const FLAC__FileDecoderStateString[];
 163
 164
 165 /***********************************************************************
 166  *
 167  * class FLAC__FileDecoder : public FLAC__StreamDecoder
 168  *
 169  ***********************************************************************/
 170
 171 struct FLAC__FileDecoderProtected;
 172 struct FLAC__FileDecoderPrivate;
 173 /** The opaque structure definition for the file decoder type.  See the
 174  *  \link flac_file_decoder file decoder module \endlink for a detailed
 175  *  description.
 176  */
 177 typedef struct {
 178         struct FLAC__FileDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
 179         struct FLAC__FileDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
 180 } FLAC__FileDecoder;
 181
 182 /** Signature for the write callback.
 183  *  See FLAC__file_decoder_set_write_callback()
 184  *  and FLAC__SeekableStreamDecoderWriteCallback for more info.
 185  *
 186  * \param  decoder  The decoder instance calling the callback.
 187  * \param  frame    The description of the decoded frame.
 188  * \param  buffer   An array of pointers to decoded channels of data.
 189  * \param  client_data  The callee's client data set through
 190  *                      FLAC__file_decoder_set_client_data().
 191  * \retval FLAC__StreamDecoderWriteStatus
 192  *    The callee's return status.
 193  */
 194 typedef FLAC__StreamDecoderWriteStatus (*FLAC__FileDecoderWriteCallback)(const FLAC__FileDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
 195
 196 /** Signature for the metadata callback.
 197  *  See FLAC__file_decoder_set_metadata_callback()
 198  *  and FLAC__SeekableStreamDecoderMetadataCallback for more info.
 199  *
 200  * \param  decoder  The decoder instance calling the callback.
 201  * \param  metadata The decoded metadata block.
 202  * \param  client_data  The callee's client data set through
 203  *                      FLAC__file_decoder_set_client_data().
 204  */
 205 typedef void (*FLAC__FileDecoderMetadataCallback)(const FLAC__FileDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
 206
 207 /** Signature for the error callback.
 208  *  See FLAC__file_decoder_set_error_callback()
 209  *  and FLAC__SeekableStreamDecoderErrorCallback for more info.
 210  *
 211  * \param  decoder  The decoder instance calling the callback.
 212  * \param  status   The error encountered by the decoder.
 213  * \param  client_data  The callee's client data set through
 214  *                      FLAC__file_decoder_set_client_data().
 215  */
 216 typedef void (*FLAC__FileDecoderErrorCallback)(const FLAC__FileDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
 217
 218
 219 /***********************************************************************
 220  *
 221  * Class constructor/destructor
 222  *
 223  ***********************************************************************/
 224
 225 /** Create a new file decoder instance.  The instance is created with
 226  *  default settings; see the individual FLAC__file_decoder_set_*()
 227  *  functions for each setting's default.
 228  *
 229  * \retval FLAC__FileDecoder*
 230  *    \c NULL if there was an error allocating memory, else the new instance.
 231  */
 232 FLAC_API FLAC__FileDecoder *FLAC__file_decoder_new();
 233
 234 /** Free a decoder instance.  Deletes the object pointed to by \a decoder.
 235  *
 236  * \param decoder  A pointer to an existing decoder.
 237  * \assert
 238  *    \code decoder != NULL \endcode
 239  */
 240 FLAC_API void FLAC__file_decoder_delete(FLAC__FileDecoder *decoder);
 241
 242
 243 /***********************************************************************
 244  *
 245  * Public class method prototypes
 246  *
 247  ***********************************************************************/
 248
 249 /** Set the "MD5 signature checking" flag.
 250  *  This is inherited from FLAC__SeekableStreamDecoder; see
 251  *  FLAC__seekable_stream_decoder_set_md5_checking().
 252  *
 253  * \default \c false
 254  * \param  decoder  A decoder instance to set.
 255  * \param  value    See above.
 256  * \assert
 257  *    \code decoder != NULL \endcode
 258  * \retval FLAC__bool
 259  *    \c false if the decoder is already initialized, else \c true.
 260  */
 261 FLAC_API FLAC__bool FLAC__file_decoder_set_md5_checking(FLAC__FileDecoder *decoder, FLAC__bool value);
 262
 263 /** Set the input file name to decode.
 264  *
 265  * \default \c "-"
 266  * \param  decoder  A decoder instance to set.
 267  * \param  value    The input file name, or "-" for \c stdin.
 268  * \assert
 269  *    \code decoder != NULL \endcode
 270  *    \code value != NULL \endcode
 271  * \retval FLAC__bool
 272  *    \c false if the decoder is already initialized, or there was a memory
 273  *    allocation error, else \c true.
 274  */
 275 FLAC_API FLAC__bool FLAC__file_decoder_set_filename(FLAC__FileDecoder *decoder, const char *value);
 276
 277 /** Set the write callback.
 278  *  This is inherited from FLAC__SeekableStreamDecoder; see
 279  *  FLAC__seekable_stream_decoder_set_write_callback().
 280  *
 281  * \note
 282  * The callback is mandatory and must be set before initialization.
 283  *
 284  * \default \c NULL
 285  * \param  decoder  A decoder instance to set.
 286  * \param  value    See above.
 287  * \assert
 288  *    \code decoder != NULL \endcode
 289  *    \code value != NULL \endcode
 290  * \retval FLAC__bool
 291  *    \c false if the decoder is already initialized, else \c true.
 292  */
 293 FLAC_API FLAC__bool FLAC__file_decoder_set_write_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderWriteCallback value);
 294
 295 /** Set the metadata callback.
 296  *  This is inherited from FLAC__SeekableStreamDecoder; see
 297  *  FLAC__seekable_stream_decoder_set_metadata_callback().
 298  *
 299  * \note
 300  * The callback is mandatory and must be set before initialization.
 301  *
 302  * \default \c NULL
 303  * \param  decoder  A decoder instance to set.
 304  * \param  value    See above.
 305  * \assert
 306  *    \code decoder != NULL \endcode
 307  *    \code value != NULL \endcode
 308  * \retval FLAC__bool
 309  *    \c false if the decoder is already initialized, else \c true.
 310  */
 311 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderMetadataCallback value);
 312
 313 /** Set the error callback.
 314  *  This is inherited from FLAC__SeekableStreamDecoder; see
 315  *  FLAC__seekable_stream_decoder_set_error_callback().
 316  *
 317  * \note
 318  * The callback is mandatory and must be set before initialization.
 319  *
 320  * \default \c NULL
 321  * \param  decoder  A decoder instance to set.
 322  * \param  value    See above.
 323  * \assert
 324  *    \code decoder != NULL \endcode
 325  *    \code value != NULL \endcode
 326  * \retval FLAC__bool
 327  *    \c false if the decoder is already initialized, else \c true.
 328  */
 329 FLAC_API FLAC__bool FLAC__file_decoder_set_error_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderErrorCallback value);
 330
 331 /** Set the client data to be passed back to callbacks.
 332  *  This value will be supplied to callbacks in their \a client_data
 333  *  argument.
 334  *
 335  * \default \c NULL
 336  * \param  decoder  A decoder instance to set.
 337  * \param  value    See above.
 338  * \assert
 339  *    \code decoder != NULL \endcode
 340  * \retval FLAC__bool
 341  *    \c false if the decoder is already initialized, else \c true.
 342  */
 343 FLAC_API FLAC__bool FLAC__file_decoder_set_client_data(FLAC__FileDecoder *decoder, void *value);
 344
 345 /** This is inherited from FLAC__SeekableStreamDecoder; see
 346  *  FLAC__seekable_stream_decoder_set_metadata_respond().
 347  *
 348  * \default By default, only the \c STREAMINFO block is returned via the
 349  *          metadata callback.
 350  * \param  decoder  A decoder instance to set.
 351  * \param  type     See above.
 352  * \assert
 353  *    \code decoder != NULL \endcode
 354  *    \a type is valid
 355  * \retval FLAC__bool
 356  *    \c false if the decoder is already initialized, else \c true.
 357  */
 358 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond(FLAC__FileDecoder *decoder, FLAC__MetadataType type);
 359
 360 /** This is inherited from FLAC__SeekableStreamDecoder; see
 361  *  FLAC__seekable_stream_decoder_set_metadata_respond_application().
 362  *
 363  * \default By default, only the \c STREAMINFO block is returned via the
 364  *          metadata callback.
 365  * \param  decoder  A decoder instance to set.
 366  * \param  id       See above.
 367  * \assert
 368  *    \code decoder != NULL \endcode
 369  *    \code id != NULL \endcode
 370  * \retval FLAC__bool
 371  *    \c false if the decoder is already initialized, else \c true.
 372  */
 373 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond_application(FLAC__FileDecoder *decoder, const FLAC__byte id[4]);
 374
 375 /** This is inherited from FLAC__SeekableStreamDecoder; see
 376  *  FLAC__seekable_stream_decoder_set_metadata_respond_all().
 377  *
 378  * \default By default, only the \c STREAMINFO block is returned via the
 379  *          metadata callback.
 380  * \param  decoder  A decoder instance to set.
 381  * \assert
 382  *    \code decoder != NULL \endcode
 383  * \retval FLAC__bool
 384  *    \c false if the decoder is already initialized, else \c true.
 385  */
 386 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond_all(FLAC__FileDecoder *decoder);
 387
 388 /** This is inherited from FLAC__SeekableStreamDecoder; see
 389  *  FLAC__seekable_stream_decoder_set_metadata_ignore().
 390  *
 391  * \default By default, only the \c STREAMINFO block is returned via the
 392  *          metadata callback.
 393  * \param  decoder  A decoder instance to set.
 394  * \param  type     See above.
 395  * \assert
 396  *    \code decoder != NULL \endcode
 397  *    \a type is valid
 398  * \retval FLAC__bool
 399  *    \c false if the decoder is already initialized, else \c true.
 400  */
 401 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore(FLAC__FileDecoder *decoder, FLAC__MetadataType type);
 402
 403 /** This is inherited from FLAC__SeekableStreamDecoder; see
 404  *  FLAC__seekable_stream_decoder_set_metadata_ignore_application().
 405  *
 406  * \default By default, only the \c STREAMINFO block is returned via the
 407  *          metadata callback.
 408  * \param  decoder  A decoder instance to set.
 409  * \param  id       See above.
 410  * \assert
 411  *    \code decoder != NULL \endcode
 412  *    \code id != NULL \endcode
 413  * \retval FLAC__bool
 414  *    \c false if the decoder is already initialized, else \c true.
 415  */
 416 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore_application(FLAC__FileDecoder *decoder, const FLAC__byte id[4]);
 417
 418 /** This is inherited from FLAC__SeekableStreamDecoder; see
 419  *  FLAC__seekable_stream_decoder_set_metadata_ignore_all().
 420  *
 421  * \default By default, only the \c STREAMINFO block is returned via the
 422  *          metadata callback.
 423  * \param  decoder  A decoder instance to set.
 424  * \assert
 425  *    \code decoder != NULL \endcode
 426  * \retval FLAC__bool
 427  *    \c false if the decoder is already initialized, else \c true.
 428  */
 429 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore_all(FLAC__FileDecoder *decoder);
 430
 431 /** Get the current decoder state.
 432  *
 433  * \param  decoder  A decoder instance to query.
 434  * \assert
 435  *    \code decoder != NULL \endcode
 436  * \retval FLAC__FileDecoderState
 437  *    The current decoder state.
 438  */
 439 FLAC_API FLAC__FileDecoderState FLAC__file_decoder_get_state(const FLAC__FileDecoder *decoder);
 440
 441 /** Get the state of the underlying seekable stream decoder.
 442  *  Useful when the file decoder state is
 443  *  \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR.
 444  *
 445  * \param  decoder  A decoder instance to query.
 446  * \assert
 447  *    \code decoder != NULL \endcode
 448  * \retval FLAC__SeekableStreamDecoderState
 449  *    The seekable stream decoder state.
 450  */
 451 FLAC_API FLAC__SeekableStreamDecoderState FLAC__file_decoder_get_seekable_stream_decoder_state(const FLAC__FileDecoder *decoder);
 452
 453 /** Get the state of the underlying stream decoder.
 454  *  Useful when the file decoder state is
 455  *  \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR and the seekable stream
 456  *  decoder state is \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
 457  *
 458  * \param  decoder  A decoder instance to query.
 459  * \assert
 460  *    \code decoder != NULL \endcode
 461  * \retval FLAC__StreamDecoderState
 462  *    The seekable stream decoder state.
 463  */
 464 FLAC_API FLAC__StreamDecoderState FLAC__file_decoder_get_stream_decoder_state(const FLAC__FileDecoder *decoder);
 465
 466 /** Get the current decoder state as a C string.
 467  *  This version automatically resolves
 468  *  \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR by getting the
 469  *  seekable stream decoder's state.
 470  *
 471  * \param  decoder  A decoder instance to query.
 472  * \assert
 473  *    \code decoder != NULL \endcode
 474  * \retval const char *
 475  *    The decoder state as a C string.  Do not modify the contents.
 476  */
 477 FLAC_API const char *FLAC__file_decoder_get_resolved_state_string(const FLAC__FileDecoder *decoder);
 478
 479 /** Get the "MD5 signature checking" flag.
 480  *  This is inherited from FLAC__SeekableStreamDecoder; see
 481  *  FLAC__seekable_stream_decoder_get_md5_checking().
 482  *
 483  * \param  decoder  A decoder instance to query.
 484  * \assert
 485  *    \code decoder != NULL \endcode
 486  * \retval FLAC__bool
 487  *    See above.
 488  */
 489 FLAC_API FLAC__bool FLAC__file_decoder_get_md5_checking(const FLAC__FileDecoder *decoder);
 490
 491 /** This is inherited from FLAC__SeekableStreamDecoder; see
 492  *  FLAC__seekable_stream_decoder_get_channels().
 493  *
 494  * \param  decoder  A decoder instance to query.
 495  * \assert
 496  *    \code decoder != NULL \endcode
 497  * \retval unsigned
 498  *    See above.
 499  */
 500 FLAC_API unsigned FLAC__file_decoder_get_channels(const FLAC__FileDecoder *decoder);
 501
 502 /** This is inherited from FLAC__SeekableStreamDecoder; see
 503  *  FLAC__seekable_stream_decoder_get_channel_assignment().
 504  *
 505  * \param  decoder  A decoder instance to query.
 506  * \assert
 507  *    \code decoder != NULL \endcode
 508  * \retval FLAC__ChannelAssignment
 509  *    See above.
 510  */
 511 FLAC_API FLAC__ChannelAssignment FLAC__file_decoder_get_channel_assignment(const FLAC__FileDecoder *decoder);
 512
 513 /** This is inherited from FLAC__SeekableStreamDecoder; see
 514  *  FLAC__seekable_stream_decoder_get_bits_per_sample().
 515  *
 516  * \param  decoder  A decoder instance to query.
 517  * \assert
 518  *    \code decoder != NULL \endcode
 519  * \retval unsigned
 520  *    See above.
 521  */
 522 FLAC_API unsigned FLAC__file_decoder_get_bits_per_sample(const FLAC__FileDecoder *decoder);
 523
 524 /** This is inherited from FLAC__SeekableStreamDecoder; see
 525  *  FLAC__seekable_stream_decoder_get_sample_rate().
 526  *
 527  * \param  decoder  A decoder instance to query.
 528  * \assert
 529  *    \code decoder != NULL \endcode
 530  * \retval unsigned
 531  *    See above.
 532  */
 533 FLAC_API unsigned FLAC__file_decoder_get_sample_rate(const FLAC__FileDecoder *decoder);
 534
 535 /** This is inherited from FLAC__SeekableStreamDecoder; see
 536  *  FLAC__seekable_stream_decoder_get_blocksize().
 537  *
 538  * \param  decoder  A decoder instance to query.
 539  * \assert
 540  *    \code decoder != NULL \endcode
 541  * \retval unsigned
 542  *    See above.
 543  */
 544 FLAC_API unsigned FLAC__file_decoder_get_blocksize(const FLAC__FileDecoder *decoder);
 545
 546 /** This is inherited from FLAC__SeekableStreamDecoder; see
 547  *  FLAC__seekable_stream_decoder_get_decode_position().
 548  *
 549  * \param  decoder   A decoder instance to query.
 550  * \param  position  Address at which to return the desired position.
 551  * \assert
 552  *    \code decoder != NULL \endcode
 553  *    \code position != NULL \endcode
 554  * \retval FLAC__bool
 555  *    \c true if successful, \c false if there was an error from
 556  *    the 'tell' callback.
 557  */
 558 FLAC_API FLAC__bool FLAC__file_decoder_get_decode_position(const FLAC__FileDecoder *decoder, FLAC__uint64 *position);
 559
 560 /** Initialize the decoder instance.
 561  *  Should be called after FLAC__file_decoder_new() and
 562  *  FLAC__file_decoder_set_*() but before any of the
 563  *  FLAC__file_decoder_process_*() functions.  Will set and return
 564  *  the decoder state, which will be FLAC__FILE_DECODER_OK if
 565  *  initialization succeeded.
 566  *
 567  * \param  decoder  An uninitialized decoder instance.
 568  * \assert
 569  *    \code decoder != NULL \endcode
 570  * \retval FLAC__FileDecoderState
 571  *    \c FLAC__FILE_DECODER_OK if initialization was successful; see
 572  *    FLAC__FileDecoderState for the meanings of other return values.
 573  */
 574 FLAC_API FLAC__FileDecoderState FLAC__file_decoder_init(FLAC__FileDecoder *decoder);
 575
 576 /** Finish the decoding process.
 577  *  Flushes the decoding buffer, releases resources, resets the decoder
 578  *  settings to their defaults, and returns the decoder state to
 579  *  FLAC__FILE_DECODER_UNINITIALIZED.
 580  *
 581  *  In the event of a prematurely-terminated decode, it is not strictly
 582  *  necessary to call this immediately before FLAC__file_decoder_delete()
 583  *  but it is good practice to match every FLAC__file_decoder_init() with
 584  *  a FLAC__file_decoder_finish().
 585  *
 586  * \param  decoder  An uninitialized decoder instance.
 587  * \assert
 588  *    \code decoder != NULL \endcode
 589  * \retval FLAC__bool
 590  *    \c false if MD5 checking is on AND a STREAMINFO block was available
 591  *    AND the MD5 signature in the STREAMINFO block was non-zero AND the
 592  *    signature does not match the one computed by the decoder; else
 593  *    \c true.
 594  */
 595 FLAC_API FLAC__bool FLAC__file_decoder_finish(FLAC__FileDecoder *decoder);
 596
 597 /** This is inherited from FLAC__SeekableStreamDecoder; see
 598  *  FLAC__seekable_stream_decoder_process_single().
 599  *
 600  * \param  decoder  A decoder instance.
 601  * \assert
 602  *    \code decoder != NULL \endcode
 603  * \retval FLAC__bool
 604  *    See above.
 605  */
 606 FLAC_API FLAC__bool FLAC__file_decoder_process_single(FLAC__FileDecoder *decoder);
 607
 608 /** This is inherited from FLAC__SeekableStreamDecoder; see
 609  *  FLAC__seekable_stream_decoder_process_until_end_of_metadata().
 610  *
 611  * \param  decoder  A decoder instance.
 612  * \assert
 613  *    \code decoder != NULL \endcode
 614  * \retval FLAC__bool
 615  *    See above.
 616  */
 617 FLAC_API FLAC__bool FLAC__file_decoder_process_until_end_of_metadata(FLAC__FileDecoder *decoder);
 618
 619 /** This is inherited from FLAC__SeekableStreamDecoder; see
 620  *  FLAC__seekable_stream_decoder_process_until_end_of_stream().
 621  *
 622  * \param  decoder  A decoder instance.
 623  * \assert
 624  *    \code decoder != NULL \endcode
 625  * \retval FLAC__bool
 626  *    See above.
 627  */
 628 FLAC_API FLAC__bool FLAC__file_decoder_process_until_end_of_file(FLAC__FileDecoder *decoder);
 629
 630 /** This is inherited from FLAC__SeekableStreamDecoder; see
 631  *  FLAC__seekable_stream_decoder_skip_single_frame().
 632  *
 633  * \param  decoder  A decoder instance.
 634  * \assert
 635  *    \code decoder != NULL \endcode
 636  * \retval FLAC__bool
 637  *    See above.
 638  */
 639 FLAC_API FLAC__bool FLAC__file_decoder_skip_single_frame(FLAC__FileDecoder *decoder);
 640
 641 /** Flush the input and seek to an absolute sample.
 642  *  This is inherited from FLAC__SeekableStreamDecoder; see
 643  *  FLAC__seekable_stream_decoder_seek_absolute().
 644  *
 645  * \param  decoder  A decoder instance.
 646  * \param  sample   The target sample number to seek to.
 647  * \assert
 648  *    \code decoder != NULL \endcode
 649  * \retval FLAC__bool
 650  *    \c true if successful, else \c false.
 651  */
 652 FLAC_API FLAC__bool FLAC__file_decoder_seek_absolute(FLAC__FileDecoder *decoder, FLAC__uint64 sample);
 653
 654 /* \} */
 655
 656 #ifdef __cplusplus
 657 }
 658 #endif
 659
 660 #endif