include/OggFLAC/file_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__FILE_DECODER_H
  21 #define OggFLAC__FILE_DECODER_H
  22
  23 #include "export.h"
  24
  25 #include "FLAC/file_decoder.h"
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31
  32 /** \file include/OggFLAC/file_decoder.h
  33  *
  34  *  \brief
  35  *  This module contains the functions which implement the file
  36  *  decoder.
  37  *
  38  *  See the detailed documentation in the
  39  *  \link oggflac_file_decoder file decoder \endlink module.
  40  */
  41
  42 /** \defgroup oggflac_file_decoder OggFLAC/file_decoder.h: file decoder interface
  43  *  \ingroup oggflac_decoder
  44  *
  45  *  \brief
  46  *  This module contains the functions which implement the file
  47  *  decoder.
  48  *
  49  * The interface here is identical to FLAC's file decoder.  See the
  50  * defaults, including the callbacks.  See the \link flac_file_decoder
  51  * FLAC file decoder module \endlink for full documentation.
  52  *
  53  * \{
  54  */
  55
  56
  57 /** State values for an OggFLAC__FileDecoder
  58  *
  59  *  The decoder's state can be obtained by calling OggFLAC__file_decoder_get_state().
  60  */
  61 typedef enum {
  62
  63         OggFLAC__FILE_DECODER_OK = 0,
  64         /**< The decoder is in the normal OK state. */
  65
  66         OggFLAC__FILE_DECODER_FLAC_FILE_DECODER_ERROR,
  67         /**< An error occurred in the underlying FLAC file decoder;
  68          * check OggFLAC__file_decoder_get_FLAC_file_decoder_state().
  69          */
  70
  71         OggFLAC__FILE_DECODER_INVALID_CALLBACK,
  72         /**< The decoder was initialized before setting all the required callbacks. */
  73
  74         OggFLAC__FILE_DECODER_MEMORY_ALLOCATION_ERROR,
  75         /**< Memory allocation failed. */
  76
  77         OggFLAC__FILE_DECODER_ALREADY_INITIALIZED,
  78         /**< OggFLAC__file_decoder_init() was called when the decoder was
  79          * already initialized, usually because
  80          * OggFLAC__file_decoder_finish() was not called.
  81          */
  82
  83         OggFLAC__FILE_DECODER_UNINITIALIZED
  84         /**< The decoder is in the uninitialized state. */
  85
  86 } OggFLAC__FileDecoderState;
  87
  88 /** Maps an OggFLAC__FileDecoderState to a C string.
  89  *
  90  *  Using an OggFLAC__FileDecoderState 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__FileDecoderStateString[];
  94
  95
  96 /***********************************************************************
  97  *
  98  * class OggFLAC__FileDecoder : public FLAC__FileDecoder
  99  *
 100  ***********************************************************************/
 101
 102 struct OggFLAC__FileDecoderProtected;
 103 struct OggFLAC__FileDecoderPrivate;
 104 /** The opaque structure definition for the file decoder type.  See the
 105  *  \link oggflac_file_decoder file decoder module \endlink for a detailed
 106  *  description.
 107  */
 108 typedef struct {
 109         struct OggFLAC__FileDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
 110         struct OggFLAC__FileDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
 111 } OggFLAC__FileDecoder;
 112
 113 typedef FLAC__StreamDecoderWriteStatus (*OggFLAC__FileDecoderWriteCallback)(const OggFLAC__FileDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
 114 typedef void (*OggFLAC__FileDecoderMetadataCallback)(const OggFLAC__FileDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
 115 typedef void (*OggFLAC__FileDecoderErrorCallback)(const OggFLAC__FileDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
 116
 117
 118 /***********************************************************************
 119  *
 120  * Class constructor/destructor
 121  *
 122  ***********************************************************************/
 123
 124 /** Create a new file decoder instance.  The instance is created with
 125  *  default settings; see the individual OggFLAC__file_decoder_set_*()
 126  *  functions for each setting's default.
 127  *
 128  * \retval OggFLAC__FileDecoder*
 129  *    \c NULL if there was an error allocating memory, else the new instance.
 130  */
 131 OggFLAC_API OggFLAC__FileDecoder *OggFLAC__file_decoder_new();
 132
 133 /** Free a decoder instance.  Deletes the object pointed to by \a decoder.
 134  *
 135  * \param decoder  A pointer to an existing decoder.
 136  * \assert
 137  *    \code decoder != NULL \endcode
 138  */
 139 OggFLAC_API void OggFLAC__file_decoder_delete(OggFLAC__FileDecoder *decoder);
 140
 141
 142 /***********************************************************************
 143  *
 144  * Public class method prototypes
 145  *
 146  ***********************************************************************/
 147
 148 /*@@@inherit set_serial_number*/
 149
 150 /** Set the "MD5 signature checking" flag.
 151  *  This is inherited from FLAC__FileDecoder; see
 152  *  FLAC__file_decoder_set_md5_checking().
 153  *
 154  * \default \c false
 155  * \param  decoder  A decoder instance to set.
 156  * \param  value    See above.
 157  * \assert
 158  *    \code decoder != NULL \endcode
 159  * \retval FLAC__bool
 160  *    \c false if the decoder is already initialized, else \c true.
 161  */
 162 OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_md5_checking(OggFLAC__FileDecoder *decoder, FLAC__bool value);
 163
 164 /** Set the input file name to decode.
 165  *  This is inherited from FLAC__FileDecoder; see
 166  *  FLAC__file_decoder_set_filename().
 167  *
 168  * \default \c "-"
 169  * \param  decoder  A decoder instance to set.
 170  * \param  value    The input file name, or "-" for \c stdin.
 171  * \assert
 172  *    \code decoder != NULL \endcode
 173  *    \code value != NULL \endcode
 174  * \retval FLAC__bool
 175  *    \c false if the decoder is already initialized, or there was a memory
 176  *    allocation error, else \c true.
 177  */
 178 OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_filename(OggFLAC__FileDecoder *decoder, const char *value);
 179
 180 /** Set the write callback.
 181  *  This is inherited from FLAC__FileDecoder; see
 182  *  FLAC__file_decoder_set_write_callback().
 183  *
 184  * \note
 185  * The callback is mandatory and must be set before initialization.
 186  *
 187  * \default \c NULL
 188  * \param  decoder  A decoder instance to set.
 189  * \param  value    See above.
 190  * \assert
 191  *    \code decoder != NULL \endcode
 192  *    \code value != NULL \endcode
 193  * \retval FLAC__bool
 194  *    \c false if the decoder is already initialized, else \c true.
 195  */
 196 OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_write_callback(OggFLAC__FileDecoder *decoder, OggFLAC__FileDecoderWriteCallback value);
 197
 198 /** Set the metadata callback.
 199  *  This is inherited from FLAC__FileDecoder; see
 200  *  FLAC__file_decoder_set_metadata_callback().
 201  *
 202  * \note
 203  * The callback is mandatory and must be set before initialization.
 204  *
 205  * \default \c NULL
 206  * \param  decoder  A decoder instance to set.
 207  * \param  value    See above.
 208  * \assert
 209  *    \code decoder != NULL \endcode
 210  *    \code value != NULL \endcode
 211  * \retval FLAC__bool
 212  *    \c false if the decoder is already initialized, else \c true.
 213  */
 214 OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_metadata_callback(OggFLAC__FileDecoder *decoder, OggFLAC__FileDecoderMetadataCallback value);
 215
 216 /** Set the error callback.
 217  *  This is inherited from FLAC__FileDecoder; see
 218  *  FLAC__file_decoder_set_error_callback().
 219  *
 220  * \note
 221  * The callback is mandatory and must be set before initialization.
 222  *
 223  * \default \c NULL
 224  * \param  decoder  A decoder instance to set.
 225  * \param  value    See above.
 226  * \assert
 227  *    \code decoder != NULL \endcode
 228  *    \code value != NULL \endcode
 229  * \retval FLAC__bool
 230  *    \c false if the decoder is already initialized, else \c true.
 231  */
 232 OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_error_callback(OggFLAC__FileDecoder *decoder, OggFLAC__FileDecoderErrorCallback value);
 233
 234 /** Set the client data to be passed back to callbacks.
 235  *  This value will be supplied to callbacks in their \a client_data
 236  *  argument.
 237  *
 238  * \default \c NULL
 239  * \param  decoder  A decoder instance to set.
 240  * \param  value    See above.
 241  * \assert
 242  *    \code decoder != NULL \endcode
 243  * \retval FLAC__bool
 244  *    \c false if the decoder is already initialized, else \c true.
 245  */
 246 OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_client_data(OggFLAC__FileDecoder *decoder, void *value);
 247
 248 /** This is inherited from FLAC__FileDecoder; see
 249  *  FLAC__file_decoder_set_metadata_respond().
 250  *
 251  * \default By default, only the \c STREAMINFO block is returned via the
 252  *          metadata callback.
 253  * \param  decoder  A decoder instance to set.
 254  * \param  type     See above.
 255  * \assert
 256  *    \code decoder != NULL \endcode
 257  *    \a type is valid
 258  * \retval FLAC__bool
 259  *    \c false if the decoder is already initialized, else \c true.
 260  */
 261 OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_metadata_respond(OggFLAC__FileDecoder *decoder, OggFLAC__MetadataType type);
 262
 263 /** This is inherited from FLAC__FileDecoder; see
 264  *  FLAC__file_decoder_set_metadata_respond_application().
 265  *
 266  * \default By default, only the \c STREAMINFO block is returned via the
 267  *          metadata callback.
 268  * \param  decoder  A decoder instance to set.
 269  * \param  id       See above.
 270  * \assert
 271  *    \code decoder != NULL \endcode
 272  *    \code id != NULL \endcode
 273  * \retval FLAC__bool
 274  *    \c false if the decoder is already initialized, else \c true.
 275  */
 276 OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_metadata_respond_application(OggFLAC__FileDecoder *decoder, const FLAC__byte id[4]);
 277
 278 /** This is inherited from FLAC__FileDecoder; see
 279  *  FLAC__file_decoder_set_metadata_respond_all().
 280  *
 281  * \default By default, only the \c STREAMINFO block is returned via the
 282  *          metadata callback.
 283  * \param  decoder  A decoder instance to set.
 284  * \assert
 285  *    \code decoder != NULL \endcode
 286  * \retval FLAC__bool
 287  *    \c false if the decoder is already initialized, else \c true.
 288  */
 289 OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_metadata_respond_all(OggFLAC__FileDecoder *decoder);
 290
 291 /** This is inherited from FLAC__FileDecoder; see
 292  *  FLAC__file_decoder_set_metadata_ignore().
 293  *
 294  * \default By default, only the \c STREAMINFO block is returned via the
 295  *          metadata callback.
 296  * \param  decoder  A decoder instance to set.
 297  * \param  type     See above.
 298  * \assert
 299  *    \code decoder != NULL \endcode
 300  *    \a type is valid
 301  * \retval FLAC__bool
 302  *    \c false if the decoder is already initialized, else \c true.
 303  */
 304 OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_metadata_ignore(OggFLAC__FileDecoder *decoder, OggFLAC__MetadataType type);
 305
 306 /** This is inherited from FLAC__FileDecoder; see
 307  *  FLAC__file_decoder_set_metadata_ignore_application().
 308  *
 309  * \default By default, only the \c STREAMINFO block is returned via the
 310  *          metadata callback.
 311  * \param  decoder  A decoder instance to set.
 312  * \param  id       See above.
 313  * \assert
 314  *    \code decoder != NULL \endcode
 315  *    \code id != NULL \endcode
 316  * \retval FLAC__bool
 317  *    \c false if the decoder is already initialized, else \c true.
 318  */
 319 OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_metadata_ignore_application(OggFLAC__FileDecoder *decoder, const FLAC__byte id[4]);
 320
 321 /** This is inherited from FLAC__FileDecoder; see
 322  *  FLAC__file_decoder_set_metadata_ignore_all().
 323  *
 324  * \default By default, only the \c STREAMINFO block is returned via the
 325  *          metadata callback.
 326  * \param  decoder  A decoder instance to set.
 327  * \assert
 328  *    \code decoder != NULL \endcode
 329  * \retval FLAC__bool
 330  *    \c false if the decoder is already initialized, else \c true.
 331  */
 332 OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_metadata_ignore_all(OggFLAC__FileDecoder *decoder);
 333
 334 /** Get the current decoder state.
 335  *
 336  * \param  decoder  A decoder instance to query.
 337  * \assert
 338  *    \code decoder != NULL \endcode
 339  * \retval OggFLAC__FileDecoderState
 340  *    The current decoder state.
 341  */
 342 OggFLAC_API OggFLAC__FileDecoderState OggFLAC__file_decoder_get_state(const OggFLAC__FileDecoder *decoder);
 343
 344 /** Get the state of the underlying FLAC file decoder.
 345  *  Useful when the file decoder state is
 346  *  \c OggFLAC__FILE_DECODER_FLAC_FILE_DECODER_ERROR.
 347  *
 348  * \param  decoder  A decoder instance to query.
 349  * \assert
 350  *    \code decoder != NULL \endcode
 351  * \retval FLAC__FileDecoderState
 352  *    The FLAC file decoder state.
 353  */
 354 OggFLAC_API FLAC__FileDecoderState OggFLAC__file_decoder_get_FLAC_file_decoder_state(const OggFLAC__FileDecoder *decoder);
 355
 356 /** Get the state of the underlying FLAC file decoder's seekable stream decoder.
 357  *  Useful when the file decoder state is
 358  *  \c OggFLAC__FILE_DECODER_FLAC_FILE_DECODER_ERROR and the FLAC file decoder state is
 359  *  \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR.
 360  *
 361  * \param  decoder  A decoder instance to query.
 362  * \assert
 363  *    \code decoder != NULL \endcode
 364  * \retval FLAC__SeekableStreamDecoderState
 365  *    The FLAC seekable stream decoder state.
 366  */
 367 OggFLAC_API FLAC__SeekableStreamDecoderState OggFLAC__file_decoder_get_FLAC_seekable_stream_decoder_state(const OggFLAC__FileDecoder *decoder);
 368
 369 /** Get the state of the underlying FLAC file decoder's stream decoder.
 370  *  Useful when the file decoder state is
 371  *  \c OggFLAC__FILE_DECODER_FLAC_FILE_DECODER_ERROR and the FLAC file decoder state is
 372  *  \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR and the
 373  *  FLAC seekable stream decoder state is \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
 374  *
 375  * \param  decoder  A decoder instance to query.
 376  * \assert
 377  *    \code decoder != NULL \endcode
 378  * \retval FLAC__StreamDecoderState
 379  *    The FLAC stream decoder state.
 380  */
 381 OggFLAC_API FLAC__StreamDecoderState OggFLAC__file_decoder_get_FLAC_stream_decoder_state(const OggFLAC__FileDecoder *decoder);
 382
 383 /** This is inherited from FLAC__FileDecoder; see
 384  *  FLAC__file_decoder_get_md5_checking().
 385  *
 386  * \param  decoder  A decoder instance to query.
 387  * \assert
 388  *    \code decoder != NULL \endcode
 389  * \retval FLAC__bool
 390  *    See above.
 391  */
 392 OggFLAC_API FLAC__bool OggFLAC__file_decoder_get_md5_checking(const OggFLAC__FileDecoder *decoder);
 393
 394 /** This is inherited from FLAC__FileDecoder; see
 395  *  FLAC__file_decoder_get_channels().
 396  *
 397  * \param  decoder  A decoder instance to query.
 398  * \assert
 399  *    \code decoder != NULL \endcode
 400  * \retval unsigned
 401  *    See above.
 402  */
 403 OggFLAC_API unsigned OggFLAC__file_decoder_get_channels(const OggFLAC__FileDecoder *decoder);
 404
 405 /** This is inherited from FLAC__FileDecoder; see
 406  *  FLAC__file_decoder_get_channel_assignment().
 407  *
 408  * \param  decoder  A decoder instance to query.
 409  * \assert
 410  *    \code decoder != NULL \endcode
 411  * \retval OggFLAC__ChannelAssignment
 412  *    See above.
 413  */
 414 OggFLAC_API OggFLAC__ChannelAssignment OggFLAC__file_decoder_get_channel_assignment(const OggFLAC__FileDecoder *decoder);
 415
 416 /** This is inherited from FLAC__FileDecoder; see
 417  *  FLAC__file_decoder_get_bits_per_sample().
 418  *
 419  * \param  decoder  A decoder instance to query.
 420  * \assert
 421  *    \code decoder != NULL \endcode
 422  * \retval unsigned
 423  *    See above.
 424  */
 425 OggFLAC_API unsigned OggFLAC__file_decoder_get_bits_per_sample(const OggFLAC__FileDecoder *decoder);
 426
 427 /** This is inherited from FLAC__FileDecoder; see
 428  *  FLAC__file_decoder_get_sample_rate().
 429  *
 430  * \param  decoder  A decoder instance to query.
 431  * \assert
 432  *    \code decoder != NULL \endcode
 433  * \retval unsigned
 434  *    See above.
 435  */
 436 OggFLAC_API unsigned OggFLAC__file_decoder_get_sample_rate(const OggFLAC__FileDecoder *decoder);
 437
 438 /** This is inherited from FLAC__FileDecoder; see
 439  *  FLAC__file_decoder_get_blocksize().
 440  *
 441  * \param  decoder  A decoder instance to query.
 442  * \assert
 443  *    \code decoder != NULL \endcode
 444  * \retval unsigned
 445  *    See above.
 446  */
 447 OggFLAC_API unsigned OggFLAC__file_decoder_get_blocksize(const OggFLAC__FileDecoder *decoder);
 448
 449 /** Initialize the decoder instance.
 450  *  Should be called after OggFLAC__file_decoder_new() and
 451  *  OggFLAC__file_decoder_set_*() but before any of the
 452  *  OggFLAC__file_decoder_process_*() functions.  Will set and return
 453  *  the decoder state, which will be OggFLAC__FILE_DECODER_OK if
 454  *  initialization succeeded.
 455  *
 456  * \param  decoder  An uninitialized decoder instance.
 457  * \assert
 458  *    \code decoder != NULL \endcode
 459  * \retval OggFLAC__FileDecoderState
 460  *    \c OggFLAC__FILE_DECODER_OK if initialization was successful; see
 461  *    OggFLAC__FileDecoderState for the meanings of other return values.
 462  */
 463 OggFLAC_API OggFLAC__FileDecoderState OggFLAC__file_decoder_init(OggFLAC__FileDecoder *decoder);
 464
 465 /** Finish the decoding process.
 466  *  Flushes the decoding buffer, releases resources, resets the decoder
 467  *  settings to their defaults, and returns the decoder state to
 468  *  OggFLAC__FILE_DECODER_UNINITIALIZED.
 469  *
 470  *  In the event of a prematurely-terminated decode, it is not strictly
 471  *  necessary to call this immediately before OggFLAC__file_decoder_delete()
 472  *  but it is good practice to match every OggFLAC__file_decoder_init() with
 473  *  an OggFLAC__file_decoder_finish().
 474  *
 475  * \param  decoder  An uninitialized decoder instance.
 476  * \assert
 477  *    \code decoder != NULL \endcode
 478  * \retval FLAC__bool
 479  *    \c false if MD5 checking is on AND a STREAMINFO block was available
 480  *    AND the MD5 signature in the STREAMINFO block was non-zero AND the
 481  *    signature does not match the one computed by the decoder; else
 482  *    \c true.
 483  */
 484 OggFLAC_API FLAC__bool OggFLAC__file_decoder_finish(OggFLAC__FileDecoder *decoder);
 485
 486 /** This is inherited from FLAC__FileDecoder; see
 487  *  FLAC__file_decoder_process_single().
 488  *
 489  * \param  decoder  A decoder instance.
 490  * \assert
 491  *    \code decoder != NULL \endcode
 492  * \retval FLAC__bool
 493  *    See above.
 494  */
 495 OggFLAC_API FLAC__bool OggFLAC__file_decoder_process_single(OggFLAC__FileDecoder *decoder);
 496
 497 /** This is inherited from FLAC__FileDecoder; see
 498  *  FLAC__file_decoder_process_until_end_of_metadata().
 499  *
 500  * \param  decoder  A decoder instance.
 501  * \assert
 502  *    \code decoder != NULL \endcode
 503  * \retval FLAC__bool
 504  *    See above.
 505  */
 506 OggFLAC_API FLAC__bool OggFLAC__file_decoder_process_until_end_of_metadata(OggFLAC__FileDecoder *decoder);
 507
 508 /** This is inherited from FLAC__FileDecoder; see
 509  *  FLAC__file_decoder_process_until_end_of_stream().
 510  *
 511  * \param  decoder  A decoder instance.
 512  * \assert
 513  *    \code decoder != NULL \endcode
 514  * \retval FLAC__bool
 515  *    See above.
 516  */
 517 OggFLAC_API FLAC__bool OggFLAC__file_decoder_process_until_end_of_file(OggFLAC__FileDecoder *decoder);
 518
 519 /** This is inherited from FLAC__FileDecoder; see
 520  *  FLAC__file_decoder_process_remaining_frames().
 521  *
 522  * \param  decoder  A decoder instance.
 523  * \assert
 524  *    \code decoder != NULL \endcode
 525  * \retval FLAC__bool
 526  *    See above.
 527  */
 528 OggFLAC_API FLAC__bool OggFLAC__file_decoder_process_remaining_frames(OggFLAC__FileDecoder *decoder);
 529
 530 /** This is inherited from FLAC__FileDecoder; see
 531  *  FLAC__file_decoder_seek_absolute().
 532  *
 533  * \param  decoder  A decoder instance.
 534  * \param  sample   The target sample number to seek to.
 535  * \assert
 536  *    \code decoder != NULL \endcode
 537  * \retval FLAC__bool
 538  *    \c true if successful, else \c false.
 539  */
 540 OggFLAC_API FLAC__bool OggFLAC__file_decoder_seek_absolute(OggFLAC__FileDecoder *decoder, FLAC__uint64 sample);
 541
 542 /* \} */
 543
 544 #ifdef __cplusplus
 545 }
 546 #endif
 547
 548 #endif