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