include/OggFLAC/seekable_stream_decoder.h

   1 /* libOggFLAC - Free Lossless Audio Codec + Ogg library
   2  * Copyright (C) 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 OggFLAC__SEEKABLE_STREAM_DECODER_H
  21 #define OggFLAC__SEEKABLE_STREAM_DECODER_H
  22
  23 #include "export.h"
  24
  25 #include "FLAC/seekable_stream_decoder.h"
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31
  32 /** \file include/OggFLAC/seekable_stream_decoder.h
  33  *
  34  *  \brief
  35  *  This module contains the functions which implement the seekable stream
  36  *  decoder.
  37  *
  38  *  See the detailed documentation in the
  39  *  \link oggflac_seekable_stream_decoder seekable stream decoder \endlink module.
  40  */
  41
  42 /** \defgroup oggflac_seekable_stream_decoder OggFLAC/seekable_stream_decoder.h: seekable stream decoder interface
  43  *  \ingroup oggflac_decoder
  44  *
  45  *  \brief
  46  *  This module contains the functions which implement the seekable stream
  47  *  decoder.
  48  *
  49  * The interface here is identical to FLAC's seekable stream decoder.  See the
  50  * defaults, including the callbacks.  See the \link flac_seekable_stream_decoder
  51  * FLAC seekable stream decoder module \endlink for full documentation.
  52  *
  53  * \{
  54  */
  55
  56
  57 /** State values for an OggFLAC__SeekableStreamDecoder
  58  *
  59  *  The decoder's state can be obtained by calling OggFLAC__seekable_stream_decoder_get_state().
  60  */
  61 typedef enum {
  62
  63         OggFLAC__SEEKABLE_STREAM_DECODER_OK = 0,
  64         /**< The decoder is in the normal OK state. */
  65
  66         OggFLAC__SEEKABLE_STREAM_DECODER_FLAC_SEEKABLE_STREAM_DECODER_ERROR,
  67         /**< An error occurred in the underlying FLAC seekable stream decoder;
  68          * check OggFLAC__seekable_stream_decoder_get_FLAC_seekable_stream_decoder_state().
  69          */
  70
  71         OggFLAC__SEEKABLE_STREAM_DECODER_INVALID_CALLBACK,
  72         /**< The decoder was initialized before setting all the required callbacks. */
  73
  74         OggFLAC__SEEKABLE_STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
  75         /**< Memory allocation failed. */
  76
  77         OggFLAC__SEEKABLE_STREAM_DECODER_ALREADY_INITIALIZED,
  78         /**< OggFLAC__seekable_stream_decoder_init() was called when the decoder was
  79          * already initialized, usually because
  80          * OggFLAC__seekable_stream_decoder_finish() was not called.
  81          */
  82
  83         OggFLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED
  84         /**< The decoder is in the uninitialized state. */
  85
  86 } OggFLAC__SeekableStreamDecoderState;
  87
  88 /** Maps an OggFLAC__SeekableStreamDecoderState to a C string.
  89  *
  90  *  Using an OggFLAC__SeekableStreamDecoderState as the index to this array
  91  *  will give the string equivalent.  The contents should not be modified.
  92  */
  93 extern OggFLAC_API const char * const OggFLAC__SeekableStreamDecoderStateString[];
  94
  95
  96 /***********************************************************************
  97  *
  98  * class OggFLAC__SeekableStreamDecoder : public FLAC__StreamDecoder
  99  *
 100  ***********************************************************************/
 101
 102 struct OggFLAC__SeekableStreamDecoderProtected;
 103 struct OggFLAC__SeekableStreamDecoderPrivate;
 104 /** The opaque structure definition for the seekable stream decoder type.
 105  *  See the
 106  *  \link oggflac_seekable_stream_decoder seekable stream decoder module \endlink
 107  *  for a detailed description.
 108  */
 109 typedef struct {
 110         struct OggFLAC__SeekableStreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
 111         struct OggFLAC__SeekableStreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
 112 } OggFLAC__SeekableStreamDecoder;
 113
 114 /*@@@ document */
 115 typedef FLAC__SeekableStreamDecoderReadStatus (*OggFLAC__SeekableStreamDecoderReadCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
 116 typedef FLAC__SeekableStreamDecoderSeekStatus (*OggFLAC__SeekableStreamDecoderSeekCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
 117 typedef FLAC__SeekableStreamDecoderTellStatus (*OggFLAC__SeekableStreamDecoderTellCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
 118 typedef FLAC__SeekableStreamDecoderLengthStatus (*OggFLAC__SeekableStreamDecoderLengthCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
 119 typedef FLAC__bool (*OggFLAC__SeekableStreamDecoderEofCallback)(const OggFLAC__SeekableStreamDecoder *decoder, void *client_data);
 120 typedef FLAC__StreamDecoderWriteStatus (*OggFLAC__SeekableStreamDecoderWriteCallback)(const OggFLAC__SeekableStreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
 121 typedef void (*OggFLAC__SeekableStreamDecoderMetadataCallback)(const OggFLAC__SeekableStreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
 122 typedef void (*OggFLAC__SeekableStreamDecoderErrorCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
 123
 124
 125 /***********************************************************************
 126  *
 127  * Class constructor/destructor
 128  *
 129  ***********************************************************************/
 130
 131 /** Create a new seekable stream decoder instance.  The instance is created
 132  *  with default settings; see the individual
 133  *  OggFLAC__seekable_stream_decoder_set_*() functions for each setting's
 134  *  default.
 135  *
 136  * \retval OggFLAC__SeekableStreamDecoder*
 137  *    \c NULL if there was an error allocating memory, else the new instance.
 138  */
 139 OggFLAC_API OggFLAC__SeekableStreamDecoder *OggFLAC__seekable_stream_decoder_new();
 140
 141 /** Free a decoder instance.  Deletes the object pointed to by \a decoder.
 142  *
 143  * \param decoder  A pointer to an existing decoder.
 144  * \assert
 145  *    \code decoder != NULL \endcode
 146  */
 147 OggFLAC_API void OggFLAC__seekable_stream_decoder_delete(OggFLAC__SeekableStreamDecoder *decoder);
 148
 149
 150 /***********************************************************************
 151  *
 152  * Public class method prototypes
 153  *
 154  ***********************************************************************/
 155
 156 /*@@@inherit set_serial_number*/
 157
 158 /** Set the "MD5 signature checking" flag.
 159  *  This is inherited from FLAC__SeekableStreamDecoder; see
 160  *  FLAC__seekable_stream_decoder_set_md5_checking().
 161  *
 162  * \default \c false
 163  * \param  decoder  A decoder instance to set.
 164  * \param  value    Flag value (see above).
 165  * \assert
 166  *    \code decoder != NULL \endcode
 167  * \retval FLAC__bool
 168  *    \c false if the decoder is already initialized, else \c true.
 169  */
 170 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_md5_checking(OggFLAC__SeekableStreamDecoder *decoder, FLAC__bool value);
 171
 172 /** Set the read callback.
 173  *  This is inherited from FLAC__SeekableStreamDecoder; see
 174  *  FLAC__seekable_stream_decoder_set_read_callback().
 175  *
 176  * \note
 177  * The callback is mandatory and must be set before initialization.
 178  *
 179  * \default \c NULL
 180  * \param  decoder  A decoder instance to set.
 181  * \param  value    See above.
 182  * \assert
 183  *    \code decoder != NULL \endcode
 184  *    \code value != NULL \endcode
 185  * \retval FLAC__bool
 186  *    \c false if the decoder is already initialized, else \c true.
 187  */
 188 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_read_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderReadCallback value);
 189
 190 /** Set the seek callback.
 191  *  This is inherited from FLAC__SeekableStreamDecoder; see
 192  *  FLAC__seekable_stream_decoder_set_seek_callback().
 193  *
 194  * \note
 195  * The callback is mandatory and must be set before initialization.
 196  *
 197  * \default \c NULL
 198  * \param  decoder  A decoder instance to set.
 199  * \param  value    See above.
 200  * \assert
 201  *    \code decoder != NULL \endcode
 202  *    \code value != NULL \endcode
 203  * \retval FLAC__bool
 204  *    \c false if the decoder is already initialized, else \c true.
 205  */
 206 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_seek_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderSeekCallback value);
 207
 208 /** Set the tell callback.
 209  *  This is inherited from FLAC__SeekableStreamDecoder; see
 210  *  FLAC__seekable_stream_decoder_set_tell_callback().
 211  *
 212  * \note
 213  * The callback is mandatory and must be set before initialization.
 214  *
 215  * \default \c NULL
 216  * \param  decoder  A decoder instance to set.
 217  * \param  value    See above.
 218  * \assert
 219  *    \code decoder != NULL \endcode
 220  *    \code value != NULL \endcode
 221  * \retval FLAC__bool
 222  *    \c false if the decoder is already initialized, else \c true.
 223  */
 224 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_tell_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderTellCallback value);
 225
 226 /** Set the length callback.
 227  *  This is inherited from FLAC__SeekableStreamDecoder; see
 228  *  FLAC__seekable_stream_decoder_set_length_callback().
 229  *
 230  * \note
 231  * The callback is mandatory and must be set before initialization.
 232  *
 233  * \default \c NULL
 234  * \param  decoder  A decoder instance to set.
 235  * \param  value    See above.
 236  * \assert
 237  *    \code decoder != NULL \endcode
 238  *    \code value != NULL \endcode
 239  * \retval FLAC__bool
 240  *    \c false if the decoder is already initialized, else \c true.
 241  */
 242 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_length_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderLengthCallback value);
 243
 244 /** Set the eof callback.
 245  *  This is inherited from FLAC__SeekableStreamDecoder; see
 246  *  FLAC__seekable_stream_decoder_set_eof_callback().
 247  *
 248  * \note
 249  * The callback is mandatory and must be set before initialization.
 250  *
 251  * \default \c NULL
 252  * \param  decoder  A decoder instance to set.
 253  * \param  value    See above.
 254  * \assert
 255  *    \code decoder != NULL \endcode
 256  *    \code value != NULL \endcode
 257  * \retval FLAC__bool
 258  *    \c false if the decoder is already initialized, else \c true.
 259  */
 260 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_eof_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderEofCallback value);
 261
 262 /** Set the write callback.
 263  *  This is inherited from FLAC__SeekableStreamDecoder; see
 264  *  FLAC__seekable_stream_decoder_set_write_callback().
 265  *
 266  * \note
 267  * The callback is mandatory and must be set before initialization.
 268  *
 269  * \default \c NULL
 270  * \param  decoder  A decoder instance to set.
 271  * \param  value    See above.
 272  * \assert
 273  *    \code decoder != NULL \endcode
 274  *    \code value != NULL \endcode
 275  * \retval FLAC__bool
 276  *    \c false if the decoder is already initialized, else \c true.
 277  */
 278 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_write_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderWriteCallback value);
 279
 280 /** Set the metadata callback.
 281  *  This is inherited from FLAC__SeekableStreamDecoder; see
 282  *  FLAC__seekable_stream_decoder_set_metadata_callback().
 283  *
 284  * \note
 285  * The callback is mandatory and must be set before initialization.
 286  *
 287  * \default \c NULL
 288  * \param  decoder  A decoder instance to set.
 289  * \param  value    See above.
 290  * \assert
 291  *    \code decoder != NULL \endcode
 292  *    \code value != NULL \endcode
 293  * \retval FLAC__bool
 294  *    \c false if the decoder is already initialized, else \c true.
 295  */
 296 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderMetadataCallback value);
 297
 298 /** Set the error callback.
 299  *  This is inherited from FLAC__SeekableStreamDecoder; see
 300  *  FLAC__seekable_stream_decoder_set_error_callback().
 301  *
 302  * \note
 303  * The callback is mandatory and must be set before initialization.
 304  *
 305  * \default \c NULL
 306  * \param  decoder  A decoder instance to set.
 307  * \param  value    See above.
 308  * \assert
 309  *    \code decoder != NULL \endcode
 310  *    \code value != NULL \endcode
 311  * \retval FLAC__bool
 312  *    \c false if the decoder is already initialized, else \c true.
 313  */
 314 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_error_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderErrorCallback value);
 315
 316 /** Set the client data to be passed back to callbacks.
 317  *  This value will be supplied to callbacks in their \a client_data
 318  *  argument.
 319  *
 320  * \default \c NULL
 321  * \param  decoder  A decoder instance to set.
 322  * \param  value    See above.
 323  * \assert
 324  *    \code decoder != NULL \endcode
 325  * \retval FLAC__bool
 326  *    \c false if the decoder is already initialized, else \c true.
 327  */
 328 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_client_data(OggFLAC__SeekableStreamDecoder *decoder, void *value);
 329
 330 /** This is inherited from FLAC__SeekableStreamDecoder; see
 331  *  FLAC__seekable_stream_decoder_set_metadata_respond().
 332  *
 333  * \default By default, only the \c STREAMINFO block is returned via the
 334  *          metadata callback.
 335  * \param  decoder  A decoder instance to set.
 336  * \param  type     See above.
 337  * \assert
 338  *    \code decoder != NULL \endcode
 339  *    \a type is valid
 340  * \retval FLAC__bool
 341  *    \c false if the decoder is already initialized, else \c true.
 342  */
 343 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__MetadataType type);
 344
 345 /** This is inherited from FLAC__SeekableStreamDecoder; see
 346  *  FLAC__seekable_stream_decoder_set_metadata_respond_application().
 347  *
 348  * \default By default, only the \c STREAMINFO block is returned via the
 349  *          metadata callback.
 350  * \param  decoder  A decoder instance to set.
 351  * \param  id       See above.
 352  * \assert
 353  *    \code decoder != NULL \endcode
 354  *    \code id != NULL \endcode
 355  * \retval FLAC__bool
 356  *    \c false if the decoder is already initialized, else \c true.
 357  */
 358 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond_application(OggFLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
 359
 360 /** This is inherited from FLAC__SeekableStreamDecoder; see
 361  *  FLAC__seekable_stream_decoder_set_metadata_respond_all().
 362  *
 363  * \default By default, only the \c STREAMINFO block is returned via the
 364  *          metadata callback.
 365  * \param  decoder  A decoder instance to set.
 366  * \assert
 367  *    \code decoder != NULL \endcode
 368  * \retval FLAC__bool
 369  *    \c false if the decoder is already initialized, else \c true.
 370  */
 371 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond_all(OggFLAC__SeekableStreamDecoder *decoder);
 372
 373 /** This is inherited from FLAC__SeekableStreamDecoder; see
 374  *  FLAC__seekable_stream_decoder_set_metadata_ignore().
 375  *
 376  * \default By default, only the \c STREAMINFO block is returned via the
 377  *          metadata callback.
 378  * \param  decoder  A decoder instance to set.
 379  * \param  type     See above.
 380  * \assert
 381  *    \code decoder != NULL \endcode
 382  *    \a type is valid
 383  * \retval FLAC__bool
 384  *    \c false if the decoder is already initialized, else \c true.
 385  */
 386 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_ignore(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__MetadataType type);
 387
 388 /** This is inherited from FLAC__SeekableStreamDecoder; see
 389  *  FLAC__seekable_stream_decoder_set_metadata_ignore_application().
 390  *
 391  * \default By default, only the \c STREAMINFO block is returned via the
 392  *          metadata callback.
 393  * \param  decoder  A decoder instance to set.
 394  * \param  id       See above.
 395  * \assert
 396  *    \code decoder != NULL \endcode
 397  *    \code id != NULL \endcode
 398  * \retval FLAC__bool
 399  *    \c false if the decoder is already initialized, else \c true.
 400  */
 401 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_ignore_application(OggFLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
 402
 403 /** This is inherited from FLAC__SeekableStreamDecoder; see
 404  *  FLAC__seekable_stream_decoder_set_metadata_ignore_all().
 405  *
 406  * \default By default, only the \c STREAMINFO block is returned via the
 407  *          metadata callback.
 408  * \param  decoder  A decoder instance to set.
 409  * \assert
 410  *    \code decoder != NULL \endcode
 411  * \retval FLAC__bool
 412  *    \c false if the decoder is already initialized, else \c true.
 413  */
 414 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_ignore_all(OggFLAC__SeekableStreamDecoder *decoder);
 415
 416 /** Get the current decoder state.
 417  *
 418  * \param  decoder  A decoder instance to query.
 419  * \assert
 420  *    \code decoder != NULL \endcode
 421  * \retval OggFLAC__SeekableStreamDecoderState
 422  *    The current decoder state.
 423  */
 424 OggFLAC_API OggFLAC__SeekableStreamDecoderState OggFLAC__seekable_stream_decoder_get_state(const OggFLAC__SeekableStreamDecoder *decoder);
 425
 426 /** Get the state of the underlying FLAC seekable stream decoder.
 427  *  Useful when the seekable stream decoder state is
 428  *  \c OggFLAC__SEEKABLE_STREAM_DECODER_FLAC_SEEKABLE_STREAM_DECODER_ERROR.
 429  *
 430  * \param  decoder  A decoder instance to query.
 431  * \assert
 432  *    \code decoder != NULL \endcode
 433  * \retval FLAC__SeekableStreamDecoderState
 434  *    The FLAC seekable stream decoder state.
 435  */
 436 OggFLAC_API FLAC__SeekableStreamDecoderState OggFLAC__seekable_stream_decoder_get_FLAC_seekable_stream_decoder_state(const OggFLAC__SeekableStreamDecoder *decoder);
 437
 438 /** Get the state of the underlying FLAC seekable stream decoder's stream decoder.
 439  *  Useful when the seekable stream decoder state is
 440  *  \c OggFLAC__SEEKABLE_STREAM_DECODER_FLAC_SEEKABLE_STREAM_DECODER_ERROR and the
 441  *  FLAC seekable stream decoder state is \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR
 442  *
 443  * \param  decoder  A decoder instance to query.
 444  * \assert
 445  *    \code decoder != NULL \endcode
 446  * \retval FLAC__StreamDecoderState
 447  *    The FLAC stream decoder state.
 448  */
 449 OggFLAC_API FLAC__StreamDecoderState OggFLAC__seekable_stream_decoder_get_FLAC_stream_decoder_state(const OggFLAC__SeekableStreamDecoder *decoder);
 450
 451 /** This is inherited from FLAC__SeekableStreamDecoder; see
 452  *  FLAC__seekable_stream_decoder_get_md5_checking().
 453  *
 454  * \param  decoder  A decoder instance to query.
 455  * \assert
 456  *    \code decoder != NULL \endcode
 457  * \retval FLAC__bool
 458  *    See above.
 459  */
 460 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_get_md5_checking(const OggFLAC__SeekableStreamDecoder *decoder);
 461
 462 /** This is inherited from FLAC__SeekableStreamDecoder; see
 463  *  FLAC__seekable_stream_decoder_get_channels().
 464  *
 465  * \param  decoder  A decoder instance to query.
 466  * \assert
 467  *    \code decoder != NULL \endcode
 468  * \retval unsigned
 469  *    See above.
 470  */
 471 OggFLAC_API unsigned OggFLAC__seekable_stream_decoder_get_channels(const OggFLAC__SeekableStreamDecoder *decoder);
 472
 473 /** This is inherited from FLAC__SeekableStreamDecoder; see
 474  *  FLAC__seekable_stream_decoder_get_channel_assignment().
 475  *
 476  * \param  decoder  A decoder instance to query.
 477  * \assert
 478  *    \code decoder != NULL \endcode
 479  * \retval OggFLAC__ChannelAssignment
 480  *    See above.
 481  */
 482 OggFLAC_API OggFLAC__ChannelAssignment OggFLAC__seekable_stream_decoder_get_channel_assignment(const OggFLAC__SeekableStreamDecoder *decoder);
 483
 484 /** This is inherited from FLAC__SeekableStreamDecoder; see
 485  *  FLAC__seekable_stream_decoder_get_bits_per_sample().
 486  *
 487  * \param  decoder  A decoder instance to query.
 488  * \assert
 489  *    \code decoder != NULL \endcode
 490  * \retval unsigned
 491  *    See above.
 492  */
 493 OggFLAC_API unsigned OggFLAC__seekable_stream_decoder_get_bits_per_sample(const OggFLAC__SeekableStreamDecoder *decoder);
 494
 495 /** This is inherited from FLAC__SeekableStreamDecoder; see
 496  *  FLAC__seekable_stream_decoder_get_sample_rate().
 497  *
 498  * \param  decoder  A decoder instance to query.
 499  * \assert
 500  *    \code decoder != NULL \endcode
 501  * \retval unsigned
 502  *    See above.
 503  */
 504 OggFLAC_API unsigned OggFLAC__seekable_stream_decoder_get_sample_rate(const OggFLAC__SeekableStreamDecoder *decoder);
 505
 506 /** This is inherited from FLAC__SeekableStreamDecoder; see
 507  *  FLAC__seekable_stream_decoder_get_blocksize().
 508  *
 509  * \param  decoder  A decoder instance to query.
 510  * \assert
 511  *    \code decoder != NULL \endcode
 512  * \retval unsigned
 513  *    See above.
 514  */
 515 OggFLAC_API unsigned OggFLAC__seekable_stream_decoder_get_blocksize(const OggFLAC__SeekableStreamDecoder *decoder);
 516
 517 /** Initialize the decoder instance.
 518  *  Should be called after OggFLAC__seekable_stream_decoder_new() and
 519  *  OggFLAC__seekable_stream_decoder_set_*() but before any of the
 520  *  OggFLAC__seekable_stream_decoder_process_*() functions.  Will set and return
 521  *  the decoder state, which will be OggFLAC__SEEKABLE_STREAM_DECODER_OK
 522  *  if initialization succeeded.
 523  *
 524  * \param  decoder  An uninitialized decoder instance.
 525  * \assert
 526  *    \code decoder != NULL \endcode
 527  * \retval OggFLAC__SeekableStreamDecoderState
 528  *    \c OggFLAC__SEEKABLE_STREAM_DECODER_OK if initialization was
 529  *    successful; see OggFLAC__SeekableStreamDecoderState for the meanings
 530  *    of other return values.
 531  */
 532 OggFLAC_API OggFLAC__SeekableStreamDecoderState OggFLAC__seekable_stream_decoder_init(OggFLAC__SeekableStreamDecoder *decoder);
 533
 534 /** Finish the decoding process.
 535  *  Flushes the decoding buffer, releases resources, resets the decoder
 536  *  settings to their defaults, and returns the decoder state to
 537  *  OggFLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED.
 538  *
 539  *  In the event of a prematurely-terminated decode, it is not strictly
 540  *  necessary to call this immediately before
 541  *  OggFLAC__seekable_stream_decoder_delete() but it is good practice to match
 542  *  every OggFLAC__seekable_stream_decoder_init() with a
 543  *  OggFLAC__seekable_stream_decoder_finish().
 544  *
 545  * \param  decoder  An uninitialized decoder instance.
 546  * \assert
 547  *    \code decoder != NULL \endcode
 548  * \retval FLAC__bool
 549  *    \c false if MD5 checking is on AND a STREAMINFO block was available
 550  *    AND the MD5 signature in the STREAMINFO block was non-zero AND the
 551  *    signature does not match the one computed by the decoder; else
 552  *    \c true.
 553  */
 554 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_finish(OggFLAC__SeekableStreamDecoder *decoder);
 555
 556 /** This is inherited from FLAC__SeekableStreamDecoder; see
 557  *  FLAC__seekable_stream_decoder_flush().
 558  *
 559  * \param  decoder  A decoder instance.
 560  * \assert
 561  *    \code decoder != NULL \endcode
 562  * \retval FLAC__bool
 563  *    \c true if successful, else \c false if a memory allocation
 564  *    or stream decoder error occurs.
 565  */
 566 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_flush(OggFLAC__SeekableStreamDecoder *decoder);
 567
 568 /** This is inherited from FLAC__SeekableStreamDecoder; see
 569  *  FLAC__seekable_stream_decoder_reset().
 570  *
 571  * \param  decoder  A decoder instance.
 572  * \assert
 573  *    \code decoder != NULL \endcode
 574  * \retval FLAC__bool
 575  *    \c true if successful, else \c false if a memory allocation
 576  *    or stream decoder error occurs.
 577  */
 578 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_reset(OggFLAC__SeekableStreamDecoder *decoder);
 579
 580 /** This is inherited from FLAC__SeekableStreamDecoder; see
 581  *  FLAC__seekable_stream_decoder_process_single().
 582  *
 583  * \param  decoder  A decoder instance.
 584  * \assert
 585  *    \code decoder != NULL \endcode
 586  * \retval FLAC__bool
 587  *    See above.
 588  */
 589 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_process_single(OggFLAC__SeekableStreamDecoder *decoder);
 590
 591 /** This is inherited from FLAC__SeekableStreamDecoder; see
 592  *  FLAC__seekable_stream_decoder_process_until_end_of_metadata().
 593  *
 594  * \param  decoder  A decoder instance.
 595  * \assert
 596  *    \code decoder != NULL \endcode
 597  * \retval FLAC__bool
 598  *    See above.
 599  */
 600 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_process_until_end_of_metadata(OggFLAC__SeekableStreamDecoder *decoder);
 601
 602 /** This is inherited from FLAC__SeekableStreamDecoder; see
 603  *  FLAC__seekable_stream_decoder_process_until_end_of_stream().
 604  *
 605  * \param  decoder  A decoder instance.
 606  * \assert
 607  *    \code decoder != NULL \endcode
 608  * \retval FLAC__bool
 609  *    See above.
 610  */
 611 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_process_until_end_of_stream(OggFLAC__SeekableStreamDecoder *decoder);
 612
 613 /** This is inherited from FLAC__SeekableStreamDecoder; see
 614  *  FLAC__seekable_stream_decoder_seek_absolute().
 615  *
 616  * \param  decoder  A decoder instance.
 617  * \param  sample   The target sample number to seek to.
 618  * \assert
 619  *    \code decoder != NULL \endcode
 620  * \retval FLAC__bool
 621  *    \c true if successful, else \c false.
 622  */
 623 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_seek_absolute(OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 sample);
 624
 625 /* \} */
 626
 627 #ifdef __cplusplus
 628 }
 629 #endif
 630
 631 #endif