include/FLAC/seekable_stream_decoder.h

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