include/OggFLAC/seekable_stream_decoder.h

   1 /* libOggFLAC - Free Lossless Audio Codec + Ogg library
   2  * Copyright (C) 2002,2003,2004,2005,2006 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 OggFLAC__SEEKABLE_STREAM_DECODER_H
  33 #define OggFLAC__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/OggFLAC/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 oggflac_seekable_stream_decoder seekable stream decoder \endlink module.
  51  */
  52
  53 /** \defgroup oggflac_seekable_stream_decoder OggFLAC/seekable_stream_decoder.h: seekable stream decoder interface
  54  *  \ingroup oggflac_decoder
  55  *
  56  *  \brief
  57  *  This module contains the functions which implement the seekable stream
  58  *  decoder.
  59  *
  60  * The interface here is nearly identical to FLAC's seekable stream decoder,
  61  * including the callbacks, with the addition of
  62  * OggFLAC__seekable_stream_decoder_set_serial_number().  See the
  63  * \link flac_seekable_stream_decoder FLAC seekable stream decoder module \endlink
  64  * for full documentation.
  65  *
  66  * \{
  67  */
  68
  69
  70 /** State values for an OggFLAC__SeekableStreamDecoder
  71  *
  72  *  The decoder's state can be obtained by calling OggFLAC__seekable_stream_decoder_get_state().
  73  */
  74 typedef enum {
  75
  76         OggFLAC__SEEKABLE_STREAM_DECODER_OK = 0,
  77         /**< The decoder is in the normal OK state. */
  78
  79         OggFLAC__SEEKABLE_STREAM_DECODER_SEEKING,
  80         /**< The decoder is in the process of seeking. */
  81
  82         OggFLAC__SEEKABLE_STREAM_DECODER_END_OF_STREAM,
  83         /**< The decoder has reached the end of the stream. */
  84
  85         OggFLAC__SEEKABLE_STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
  86         /**< Memory allocation failed. */
  87
  88         OggFLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR,
  89         /**< An error occurred in the underlying stream decoder;
  90          * check OggFLAC__seekable_stream_decoder_get_stream_decoder_state().
  91          */
  92
  93         OggFLAC__SEEKABLE_STREAM_DECODER_READ_ERROR,
  94         /**< The read callback returned an error. */
  95
  96         OggFLAC__SEEKABLE_STREAM_DECODER_SEEK_ERROR,
  97         /**< An error occurred while seeking or the seek or tell
  98          * callback returned an error.
  99          */
 100
 101         OggFLAC__SEEKABLE_STREAM_DECODER_ALREADY_INITIALIZED,
 102         /**< OggFLAC__seekable_stream_decoder_init() was called when the decoder was
 103          * already initialized, usually because
 104          * OggFLAC__seekable_stream_decoder_finish() was not called.
 105          */
 106
 107         OggFLAC__SEEKABLE_STREAM_DECODER_INVALID_CALLBACK,
 108         /**< The decoder was initialized before setting all the required callbacks. */
 109
 110         OggFLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED
 111         /**< The decoder is in the uninitialized state. */
 112
 113 } OggFLAC__SeekableStreamDecoderState;
 114
 115 /** Maps an OggFLAC__SeekableStreamDecoderState to a C string.
 116  *
 117  *  Using an OggFLAC__SeekableStreamDecoderState as the index to this array
 118  *  will give the string equivalent.  The contents should not be modified.
 119  */
 120 extern OggFLAC_API const char * const OggFLAC__SeekableStreamDecoderStateString[];
 121
 122
 123 /** Return values for the OggFLAC__SeekableStreamDecoder read callback.
 124  */
 125 typedef enum {
 126
 127         OggFLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_OK,
 128         /**< The read was OK and decoding can continue. */
 129
 130         OggFLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_ERROR
 131         /**< An unrecoverable error occurred.  The decoder will return from the process call. */
 132
 133 } OggFLAC__SeekableStreamDecoderReadStatus;
 134
 135 /** Maps a OggFLAC__SeekableStreamDecoderReadStatus to a C string.
 136  *
 137  *  Using a OggFLAC__SeekableStreamDecoderReadStatus as the index to this array
 138  *  will give the string equivalent.  The contents should not be modified.
 139  */
 140 extern OggFLAC_API const char * const OggFLAC__SeekableStreamDecoderReadStatusString[];
 141
 142
 143 /** Return values for the OggFLAC__SeekableStreamDecoder seek callback.
 144  */
 145 typedef enum {
 146
 147         OggFLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_OK,
 148         /**< The seek was OK and decoding can continue. */
 149
 150         OggFLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_ERROR
 151         /**< An unrecoverable error occurred.  The decoder will return from the process call. */
 152
 153 } OggFLAC__SeekableStreamDecoderSeekStatus;
 154
 155 /** Maps a OggFLAC__SeekableStreamDecoderSeekStatus to a C string.
 156  *
 157  *  Using a OggFLAC__SeekableStreamDecoderSeekStatus as the index to this array
 158  *  will give the string equivalent.  The contents should not be modified.
 159  */
 160 extern OggFLAC_API const char * const OggFLAC__SeekableStreamDecoderSeekStatusString[];
 161
 162
 163 /** Return values for the OggFLAC__SeekableStreamDecoder tell callback.
 164  */
 165 typedef enum {
 166
 167         OggFLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_OK,
 168         /**< The tell was OK and decoding can continue. */
 169
 170         OggFLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_ERROR
 171         /**< An unrecoverable error occurred.  The decoder will return from the process call. */
 172
 173 } OggFLAC__SeekableStreamDecoderTellStatus;
 174
 175 /** Maps a OggFLAC__SeekableStreamDecoderTellStatus to a C string.
 176  *
 177  *  Using a OggFLAC__SeekableStreamDecoderTellStatus as the index to this array
 178  *  will give the string equivalent.  The contents should not be modified.
 179  */
 180 extern OggFLAC_API const char * const OggFLAC__SeekableStreamDecoderTellStatusString[];
 181
 182
 183 /** Return values for the OggFLAC__SeekableStreamDecoder length callback.
 184  */
 185 typedef enum {
 186
 187         OggFLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_OK,
 188         /**< The length call was OK and decoding can continue. */
 189
 190         OggFLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_ERROR
 191         /**< An unrecoverable error occurred.  The decoder will return from the process call. */
 192
 193 } OggFLAC__SeekableStreamDecoderLengthStatus;
 194
 195 /** Maps a OggFLAC__SeekableStreamDecoderLengthStatus to a C string.
 196  *
 197  *  Using a OggFLAC__SeekableStreamDecoderLengthStatus as the index to this array
 198  *  will give the string equivalent.  The contents should not be modified.
 199  */
 200 extern OggFLAC_API const char * const OggFLAC__SeekableStreamDecoderLengthStatusString[];
 201
 202
 203 /***********************************************************************
 204  *
 205  * class OggFLAC__SeekableStreamDecoder : public FLAC__StreamDecoder
 206  *
 207  ***********************************************************************/
 208
 209 struct OggFLAC__SeekableStreamDecoderProtected;
 210 struct OggFLAC__SeekableStreamDecoderPrivate;
 211 /** The opaque structure definition for the seekable stream decoder type.
 212  *  See the
 213  *  \link oggflac_seekable_stream_decoder seekable stream decoder module \endlink
 214  *  for a detailed description.
 215  */
 216 typedef struct {
 217         struct OggFLAC__SeekableStreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
 218         struct OggFLAC__SeekableStreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
 219 } OggFLAC__SeekableStreamDecoder;
 220
 221 /** Signature for the read callback.
 222  *  See OggFLAC__seekable_stream_decoder_set_read_callback()
 223  *  and OggFLAC__StreamDecoderReadCallback for more info.
 224  *
 225  * \param  decoder  The decoder instance calling the callback.
 226  * \param  buffer   A pointer to a location for the callee to store
 227  *                  data to be decoded.
 228  * \param  bytes    A pointer to the size of the buffer.
 229  * \param  client_data  The callee's client data set through
 230  *                      OggFLAC__seekable_stream_decoder_set_client_data().
 231  * \retval FLAC__SeekableStreamDecoderReadStatus
 232  *    The callee's return status.
 233  */
 234 typedef OggFLAC__SeekableStreamDecoderReadStatus (*OggFLAC__SeekableStreamDecoderReadCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
 235
 236 /** Signature for the seek callback.
 237  *  See OggFLAC__seekable_stream_decoder_set_seek_callback() for more info.
 238  *
 239  * \param  decoder  The decoder instance calling the callback.
 240  * \param  absolute_byte_offset  The offset from the beginning of the stream
 241  *                               to seek to.
 242  * \param  client_data  The callee's client data set through
 243  *                      OggFLAC__seekable_stream_decoder_set_client_data().
 244  * \retval FLAC__SeekableStreamDecoderSeekStatus
 245  *    The callee's return status.
 246  */
 247 typedef OggFLAC__SeekableStreamDecoderSeekStatus (*OggFLAC__SeekableStreamDecoderSeekCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
 248
 249 /** Signature for the tell callback.
 250  *  See OggFLAC__seekable_stream_decoder_set_tell_callback() for more info.
 251  *
 252  * \param  decoder  The decoder instance calling the callback.
 253  * \param  absolute_byte_offset  A pointer to storage for the current offset
 254  *                               from the beginning of the stream.
 255  * \param  client_data  The callee's client data set through
 256  *                      OggFLAC__seekable_stream_decoder_set_client_data().
 257  * \retval FLAC__SeekableStreamDecoderTellStatus
 258  *    The callee's return status.
 259  */
 260 typedef OggFLAC__SeekableStreamDecoderTellStatus (*OggFLAC__SeekableStreamDecoderTellCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
 261
 262 /** Signature for the length callback.
 263  *  See OggFLAC__seekable_stream_decoder_set_length_callback() for more info.
 264  *
 265  * \param  decoder  The decoder instance calling the callback.
 266  * \param  stream_length  A pointer to storage for the length of the stream
 267  *                        in bytes.
 268  * \param  client_data  The callee's client data set through
 269  *                      OggFLAC__seekable_stream_decoder_set_client_data().
 270  * \retval FLAC__SeekableStreamDecoderLengthStatus
 271  *    The callee's return status.
 272  */
 273 typedef OggFLAC__SeekableStreamDecoderLengthStatus (*OggFLAC__SeekableStreamDecoderLengthCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
 274
 275 /** Signature for the EOF callback.
 276  *  See OggFLAC__seekable_stream_decoder_set_eof_callback() for more info.
 277  *
 278  * \param  decoder  The decoder instance calling the callback.
 279  * \param  client_data  The callee's client data set through
 280  *                      OggFLAC__seekable_stream_decoder_set_client_data().
 281  * \retval FLAC__bool
 282  *    \c true if the currently at the end of the stream, else \c false.
 283  */
 284 typedef FLAC__bool (*OggFLAC__SeekableStreamDecoderEofCallback)(const OggFLAC__SeekableStreamDecoder *decoder, void *client_data);
 285
 286 /** Signature for the write callback.
 287  *  See OggFLAC__seekable_stream_decoder_set_write_callback()
 288  *  and OggFLAC__StreamDecoderWriteCallback for more info.
 289  *
 290  * \param  decoder  The decoder instance calling the callback.
 291  * \param  frame    The description of the decoded frame.
 292  * \param  buffer   An array of pointers to decoded channels of data.
 293  * \param  client_data  The callee's client data set through
 294  *                      OggFLAC__seekable_stream_decoder_set_client_data().
 295  * \retval FLAC__StreamDecoderWriteStatus
 296  *    The callee's return status.
 297  */
 298 typedef FLAC__StreamDecoderWriteStatus (*OggFLAC__SeekableStreamDecoderWriteCallback)(const OggFLAC__SeekableStreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
 299
 300 /** Signature for the metadata callback.
 301  *  See OggFLAC__seekable_stream_decoder_set_metadata_callback()
 302  *  and OggFLAC__StreamDecoderMetadataCallback for more info.
 303  *
 304  * \param  decoder  The decoder instance calling the callback.
 305  * \param  metadata The decoded metadata block.
 306  * \param  client_data  The callee's client data set through
 307  *                      OggFLAC__seekable_stream_decoder_set_client_data().
 308  */
 309 typedef void (*OggFLAC__SeekableStreamDecoderMetadataCallback)(const OggFLAC__SeekableStreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
 310
 311 /** Signature for the error callback.
 312  *  See OggFLAC__seekable_stream_decoder_set_error_callback()
 313  *  and OggFLAC__StreamDecoderErrorCallback for more info.
 314  *
 315  * \param  decoder  The decoder instance calling the callback.
 316  * \param  status   The error encountered by the decoder.
 317  * \param  client_data  The callee's client data set through
 318  *                      OggFLAC__seekable_stream_decoder_set_client_data().
 319  */
 320 typedef void (*OggFLAC__SeekableStreamDecoderErrorCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
 321
 322
 323 /***********************************************************************
 324  *
 325  * Class constructor/destructor
 326  *
 327  ***********************************************************************/
 328
 329 /** Create a new seekable stream decoder instance.  The instance is created
 330  *  with default settings; see the individual
 331  *  OggFLAC__seekable_stream_decoder_set_*() functions for each setting's
 332  *  default.
 333  *
 334  * \retval OggFLAC__SeekableStreamDecoder*
 335  *    \c NULL if there was an error allocating memory, else the new instance.
 336  */
 337 OggFLAC_API OggFLAC__SeekableStreamDecoder *OggFLAC__seekable_stream_decoder_new();
 338
 339 /** Free a decoder instance.  Deletes the object pointed to by \a decoder.
 340  *
 341  * \param decoder  A pointer to an existing decoder.
 342  * \assert
 343  *    \code decoder != NULL \endcode
 344  */
 345 OggFLAC_API void OggFLAC__seekable_stream_decoder_delete(OggFLAC__SeekableStreamDecoder *decoder);
 346
 347
 348 /***********************************************************************
 349  *
 350  * Public class method prototypes
 351  *
 352  ***********************************************************************/
 353
 354 /** Set the "MD5 signature checking" flag.
 355  *  This is inherited from FLAC__SeekableStreamDecoder; see
 356  *  FLAC__seekable_stream_decoder_set_md5_checking().
 357  *
 358  * \default \c false
 359  * \param  decoder  A decoder instance to set.
 360  * \param  value    Flag value (see above).
 361  * \assert
 362  *    \code decoder != NULL \endcode
 363  * \retval FLAC__bool
 364  *    \c false if the decoder is already initialized, else \c true.
 365  */
 366 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_md5_checking(OggFLAC__SeekableStreamDecoder *decoder, FLAC__bool value);
 367
 368 /** Set the read callback.
 369  *  This is inherited from FLAC__SeekableStreamDecoder; see
 370  *  FLAC__seekable_stream_decoder_set_read_callback().
 371  *
 372  * \note
 373  * The callback is mandatory and must be set before initialization.
 374  *
 375  * \default \c NULL
 376  * \param  decoder  A decoder instance to set.
 377  * \param  value    See above.
 378  * \assert
 379  *    \code decoder != NULL \endcode
 380  *    \code value != NULL \endcode
 381  * \retval FLAC__bool
 382  *    \c false if the decoder is already initialized, else \c true.
 383  */
 384 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_read_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderReadCallback value);
 385
 386 /** Set the seek callback.
 387  *  This is inherited from FLAC__SeekableStreamDecoder; see
 388  *  FLAC__seekable_stream_decoder_set_seek_callback().
 389  *
 390  * \note
 391  * The callback is mandatory and must be set before initialization.
 392  *
 393  * \default \c NULL
 394  * \param  decoder  A decoder instance to set.
 395  * \param  value    See above.
 396  * \assert
 397  *    \code decoder != NULL \endcode
 398  *    \code value != NULL \endcode
 399  * \retval FLAC__bool
 400  *    \c false if the decoder is already initialized, else \c true.
 401  */
 402 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_seek_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderSeekCallback value);
 403
 404 /** Set the tell callback.
 405  *  This is inherited from FLAC__SeekableStreamDecoder; see
 406  *  FLAC__seekable_stream_decoder_set_tell_callback().
 407  *
 408  * \note
 409  * The callback is mandatory and must be set before initialization.
 410  *
 411  * \default \c NULL
 412  * \param  decoder  A decoder instance to set.
 413  * \param  value    See above.
 414  * \assert
 415  *    \code decoder != NULL \endcode
 416  *    \code value != NULL \endcode
 417  * \retval FLAC__bool
 418  *    \c false if the decoder is already initialized, else \c true.
 419  */
 420 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_tell_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderTellCallback value);
 421
 422 /** Set the length callback.
 423  *  This is inherited from FLAC__SeekableStreamDecoder; see
 424  *  FLAC__seekable_stream_decoder_set_length_callback().
 425  *
 426  * \note
 427  * The callback is mandatory and must be set before initialization.
 428  *
 429  * \default \c NULL
 430  * \param  decoder  A decoder instance to set.
 431  * \param  value    See above.
 432  * \assert
 433  *    \code decoder != NULL \endcode
 434  *    \code value != NULL \endcode
 435  * \retval FLAC__bool
 436  *    \c false if the decoder is already initialized, else \c true.
 437  */
 438 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_length_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderLengthCallback value);
 439
 440 /** Set the eof callback.
 441  *  This is inherited from FLAC__SeekableStreamDecoder; see
 442  *  FLAC__seekable_stream_decoder_set_eof_callback().
 443  *
 444  * \note
 445  * The callback is mandatory and must be set before initialization.
 446  *
 447  * \default \c NULL
 448  * \param  decoder  A decoder instance to set.
 449  * \param  value    See above.
 450  * \assert
 451  *    \code decoder != NULL \endcode
 452  *    \code value != NULL \endcode
 453  * \retval FLAC__bool
 454  *    \c false if the decoder is already initialized, else \c true.
 455  */
 456 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_eof_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderEofCallback value);
 457
 458 /** Set the write callback.
 459  *  This is inherited from FLAC__SeekableStreamDecoder; see
 460  *  FLAC__seekable_stream_decoder_set_write_callback().
 461  *
 462  * \note
 463  * The callback is mandatory and must be set before initialization.
 464  *
 465  * \default \c NULL
 466  * \param  decoder  A decoder instance to set.
 467  * \param  value    See above.
 468  * \assert
 469  *    \code decoder != NULL \endcode
 470  *    \code value != NULL \endcode
 471  * \retval FLAC__bool
 472  *    \c false if the decoder is already initialized, else \c true.
 473  */
 474 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_write_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderWriteCallback value);
 475
 476 /** Set the metadata callback.
 477  *  This is inherited from FLAC__SeekableStreamDecoder; see
 478  *  FLAC__seekable_stream_decoder_set_metadata_callback().
 479  *
 480  * \note
 481  * The callback is mandatory and must be set before initialization.
 482  *
 483  * \default \c NULL
 484  * \param  decoder  A decoder instance to set.
 485  * \param  value    See above.
 486  * \assert
 487  *    \code decoder != NULL \endcode
 488  *    \code value != NULL \endcode
 489  * \retval FLAC__bool
 490  *    \c false if the decoder is already initialized, else \c true.
 491  */
 492 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderMetadataCallback value);
 493
 494 /** Set the error callback.
 495  *  This is inherited from FLAC__SeekableStreamDecoder; see
 496  *  FLAC__seekable_stream_decoder_set_error_callback().
 497  *
 498  * \note
 499  * The callback is mandatory and must be set before initialization.
 500  *
 501  * \default \c NULL
 502  * \param  decoder  A decoder instance to set.
 503  * \param  value    See above.
 504  * \assert
 505  *    \code decoder != NULL \endcode
 506  *    \code value != NULL \endcode
 507  * \retval FLAC__bool
 508  *    \c false if the decoder is already initialized, else \c true.
 509  */
 510 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_error_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderErrorCallback value);
 511
 512 /** Set the client data to be passed back to callbacks.
 513  *  This value will be supplied to callbacks in their \a client_data
 514  *  argument.
 515  *
 516  * \default \c NULL
 517  * \param  decoder  A decoder instance to set.
 518  * \param  value    See above.
 519  * \assert
 520  *    \code decoder != NULL \endcode
 521  * \retval FLAC__bool
 522  *    \c false if the decoder is already initialized, else \c true.
 523  */
 524 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_client_data(OggFLAC__SeekableStreamDecoder *decoder, void *value);
 525
 526 /** Set the serial number for the Ogg stream.
 527  * The default behavior is to use the serial number of the first Ogg
 528  * page.  Setting a serial number here will explicitly specify which
 529  * stream is to be decoded.
 530  *
 531  * \default \c use serial number of first page
 532  * \param  decoder        A decoder instance to set.
 533  * \param  serial_number  See above.
 534  * \assert
 535  *    \code decoder != NULL \endcode
 536  * \retval FLAC__bool
 537  *    \c false if the decoder is already initialized, else \c true.
 538  */
 539 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_serial_number(OggFLAC__SeekableStreamDecoder *decoder, long serial_number);
 540
 541 /** This is inherited from FLAC__SeekableStreamDecoder; see
 542  *  FLAC__seekable_stream_decoder_set_metadata_respond().
 543  *
 544  * \default By default, only the \c STREAMINFO block is returned via the
 545  *          metadata callback.
 546  * \param  decoder  A decoder instance to set.
 547  * \param  type     See above.
 548  * \assert
 549  *    \code decoder != NULL \endcode
 550  *    \a type is valid
 551  * \retval FLAC__bool
 552  *    \c false if the decoder is already initialized, else \c true.
 553  */
 554 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond(OggFLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type);
 555
 556 /** This is inherited from FLAC__SeekableStreamDecoder; see
 557  *  FLAC__seekable_stream_decoder_set_metadata_respond_application().
 558  *
 559  * \default By default, only the \c STREAMINFO block is returned via the
 560  *          metadata callback.
 561  * \param  decoder  A decoder instance to set.
 562  * \param  id       See above.
 563  * \assert
 564  *    \code decoder != NULL \endcode
 565  *    \code id != NULL \endcode
 566  * \retval FLAC__bool
 567  *    \c false if the decoder is already initialized, else \c true.
 568  */
 569 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond_application(OggFLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
 570
 571 /** This is inherited from FLAC__SeekableStreamDecoder; see
 572  *  FLAC__seekable_stream_decoder_set_metadata_respond_all().
 573  *
 574  * \default By default, only the \c STREAMINFO block is returned via the
 575  *          metadata callback.
 576  * \param  decoder  A decoder instance to set.
 577  * \assert
 578  *    \code decoder != NULL \endcode
 579  * \retval FLAC__bool
 580  *    \c false if the decoder is already initialized, else \c true.
 581  */
 582 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond_all(OggFLAC__SeekableStreamDecoder *decoder);
 583
 584 /** This is inherited from FLAC__SeekableStreamDecoder; see
 585  *  FLAC__seekable_stream_decoder_set_metadata_ignore().
 586  *
 587  * \default By default, only the \c STREAMINFO block is returned via the
 588  *          metadata callback.
 589  * \param  decoder  A decoder instance to set.
 590  * \param  type     See above.
 591  * \assert
 592  *    \code decoder != NULL \endcode
 593  *    \a type is valid
 594  * \retval FLAC__bool
 595  *    \c false if the decoder is already initialized, else \c true.
 596  */
 597 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_ignore(OggFLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type);
 598
 599 /** This is inherited from FLAC__SeekableStreamDecoder; see
 600  *  FLAC__seekable_stream_decoder_set_metadata_ignore_application().
 601  *
 602  * \default By default, only the \c STREAMINFO block is returned via the
 603  *          metadata callback.
 604  * \param  decoder  A decoder instance to set.
 605  * \param  id       See above.
 606  * \assert
 607  *    \code decoder != NULL \endcode
 608  *    \code id != NULL \endcode
 609  * \retval FLAC__bool
 610  *    \c false if the decoder is already initialized, else \c true.
 611  */
 612 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_ignore_application(OggFLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
 613
 614 /** This is inherited from FLAC__SeekableStreamDecoder; see
 615  *  FLAC__seekable_stream_decoder_set_metadata_ignore_all().
 616  *
 617  * \default By default, only the \c STREAMINFO block is returned via the
 618  *          metadata callback.
 619  * \param  decoder  A decoder instance to set.
 620  * \assert
 621  *    \code decoder != NULL \endcode
 622  * \retval FLAC__bool
 623  *    \c false if the decoder is already initialized, else \c true.
 624  */
 625 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_ignore_all(OggFLAC__SeekableStreamDecoder *decoder);
 626
 627 /** Get the current decoder state.
 628  *
 629  * \param  decoder  A decoder instance to query.
 630  * \assert
 631  *    \code decoder != NULL \endcode
 632  * \retval OggFLAC__SeekableStreamDecoderState
 633  *    The current decoder state.
 634  */
 635 OggFLAC_API OggFLAC__SeekableStreamDecoderState OggFLAC__seekable_stream_decoder_get_state(const OggFLAC__SeekableStreamDecoder *decoder);
 636
 637 /** Get the state of the underlying stream decoder.
 638  *  Useful when the seekable stream decoder state is
 639  *  \c OggFLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
 640  *
 641  * \param  decoder  A decoder instance to query.
 642  * \assert
 643  *    \code decoder != NULL \endcode
 644  * \retval OggFLAC__StreamDecoderState
 645  *    The stream decoder state.
 646  */
 647 OggFLAC_API OggFLAC__StreamDecoderState OggFLAC__seekable_stream_decoder_get_stream_decoder_state(const OggFLAC__SeekableStreamDecoder *decoder);
 648
 649 /** Get the state of the underlying stream decoder's FLAC stream decoder.
 650  *  Useful when the seekable stream decoder state is
 651  *  \c OggFLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR and the
 652  *  stream decoder state is \c OggFLAC__STREAM_DECODER_FLAC_STREAM_DECODER_ERROR
 653  *
 654  * \param  decoder  A decoder instance to query.
 655  * \assert
 656  *    \code decoder != NULL \endcode
 657  * \retval FLAC__StreamDecoderState
 658  *    The FLAC stream decoder state.
 659  */
 660 OggFLAC_API FLAC__StreamDecoderState OggFLAC__seekable_stream_decoder_get_FLAC_stream_decoder_state(const OggFLAC__SeekableStreamDecoder *decoder);
 661
 662 /** Get the current decoder state as a C string.
 663  *  This version automatically resolves
 664  *  \c OggFLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR
 665  *  by getting the stream decoder's state.
 666  *
 667  * \param  decoder  A decoder instance to query.
 668  * \assert
 669  *    \code decoder != NULL \endcode
 670  * \retval const char *
 671  *    The decoder state as a C string.  Do not modify the contents.
 672  */
 673 OggFLAC_API const char *OggFLAC__seekable_stream_decoder_get_resolved_state_string(const OggFLAC__SeekableStreamDecoder *decoder);
 674
 675 /** This is inherited from FLAC__SeekableStreamDecoder; see
 676  *  FLAC__seekable_stream_decoder_get_md5_checking().
 677  *
 678  * \param  decoder  A decoder instance to query.
 679  * \assert
 680  *    \code decoder != NULL \endcode
 681  * \retval FLAC__bool
 682  *    See above.
 683  */
 684 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_get_md5_checking(const OggFLAC__SeekableStreamDecoder *decoder);
 685
 686 /** This is inherited from FLAC__SeekableStreamDecoder; see
 687  *  FLAC__seekable_stream_decoder_get_channels().
 688  *
 689  * \param  decoder  A decoder instance to query.
 690  * \assert
 691  *    \code decoder != NULL \endcode
 692  * \retval unsigned
 693  *    See above.
 694  */
 695 OggFLAC_API unsigned OggFLAC__seekable_stream_decoder_get_channels(const OggFLAC__SeekableStreamDecoder *decoder);
 696
 697 /** This is inherited from FLAC__SeekableStreamDecoder; see
 698  *  FLAC__seekable_stream_decoder_get_channel_assignment().
 699  *
 700  * \param  decoder  A decoder instance to query.
 701  * \assert
 702  *    \code decoder != NULL \endcode
 703  * \retval OggFLAC__ChannelAssignment
 704  *    See above.
 705  */
 706 OggFLAC_API FLAC__ChannelAssignment OggFLAC__seekable_stream_decoder_get_channel_assignment(const OggFLAC__SeekableStreamDecoder *decoder);
 707
 708 /** This is inherited from FLAC__SeekableStreamDecoder; see
 709  *  FLAC__seekable_stream_decoder_get_bits_per_sample().
 710  *
 711  * \param  decoder  A decoder instance to query.
 712  * \assert
 713  *    \code decoder != NULL \endcode
 714  * \retval unsigned
 715  *    See above.
 716  */
 717 OggFLAC_API unsigned OggFLAC__seekable_stream_decoder_get_bits_per_sample(const OggFLAC__SeekableStreamDecoder *decoder);
 718
 719 /** This is inherited from FLAC__SeekableStreamDecoder; see
 720  *  FLAC__seekable_stream_decoder_get_sample_rate().
 721  *
 722  * \param  decoder  A decoder instance to query.
 723  * \assert
 724  *    \code decoder != NULL \endcode
 725  * \retval unsigned
 726  *    See above.
 727  */
 728 OggFLAC_API unsigned OggFLAC__seekable_stream_decoder_get_sample_rate(const OggFLAC__SeekableStreamDecoder *decoder);
 729
 730 /** This is inherited from FLAC__SeekableStreamDecoder; see
 731  *  FLAC__seekable_stream_decoder_get_blocksize().
 732  *
 733  * \param  decoder  A decoder instance to query.
 734  * \assert
 735  *    \code decoder != NULL \endcode
 736  * \retval unsigned
 737  *    See above.
 738  */
 739 OggFLAC_API unsigned OggFLAC__seekable_stream_decoder_get_blocksize(const OggFLAC__SeekableStreamDecoder *decoder);
 740
 741 /** Initialize the decoder instance.
 742  *  Should be called after OggFLAC__seekable_stream_decoder_new() and
 743  *  OggFLAC__seekable_stream_decoder_set_*() but before any of the
 744  *  OggFLAC__seekable_stream_decoder_process_*() functions.  Will set and return
 745  *  the decoder state, which will be OggFLAC__SEEKABLE_STREAM_DECODER_OK
 746  *  if initialization succeeded.
 747  *
 748  * \param  decoder  An uninitialized decoder instance.
 749  * \assert
 750  *    \code decoder != NULL \endcode
 751  * \retval OggFLAC__SeekableStreamDecoderState
 752  *    \c OggFLAC__SEEKABLE_STREAM_DECODER_OK if initialization was
 753  *    successful; see OggFLAC__SeekableStreamDecoderState for the meanings
 754  *    of other return values.
 755  */
 756 OggFLAC_API OggFLAC__SeekableStreamDecoderState OggFLAC__seekable_stream_decoder_init(OggFLAC__SeekableStreamDecoder *decoder);
 757
 758 /** Finish the decoding process.
 759  *  Flushes the decoding buffer, releases resources, resets the decoder
 760  *  settings to their defaults, and returns the decoder state to
 761  *  OggFLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED.
 762  *
 763  *  In the event of a prematurely-terminated decode, it is not strictly
 764  *  necessary to call this immediately before
 765  *  OggFLAC__seekable_stream_decoder_delete() but it is good practice to match
 766  *  every OggFLAC__seekable_stream_decoder_init() with a
 767  *  OggFLAC__seekable_stream_decoder_finish().
 768  *
 769  * \param  decoder  An uninitialized decoder instance.
 770  * \assert
 771  *    \code decoder != NULL \endcode
 772  * \retval FLAC__bool
 773  *    \c false if MD5 checking is on AND a STREAMINFO block was available
 774  *    AND the MD5 signature in the STREAMINFO block was non-zero AND the
 775  *    signature does not match the one computed by the decoder; else
 776  *    \c true.
 777  */
 778 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_finish(OggFLAC__SeekableStreamDecoder *decoder);
 779
 780 /** This is inherited from FLAC__SeekableStreamDecoder; see
 781  *  FLAC__seekable_stream_decoder_flush().
 782  *
 783  * \param  decoder  A decoder instance.
 784  * \assert
 785  *    \code decoder != NULL \endcode
 786  * \retval FLAC__bool
 787  *    \c true if successful, else \c false if a memory allocation
 788  *    or stream decoder error occurs.
 789  */
 790 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_flush(OggFLAC__SeekableStreamDecoder *decoder);
 791
 792 /** This is inherited from FLAC__SeekableStreamDecoder; see
 793  *  FLAC__seekable_stream_decoder_reset().
 794  *
 795  * \param  decoder  A decoder instance.
 796  * \assert
 797  *    \code decoder != NULL \endcode
 798  * \retval FLAC__bool
 799  *    \c true if successful, else \c false if a memory allocation
 800  *    or stream decoder error occurs.
 801  */
 802 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_reset(OggFLAC__SeekableStreamDecoder *decoder);
 803
 804 /** This is inherited from FLAC__SeekableStreamDecoder; see
 805  *  FLAC__seekable_stream_decoder_process_single().
 806  *
 807  * \param  decoder  A decoder instance.
 808  * \assert
 809  *    \code decoder != NULL \endcode
 810  * \retval FLAC__bool
 811  *    See above.
 812  */
 813 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_process_single(OggFLAC__SeekableStreamDecoder *decoder);
 814
 815 /** This is inherited from FLAC__SeekableStreamDecoder; see
 816  *  FLAC__seekable_stream_decoder_process_until_end_of_metadata().
 817  *
 818  * \param  decoder  A decoder instance.
 819  * \assert
 820  *    \code decoder != NULL \endcode
 821  * \retval FLAC__bool
 822  *    See above.
 823  */
 824 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_process_until_end_of_metadata(OggFLAC__SeekableStreamDecoder *decoder);
 825
 826 /** This is inherited from FLAC__SeekableStreamDecoder; see
 827  *  FLAC__seekable_stream_decoder_process_until_end_of_stream().
 828  *
 829  * \param  decoder  A decoder instance.
 830  * \assert
 831  *    \code decoder != NULL \endcode
 832  * \retval FLAC__bool
 833  *    See above.
 834  */
 835 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_process_until_end_of_stream(OggFLAC__SeekableStreamDecoder *decoder);
 836
 837 /** This is inherited from FLAC__SeekableStreamDecoder; see
 838  *  FLAC__seekable_stream_decoder_seek_absolute().
 839  *
 840  * \param  decoder  A decoder instance.
 841  * \param  sample   The target sample number to seek to.
 842  * \assert
 843  *    \code decoder != NULL \endcode
 844  * \retval FLAC__bool
 845  *    \c true if successful, else \c false.
 846  */
 847 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_seek_absolute(OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 sample);
 848
 849 /* \} */
 850
 851 #ifdef __cplusplus
 852 }
 853 #endif
 854
 855 #endif