include/FLAC/seekable_stream_decoder.h

   1 /* libFLAC - Free Lossless Audio Codec library
   2  * Copyright (C) 2000,2001,2002  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__SEEKABLE_STREAM_DECODER_H
  21 #define FLAC__SEEKABLE_STREAM_DECODER_H
  22
  23 #include "stream_decoder.h"
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29
  30 /** \file include/FLAC/seekable_stream_decoder.h
  31  *
  32  *  \brief
  33  *  This module contains the functions which implement the seekable stream
  34  *  decoder.
  35  *
  36  *  See the detailed documentation in the
  37  *  \link flac_seekable_stream_decoder seekable stream decoder \endlink module.
  38  */
  39
  40 /** \defgroup flac_seekable_stream_decoder FLAC/seekable_stream_decoder.h: seekable stream decoder interface
  41  *  \ingroup flac_decoder
  42  *
  43  *  \brief
  44  *  This module contains the functions which implement the seekable stream
  45  *  decoder.
  46  *
  47  * The basic usage of this decoder is as follows:
  48  * - The program creates an instance of a decoder using
  49  *   FLAC__seekable_stream_decoder_new().
  50  * - The program overrides the default settings and sets callbacks for
  51  *   reading, writing, seeking, error reporting, and metadata reporting
  52  *   using FLAC__seekable_stream_decoder_set_*() functions.
  53  * - The program initializes the instance to validate the settings and
  54  *   prepare for decoding using FLAC__seekable_stream_decoder_init().
  55  * - The program calls the FLAC__seekable_stream_decoder_process_*()
  56  *   functions to decode data, which subsequently calls the callbacks.
  57  * - The program finishes the decoding with
  58  *   FLAC__seekable_stream_decoder_finish(), which flushes the input and
  59  *   output and resets the decoder to the uninitialized state.
  60  * - The instance may be used again or deleted with
  61  *   FLAC__seekable_stream_decoder_delete().
  62  *
  63  * The seekable stream decoder is a wrapper around the
  64  * \link flac_stream_decoder stream decoder \endlink which also provides
  65  * seeking capability.  In addition to the Read/Write/Metadata/Error
  66  * callbacks of the stream decoder, the user must also provide the following:
  67  *
  68  * - Seek callback - This function will be called when the decoder wants to
  69  *   seek to an absolute position in the stream.
  70  * - Tell callback - This function will be called when the decoder wants to
  71  *   know the current absolute position of the stream.
  72  * - Length callback - This function will be called when the decoder wants
  73  *   to know length of the stream.  The seeking algorithm currently requires
  74  *   that the overall stream length be known.
  75  * - EOF callback - This function will be called when the decoder wants to
  76  *   know if it is at the end of the stream.  This could be synthesized from
  77  *   the tell and length callbacks but it may be more expensive that way, so
  78  *   there is a separate callback for it.
  79  *
  80  * Seeking is exposed through the
  81  * FLAC__seekable_stream_decoder_seek_absolute() method.  At any point after
  82  * the seekable stream decoder has been initialized, the user can call this
  83  * function to seek to an exact sample within the stream.  Subsequently, the
  84  * first time the write callback is called it will be passed a (possibly
  85  * partial) block starting at that sample.
  86  *
  87  * The seekable stream decoder also provides MD5 signature checking.  If
  88  * this is turned on before initialization,
  89  * FLAC__seekable_stream_decoder_finish() will report when the decoded MD5
  90  * signature does not match the one stored in the STREAMINFO block.  MD5
  91  * checking is automatically turned off (until the next
  92  * FLAC__seekable_stream_decoder_reset()) if there is no signature in the
  93  * STREAMINFO block or when a seek is attempted.
  94  *
  95  * Make sure to read the detailed description of the
  96  * \link flac_stream_decoder stream decoder module \endlink since the
  97  * seekable stream decoder inherits much of its behavior.
  98  *
  99  * \note
 100  * The "set" functions may only be called when the decoder is in the
 101  * state FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED, i.e. after
 102  * FLAC__seekable_stream_decoder_new() or
 103  * FLAC__seekable_stream_decoder_finish(), but before
 104  * FLAC__seekable_stream_decoder_init().  If this is the case they will
 105  * return \c true, otherwise \c false.
 106  *
 107  * \note
 108  * FLAC__stream_decoder_finish() resets all settings to the constructor
 109  * defaults, including the callbacks.
 110  *
 111  * \{
 112  */
 113
 114
 115 /** State values for a FLAC__SeekableStreamDecoder
 116  *
 117  *  The decoder's state can be obtained by calling FLAC__seekable_stream_decoder_get_state().
 118  */
 119 typedef enum {
 120
 121         FLAC__SEEKABLE_STREAM_DECODER_OK = 0,
 122         /**< The decoder is in the normal OK state. */
 123
 124         FLAC__SEEKABLE_STREAM_DECODER_SEEKING,
 125         /**< The decoder is in the process of seeking. */
 126
 127         FLAC__SEEKABLE_STREAM_DECODER_END_OF_STREAM,
 128         /**< The decoder has reached the end of the stream. */
 129
 130         FLAC__SEEKABLE_STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
 131         /**< An error occurred allocating memory. */
 132
 133         FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR,
 134         /**< An error occurred in the underlying stream decoder. */
 135
 136         FLAC__SEEKABLE_STREAM_DECODER_READ_ERROR,
 137         /**< The read callback returned an error. */
 138
 139         FLAC__SEEKABLE_STREAM_DECODER_SEEK_ERROR,
 140         /**< An error occurred while seeking or the seek or tell
 141          * callback returned an error.
 142          */
 143
 144         FLAC__SEEKABLE_STREAM_DECODER_ALREADY_INITIALIZED,
 145         /**< FLAC__seekable_stream_decoder_init() was called when the
 146          * decoder was already initialized, usually because
 147          * FLAC__seekable_stream_decoder_finish() was not called.
 148          */
 149
 150         FLAC__SEEKABLE_STREAM_DECODER_INVALID_CALLBACK,
 151         /**< FLAC__seekable_stream_decoder_init() was called without all
 152          * callbacks being set.
 153          */
 154
 155         FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED
 156         /**< The decoder is in the uninitialized state. */
 157
 158 } FLAC__SeekableStreamDecoderState;
 159
 160 /** Maps a FLAC__SeekableStreamDecoderState to a C string.
 161  *
 162  *  Using a FLAC__SeekableStreamDecoderState as the index to this array
 163  *  will give the string equivalent.  The contents should not be modified.
 164  */
 165 extern const char * const FLAC__SeekableStreamDecoderStateString[];
 166
 167
 168 /** Return values for the FLAC__SeekableStreamDecoder read callback.
 169  */
 170 typedef enum {
 171
 172         FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_OK,
 173         /**< The read was OK and decoding can continue. */
 174
 175         FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_ERROR
 176         /**< An unrecoverable error occurred.  The decoder will return from the process call. */
 177
 178 } FLAC__SeekableStreamDecoderReadStatus;
 179
 180 /** Maps a FLAC__SeekableStreamDecoderReadStatus to a C string.
 181  *
 182  *  Using a FLAC__SeekableStreamDecoderReadStatus as the index to this array
 183  *  will give the string equivalent.  The contents should not be modified.
 184  */
 185 extern const char * const FLAC__SeekableStreamDecoderReadStatusString[];
 186
 187
 188 /** Return values for the FLAC__SeekableStreamDecoder seek callback.
 189  */
 190 typedef enum {
 191
 192         FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_OK,
 193         /**< The seek was OK and decoding can continue. */
 194
 195         FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_ERROR
 196         /**< An unrecoverable error occurred.  The decoder will return from the process call. */
 197
 198 } FLAC__SeekableStreamDecoderSeekStatus;
 199
 200 /** Maps a FLAC__SeekableStreamDecoderSeekStatus to a C string.
 201  *
 202  *  Using a FLAC__SeekableStreamDecoderSeekStatus as the index to this array
 203  *  will give the string equivalent.  The contents should not be modified.
 204  */
 205 extern const char * const FLAC__SeekableStreamDecoderSeekStatusString[];
 206
 207
 208 /** Return values for the FLAC__SeekableStreamDecoder tell callback.
 209  */
 210 typedef enum {
 211
 212         FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_OK,
 213         /**< The tell was OK and decoding can continue. */
 214
 215         FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_ERROR
 216         /**< An unrecoverable error occurred.  The decoder will return from the process call. */
 217
 218 } FLAC__SeekableStreamDecoderTellStatus;
 219
 220 /** Maps a FLAC__SeekableStreamDecoderTellStatus to a C string.
 221  *
 222  *  Using a FLAC__SeekableStreamDecoderTellStatus as the index to this array
 223  *  will give the string equivalent.  The contents should not be modified.
 224  */
 225 extern const char * const FLAC__SeekableStreamDecoderTellStatusString[];
 226
 227
 228 /** Return values for the FLAC__SeekableStreamDecoder length callback.
 229  */
 230 typedef enum {
 231
 232         FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_OK,
 233         /**< The length call was OK and decoding can continue. */
 234
 235         FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_ERROR
 236         /**< An unrecoverable error occurred.  The decoder will return from the process call. */
 237
 238 } FLAC__SeekableStreamDecoderLengthStatus;
 239
 240 /** Maps a FLAC__SeekableStreamDecoderLengthStatus to a C string.
 241  *
 242  *  Using a FLAC__SeekableStreamDecoderLengthStatus as the index to this array
 243  *  will give the string equivalent.  The contents should not be modified.
 244  */
 245 extern const char * const FLAC__SeekableStreamDecoderLengthStatusString[];
 246
 247
 248 /***********************************************************************
 249  *
 250  * class FLAC__SeekableStreamDecoder : public FLAC__StreamDecoder
 251  *
 252  ***********************************************************************/
 253
 254 struct FLAC__SeekableStreamDecoderProtected;
 255 struct FLAC__SeekableStreamDecoderPrivate;
 256 /** The opaque structure definition for the seekable stream decoder type.
 257  *  See the
 258  *  \link flac_seekable_stream_decoder seekable stream decoder module \endlink
 259  *  for a detailed description.
 260  */
 261 typedef struct {
 262         struct FLAC__SeekableStreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
 263         struct FLAC__SeekableStreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
 264 } FLAC__SeekableStreamDecoder;
 265
 266 /** Signature for the read callback.
 267  *  See FLAC__seekable_stream_decoder_set_read_callback()
 268  *  and FLAC__StreamDecoderReadCallback for more info.
 269  *
 270  * \param  decoder  The decoder instance calling the callback.
 271  * \param  buffer   A pointer to a location for the callee to store
 272  *                  data to be decoded.
 273  * \param  bytes    A pointer to the size of the buffer.
 274  * \param  client_data  The callee's client data set through
 275  *                      FLAC__seekable_stream_decoder_set_client_data().
 276  * \retval FLAC__SeekableStreamDecoderReadStatus
 277  *    The callee's return status.
 278  */
 279 typedef FLAC__SeekableStreamDecoderReadStatus (*FLAC__SeekableStreamDecoderReadCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
 280
 281 /** Signature for the seek callback.
 282  *  See FLAC__seekable_stream_decoder_set_seek_callback() for more info.
 283  *
 284  * \param  decoder  The decoder instance calling the callback.
 285  * \param  absolute_byte_offset  The offset from the beginning of the stream
 286  *                               to seek to.
 287  * \param  client_data  The callee's client data set through
 288  *                      FLAC__seekable_stream_decoder_set_client_data().
 289  * \retval FLAC__SeekableStreamDecoderSeekStatus
 290  *    The callee's return status.
 291  */
 292 typedef FLAC__SeekableStreamDecoderSeekStatus (*FLAC__SeekableStreamDecoderSeekCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
 293
 294 /** Signature for the tell callback.
 295  *  See FLAC__seekable_stream_decoder_set_tell_callback() for more info.
 296  *
 297  * \param  decoder  The decoder instance calling the callback.
 298  * \param  absolute_byte_offset  A pointer to storage for the current offset
 299  *                               from the beginning of the stream.
 300  * \param  client_data  The callee's client data set through
 301  *                      FLAC__seekable_stream_decoder_set_client_data().
 302  * \retval FLAC__SeekableStreamDecoderTellStatus
 303  *    The callee's return status.
 304  */
 305 typedef FLAC__SeekableStreamDecoderTellStatus (*FLAC__SeekableStreamDecoderTellCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
 306
 307 /** Signature for the length callback.
 308  *  See FLAC__seekable_stream_decoder_set_length_callback() for more info.
 309  *
 310  * \param  decoder  The decoder instance calling the callback.
 311  * \param  stream_length  A pointer to storage for the length of the stream
 312  *                        in bytes.
 313  * \param  client_data  The callee's client data set through
 314  *                      FLAC__seekable_stream_decoder_set_client_data().
 315  * \retval FLAC__SeekableStreamDecoderLengthStatus
 316  *    The callee's return status.
 317  */
 318 typedef FLAC__SeekableStreamDecoderLengthStatus (*FLAC__SeekableStreamDecoderLengthCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
 319
 320 /** Signature for the EOF callback.
 321  *  See FLAC__seekable_stream_decoder_set_eof_callback() for more info.
 322  *
 323  * \param  decoder  The decoder instance calling the callback.
 324  * \param  client_data  The callee's client data set through
 325  *                      FLAC__seekable_stream_decoder_set_client_data().
 326  * \retval FLAC__bool
 327  *    \c true if the currently at the end of the stream, else \c false.
 328  */
 329 typedef FLAC__bool (*FLAC__SeekableStreamDecoderEofCallback)(const FLAC__SeekableStreamDecoder *decoder, void *client_data);
 330
 331 /** Signature for the write callback.
 332  *  See FLAC__seekable_stream_decoder_set_write_callback()
 333  *  and FLAC__StreamDecoderWriteCallback for more info.
 334  *
 335  * \param  decoder  The decoder instance calling the callback.
 336  * \param  frame    The description of the decoded frame.
 337  * \param  buffer   An array of pointers to decoded channels of data.
 338  * \param  client_data  The callee's client data set through
 339  *                      FLAC__seekable_stream_decoder_set_client_data().
 340  * \retval FLAC__StreamDecoderWriteStatus
 341  *    The callee's return status.
 342  */
 343 typedef FLAC__StreamDecoderWriteStatus (*FLAC__SeekableStreamDecoderWriteCallback)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
 344
 345 /** Signature for the metadata callback.
 346  *  See FLAC__seekable_stream_decoder_set_metadata_callback()
 347  *  and FLAC__StreamDecoderMetadataCallback for more info.
 348  *
 349  * \param  decoder  The decoder instance calling the callback.
 350  * \param  metadata The decoded metadata block.
 351  * \param  client_data  The callee's client data set through
 352  *                      FLAC__seekable_stream_decoder_set_client_data().
 353  */
 354 typedef void (*FLAC__SeekableStreamDecoderMetadataCallback)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
 355
 356 /** Signature for the error callback.
 357  *  See FLAC__seekable_stream_decoder_set_error_callback()
 358  *  and FLAC__StreamDecoderErrorCallback for more info.
 359  *
 360  * \param  decoder  The decoder instance calling the callback.
 361  * \param  status   The error encountered by the decoder.
 362  * \param  client_data  The callee's client data set through
 363  *                      FLAC__seekable_stream_decoder_set_client_data().
 364  */
 365 typedef void (*FLAC__SeekableStreamDecoderErrorCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
 366
 367
 368 /***********************************************************************
 369  *
 370  * Class constructor/destructor
 371  *
 372  ***********************************************************************/
 373
 374 /** Create a new seekable stream decoder instance.  The instance is created
 375  *  with default settings; see the individual
 376  *  FLAC__seekable_stream_decoder_set_*() functions for each setting's
 377  *  default.
 378  *
 379  * \retval FLAC__SeekableStreamDecoder*
 380  *    \c NULL if there was an error allocating memory, else the new instance.
 381  */
 382 FLAC__SeekableStreamDecoder *FLAC__seekable_stream_decoder_new();
 383
 384 /** Free a decoder instance.  Deletes the object pointed to by \a decoder.
 385  *
 386  * \param decoder  A pointer to an existing decoder.
 387  * \assert
 388  *    \code decoder != NULL \endcode
 389  */
 390 void FLAC__seekable_stream_decoder_delete(FLAC__SeekableStreamDecoder *decoder);
 391
 392
 393 /***********************************************************************
 394  *
 395  * Public class method prototypes
 396  *
 397  ***********************************************************************/
 398
 399 /** Set the "MD5 signature checking" flag.  If \c true, the decoder will
 400  *  compute the MD5 signature of the unencoded audio data while decoding
 401  *  and compare it to the signature from the STREAMINFO block, if it
 402  *  exists, during FLAC__seekable_stream_decoder_finish().
 403  *
 404  *  MD5 signature checking will be turned off (until the next
 405  *  FLAC__seekable_stream_decoder_reset()) if there is no signature in
 406  *  the STREAMINFO block or when a seek is attempted.
 407  *
 408  * \default \c false
 409  * \param  decoder  A decoder instance to set.
 410  * \param  value    Flag value (see above).
 411  * \assert
 412  *    \code decoder != NULL \endcode
 413  * \retval FLAC__bool
 414  *    \c false if the decoder is already initialized, else \c true.
 415  */
 416 FLAC__bool FLAC__seekable_stream_decoder_set_md5_checking(FLAC__SeekableStreamDecoder *decoder, FLAC__bool value);
 417
 418 /** Set the read callback.
 419  *  This is inherited from FLAC__StreamDecoder; see
 420  *  FLAC__stream_decoder_set_read_callback().
 421  *
 422  * \note
 423  * The callback is mandatory and must be set before initialization.
 424  *
 425  * \default \c NULL
 426  * \param  decoder  A decoder instance to set.
 427  * \param  value    See above.
 428  * \assert
 429  *    \code decoder != NULL \endcode
 430  *    \code value != NULL \endcode
 431  * \retval FLAC__bool
 432  *    \c false if the decoder is already initialized, else \c true.
 433  */
 434 FLAC__bool FLAC__seekable_stream_decoder_set_read_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderReadCallback value);
 435
 436 /** Set the seek callback.
 437  *  The supplied function will be called when the decoder needs to seek
 438  *  the input stream.  The decoder will pass the absolute byte offset
 439  *  to seek to, 0 meaning the beginning of the stream.
 440  *
 441  * \note
 442  * The callback is mandatory and must be set before initialization.
 443  *
 444  * \default \c NULL
 445  * \param  decoder  A decoder instance to set.
 446  * \param  value    See above.
 447  * \assert
 448  *    \code decoder != NULL \endcode
 449  *    \code value != NULL \endcode
 450  * \retval FLAC__bool
 451  *    \c false if the decoder is already initialized, else \c true.
 452  */
 453 FLAC__bool FLAC__seekable_stream_decoder_set_seek_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderSeekCallback value);
 454
 455 /** Set the tell callback.
 456  *  The supplied function will be called when the decoder wants to know
 457  *  the current position of the stream.  The callback should return the
 458  *  byte offset from the beginning of the stream.
 459  *
 460  * \note
 461  * The callback is mandatory and must be set before initialization.
 462  *
 463  * \default \c NULL
 464  * \param  decoder  A decoder instance to set.
 465  * \param  value    See above.
 466  * \assert
 467  *    \code decoder != NULL \endcode
 468  *    \code value != NULL \endcode
 469  * \retval FLAC__bool
 470  *    \c false if the decoder is already initialized, else \c true.
 471  */
 472 FLAC__bool FLAC__seekable_stream_decoder_set_tell_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderTellCallback value);
 473
 474 /** Set the length callback.
 475  *  The supplied function will be called when the decoder wants to know
 476  *  the total length of the stream in bytes.
 477  *
 478  * \note
 479  * The callback is mandatory and must be set before initialization.
 480  *
 481  * \default \c NULL
 482  * \param  decoder  A decoder instance to set.
 483  * \param  value    See above.
 484  * \assert
 485  *    \code decoder != NULL \endcode
 486  *    \code value != NULL \endcode
 487  * \retval FLAC__bool
 488  *    \c false if the decoder is already initialized, else \c true.
 489  */
 490 FLAC__bool FLAC__seekable_stream_decoder_set_length_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderLengthCallback value);
 491
 492 /** Set the eof callback.
 493  *  The supplied function will be called when the decoder needs to know
 494  *  if the end of the stream has been reached.
 495  *
 496  * \note
 497  * The callback is mandatory and must be set before initialization.
 498  *
 499  * \default \c NULL
 500  * \param  decoder  A decoder instance to set.
 501  * \param  value    See above.
 502  * \assert
 503  *    \code decoder != NULL \endcode
 504  *    \code value != NULL \endcode
 505  * \retval FLAC__bool
 506  *    \c false if the decoder is already initialized, else \c true.
 507  */
 508 FLAC__bool FLAC__seekable_stream_decoder_set_eof_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderEofCallback value);
 509
 510 /** Set the write callback.
 511  *  This is inherited from FLAC__StreamDecoder; see
 512  *  FLAC__stream_decoder_set_write_callback().
 513  *
 514  * \note
 515  * The callback is mandatory and must be set before initialization.
 516  *
 517  * \default \c NULL
 518  * \param  decoder  A decoder instance to set.
 519  * \param  value    See above.
 520  * \assert
 521  *    \code decoder != NULL \endcode
 522  *    \code value != NULL \endcode
 523  * \retval FLAC__bool
 524  *    \c false if the decoder is already initialized, else \c true.
 525  */
 526 FLAC__bool FLAC__seekable_stream_decoder_set_write_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderWriteCallback value);
 527
 528 /** Set the metadata callback.
 529  *  This is inherited from FLAC__StreamDecoder; see
 530  *  FLAC__stream_decoder_set_metadata_callback().
 531  *
 532  * \note
 533  * The callback is mandatory and must be set before initialization.
 534  *
 535  * \default \c NULL
 536  * \param  decoder  A decoder instance to set.
 537  * \param  value    See above.
 538  * \assert
 539  *    \code decoder != NULL \endcode
 540  *    \code value != NULL \endcode
 541  * \retval FLAC__bool
 542  *    \c false if the decoder is already initialized, else \c true.
 543  */
 544 FLAC__bool FLAC__seekable_stream_decoder_set_metadata_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderMetadataCallback value);
 545
 546 /** Set the error callback.
 547  *  This is inherited from FLAC__StreamDecoder; see
 548  *  FLAC__stream_decoder_set_error_callback().
 549  *
 550  * \note
 551  * The callback is mandatory and must be set before initialization.
 552  *
 553  * \default \c NULL
 554  * \param  decoder  A decoder instance to set.
 555  * \param  value    See above.
 556  * \assert
 557  *    \code decoder != NULL \endcode
 558  *    \code value != NULL \endcode
 559  * \retval FLAC__bool
 560  *    \c false if the decoder is already initialized, else \c true.
 561  */
 562 FLAC__bool FLAC__seekable_stream_decoder_set_error_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderErrorCallback value);
 563
 564 /** Set the client data to be passed back to callbacks.
 565  *  This value will be supplied to callbacks in their \a client_data
 566  *  argument.
 567  *
 568  * \default \c NULL
 569  * \param  decoder  A decoder instance to set.
 570  * \param  value    See above.
 571  * \assert
 572  *    \code decoder != NULL \endcode
 573  * \retval FLAC__bool
 574  *    \c false if the decoder is already initialized, else \c true.
 575  */
 576 FLAC__bool FLAC__seekable_stream_decoder_set_client_data(FLAC__SeekableStreamDecoder *decoder, void *value);
 577
 578 /** This is inherited from FLAC__StreamDecoder; see
 579  *  FLAC__stream_decoder_set_metadata_respond().
 580  *
 581  * \default By default, only the \c STREAMINFO block is returned via the
 582  *          metadata callback.
 583  * \param  decoder  A decoder instance to set.
 584  * \param  type     See above.
 585  * \assert
 586  *    \code decoder != NULL \endcode
 587  *    \a type is valid
 588  * \retval FLAC__bool
 589  *    \c false if the decoder is already initialized, else \c true.
 590  */
 591 FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond(FLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type);
 592
 593 /** This is inherited from FLAC__StreamDecoder; see
 594  *  FLAC__stream_decoder_set_metadata_respond_application().
 595  *
 596  * \default By default, only the \c STREAMINFO block is returned via the
 597  *          metadata callback.
 598  * \param  decoder  A decoder instance to set.
 599  * \param  id       See above.
 600  * \assert
 601  *    \code decoder != NULL \endcode
 602  *    \code id != NULL \endcode
 603  * \retval FLAC__bool
 604  *    \c false if the decoder is already initialized, else \c true.
 605  */
 606 FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond_application(FLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
 607
 608 /** This is inherited from FLAC__StreamDecoder; see
 609  *  FLAC__stream_decoder_set_metadata_respond_all().
 610  *
 611  * \default By default, only the \c STREAMINFO block is returned via the
 612  *          metadata callback.
 613  * \param  decoder  A decoder instance to set.
 614  * \assert
 615  *    \code decoder != NULL \endcode
 616  * \retval FLAC__bool
 617  *    \c false if the decoder is already initialized, else \c true.
 618  */
 619 FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond_all(FLAC__SeekableStreamDecoder *decoder);
 620
 621 /** This is inherited from FLAC__StreamDecoder; see
 622  *  FLAC__stream_decoder_set_metadata_ignore().
 623  *
 624  * \default By default, only the \c STREAMINFO block is returned via the
 625  *          metadata callback.
 626  * \param  decoder  A decoder instance to set.
 627  * \param  type     See above.
 628  * \assert
 629  *    \code decoder != NULL \endcode
 630  *    \a type is valid
 631  * \retval FLAC__bool
 632  *    \c false if the decoder is already initialized, else \c true.
 633  */
 634 FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore(FLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type);
 635
 636 /** This is inherited from FLAC__StreamDecoder; see
 637  *  FLAC__stream_decoder_set_metadata_ignore_application().
 638  *
 639  * \default By default, only the \c STREAMINFO block is returned via the
 640  *          metadata callback.
 641  * \param  decoder  A decoder instance to set.
 642  * \param  id       See above.
 643  * \assert
 644  *    \code decoder != NULL \endcode
 645  *    \code id != NULL \endcode
 646  * \retval FLAC__bool
 647  *    \c false if the decoder is already initialized, else \c true.
 648  */
 649 FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore_application(FLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
 650
 651 /** This is inherited from FLAC__StreamDecoder; see
 652  *  FLAC__stream_decoder_set_metadata_ignore_all().
 653  *
 654  * \default By default, only the \c STREAMINFO block is returned via the
 655  *          metadata callback.
 656  * \param  decoder  A decoder instance to set.
 657  * \assert
 658  *    \code decoder != NULL \endcode
 659  * \retval FLAC__bool
 660  *    \c false if the decoder is already initialized, else \c true.
 661  */
 662 FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore_all(FLAC__SeekableStreamDecoder *decoder);
 663
 664 /** Get the current decoder state.
 665  *
 666  * \param  decoder  A decoder instance to query.
 667  * \assert
 668  *    \code decoder != NULL \endcode
 669  * \retval FLAC__SeekableStreamDecoderState
 670  *    The current decoder state.
 671  */
 672 FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_get_state(const FLAC__SeekableStreamDecoder *decoder);
 673
 674 /** Get the state of the underlying stream decoder.
 675  *  Useful when the seekable stream decoder state is
 676  *  \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
 677  *
 678  * \param  decoder  A decoder instance to query.
 679  * \assert
 680  *    \code decoder != NULL \endcode
 681  * \retval FLAC__StreamDecoderState
 682  *    The stream decoder state.
 683  */
 684 FLAC__StreamDecoderState FLAC__seekable_stream_decoder_get_stream_decoder_state(const FLAC__SeekableStreamDecoder *decoder);
 685
 686 /** Get the "MD5 signature checking" flag.
 687  *  This is the value of the setting, not whether or not the decoder is
 688  *  currently checking the MD5 (remember, it can be turned off automatically
 689  *  by a seek).  When the decoder is reset the flag will be restored to the
 690  *  value returned by this function.
 691  *
 692  * \param  decoder  A decoder instance to query.
 693  * \assert
 694  *    \code decoder != NULL \endcode
 695  * \retval FLAC__bool
 696  *    See above.
 697  */
 698 FLAC__bool FLAC__seekable_stream_decoder_get_md5_checking(const FLAC__SeekableStreamDecoder *decoder);
 699
 700 /** This is inherited from FLAC__StreamDecoder; see
 701  *  FLAC__stream_decoder_get_channels().
 702  *
 703  * \param  decoder  A decoder instance to query.
 704  * \assert
 705  *    \code decoder != NULL \endcode
 706  * \retval unsigned
 707  *    See above.
 708  */
 709 unsigned FLAC__seekable_stream_decoder_get_channels(const FLAC__SeekableStreamDecoder *decoder);
 710
 711 /** This is inherited from FLAC__StreamDecoder; see
 712  *  FLAC__stream_decoder_get_channel_assignment().
 713  *
 714  * \param  decoder  A decoder instance to query.
 715  * \assert
 716  *    \code decoder != NULL \endcode
 717  * \retval FLAC__ChannelAssignment
 718  *    See above.
 719  */
 720 FLAC__ChannelAssignment FLAC__seekable_stream_decoder_get_channel_assignment(const FLAC__SeekableStreamDecoder *decoder);
 721
 722 /** This is inherited from FLAC__StreamDecoder; see
 723  *  FLAC__stream_decoder_get_bits_per_sample().
 724  *
 725  * \param  decoder  A decoder instance to query.
 726  * \assert
 727  *    \code decoder != NULL \endcode
 728  * \retval unsigned
 729  *    See above.
 730  */
 731 unsigned FLAC__seekable_stream_decoder_get_bits_per_sample(const FLAC__SeekableStreamDecoder *decoder);
 732
 733 /** This is inherited from FLAC__StreamDecoder; see
 734  *  FLAC__stream_decoder_get_sample_rate().
 735  *
 736  * \param  decoder  A decoder instance to query.
 737  * \assert
 738  *    \code decoder != NULL \endcode
 739  * \retval unsigned
 740  *    See above.
 741  */
 742 unsigned FLAC__seekable_stream_decoder_get_sample_rate(const FLAC__SeekableStreamDecoder *decoder);
 743
 744 /** This is inherited from FLAC__StreamDecoder; see
 745  *  FLAC__stream_decoder_get_blocksize().
 746  *
 747  * \param  decoder  A decoder instance to query.
 748  * \assert
 749  *    \code decoder != NULL \endcode
 750  * \retval unsigned
 751  *    See above.
 752  */
 753 unsigned FLAC__seekable_stream_decoder_get_blocksize(const FLAC__SeekableStreamDecoder *decoder);
 754
 755 /** Initialize the decoder instance.
 756  *  Should be called after FLAC__seekable_stream_decoder_new() and
 757  *  FLAC__seekable_stream_decoder_set_*() but before any of the
 758  *  FLAC__seekable_stream_decoder_process_*() functions.  Will set and return
 759  *  the decoder state, which will be FLAC__SEEKABLE_STREAM_DECODER_OK
 760  *  if initialization succeeded.
 761  *
 762  * \param  decoder  An uninitialized decoder instance.
 763  * \assert
 764  *    \code decoder != NULL \endcode
 765  * \retval FLAC__SeekableStreamDecoderState
 766  *    \c FLAC__SEEKABLE_STREAM_DECODER_OK if initialization was
 767  *    successful; see FLAC__SeekableStreamDecoderState for the meanings
 768  *    of other return values.
 769  */
 770 FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_init(FLAC__SeekableStreamDecoder *decoder);
 771
 772 /** Finish the decoding process.
 773  *  Flushes the decoding buffer, releases resources, resets the decoder
 774  *  settings to their defaults, and returns the decoder state to
 775  *  FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED.
 776  *
 777  *  In the event of a prematurely-terminated decode, it is not strictly
 778  *  necessary to call this immediately before
 779  *  FLAC__seekable_stream_decoder_delete() but it is good practice to match
 780  *  every FLAC__seekable_stream_decoder_init() with a
 781  *  FLAC__seekable_stream_decoder_finish().
 782  *
 783  * \param  decoder  An uninitialized decoder instance.
 784  * \assert
 785  *    \code decoder != NULL \endcode
 786  * \retval FLAC__bool
 787  *    \c false if MD5 checking is on AND a STREAMINFO block was available
 788  *    AND the MD5 signature in the STREAMINFO block was non-zero AND the
 789  *    signature does not match the one computed by the decoder; else
 790  *    \c true.
 791  */
 792 FLAC__bool FLAC__seekable_stream_decoder_finish(FLAC__SeekableStreamDecoder *decoder);
 793
 794 /** Flush the stream input.
 795  *  The decoder's input buffer will be cleared and the state set to
 796  *  \c FLAC__SEEKABLE_STREAM_DECODER_OK.  This will also turn off MD5
 797  *  checking.
 798  *
 799  * \param  decoder  A decoder instance.
 800  * \assert
 801  *    \code decoder != NULL \endcode
 802  * \retval FLAC__bool
 803  *    \c true if successful, else \c false if a memory allocation
 804  *    or stream decoder error occurs.
 805  */
 806 FLAC__bool FLAC__seekable_stream_decoder_flush(FLAC__SeekableStreamDecoder *decoder);
 807
 808 /** Reset the decoding process.
 809  *  The decoder's input buffer will be cleared and the state set to
 810  *  \c FLAC__SEEKABLE_STREAM_DECODER_OK.  This is similar to
 811  *  FLAC__seekable_stream_decoder_finish() except that the settings are
 812  *  preserved; there is no need to call FLAC__seekable_stream_decoder_init()
 813  *  before decoding again.  MD5 checking will be restored to its original
 814  *  setting.
 815  *
 816  * \param  decoder  A decoder instance.
 817  * \assert
 818  *    \code decoder != NULL \endcode
 819  * \retval FLAC__bool
 820  *    \c true if successful, else \c false if a memory allocation
 821  *    or stream decoder error occurs.
 822  */
 823 FLAC__bool FLAC__seekable_stream_decoder_reset(FLAC__SeekableStreamDecoder *decoder);
 824
 825 /** This is inherited from FLAC__StreamDecoder; see
 826  *  FLAC__stream_decoder_process_single().
 827  *
 828  * \param  decoder  A decoder instance.
 829  * \assert
 830  *    \code decoder != NULL \endcode
 831  * \retval FLAC__bool
 832  *    See above.
 833  */
 834 FLAC__bool FLAC__seekable_stream_decoder_process_single(FLAC__SeekableStreamDecoder *decoder);
 835
 836 /** This is inherited from FLAC__StreamDecoder; see
 837  *  FLAC__stream_decoder_process_until_end_of_metadata().
 838  *
 839  * \param  decoder  A decoder instance.
 840  * \assert
 841  *    \code decoder != NULL \endcode
 842  * \retval FLAC__bool
 843  *    See above.
 844  */
 845 FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_metadata(FLAC__SeekableStreamDecoder *decoder);
 846
 847 /** This is inherited from FLAC__StreamDecoder; see
 848  *  FLAC__stream_decoder_process_until_end_of_stream().
 849  *
 850  * \param  decoder  A decoder instance.
 851  * \assert
 852  *    \code decoder != NULL \endcode
 853  * \retval FLAC__bool
 854  *    See above.
 855  */
 856 FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_stream(FLAC__SeekableStreamDecoder *decoder);
 857
 858 /** Flush the input and seek to an absolute sample.
 859  *  Decoding will resume at the given sample.  Note that because of
 860  *  this, the next write callback may contain a partial block.
 861  *
 862  * \param  decoder  A decoder instance.
 863  * \param  sample   The target sample number to seek to.
 864  * \assert
 865  *    \code decoder != NULL \endcode
 866  * \retval FLAC__bool
 867  *    \c true if successful, else \c false.
 868  */
 869 FLAC__bool FLAC__seekable_stream_decoder_seek_absolute(FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 sample);
 870
 871 /* \} */
 872
 873 #ifdef __cplusplus
 874 }
 875 #endif
 876
 877 #endif