include/FLAC/file_decoder.h

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