annotate win32-mingw/include/FLAC/stream_decoder.h @ 90:07fe46ff1966

Add more mingw builds
author Chris Cannam <cannam@all-day-breakfast.com>
date Wed, 20 Mar 2013 14:01:32 +0000
parents
children
rev   line source
cannam@90 1 /* libFLAC - Free Lossless Audio Codec library
cannam@90 2 * Copyright (C) 2000,2001,2002,2003,2004,2005,2006,2007 Josh Coalson
cannam@90 3 *
cannam@90 4 * Redistribution and use in source and binary forms, with or without
cannam@90 5 * modification, are permitted provided that the following conditions
cannam@90 6 * are met:
cannam@90 7 *
cannam@90 8 * - Redistributions of source code must retain the above copyright
cannam@90 9 * notice, this list of conditions and the following disclaimer.
cannam@90 10 *
cannam@90 11 * - Redistributions in binary form must reproduce the above copyright
cannam@90 12 * notice, this list of conditions and the following disclaimer in the
cannam@90 13 * documentation and/or other materials provided with the distribution.
cannam@90 14 *
cannam@90 15 * - Neither the name of the Xiph.org Foundation nor the names of its
cannam@90 16 * contributors may be used to endorse or promote products derived from
cannam@90 17 * this software without specific prior written permission.
cannam@90 18 *
cannam@90 19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
cannam@90 20 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
cannam@90 21 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
cannam@90 22 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR
cannam@90 23 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
cannam@90 24 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
cannam@90 25 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
cannam@90 26 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
cannam@90 27 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
cannam@90 28 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
cannam@90 29 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
cannam@90 30 */
cannam@90 31
cannam@90 32 #ifndef FLAC__STREAM_DECODER_H
cannam@90 33 #define FLAC__STREAM_DECODER_H
cannam@90 34
cannam@90 35 #include <stdio.h> /* for FILE */
cannam@90 36 #include "export.h"
cannam@90 37 #include "format.h"
cannam@90 38
cannam@90 39 #ifdef __cplusplus
cannam@90 40 extern "C" {
cannam@90 41 #endif
cannam@90 42
cannam@90 43
cannam@90 44 /** \file include/FLAC/stream_decoder.h
cannam@90 45 *
cannam@90 46 * \brief
cannam@90 47 * This module contains the functions which implement the stream
cannam@90 48 * decoder.
cannam@90 49 *
cannam@90 50 * See the detailed documentation in the
cannam@90 51 * \link flac_stream_decoder stream decoder \endlink module.
cannam@90 52 */
cannam@90 53
cannam@90 54 /** \defgroup flac_decoder FLAC/ \*_decoder.h: decoder interfaces
cannam@90 55 * \ingroup flac
cannam@90 56 *
cannam@90 57 * \brief
cannam@90 58 * This module describes the decoder layers provided by libFLAC.
cannam@90 59 *
cannam@90 60 * The stream decoder can be used to decode complete streams either from
cannam@90 61 * the client via callbacks, or directly from a file, depending on how
cannam@90 62 * it is initialized. When decoding via callbacks, the client provides
cannam@90 63 * callbacks for reading FLAC data and writing decoded samples, and
cannam@90 64 * handling metadata and errors. If the client also supplies seek-related
cannam@90 65 * callback, the decoder function for sample-accurate seeking within the
cannam@90 66 * FLAC input is also available. When decoding from a file, the client
cannam@90 67 * needs only supply a filename or open \c FILE* and write/metadata/error
cannam@90 68 * callbacks; the rest of the callbacks are supplied internally. For more
cannam@90 69 * info see the \link flac_stream_decoder stream decoder \endlink module.
cannam@90 70 */
cannam@90 71
cannam@90 72 /** \defgroup flac_stream_decoder FLAC/stream_decoder.h: stream decoder interface
cannam@90 73 * \ingroup flac_decoder
cannam@90 74 *
cannam@90 75 * \brief
cannam@90 76 * This module contains the functions which implement the stream
cannam@90 77 * decoder.
cannam@90 78 *
cannam@90 79 * The stream decoder can decode native FLAC, and optionally Ogg FLAC
cannam@90 80 * (check FLAC_API_SUPPORTS_OGG_FLAC) streams and files.
cannam@90 81 *
cannam@90 82 * The basic usage of this decoder is as follows:
cannam@90 83 * - The program creates an instance of a decoder using
cannam@90 84 * FLAC__stream_decoder_new().
cannam@90 85 * - The program overrides the default settings using
cannam@90 86 * FLAC__stream_decoder_set_*() functions.
cannam@90 87 * - The program initializes the instance to validate the settings and
cannam@90 88 * prepare for decoding using
cannam@90 89 * - FLAC__stream_decoder_init_stream() or FLAC__stream_decoder_init_FILE()
cannam@90 90 * or FLAC__stream_decoder_init_file() for native FLAC,
cannam@90 91 * - FLAC__stream_decoder_init_ogg_stream() or FLAC__stream_decoder_init_ogg_FILE()
cannam@90 92 * or FLAC__stream_decoder_init_ogg_file() for Ogg FLAC
cannam@90 93 * - The program calls the FLAC__stream_decoder_process_*() functions
cannam@90 94 * to decode data, which subsequently calls the callbacks.
cannam@90 95 * - The program finishes the decoding with FLAC__stream_decoder_finish(),
cannam@90 96 * which flushes the input and output and resets the decoder to the
cannam@90 97 * uninitialized state.
cannam@90 98 * - The instance may be used again or deleted with
cannam@90 99 * FLAC__stream_decoder_delete().
cannam@90 100 *
cannam@90 101 * In more detail, the program will create a new instance by calling
cannam@90 102 * FLAC__stream_decoder_new(), then call FLAC__stream_decoder_set_*()
cannam@90 103 * functions to override the default decoder options, and call
cannam@90 104 * one of the FLAC__stream_decoder_init_*() functions.
cannam@90 105 *
cannam@90 106 * There are three initialization functions for native FLAC, one for
cannam@90 107 * setting up the decoder to decode FLAC data from the client via
cannam@90 108 * callbacks, and two for decoding directly from a FLAC file.
cannam@90 109 *
cannam@90 110 * For decoding via callbacks, use FLAC__stream_decoder_init_stream().
cannam@90 111 * You must also supply several callbacks for handling I/O. Some (like
cannam@90 112 * seeking) are optional, depending on the capabilities of the input.
cannam@90 113 *
cannam@90 114 * For decoding directly from a file, use FLAC__stream_decoder_init_FILE()
cannam@90 115 * or FLAC__stream_decoder_init_file(). Then you must only supply an open
cannam@90 116 * \c FILE* or filename and fewer callbacks; the decoder will handle
cannam@90 117 * the other callbacks internally.
cannam@90 118 *
cannam@90 119 * There are three similarly-named init functions for decoding from Ogg
cannam@90 120 * FLAC streams. Check \c FLAC_API_SUPPORTS_OGG_FLAC to find out if the
cannam@90 121 * library has been built with Ogg support.
cannam@90 122 *
cannam@90 123 * Once the decoder is initialized, your program will call one of several
cannam@90 124 * functions to start the decoding process:
cannam@90 125 *
cannam@90 126 * - FLAC__stream_decoder_process_single() - Tells the decoder to process at
cannam@90 127 * most one metadata block or audio frame and return, calling either the
cannam@90 128 * metadata callback or write callback, respectively, once. If the decoder
cannam@90 129 * loses sync it will return with only the error callback being called.
cannam@90 130 * - FLAC__stream_decoder_process_until_end_of_metadata() - Tells the decoder
cannam@90 131 * to process the stream from the current location and stop upon reaching
cannam@90 132 * the first audio frame. The client will get one metadata, write, or error
cannam@90 133 * callback per metadata block, audio frame, or sync error, respectively.
cannam@90 134 * - FLAC__stream_decoder_process_until_end_of_stream() - Tells the decoder
cannam@90 135 * to process the stream from the current location until the read callback
cannam@90 136 * returns FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM or
cannam@90 137 * FLAC__STREAM_DECODER_READ_STATUS_ABORT. The client will get one metadata,
cannam@90 138 * write, or error callback per metadata block, audio frame, or sync error,
cannam@90 139 * respectively.
cannam@90 140 *
cannam@90 141 * When the decoder has finished decoding (normally or through an abort),
cannam@90 142 * the instance is finished by calling FLAC__stream_decoder_finish(), which
cannam@90 143 * ensures the decoder is in the correct state and frees memory. Then the
cannam@90 144 * instance may be deleted with FLAC__stream_decoder_delete() or initialized
cannam@90 145 * again to decode another stream.
cannam@90 146 *
cannam@90 147 * Seeking is exposed through the FLAC__stream_decoder_seek_absolute() method.
cannam@90 148 * At any point after the stream decoder has been initialized, the client can
cannam@90 149 * call this function to seek to an exact sample within the stream.
cannam@90 150 * Subsequently, the first time the write callback is called it will be
cannam@90 151 * passed a (possibly partial) block starting at that sample.
cannam@90 152 *
cannam@90 153 * If the client cannot seek via the callback interface provided, but still
cannam@90 154 * has another way of seeking, it can flush the decoder using
cannam@90 155 * FLAC__stream_decoder_flush() and start feeding data from the new position
cannam@90 156 * through the read callback.
cannam@90 157 *
cannam@90 158 * The stream decoder also provides MD5 signature checking. If this is
cannam@90 159 * turned on before initialization, FLAC__stream_decoder_finish() will
cannam@90 160 * report when the decoded MD5 signature does not match the one stored
cannam@90 161 * in the STREAMINFO block. MD5 checking is automatically turned off
cannam@90 162 * (until the next FLAC__stream_decoder_reset()) if there is no signature
cannam@90 163 * in the STREAMINFO block or when a seek is attempted.
cannam@90 164 *
cannam@90 165 * The FLAC__stream_decoder_set_metadata_*() functions deserve special
cannam@90 166 * attention. By default, the decoder only calls the metadata_callback for
cannam@90 167 * the STREAMINFO block. These functions allow you to tell the decoder
cannam@90 168 * explicitly which blocks to parse and return via the metadata_callback
cannam@90 169 * and/or which to skip. Use a FLAC__stream_decoder_set_metadata_respond_all(),
cannam@90 170 * FLAC__stream_decoder_set_metadata_ignore() ... or FLAC__stream_decoder_set_metadata_ignore_all(),
cannam@90 171 * FLAC__stream_decoder_set_metadata_respond() ... sequence to exactly specify
cannam@90 172 * which blocks to return. Remember that metadata blocks can potentially
cannam@90 173 * be big (for example, cover art) so filtering out the ones you don't
cannam@90 174 * use can reduce the memory requirements of the decoder. Also note the
cannam@90 175 * special forms FLAC__stream_decoder_set_metadata_respond_application(id)
cannam@90 176 * and FLAC__stream_decoder_set_metadata_ignore_application(id) for
cannam@90 177 * filtering APPLICATION blocks based on the application ID.
cannam@90 178 *
cannam@90 179 * STREAMINFO and SEEKTABLE blocks are always parsed and used internally, but
cannam@90 180 * they still can legally be filtered from the metadata_callback.
cannam@90 181 *
cannam@90 182 * \note
cannam@90 183 * The "set" functions may only be called when the decoder is in the
cannam@90 184 * state FLAC__STREAM_DECODER_UNINITIALIZED, i.e. after
cannam@90 185 * FLAC__stream_decoder_new() or FLAC__stream_decoder_finish(), but
cannam@90 186 * before FLAC__stream_decoder_init_*(). If this is the case they will
cannam@90 187 * return \c true, otherwise \c false.
cannam@90 188 *
cannam@90 189 * \note
cannam@90 190 * FLAC__stream_decoder_finish() resets all settings to the constructor
cannam@90 191 * defaults, including the callbacks.
cannam@90 192 *
cannam@90 193 * \{
cannam@90 194 */
cannam@90 195
cannam@90 196
cannam@90 197 /** State values for a FLAC__StreamDecoder
cannam@90 198 *
cannam@90 199 * The decoder's state can be obtained by calling FLAC__stream_decoder_get_state().
cannam@90 200 */
cannam@90 201 typedef enum {
cannam@90 202
cannam@90 203 FLAC__STREAM_DECODER_SEARCH_FOR_METADATA = 0,
cannam@90 204 /**< The decoder is ready to search for metadata. */
cannam@90 205
cannam@90 206 FLAC__STREAM_DECODER_READ_METADATA,
cannam@90 207 /**< The decoder is ready to or is in the process of reading metadata. */
cannam@90 208
cannam@90 209 FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC,
cannam@90 210 /**< The decoder is ready to or is in the process of searching for the
cannam@90 211 * frame sync code.
cannam@90 212 */
cannam@90 213
cannam@90 214 FLAC__STREAM_DECODER_READ_FRAME,
cannam@90 215 /**< The decoder is ready to or is in the process of reading a frame. */
cannam@90 216
cannam@90 217 FLAC__STREAM_DECODER_END_OF_STREAM,
cannam@90 218 /**< The decoder has reached the end of the stream. */
cannam@90 219
cannam@90 220 FLAC__STREAM_DECODER_OGG_ERROR,
cannam@90 221 /**< An error occurred in the underlying Ogg layer. */
cannam@90 222
cannam@90 223 FLAC__STREAM_DECODER_SEEK_ERROR,
cannam@90 224 /**< An error occurred while seeking. The decoder must be flushed
cannam@90 225 * with FLAC__stream_decoder_flush() or reset with
cannam@90 226 * FLAC__stream_decoder_reset() before decoding can continue.
cannam@90 227 */
cannam@90 228
cannam@90 229 FLAC__STREAM_DECODER_ABORTED,
cannam@90 230 /**< The decoder was aborted by the read callback. */
cannam@90 231
cannam@90 232 FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
cannam@90 233 /**< An error occurred allocating memory. The decoder is in an invalid
cannam@90 234 * state and can no longer be used.
cannam@90 235 */
cannam@90 236
cannam@90 237 FLAC__STREAM_DECODER_UNINITIALIZED
cannam@90 238 /**< The decoder is in the uninitialized state; one of the
cannam@90 239 * FLAC__stream_decoder_init_*() functions must be called before samples
cannam@90 240 * can be processed.
cannam@90 241 */
cannam@90 242
cannam@90 243 } FLAC__StreamDecoderState;
cannam@90 244
cannam@90 245 /** Maps a FLAC__StreamDecoderState to a C string.
cannam@90 246 *
cannam@90 247 * Using a FLAC__StreamDecoderState as the index to this array
cannam@90 248 * will give the string equivalent. The contents should not be modified.
cannam@90 249 */
cannam@90 250 extern FLAC_API const char * const FLAC__StreamDecoderStateString[];
cannam@90 251
cannam@90 252
cannam@90 253 /** Possible return values for the FLAC__stream_decoder_init_*() functions.
cannam@90 254 */
cannam@90 255 typedef enum {
cannam@90 256
cannam@90 257 FLAC__STREAM_DECODER_INIT_STATUS_OK = 0,
cannam@90 258 /**< Initialization was successful. */
cannam@90 259
cannam@90 260 FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER,
cannam@90 261 /**< The library was not compiled with support for the given container
cannam@90 262 * format.
cannam@90 263 */
cannam@90 264
cannam@90 265 FLAC__STREAM_DECODER_INIT_STATUS_INVALID_CALLBACKS,
cannam@90 266 /**< A required callback was not supplied. */
cannam@90 267
cannam@90 268 FLAC__STREAM_DECODER_INIT_STATUS_MEMORY_ALLOCATION_ERROR,
cannam@90 269 /**< An error occurred allocating memory. */
cannam@90 270
cannam@90 271 FLAC__STREAM_DECODER_INIT_STATUS_ERROR_OPENING_FILE,
cannam@90 272 /**< fopen() failed in FLAC__stream_decoder_init_file() or
cannam@90 273 * FLAC__stream_decoder_init_ogg_file(). */
cannam@90 274
cannam@90 275 FLAC__STREAM_DECODER_INIT_STATUS_ALREADY_INITIALIZED
cannam@90 276 /**< FLAC__stream_decoder_init_*() was called when the decoder was
cannam@90 277 * already initialized, usually because
cannam@90 278 * FLAC__stream_decoder_finish() was not called.
cannam@90 279 */
cannam@90 280
cannam@90 281 } FLAC__StreamDecoderInitStatus;
cannam@90 282
cannam@90 283 /** Maps a FLAC__StreamDecoderInitStatus to a C string.
cannam@90 284 *
cannam@90 285 * Using a FLAC__StreamDecoderInitStatus as the index to this array
cannam@90 286 * will give the string equivalent. The contents should not be modified.
cannam@90 287 */
cannam@90 288 extern FLAC_API const char * const FLAC__StreamDecoderInitStatusString[];
cannam@90 289
cannam@90 290
cannam@90 291 /** Return values for the FLAC__StreamDecoder read callback.
cannam@90 292 */
cannam@90 293 typedef enum {
cannam@90 294
cannam@90 295 FLAC__STREAM_DECODER_READ_STATUS_CONTINUE,
cannam@90 296 /**< The read was OK and decoding can continue. */
cannam@90 297
cannam@90 298 FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM,
cannam@90 299 /**< The read was attempted while at the end of the stream. Note that
cannam@90 300 * the client must only return this value when the read callback was
cannam@90 301 * called when already at the end of the stream. Otherwise, if the read
cannam@90 302 * itself moves to the end of the stream, the client should still return
cannam@90 303 * the data and \c FLAC__STREAM_DECODER_READ_STATUS_CONTINUE, and then on
cannam@90 304 * the next read callback it should return
cannam@90 305 * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM with a byte count
cannam@90 306 * of \c 0.
cannam@90 307 */
cannam@90 308
cannam@90 309 FLAC__STREAM_DECODER_READ_STATUS_ABORT
cannam@90 310 /**< An unrecoverable error occurred. The decoder will return from the process call. */
cannam@90 311
cannam@90 312 } FLAC__StreamDecoderReadStatus;
cannam@90 313
cannam@90 314 /** Maps a FLAC__StreamDecoderReadStatus to a C string.
cannam@90 315 *
cannam@90 316 * Using a FLAC__StreamDecoderReadStatus as the index to this array
cannam@90 317 * will give the string equivalent. The contents should not be modified.
cannam@90 318 */
cannam@90 319 extern FLAC_API const char * const FLAC__StreamDecoderReadStatusString[];
cannam@90 320
cannam@90 321
cannam@90 322 /** Return values for the FLAC__StreamDecoder seek callback.
cannam@90 323 */
cannam@90 324 typedef enum {
cannam@90 325
cannam@90 326 FLAC__STREAM_DECODER_SEEK_STATUS_OK,
cannam@90 327 /**< The seek was OK and decoding can continue. */
cannam@90 328
cannam@90 329 FLAC__STREAM_DECODER_SEEK_STATUS_ERROR,
cannam@90 330 /**< An unrecoverable error occurred. The decoder will return from the process call. */
cannam@90 331
cannam@90 332 FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
cannam@90 333 /**< Client does not support seeking. */
cannam@90 334
cannam@90 335 } FLAC__StreamDecoderSeekStatus;
cannam@90 336
cannam@90 337 /** Maps a FLAC__StreamDecoderSeekStatus to a C string.
cannam@90 338 *
cannam@90 339 * Using a FLAC__StreamDecoderSeekStatus as the index to this array
cannam@90 340 * will give the string equivalent. The contents should not be modified.
cannam@90 341 */
cannam@90 342 extern FLAC_API const char * const FLAC__StreamDecoderSeekStatusString[];
cannam@90 343
cannam@90 344
cannam@90 345 /** Return values for the FLAC__StreamDecoder tell callback.
cannam@90 346 */
cannam@90 347 typedef enum {
cannam@90 348
cannam@90 349 FLAC__STREAM_DECODER_TELL_STATUS_OK,
cannam@90 350 /**< The tell was OK and decoding can continue. */
cannam@90 351
cannam@90 352 FLAC__STREAM_DECODER_TELL_STATUS_ERROR,
cannam@90 353 /**< An unrecoverable error occurred. The decoder will return from the process call. */
cannam@90 354
cannam@90 355 FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
cannam@90 356 /**< Client does not support telling the position. */
cannam@90 357
cannam@90 358 } FLAC__StreamDecoderTellStatus;
cannam@90 359
cannam@90 360 /** Maps a FLAC__StreamDecoderTellStatus to a C string.
cannam@90 361 *
cannam@90 362 * Using a FLAC__StreamDecoderTellStatus as the index to this array
cannam@90 363 * will give the string equivalent. The contents should not be modified.
cannam@90 364 */
cannam@90 365 extern FLAC_API const char * const FLAC__StreamDecoderTellStatusString[];
cannam@90 366
cannam@90 367
cannam@90 368 /** Return values for the FLAC__StreamDecoder length callback.
cannam@90 369 */
cannam@90 370 typedef enum {
cannam@90 371
cannam@90 372 FLAC__STREAM_DECODER_LENGTH_STATUS_OK,
cannam@90 373 /**< The length call was OK and decoding can continue. */
cannam@90 374
cannam@90 375 FLAC__STREAM_DECODER_LENGTH_STATUS_ERROR,
cannam@90 376 /**< An unrecoverable error occurred. The decoder will return from the process call. */
cannam@90 377
cannam@90 378 FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
cannam@90 379 /**< Client does not support reporting the length. */
cannam@90 380
cannam@90 381 } FLAC__StreamDecoderLengthStatus;
cannam@90 382
cannam@90 383 /** Maps a FLAC__StreamDecoderLengthStatus to a C string.
cannam@90 384 *
cannam@90 385 * Using a FLAC__StreamDecoderLengthStatus as the index to this array
cannam@90 386 * will give the string equivalent. The contents should not be modified.
cannam@90 387 */
cannam@90 388 extern FLAC_API const char * const FLAC__StreamDecoderLengthStatusString[];
cannam@90 389
cannam@90 390
cannam@90 391 /** Return values for the FLAC__StreamDecoder write callback.
cannam@90 392 */
cannam@90 393 typedef enum {
cannam@90 394
cannam@90 395 FLAC__STREAM_DECODER_WRITE_STATUS_CONTINUE,
cannam@90 396 /**< The write was OK and decoding can continue. */
cannam@90 397
cannam@90 398 FLAC__STREAM_DECODER_WRITE_STATUS_ABORT
cannam@90 399 /**< An unrecoverable error occurred. The decoder will return from the process call. */
cannam@90 400
cannam@90 401 } FLAC__StreamDecoderWriteStatus;
cannam@90 402
cannam@90 403 /** Maps a FLAC__StreamDecoderWriteStatus to a C string.
cannam@90 404 *
cannam@90 405 * Using a FLAC__StreamDecoderWriteStatus as the index to this array
cannam@90 406 * will give the string equivalent. The contents should not be modified.
cannam@90 407 */
cannam@90 408 extern FLAC_API const char * const FLAC__StreamDecoderWriteStatusString[];
cannam@90 409
cannam@90 410
cannam@90 411 /** Possible values passed back to the FLAC__StreamDecoder error callback.
cannam@90 412 * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC is the generic catch-
cannam@90 413 * all. The rest could be caused by bad sync (false synchronization on
cannam@90 414 * data that is not the start of a frame) or corrupted data. The error
cannam@90 415 * itself is the decoder's best guess at what happened assuming a correct
cannam@90 416 * sync. For example \c FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER
cannam@90 417 * could be caused by a correct sync on the start of a frame, but some
cannam@90 418 * data in the frame header was corrupted. Or it could be the result of
cannam@90 419 * syncing on a point the stream that looked like the starting of a frame
cannam@90 420 * but was not. \c FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM
cannam@90 421 * could be because the decoder encountered a valid frame made by a future
cannam@90 422 * version of the encoder which it cannot parse, or because of a false
cannam@90 423 * sync making it appear as though an encountered frame was generated by
cannam@90 424 * a future encoder.
cannam@90 425 */
cannam@90 426 typedef enum {
cannam@90 427
cannam@90 428 FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC,
cannam@90 429 /**< An error in the stream caused the decoder to lose synchronization. */
cannam@90 430
cannam@90 431 FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER,
cannam@90 432 /**< The decoder encountered a corrupted frame header. */
cannam@90 433
cannam@90 434 FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH,
cannam@90 435 /**< The frame's data did not match the CRC in the footer. */
cannam@90 436
cannam@90 437 FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM
cannam@90 438 /**< The decoder encountered reserved fields in use in the stream. */
cannam@90 439
cannam@90 440 } FLAC__StreamDecoderErrorStatus;
cannam@90 441
cannam@90 442 /** Maps a FLAC__StreamDecoderErrorStatus to a C string.
cannam@90 443 *
cannam@90 444 * Using a FLAC__StreamDecoderErrorStatus as the index to this array
cannam@90 445 * will give the string equivalent. The contents should not be modified.
cannam@90 446 */
cannam@90 447 extern FLAC_API const char * const FLAC__StreamDecoderErrorStatusString[];
cannam@90 448
cannam@90 449
cannam@90 450 /***********************************************************************
cannam@90 451 *
cannam@90 452 * class FLAC__StreamDecoder
cannam@90 453 *
cannam@90 454 ***********************************************************************/
cannam@90 455
cannam@90 456 struct FLAC__StreamDecoderProtected;
cannam@90 457 struct FLAC__StreamDecoderPrivate;
cannam@90 458 /** The opaque structure definition for the stream decoder type.
cannam@90 459 * See the \link flac_stream_decoder stream decoder module \endlink
cannam@90 460 * for a detailed description.
cannam@90 461 */
cannam@90 462 typedef struct {
cannam@90 463 struct FLAC__StreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
cannam@90 464 struct FLAC__StreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
cannam@90 465 } FLAC__StreamDecoder;
cannam@90 466
cannam@90 467 /** Signature for the read callback.
cannam@90 468 *
cannam@90 469 * A function pointer matching this signature must be passed to
cannam@90 470 * FLAC__stream_decoder_init*_stream(). The supplied function will be
cannam@90 471 * called when the decoder needs more input data. The address of the
cannam@90 472 * buffer to be filled is supplied, along with the number of bytes the
cannam@90 473 * buffer can hold. The callback may choose to supply less data and
cannam@90 474 * modify the byte count but must be careful not to overflow the buffer.
cannam@90 475 * The callback then returns a status code chosen from
cannam@90 476 * FLAC__StreamDecoderReadStatus.
cannam@90 477 *
cannam@90 478 * Here is an example of a read callback for stdio streams:
cannam@90 479 * \code
cannam@90 480 * FLAC__StreamDecoderReadStatus read_cb(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], size_t *bytes, void *client_data)
cannam@90 481 * {
cannam@90 482 * FILE *file = ((MyClientData*)client_data)->file;
cannam@90 483 * if(*bytes > 0) {
cannam@90 484 * *bytes = fread(buffer, sizeof(FLAC__byte), *bytes, file);
cannam@90 485 * if(ferror(file))
cannam@90 486 * return FLAC__STREAM_DECODER_READ_STATUS_ABORT;
cannam@90 487 * else if(*bytes == 0)
cannam@90 488 * return FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM;
cannam@90 489 * else
cannam@90 490 * return FLAC__STREAM_DECODER_READ_STATUS_CONTINUE;
cannam@90 491 * }
cannam@90 492 * else
cannam@90 493 * return FLAC__STREAM_DECODER_READ_STATUS_ABORT;
cannam@90 494 * }
cannam@90 495 * \endcode
cannam@90 496 *
cannam@90 497 * \note In general, FLAC__StreamDecoder functions which change the
cannam@90 498 * state should not be called on the \a decoder while in the callback.
cannam@90 499 *
cannam@90 500 * \param decoder The decoder instance calling the callback.
cannam@90 501 * \param buffer A pointer to a location for the callee to store
cannam@90 502 * data to be decoded.
cannam@90 503 * \param bytes A pointer to the size of the buffer. On entry
cannam@90 504 * to the callback, it contains the maximum number
cannam@90 505 * of bytes that may be stored in \a buffer. The
cannam@90 506 * callee must set it to the actual number of bytes
cannam@90 507 * stored (0 in case of error or end-of-stream) before
cannam@90 508 * returning.
cannam@90 509 * \param client_data The callee's client data set through
cannam@90 510 * FLAC__stream_decoder_init_*().
cannam@90 511 * \retval FLAC__StreamDecoderReadStatus
cannam@90 512 * The callee's return status. Note that the callback should return
cannam@90 513 * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM if and only if
cannam@90 514 * zero bytes were read and there is no more data to be read.
cannam@90 515 */
cannam@90 516 typedef FLAC__StreamDecoderReadStatus (*FLAC__StreamDecoderReadCallback)(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], size_t *bytes, void *client_data);
cannam@90 517
cannam@90 518 /** Signature for the seek callback.
cannam@90 519 *
cannam@90 520 * A function pointer matching this signature may be passed to
cannam@90 521 * FLAC__stream_decoder_init*_stream(). The supplied function will be
cannam@90 522 * called when the decoder needs to seek the input stream. The decoder
cannam@90 523 * will pass the absolute byte offset to seek to, 0 meaning the
cannam@90 524 * beginning of the stream.
cannam@90 525 *
cannam@90 526 * Here is an example of a seek callback for stdio streams:
cannam@90 527 * \code
cannam@90 528 * FLAC__StreamDecoderSeekStatus seek_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data)
cannam@90 529 * {
cannam@90 530 * FILE *file = ((MyClientData*)client_data)->file;
cannam@90 531 * if(file == stdin)
cannam@90 532 * return FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED;
cannam@90 533 * else if(fseeko(file, (off_t)absolute_byte_offset, SEEK_SET) < 0)
cannam@90 534 * return FLAC__STREAM_DECODER_SEEK_STATUS_ERROR;
cannam@90 535 * else
cannam@90 536 * return FLAC__STREAM_DECODER_SEEK_STATUS_OK;
cannam@90 537 * }
cannam@90 538 * \endcode
cannam@90 539 *
cannam@90 540 * \note In general, FLAC__StreamDecoder functions which change the
cannam@90 541 * state should not be called on the \a decoder while in the callback.
cannam@90 542 *
cannam@90 543 * \param decoder The decoder instance calling the callback.
cannam@90 544 * \param absolute_byte_offset The offset from the beginning of the stream
cannam@90 545 * to seek to.
cannam@90 546 * \param client_data The callee's client data set through
cannam@90 547 * FLAC__stream_decoder_init_*().
cannam@90 548 * \retval FLAC__StreamDecoderSeekStatus
cannam@90 549 * The callee's return status.
cannam@90 550 */
cannam@90 551 typedef FLAC__StreamDecoderSeekStatus (*FLAC__StreamDecoderSeekCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
cannam@90 552
cannam@90 553 /** Signature for the tell callback.
cannam@90 554 *
cannam@90 555 * A function pointer matching this signature may be passed to
cannam@90 556 * FLAC__stream_decoder_init*_stream(). The supplied function will be
cannam@90 557 * called when the decoder wants to know the current position of the
cannam@90 558 * stream. The callback should return the byte offset from the
cannam@90 559 * beginning of the stream.
cannam@90 560 *
cannam@90 561 * Here is an example of a tell callback for stdio streams:
cannam@90 562 * \code
cannam@90 563 * FLAC__StreamDecoderTellStatus tell_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data)
cannam@90 564 * {
cannam@90 565 * FILE *file = ((MyClientData*)client_data)->file;
cannam@90 566 * off_t pos;
cannam@90 567 * if(file == stdin)
cannam@90 568 * return FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED;
cannam@90 569 * else if((pos = ftello(file)) < 0)
cannam@90 570 * return FLAC__STREAM_DECODER_TELL_STATUS_ERROR;
cannam@90 571 * else {
cannam@90 572 * *absolute_byte_offset = (FLAC__uint64)pos;
cannam@90 573 * return FLAC__STREAM_DECODER_TELL_STATUS_OK;
cannam@90 574 * }
cannam@90 575 * }
cannam@90 576 * \endcode
cannam@90 577 *
cannam@90 578 * \note In general, FLAC__StreamDecoder functions which change the
cannam@90 579 * state should not be called on the \a decoder while in the callback.
cannam@90 580 *
cannam@90 581 * \param decoder The decoder instance calling the callback.
cannam@90 582 * \param absolute_byte_offset A pointer to storage for the current offset
cannam@90 583 * from the beginning of the stream.
cannam@90 584 * \param client_data The callee's client data set through
cannam@90 585 * FLAC__stream_decoder_init_*().
cannam@90 586 * \retval FLAC__StreamDecoderTellStatus
cannam@90 587 * The callee's return status.
cannam@90 588 */
cannam@90 589 typedef FLAC__StreamDecoderTellStatus (*FLAC__StreamDecoderTellCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
cannam@90 590
cannam@90 591 /** Signature for the length callback.
cannam@90 592 *
cannam@90 593 * A function pointer matching this signature may be passed to
cannam@90 594 * FLAC__stream_decoder_init*_stream(). The supplied function will be
cannam@90 595 * called when the decoder wants to know the total length of the stream
cannam@90 596 * in bytes.
cannam@90 597 *
cannam@90 598 * Here is an example of a length callback for stdio streams:
cannam@90 599 * \code
cannam@90 600 * FLAC__StreamDecoderLengthStatus length_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data)
cannam@90 601 * {
cannam@90 602 * FILE *file = ((MyClientData*)client_data)->file;
cannam@90 603 * struct stat filestats;
cannam@90 604 *
cannam@90 605 * if(file == stdin)
cannam@90 606 * return FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED;
cannam@90 607 * else if(fstat(fileno(file), &filestats) != 0)
cannam@90 608 * return FLAC__STREAM_DECODER_LENGTH_STATUS_ERROR;
cannam@90 609 * else {
cannam@90 610 * *stream_length = (FLAC__uint64)filestats.st_size;
cannam@90 611 * return FLAC__STREAM_DECODER_LENGTH_STATUS_OK;
cannam@90 612 * }
cannam@90 613 * }
cannam@90 614 * \endcode
cannam@90 615 *
cannam@90 616 * \note In general, FLAC__StreamDecoder functions which change the
cannam@90 617 * state should not be called on the \a decoder while in the callback.
cannam@90 618 *
cannam@90 619 * \param decoder The decoder instance calling the callback.
cannam@90 620 * \param stream_length A pointer to storage for the length of the stream
cannam@90 621 * in bytes.
cannam@90 622 * \param client_data The callee's client data set through
cannam@90 623 * FLAC__stream_decoder_init_*().
cannam@90 624 * \retval FLAC__StreamDecoderLengthStatus
cannam@90 625 * The callee's return status.
cannam@90 626 */
cannam@90 627 typedef FLAC__StreamDecoderLengthStatus (*FLAC__StreamDecoderLengthCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
cannam@90 628
cannam@90 629 /** Signature for the EOF callback.
cannam@90 630 *
cannam@90 631 * A function pointer matching this signature may be passed to
cannam@90 632 * FLAC__stream_decoder_init*_stream(). The supplied function will be
cannam@90 633 * called when the decoder needs to know if the end of the stream has
cannam@90 634 * been reached.
cannam@90 635 *
cannam@90 636 * Here is an example of a EOF callback for stdio streams:
cannam@90 637 * FLAC__bool eof_cb(const FLAC__StreamDecoder *decoder, void *client_data)
cannam@90 638 * \code
cannam@90 639 * {
cannam@90 640 * FILE *file = ((MyClientData*)client_data)->file;
cannam@90 641 * return feof(file)? true : false;
cannam@90 642 * }
cannam@90 643 * \endcode
cannam@90 644 *
cannam@90 645 * \note In general, FLAC__StreamDecoder functions which change the
cannam@90 646 * state should not be called on the \a decoder while in the callback.
cannam@90 647 *
cannam@90 648 * \param decoder The decoder instance calling the callback.
cannam@90 649 * \param client_data The callee's client data set through
cannam@90 650 * FLAC__stream_decoder_init_*().
cannam@90 651 * \retval FLAC__bool
cannam@90 652 * \c true if the currently at the end of the stream, else \c false.
cannam@90 653 */
cannam@90 654 typedef FLAC__bool (*FLAC__StreamDecoderEofCallback)(const FLAC__StreamDecoder *decoder, void *client_data);
cannam@90 655
cannam@90 656 /** Signature for the write callback.
cannam@90 657 *
cannam@90 658 * A function pointer matching this signature must be passed to one of
cannam@90 659 * the FLAC__stream_decoder_init_*() functions.
cannam@90 660 * The supplied function will be called when the decoder has decoded a
cannam@90 661 * single audio frame. The decoder will pass the frame metadata as well
cannam@90 662 * as an array of pointers (one for each channel) pointing to the
cannam@90 663 * decoded audio.
cannam@90 664 *
cannam@90 665 * \note In general, FLAC__StreamDecoder functions which change the
cannam@90 666 * state should not be called on the \a decoder while in the callback.
cannam@90 667 *
cannam@90 668 * \param decoder The decoder instance calling the callback.
cannam@90 669 * \param frame The description of the decoded frame. See
cannam@90 670 * FLAC__Frame.
cannam@90 671 * \param buffer An array of pointers to decoded channels of data.
cannam@90 672 * Each pointer will point to an array of signed
cannam@90 673 * samples of length \a frame->header.blocksize.
cannam@90 674 * Channels will be ordered according to the FLAC
cannam@90 675 * specification; see the documentation for the
cannam@90 676 * <A HREF="../format.html#frame_header">frame header</A>.
cannam@90 677 * \param client_data The callee's client data set through
cannam@90 678 * FLAC__stream_decoder_init_*().
cannam@90 679 * \retval FLAC__StreamDecoderWriteStatus
cannam@90 680 * The callee's return status.
cannam@90 681 */
cannam@90 682 typedef FLAC__StreamDecoderWriteStatus (*FLAC__StreamDecoderWriteCallback)(const FLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
cannam@90 683
cannam@90 684 /** Signature for the metadata callback.
cannam@90 685 *
cannam@90 686 * A function pointer matching this signature must be passed to one of
cannam@90 687 * the FLAC__stream_decoder_init_*() functions.
cannam@90 688 * The supplied function will be called when the decoder has decoded a
cannam@90 689 * metadata block. In a valid FLAC file there will always be one
cannam@90 690 * \c STREAMINFO block, followed by zero or more other metadata blocks.
cannam@90 691 * These will be supplied by the decoder in the same order as they
cannam@90 692 * appear in the stream and always before the first audio frame (i.e.
cannam@90 693 * write callback). The metadata block that is passed in must not be
cannam@90 694 * modified, and it doesn't live beyond the callback, so you should make
cannam@90 695 * a copy of it with FLAC__metadata_object_clone() if you will need it
cannam@90 696 * elsewhere. Since metadata blocks can potentially be large, by
cannam@90 697 * default the decoder only calls the metadata callback for the
cannam@90 698 * \c STREAMINFO block; you can instruct the decoder to pass or filter
cannam@90 699 * other blocks with FLAC__stream_decoder_set_metadata_*() calls.
cannam@90 700 *
cannam@90 701 * \note In general, FLAC__StreamDecoder functions which change the
cannam@90 702 * state should not be called on the \a decoder while in the callback.
cannam@90 703 *
cannam@90 704 * \param decoder The decoder instance calling the callback.
cannam@90 705 * \param metadata The decoded metadata block.
cannam@90 706 * \param client_data The callee's client data set through
cannam@90 707 * FLAC__stream_decoder_init_*().
cannam@90 708 */
cannam@90 709 typedef void (*FLAC__StreamDecoderMetadataCallback)(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
cannam@90 710
cannam@90 711 /** Signature for the error callback.
cannam@90 712 *
cannam@90 713 * A function pointer matching this signature must be passed to one of
cannam@90 714 * the FLAC__stream_decoder_init_*() functions.
cannam@90 715 * The supplied function will be called whenever an error occurs during
cannam@90 716 * decoding.
cannam@90 717 *
cannam@90 718 * \note In general, FLAC__StreamDecoder functions which change the
cannam@90 719 * state should not be called on the \a decoder while in the callback.
cannam@90 720 *
cannam@90 721 * \param decoder The decoder instance calling the callback.
cannam@90 722 * \param status The error encountered by the decoder.
cannam@90 723 * \param client_data The callee's client data set through
cannam@90 724 * FLAC__stream_decoder_init_*().
cannam@90 725 */
cannam@90 726 typedef void (*FLAC__StreamDecoderErrorCallback)(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
cannam@90 727
cannam@90 728
cannam@90 729 /***********************************************************************
cannam@90 730 *
cannam@90 731 * Class constructor/destructor
cannam@90 732 *
cannam@90 733 ***********************************************************************/
cannam@90 734
cannam@90 735 /** Create a new stream decoder instance. The instance is created with
cannam@90 736 * default settings; see the individual FLAC__stream_decoder_set_*()
cannam@90 737 * functions for each setting's default.
cannam@90 738 *
cannam@90 739 * \retval FLAC__StreamDecoder*
cannam@90 740 * \c NULL if there was an error allocating memory, else the new instance.
cannam@90 741 */
cannam@90 742 FLAC_API FLAC__StreamDecoder *FLAC__stream_decoder_new(void);
cannam@90 743
cannam@90 744 /** Free a decoder instance. Deletes the object pointed to by \a decoder.
cannam@90 745 *
cannam@90 746 * \param decoder A pointer to an existing decoder.
cannam@90 747 * \assert
cannam@90 748 * \code decoder != NULL \endcode
cannam@90 749 */
cannam@90 750 FLAC_API void FLAC__stream_decoder_delete(FLAC__StreamDecoder *decoder);
cannam@90 751
cannam@90 752
cannam@90 753 /***********************************************************************
cannam@90 754 *
cannam@90 755 * Public class method prototypes
cannam@90 756 *
cannam@90 757 ***********************************************************************/
cannam@90 758
cannam@90 759 /** Set the serial number for the FLAC stream within the Ogg container.
cannam@90 760 * The default behavior is to use the serial number of the first Ogg
cannam@90 761 * page. Setting a serial number here will explicitly specify which
cannam@90 762 * stream is to be decoded.
cannam@90 763 *
cannam@90 764 * \note
cannam@90 765 * This does not need to be set for native FLAC decoding.
cannam@90 766 *
cannam@90 767 * \default \c use serial number of first page
cannam@90 768 * \param decoder A decoder instance to set.
cannam@90 769 * \param serial_number See above.
cannam@90 770 * \assert
cannam@90 771 * \code decoder != NULL \endcode
cannam@90 772 * \retval FLAC__bool
cannam@90 773 * \c false if the decoder is already initialized, else \c true.
cannam@90 774 */
cannam@90 775 FLAC_API FLAC__bool FLAC__stream_decoder_set_ogg_serial_number(FLAC__StreamDecoder *decoder, long serial_number);
cannam@90 776
cannam@90 777 /** Set the "MD5 signature checking" flag. If \c true, the decoder will
cannam@90 778 * compute the MD5 signature of the unencoded audio data while decoding
cannam@90 779 * and compare it to the signature from the STREAMINFO block, if it
cannam@90 780 * exists, during FLAC__stream_decoder_finish().
cannam@90 781 *
cannam@90 782 * MD5 signature checking will be turned off (until the next
cannam@90 783 * FLAC__stream_decoder_reset()) if there is no signature in the
cannam@90 784 * STREAMINFO block or when a seek is attempted.
cannam@90 785 *
cannam@90 786 * Clients that do not use the MD5 check should leave this off to speed
cannam@90 787 * up decoding.
cannam@90 788 *
cannam@90 789 * \default \c false
cannam@90 790 * \param decoder A decoder instance to set.
cannam@90 791 * \param value Flag value (see above).
cannam@90 792 * \assert
cannam@90 793 * \code decoder != NULL \endcode
cannam@90 794 * \retval FLAC__bool
cannam@90 795 * \c false if the decoder is already initialized, else \c true.
cannam@90 796 */
cannam@90 797 FLAC_API FLAC__bool FLAC__stream_decoder_set_md5_checking(FLAC__StreamDecoder *decoder, FLAC__bool value);
cannam@90 798
cannam@90 799 /** Direct the decoder to pass on all metadata blocks of type \a type.
cannam@90 800 *
cannam@90 801 * \default By default, only the \c STREAMINFO block is returned via the
cannam@90 802 * metadata callback.
cannam@90 803 * \param decoder A decoder instance to set.
cannam@90 804 * \param type See above.
cannam@90 805 * \assert
cannam@90 806 * \code decoder != NULL \endcode
cannam@90 807 * \a type is valid
cannam@90 808 * \retval FLAC__bool
cannam@90 809 * \c false if the decoder is already initialized, else \c true.
cannam@90 810 */
cannam@90 811 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
cannam@90 812
cannam@90 813 /** Direct the decoder to pass on all APPLICATION metadata blocks of the
cannam@90 814 * given \a id.
cannam@90 815 *
cannam@90 816 * \default By default, only the \c STREAMINFO block is returned via the
cannam@90 817 * metadata callback.
cannam@90 818 * \param decoder A decoder instance to set.
cannam@90 819 * \param id See above.
cannam@90 820 * \assert
cannam@90 821 * \code decoder != NULL \endcode
cannam@90 822 * \code id != NULL \endcode
cannam@90 823 * \retval FLAC__bool
cannam@90 824 * \c false if the decoder is already initialized, else \c true.
cannam@90 825 */
cannam@90 826 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
cannam@90 827
cannam@90 828 /** Direct the decoder to pass on all metadata blocks of any type.
cannam@90 829 *
cannam@90 830 * \default By default, only the \c STREAMINFO block is returned via the
cannam@90 831 * metadata callback.
cannam@90 832 * \param decoder A decoder instance to set.
cannam@90 833 * \assert
cannam@90 834 * \code decoder != NULL \endcode
cannam@90 835 * \retval FLAC__bool
cannam@90 836 * \c false if the decoder is already initialized, else \c true.
cannam@90 837 */
cannam@90 838 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_all(FLAC__StreamDecoder *decoder);
cannam@90 839
cannam@90 840 /** Direct the decoder to filter out all metadata blocks of type \a type.
cannam@90 841 *
cannam@90 842 * \default By default, only the \c STREAMINFO block is returned via the
cannam@90 843 * metadata callback.
cannam@90 844 * \param decoder A decoder instance to set.
cannam@90 845 * \param type See above.
cannam@90 846 * \assert
cannam@90 847 * \code decoder != NULL \endcode
cannam@90 848 * \a type is valid
cannam@90 849 * \retval FLAC__bool
cannam@90 850 * \c false if the decoder is already initialized, else \c true.
cannam@90 851 */
cannam@90 852 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
cannam@90 853
cannam@90 854 /** Direct the decoder to filter out all APPLICATION metadata blocks of
cannam@90 855 * the given \a id.
cannam@90 856 *
cannam@90 857 * \default By default, only the \c STREAMINFO block is returned via the
cannam@90 858 * metadata callback.
cannam@90 859 * \param decoder A decoder instance to set.
cannam@90 860 * \param id See above.
cannam@90 861 * \assert
cannam@90 862 * \code decoder != NULL \endcode
cannam@90 863 * \code id != NULL \endcode
cannam@90 864 * \retval FLAC__bool
cannam@90 865 * \c false if the decoder is already initialized, else \c true.
cannam@90 866 */
cannam@90 867 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
cannam@90 868
cannam@90 869 /** Direct the decoder to filter out all metadata blocks of any type.
cannam@90 870 *
cannam@90 871 * \default By default, only the \c STREAMINFO block is returned via the
cannam@90 872 * metadata callback.
cannam@90 873 * \param decoder A decoder instance to set.
cannam@90 874 * \assert
cannam@90 875 * \code decoder != NULL \endcode
cannam@90 876 * \retval FLAC__bool
cannam@90 877 * \c false if the decoder is already initialized, else \c true.
cannam@90 878 */
cannam@90 879 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_all(FLAC__StreamDecoder *decoder);
cannam@90 880
cannam@90 881 /** Get the current decoder state.
cannam@90 882 *
cannam@90 883 * \param decoder A decoder instance to query.
cannam@90 884 * \assert
cannam@90 885 * \code decoder != NULL \endcode
cannam@90 886 * \retval FLAC__StreamDecoderState
cannam@90 887 * The current decoder state.
cannam@90 888 */
cannam@90 889 FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_get_state(const FLAC__StreamDecoder *decoder);
cannam@90 890
cannam@90 891 /** Get the current decoder state as a C string.
cannam@90 892 *
cannam@90 893 * \param decoder A decoder instance to query.
cannam@90 894 * \assert
cannam@90 895 * \code decoder != NULL \endcode
cannam@90 896 * \retval const char *
cannam@90 897 * The decoder state as a C string. Do not modify the contents.
cannam@90 898 */
cannam@90 899 FLAC_API const char *FLAC__stream_decoder_get_resolved_state_string(const FLAC__StreamDecoder *decoder);
cannam@90 900
cannam@90 901 /** Get the "MD5 signature checking" flag.
cannam@90 902 * This is the value of the setting, not whether or not the decoder is
cannam@90 903 * currently checking the MD5 (remember, it can be turned off automatically
cannam@90 904 * by a seek). When the decoder is reset the flag will be restored to the
cannam@90 905 * value returned by this function.
cannam@90 906 *
cannam@90 907 * \param decoder A decoder instance to query.
cannam@90 908 * \assert
cannam@90 909 * \code decoder != NULL \endcode
cannam@90 910 * \retval FLAC__bool
cannam@90 911 * See above.
cannam@90 912 */
cannam@90 913 FLAC_API FLAC__bool FLAC__stream_decoder_get_md5_checking(const FLAC__StreamDecoder *decoder);
cannam@90 914
cannam@90 915 /** Get the total number of samples in the stream being decoded.
cannam@90 916 * Will only be valid after decoding has started and will contain the
cannam@90 917 * value from the \c STREAMINFO block. A value of \c 0 means "unknown".
cannam@90 918 *
cannam@90 919 * \param decoder A decoder instance to query.
cannam@90 920 * \assert
cannam@90 921 * \code decoder != NULL \endcode
cannam@90 922 * \retval unsigned
cannam@90 923 * See above.
cannam@90 924 */
cannam@90 925 FLAC_API FLAC__uint64 FLAC__stream_decoder_get_total_samples(const FLAC__StreamDecoder *decoder);
cannam@90 926
cannam@90 927 /** Get the current number of channels in the stream being decoded.
cannam@90 928 * Will only be valid after decoding has started and will contain the
cannam@90 929 * value from the most recently decoded frame header.
cannam@90 930 *
cannam@90 931 * \param decoder A decoder instance to query.
cannam@90 932 * \assert
cannam@90 933 * \code decoder != NULL \endcode
cannam@90 934 * \retval unsigned
cannam@90 935 * See above.
cannam@90 936 */
cannam@90 937 FLAC_API unsigned FLAC__stream_decoder_get_channels(const FLAC__StreamDecoder *decoder);
cannam@90 938
cannam@90 939 /** Get the current channel assignment in the stream being decoded.
cannam@90 940 * Will only be valid after decoding has started and will contain the
cannam@90 941 * value from the most recently decoded frame header.
cannam@90 942 *
cannam@90 943 * \param decoder A decoder instance to query.
cannam@90 944 * \assert
cannam@90 945 * \code decoder != NULL \endcode
cannam@90 946 * \retval FLAC__ChannelAssignment
cannam@90 947 * See above.
cannam@90 948 */
cannam@90 949 FLAC_API FLAC__ChannelAssignment FLAC__stream_decoder_get_channel_assignment(const FLAC__StreamDecoder *decoder);
cannam@90 950
cannam@90 951 /** Get the current sample resolution in the stream being decoded.
cannam@90 952 * Will only be valid after decoding has started and will contain the
cannam@90 953 * value from the most recently decoded frame header.
cannam@90 954 *
cannam@90 955 * \param decoder A decoder instance to query.
cannam@90 956 * \assert
cannam@90 957 * \code decoder != NULL \endcode
cannam@90 958 * \retval unsigned
cannam@90 959 * See above.
cannam@90 960 */
cannam@90 961 FLAC_API unsigned FLAC__stream_decoder_get_bits_per_sample(const FLAC__StreamDecoder *decoder);
cannam@90 962
cannam@90 963 /** Get the current sample rate in Hz of the stream being decoded.
cannam@90 964 * Will only be valid after decoding has started and will contain the
cannam@90 965 * value from the most recently decoded frame header.
cannam@90 966 *
cannam@90 967 * \param decoder A decoder instance to query.
cannam@90 968 * \assert
cannam@90 969 * \code decoder != NULL \endcode
cannam@90 970 * \retval unsigned
cannam@90 971 * See above.
cannam@90 972 */
cannam@90 973 FLAC_API unsigned FLAC__stream_decoder_get_sample_rate(const FLAC__StreamDecoder *decoder);
cannam@90 974
cannam@90 975 /** Get the current blocksize of the stream being decoded.
cannam@90 976 * Will only be valid after decoding has started and will contain the
cannam@90 977 * value from the most recently decoded frame header.
cannam@90 978 *
cannam@90 979 * \param decoder A decoder instance to query.
cannam@90 980 * \assert
cannam@90 981 * \code decoder != NULL \endcode
cannam@90 982 * \retval unsigned
cannam@90 983 * See above.
cannam@90 984 */
cannam@90 985 FLAC_API unsigned FLAC__stream_decoder_get_blocksize(const FLAC__StreamDecoder *decoder);
cannam@90 986
cannam@90 987 /** Returns the decoder's current read position within the stream.
cannam@90 988 * The position is the byte offset from the start of the stream.
cannam@90 989 * Bytes before this position have been fully decoded. Note that
cannam@90 990 * there may still be undecoded bytes in the decoder's read FIFO.
cannam@90 991 * The returned position is correct even after a seek.
cannam@90 992 *
cannam@90 993 * \warning This function currently only works for native FLAC,
cannam@90 994 * not Ogg FLAC streams.
cannam@90 995 *
cannam@90 996 * \param decoder A decoder instance to query.
cannam@90 997 * \param position Address at which to return the desired position.
cannam@90 998 * \assert
cannam@90 999 * \code decoder != NULL \endcode
cannam@90 1000 * \code position != NULL \endcode
cannam@90 1001 * \retval FLAC__bool
cannam@90 1002 * \c true if successful, \c false if the stream is not native FLAC,
cannam@90 1003 * or there was an error from the 'tell' callback or it returned
cannam@90 1004 * \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED.
cannam@90 1005 */
cannam@90 1006 FLAC_API FLAC__bool FLAC__stream_decoder_get_decode_position(const FLAC__StreamDecoder *decoder, FLAC__uint64 *position);
cannam@90 1007
cannam@90 1008 /** Initialize the decoder instance to decode native FLAC streams.
cannam@90 1009 *
cannam@90 1010 * This flavor of initialization sets up the decoder to decode from a
cannam@90 1011 * native FLAC stream. I/O is performed via callbacks to the client.
cannam@90 1012 * For decoding from a plain file via filename or open FILE*,
cannam@90 1013 * FLAC__stream_decoder_init_file() and FLAC__stream_decoder_init_FILE()
cannam@90 1014 * provide a simpler interface.
cannam@90 1015 *
cannam@90 1016 * This function should be called after FLAC__stream_decoder_new() and
cannam@90 1017 * FLAC__stream_decoder_set_*() but before any of the
cannam@90 1018 * FLAC__stream_decoder_process_*() functions. Will set and return the
cannam@90 1019 * decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
cannam@90 1020 * if initialization succeeded.
cannam@90 1021 *
cannam@90 1022 * \param decoder An uninitialized decoder instance.
cannam@90 1023 * \param read_callback See FLAC__StreamDecoderReadCallback. This
cannam@90 1024 * pointer must not be \c NULL.
cannam@90 1025 * \param seek_callback See FLAC__StreamDecoderSeekCallback. This
cannam@90 1026 * pointer may be \c NULL if seeking is not
cannam@90 1027 * supported. If \a seek_callback is not \c NULL then a
cannam@90 1028 * \a tell_callback, \a length_callback, and \a eof_callback must also be supplied.
cannam@90 1029 * Alternatively, a dummy seek callback that just
cannam@90 1030 * returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
cannam@90 1031 * may also be supplied, all though this is slightly
cannam@90 1032 * less efficient for the decoder.
cannam@90 1033 * \param tell_callback See FLAC__StreamDecoderTellCallback. This
cannam@90 1034 * pointer may be \c NULL if not supported by the client. If
cannam@90 1035 * \a seek_callback is not \c NULL then a
cannam@90 1036 * \a tell_callback must also be supplied.
cannam@90 1037 * Alternatively, a dummy tell callback that just
cannam@90 1038 * returns \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
cannam@90 1039 * may also be supplied, all though this is slightly
cannam@90 1040 * less efficient for the decoder.
cannam@90 1041 * \param length_callback See FLAC__StreamDecoderLengthCallback. This
cannam@90 1042 * pointer may be \c NULL if not supported by the client. If
cannam@90 1043 * \a seek_callback is not \c NULL then a
cannam@90 1044 * \a length_callback must also be supplied.
cannam@90 1045 * Alternatively, a dummy length callback that just
cannam@90 1046 * returns \c FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
cannam@90 1047 * may also be supplied, all though this is slightly
cannam@90 1048 * less efficient for the decoder.
cannam@90 1049 * \param eof_callback See FLAC__StreamDecoderEofCallback. This
cannam@90 1050 * pointer may be \c NULL if not supported by the client. If
cannam@90 1051 * \a seek_callback is not \c NULL then a
cannam@90 1052 * \a eof_callback must also be supplied.
cannam@90 1053 * Alternatively, a dummy length callback that just
cannam@90 1054 * returns \c false
cannam@90 1055 * may also be supplied, all though this is slightly
cannam@90 1056 * less efficient for the decoder.
cannam@90 1057 * \param write_callback See FLAC__StreamDecoderWriteCallback. This
cannam@90 1058 * pointer must not be \c NULL.
cannam@90 1059 * \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This
cannam@90 1060 * pointer may be \c NULL if the callback is not
cannam@90 1061 * desired.
cannam@90 1062 * \param error_callback See FLAC__StreamDecoderErrorCallback. This
cannam@90 1063 * pointer must not be \c NULL.
cannam@90 1064 * \param client_data This value will be supplied to callbacks in their
cannam@90 1065 * \a client_data argument.
cannam@90 1066 * \assert
cannam@90 1067 * \code decoder != NULL \endcode
cannam@90 1068 * \retval FLAC__StreamDecoderInitStatus
cannam@90 1069 * \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
cannam@90 1070 * see FLAC__StreamDecoderInitStatus for the meanings of other return values.
cannam@90 1071 */
cannam@90 1072 FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_stream(
cannam@90 1073 FLAC__StreamDecoder *decoder,
cannam@90 1074 FLAC__StreamDecoderReadCallback read_callback,
cannam@90 1075 FLAC__StreamDecoderSeekCallback seek_callback,
cannam@90 1076 FLAC__StreamDecoderTellCallback tell_callback,
cannam@90 1077 FLAC__StreamDecoderLengthCallback length_callback,
cannam@90 1078 FLAC__StreamDecoderEofCallback eof_callback,
cannam@90 1079 FLAC__StreamDecoderWriteCallback write_callback,
cannam@90 1080 FLAC__StreamDecoderMetadataCallback metadata_callback,
cannam@90 1081 FLAC__StreamDecoderErrorCallback error_callback,
cannam@90 1082 void *client_data
cannam@90 1083 );
cannam@90 1084
cannam@90 1085 /** Initialize the decoder instance to decode Ogg FLAC streams.
cannam@90 1086 *
cannam@90 1087 * This flavor of initialization sets up the decoder to decode from a
cannam@90 1088 * FLAC stream in an Ogg container. I/O is performed via callbacks to the
cannam@90 1089 * client. For decoding from a plain file via filename or open FILE*,
cannam@90 1090 * FLAC__stream_decoder_init_ogg_file() and FLAC__stream_decoder_init_ogg_FILE()
cannam@90 1091 * provide a simpler interface.
cannam@90 1092 *
cannam@90 1093 * This function should be called after FLAC__stream_decoder_new() and
cannam@90 1094 * FLAC__stream_decoder_set_*() but before any of the
cannam@90 1095 * FLAC__stream_decoder_process_*() functions. Will set and return the
cannam@90 1096 * decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
cannam@90 1097 * if initialization succeeded.
cannam@90 1098 *
cannam@90 1099 * \note Support for Ogg FLAC in the library is optional. If this
cannam@90 1100 * library has been built without support for Ogg FLAC, this function
cannam@90 1101 * will return \c FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER.
cannam@90 1102 *
cannam@90 1103 * \param decoder An uninitialized decoder instance.
cannam@90 1104 * \param read_callback See FLAC__StreamDecoderReadCallback. This
cannam@90 1105 * pointer must not be \c NULL.
cannam@90 1106 * \param seek_callback See FLAC__StreamDecoderSeekCallback. This
cannam@90 1107 * pointer may be \c NULL if seeking is not
cannam@90 1108 * supported. If \a seek_callback is not \c NULL then a
cannam@90 1109 * \a tell_callback, \a length_callback, and \a eof_callback must also be supplied.
cannam@90 1110 * Alternatively, a dummy seek callback that just
cannam@90 1111 * returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
cannam@90 1112 * may also be supplied, all though this is slightly
cannam@90 1113 * less efficient for the decoder.
cannam@90 1114 * \param tell_callback See FLAC__StreamDecoderTellCallback. This
cannam@90 1115 * pointer may be \c NULL if not supported by the client. If
cannam@90 1116 * \a seek_callback is not \c NULL then a
cannam@90 1117 * \a tell_callback must also be supplied.
cannam@90 1118 * Alternatively, a dummy tell callback that just
cannam@90 1119 * returns \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
cannam@90 1120 * may also be supplied, all though this is slightly
cannam@90 1121 * less efficient for the decoder.
cannam@90 1122 * \param length_callback See FLAC__StreamDecoderLengthCallback. This
cannam@90 1123 * pointer may be \c NULL if not supported by the client. If
cannam@90 1124 * \a seek_callback is not \c NULL then a
cannam@90 1125 * \a length_callback must also be supplied.
cannam@90 1126 * Alternatively, a dummy length callback that just
cannam@90 1127 * returns \c FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
cannam@90 1128 * may also be supplied, all though this is slightly
cannam@90 1129 * less efficient for the decoder.
cannam@90 1130 * \param eof_callback See FLAC__StreamDecoderEofCallback. This
cannam@90 1131 * pointer may be \c NULL if not supported by the client. If
cannam@90 1132 * \a seek_callback is not \c NULL then a
cannam@90 1133 * \a eof_callback must also be supplied.
cannam@90 1134 * Alternatively, a dummy length callback that just
cannam@90 1135 * returns \c false
cannam@90 1136 * may also be supplied, all though this is slightly
cannam@90 1137 * less efficient for the decoder.
cannam@90 1138 * \param write_callback See FLAC__StreamDecoderWriteCallback. This
cannam@90 1139 * pointer must not be \c NULL.
cannam@90 1140 * \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This
cannam@90 1141 * pointer may be \c NULL if the callback is not
cannam@90 1142 * desired.
cannam@90 1143 * \param error_callback See FLAC__StreamDecoderErrorCallback. This
cannam@90 1144 * pointer must not be \c NULL.
cannam@90 1145 * \param client_data This value will be supplied to callbacks in their
cannam@90 1146 * \a client_data argument.
cannam@90 1147 * \assert
cannam@90 1148 * \code decoder != NULL \endcode
cannam@90 1149 * \retval FLAC__StreamDecoderInitStatus
cannam@90 1150 * \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
cannam@90 1151 * see FLAC__StreamDecoderInitStatus for the meanings of other return values.
cannam@90 1152 */
cannam@90 1153 FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_stream(
cannam@90 1154 FLAC__StreamDecoder *decoder,
cannam@90 1155 FLAC__StreamDecoderReadCallback read_callback,
cannam@90 1156 FLAC__StreamDecoderSeekCallback seek_callback,
cannam@90 1157 FLAC__StreamDecoderTellCallback tell_callback,
cannam@90 1158 FLAC__StreamDecoderLengthCallback length_callback,
cannam@90 1159 FLAC__StreamDecoderEofCallback eof_callback,
cannam@90 1160 FLAC__StreamDecoderWriteCallback write_callback,
cannam@90 1161 FLAC__StreamDecoderMetadataCallback metadata_callback,
cannam@90 1162 FLAC__StreamDecoderErrorCallback error_callback,
cannam@90 1163 void *client_data
cannam@90 1164 );
cannam@90 1165
cannam@90 1166 /** Initialize the decoder instance to decode native FLAC files.
cannam@90 1167 *
cannam@90 1168 * This flavor of initialization sets up the decoder to decode from a
cannam@90 1169 * plain native FLAC file. For non-stdio streams, you must use
cannam@90 1170 * FLAC__stream_decoder_init_stream() and provide callbacks for the I/O.
cannam@90 1171 *
cannam@90 1172 * This function should be called after FLAC__stream_decoder_new() and
cannam@90 1173 * FLAC__stream_decoder_set_*() but before any of the
cannam@90 1174 * FLAC__stream_decoder_process_*() functions. Will set and return the
cannam@90 1175 * decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
cannam@90 1176 * if initialization succeeded.
cannam@90 1177 *
cannam@90 1178 * \param decoder An uninitialized decoder instance.
cannam@90 1179 * \param file An open FLAC file. The file should have been
cannam@90 1180 * opened with mode \c "rb" and rewound. The file
cannam@90 1181 * becomes owned by the decoder and should not be
cannam@90 1182 * manipulated by the client while decoding.
cannam@90 1183 * Unless \a file is \c stdin, it will be closed
cannam@90 1184 * when FLAC__stream_decoder_finish() is called.
cannam@90 1185 * Note however that seeking will not work when
cannam@90 1186 * decoding from \c stdout since it is not seekable.
cannam@90 1187 * \param write_callback See FLAC__StreamDecoderWriteCallback. This
cannam@90 1188 * pointer must not be \c NULL.
cannam@90 1189 * \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This
cannam@90 1190 * pointer may be \c NULL if the callback is not
cannam@90 1191 * desired.
cannam@90 1192 * \param error_callback See FLAC__StreamDecoderErrorCallback. This
cannam@90 1193 * pointer must not be \c NULL.
cannam@90 1194 * \param client_data This value will be supplied to callbacks in their
cannam@90 1195 * \a client_data argument.
cannam@90 1196 * \assert
cannam@90 1197 * \code decoder != NULL \endcode
cannam@90 1198 * \code file != NULL \endcode
cannam@90 1199 * \retval FLAC__StreamDecoderInitStatus
cannam@90 1200 * \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
cannam@90 1201 * see FLAC__StreamDecoderInitStatus for the meanings of other return values.
cannam@90 1202 */
cannam@90 1203 FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_FILE(
cannam@90 1204 FLAC__StreamDecoder *decoder,
cannam@90 1205 FILE *file,
cannam@90 1206 FLAC__StreamDecoderWriteCallback write_callback,
cannam@90 1207 FLAC__StreamDecoderMetadataCallback metadata_callback,
cannam@90 1208 FLAC__StreamDecoderErrorCallback error_callback,
cannam@90 1209 void *client_data
cannam@90 1210 );
cannam@90 1211
cannam@90 1212 /** Initialize the decoder instance to decode Ogg FLAC files.
cannam@90 1213 *
cannam@90 1214 * This flavor of initialization sets up the decoder to decode from a
cannam@90 1215 * plain Ogg FLAC file. For non-stdio streams, you must use
cannam@90 1216 * FLAC__stream_decoder_init_ogg_stream() and provide callbacks for the I/O.
cannam@90 1217 *
cannam@90 1218 * This function should be called after FLAC__stream_decoder_new() and
cannam@90 1219 * FLAC__stream_decoder_set_*() but before any of the
cannam@90 1220 * FLAC__stream_decoder_process_*() functions. Will set and return the
cannam@90 1221 * decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
cannam@90 1222 * if initialization succeeded.
cannam@90 1223 *
cannam@90 1224 * \note Support for Ogg FLAC in the library is optional. If this
cannam@90 1225 * library has been built without support for Ogg FLAC, this function
cannam@90 1226 * will return \c FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER.
cannam@90 1227 *
cannam@90 1228 * \param decoder An uninitialized decoder instance.
cannam@90 1229 * \param file An open FLAC file. The file should have been
cannam@90 1230 * opened with mode \c "rb" and rewound. The file
cannam@90 1231 * becomes owned by the decoder and should not be
cannam@90 1232 * manipulated by the client while decoding.
cannam@90 1233 * Unless \a file is \c stdin, it will be closed
cannam@90 1234 * when FLAC__stream_decoder_finish() is called.
cannam@90 1235 * Note however that seeking will not work when
cannam@90 1236 * decoding from \c stdout since it is not seekable.
cannam@90 1237 * \param write_callback See FLAC__StreamDecoderWriteCallback. This
cannam@90 1238 * pointer must not be \c NULL.
cannam@90 1239 * \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This
cannam@90 1240 * pointer may be \c NULL if the callback is not
cannam@90 1241 * desired.
cannam@90 1242 * \param error_callback See FLAC__StreamDecoderErrorCallback. This
cannam@90 1243 * pointer must not be \c NULL.
cannam@90 1244 * \param client_data This value will be supplied to callbacks in their
cannam@90 1245 * \a client_data argument.
cannam@90 1246 * \assert
cannam@90 1247 * \code decoder != NULL \endcode
cannam@90 1248 * \code file != NULL \endcode
cannam@90 1249 * \retval FLAC__StreamDecoderInitStatus
cannam@90 1250 * \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
cannam@90 1251 * see FLAC__StreamDecoderInitStatus for the meanings of other return values.
cannam@90 1252 */
cannam@90 1253 FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_FILE(
cannam@90 1254 FLAC__StreamDecoder *decoder,
cannam@90 1255 FILE *file,
cannam@90 1256 FLAC__StreamDecoderWriteCallback write_callback,
cannam@90 1257 FLAC__StreamDecoderMetadataCallback metadata_callback,
cannam@90 1258 FLAC__StreamDecoderErrorCallback error_callback,
cannam@90 1259 void *client_data
cannam@90 1260 );
cannam@90 1261
cannam@90 1262 /** Initialize the decoder instance to decode native FLAC files.
cannam@90 1263 *
cannam@90 1264 * This flavor of initialization sets up the decoder to decode from a plain
cannam@90 1265 * native FLAC file. If POSIX fopen() semantics are not sufficient, (for
cannam@90 1266 * example, with Unicode filenames on Windows), you must use
cannam@90 1267 * FLAC__stream_decoder_init_FILE(), or FLAC__stream_decoder_init_stream()
cannam@90 1268 * and provide callbacks for the I/O.
cannam@90 1269 *
cannam@90 1270 * This function should be called after FLAC__stream_decoder_new() and
cannam@90 1271 * FLAC__stream_decoder_set_*() but before any of the
cannam@90 1272 * FLAC__stream_decoder_process_*() functions. Will set and return the
cannam@90 1273 * decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
cannam@90 1274 * if initialization succeeded.
cannam@90 1275 *
cannam@90 1276 * \param decoder An uninitialized decoder instance.
cannam@90 1277 * \param filename The name of the file to decode from. The file will
cannam@90 1278 * be opened with fopen(). Use \c NULL to decode from
cannam@90 1279 * \c stdin. Note that \c stdin is not seekable.
cannam@90 1280 * \param write_callback See FLAC__StreamDecoderWriteCallback. This
cannam@90 1281 * pointer must not be \c NULL.
cannam@90 1282 * \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This
cannam@90 1283 * pointer may be \c NULL if the callback is not
cannam@90 1284 * desired.
cannam@90 1285 * \param error_callback See FLAC__StreamDecoderErrorCallback. This
cannam@90 1286 * pointer must not be \c NULL.
cannam@90 1287 * \param client_data This value will be supplied to callbacks in their
cannam@90 1288 * \a client_data argument.
cannam@90 1289 * \assert
cannam@90 1290 * \code decoder != NULL \endcode
cannam@90 1291 * \retval FLAC__StreamDecoderInitStatus
cannam@90 1292 * \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
cannam@90 1293 * see FLAC__StreamDecoderInitStatus for the meanings of other return values.
cannam@90 1294 */
cannam@90 1295 FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_file(
cannam@90 1296 FLAC__StreamDecoder *decoder,
cannam@90 1297 const char *filename,
cannam@90 1298 FLAC__StreamDecoderWriteCallback write_callback,
cannam@90 1299 FLAC__StreamDecoderMetadataCallback metadata_callback,
cannam@90 1300 FLAC__StreamDecoderErrorCallback error_callback,
cannam@90 1301 void *client_data
cannam@90 1302 );
cannam@90 1303
cannam@90 1304 /** Initialize the decoder instance to decode Ogg FLAC files.
cannam@90 1305 *
cannam@90 1306 * This flavor of initialization sets up the decoder to decode from a plain
cannam@90 1307 * Ogg FLAC file. If POSIX fopen() semantics are not sufficient, (for
cannam@90 1308 * example, with Unicode filenames on Windows), you must use
cannam@90 1309 * FLAC__stream_decoder_init_ogg_FILE(), or FLAC__stream_decoder_init_ogg_stream()
cannam@90 1310 * and provide callbacks for the I/O.
cannam@90 1311 *
cannam@90 1312 * This function should be called after FLAC__stream_decoder_new() and
cannam@90 1313 * FLAC__stream_decoder_set_*() but before any of the
cannam@90 1314 * FLAC__stream_decoder_process_*() functions. Will set and return the
cannam@90 1315 * decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
cannam@90 1316 * if initialization succeeded.
cannam@90 1317 *
cannam@90 1318 * \note Support for Ogg FLAC in the library is optional. If this
cannam@90 1319 * library has been built without support for Ogg FLAC, this function
cannam@90 1320 * will return \c FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER.
cannam@90 1321 *
cannam@90 1322 * \param decoder An uninitialized decoder instance.
cannam@90 1323 * \param filename The name of the file to decode from. The file will
cannam@90 1324 * be opened with fopen(). Use \c NULL to decode from
cannam@90 1325 * \c stdin. Note that \c stdin is not seekable.
cannam@90 1326 * \param write_callback See FLAC__StreamDecoderWriteCallback. This
cannam@90 1327 * pointer must not be \c NULL.
cannam@90 1328 * \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This
cannam@90 1329 * pointer may be \c NULL if the callback is not
cannam@90 1330 * desired.
cannam@90 1331 * \param error_callback See FLAC__StreamDecoderErrorCallback. This
cannam@90 1332 * pointer must not be \c NULL.
cannam@90 1333 * \param client_data This value will be supplied to callbacks in their
cannam@90 1334 * \a client_data argument.
cannam@90 1335 * \assert
cannam@90 1336 * \code decoder != NULL \endcode
cannam@90 1337 * \retval FLAC__StreamDecoderInitStatus
cannam@90 1338 * \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
cannam@90 1339 * see FLAC__StreamDecoderInitStatus for the meanings of other return values.
cannam@90 1340 */
cannam@90 1341 FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_file(
cannam@90 1342 FLAC__StreamDecoder *decoder,
cannam@90 1343 const char *filename,
cannam@90 1344 FLAC__StreamDecoderWriteCallback write_callback,
cannam@90 1345 FLAC__StreamDecoderMetadataCallback metadata_callback,
cannam@90 1346 FLAC__StreamDecoderErrorCallback error_callback,
cannam@90 1347 void *client_data
cannam@90 1348 );
cannam@90 1349
cannam@90 1350 /** Finish the decoding process.
cannam@90 1351 * Flushes the decoding buffer, releases resources, resets the decoder
cannam@90 1352 * settings to their defaults, and returns the decoder state to
cannam@90 1353 * FLAC__STREAM_DECODER_UNINITIALIZED.
cannam@90 1354 *
cannam@90 1355 * In the event of a prematurely-terminated decode, it is not strictly
cannam@90 1356 * necessary to call this immediately before FLAC__stream_decoder_delete()
cannam@90 1357 * but it is good practice to match every FLAC__stream_decoder_init_*()
cannam@90 1358 * with a FLAC__stream_decoder_finish().
cannam@90 1359 *
cannam@90 1360 * \param decoder An uninitialized decoder instance.
cannam@90 1361 * \assert
cannam@90 1362 * \code decoder != NULL \endcode
cannam@90 1363 * \retval FLAC__bool
cannam@90 1364 * \c false if MD5 checking is on AND a STREAMINFO block was available
cannam@90 1365 * AND the MD5 signature in the STREAMINFO block was non-zero AND the
cannam@90 1366 * signature does not match the one computed by the decoder; else
cannam@90 1367 * \c true.
cannam@90 1368 */
cannam@90 1369 FLAC_API FLAC__bool FLAC__stream_decoder_finish(FLAC__StreamDecoder *decoder);
cannam@90 1370
cannam@90 1371 /** Flush the stream input.
cannam@90 1372 * The decoder's input buffer will be cleared and the state set to
cannam@90 1373 * \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC. This will also turn
cannam@90 1374 * off MD5 checking.
cannam@90 1375 *
cannam@90 1376 * \param decoder A decoder instance.
cannam@90 1377 * \assert
cannam@90 1378 * \code decoder != NULL \endcode
cannam@90 1379 * \retval FLAC__bool
cannam@90 1380 * \c true if successful, else \c false if a memory allocation
cannam@90 1381 * error occurs (in which case the state will be set to
cannam@90 1382 * \c FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR).
cannam@90 1383 */
cannam@90 1384 FLAC_API FLAC__bool FLAC__stream_decoder_flush(FLAC__StreamDecoder *decoder);
cannam@90 1385
cannam@90 1386 /** Reset the decoding process.
cannam@90 1387 * The decoder's input buffer will be cleared and the state set to
cannam@90 1388 * \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA. This is similar to
cannam@90 1389 * FLAC__stream_decoder_finish() except that the settings are
cannam@90 1390 * preserved; there is no need to call FLAC__stream_decoder_init_*()
cannam@90 1391 * before decoding again. MD5 checking will be restored to its original
cannam@90 1392 * setting.
cannam@90 1393 *
cannam@90 1394 * If the decoder is seekable, or was initialized with
cannam@90 1395 * FLAC__stream_decoder_init*_FILE() or FLAC__stream_decoder_init*_file(),
cannam@90 1396 * the decoder will also attempt to seek to the beginning of the file.
cannam@90 1397 * If this rewind fails, this function will return \c false. It follows
cannam@90 1398 * that FLAC__stream_decoder_reset() cannot be used when decoding from
cannam@90 1399 * \c stdin.
cannam@90 1400 *
cannam@90 1401 * If the decoder was initialized with FLAC__stream_encoder_init*_stream()
cannam@90 1402 * and is not seekable (i.e. no seek callback was provided or the seek
cannam@90 1403 * callback returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED), it
cannam@90 1404 * is the duty of the client to start feeding data from the beginning of
cannam@90 1405 * the stream on the next FLAC__stream_decoder_process() or
cannam@90 1406 * FLAC__stream_decoder_process_interleaved() call.
cannam@90 1407 *
cannam@90 1408 * \param decoder A decoder instance.
cannam@90 1409 * \assert
cannam@90 1410 * \code decoder != NULL \endcode
cannam@90 1411 * \retval FLAC__bool
cannam@90 1412 * \c true if successful, else \c false if a memory allocation occurs
cannam@90 1413 * (in which case the state will be set to
cannam@90 1414 * \c FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR) or a seek error
cannam@90 1415 * occurs (the state will be unchanged).
cannam@90 1416 */
cannam@90 1417 FLAC_API FLAC__bool FLAC__stream_decoder_reset(FLAC__StreamDecoder *decoder);
cannam@90 1418
cannam@90 1419 /** Decode one metadata block or audio frame.
cannam@90 1420 * This version instructs the decoder to decode a either a single metadata
cannam@90 1421 * block or a single frame and stop, unless the callbacks return a fatal
cannam@90 1422 * error or the read callback returns
cannam@90 1423 * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
cannam@90 1424 *
cannam@90 1425 * As the decoder needs more input it will call the read callback.
cannam@90 1426 * Depending on what was decoded, the metadata or write callback will be
cannam@90 1427 * called with the decoded metadata block or audio frame.
cannam@90 1428 *
cannam@90 1429 * Unless there is a fatal read error or end of stream, this function
cannam@90 1430 * will return once one whole frame is decoded. In other words, if the
cannam@90 1431 * stream is not synchronized or points to a corrupt frame header, the
cannam@90 1432 * decoder will continue to try and resync until it gets to a valid
cannam@90 1433 * frame, then decode one frame, then return. If the decoder points to
cannam@90 1434 * a frame whose frame CRC in the frame footer does not match the
cannam@90 1435 * computed frame CRC, this function will issue a
cannam@90 1436 * FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH error to the
cannam@90 1437 * error callback, and return, having decoded one complete, although
cannam@90 1438 * corrupt, frame. (Such corrupted frames are sent as silence of the
cannam@90 1439 * correct length to the write callback.)
cannam@90 1440 *
cannam@90 1441 * \param decoder An initialized decoder instance.
cannam@90 1442 * \assert
cannam@90 1443 * \code decoder != NULL \endcode
cannam@90 1444 * \retval FLAC__bool
cannam@90 1445 * \c false if any fatal read, write, or memory allocation error
cannam@90 1446 * occurred (meaning decoding must stop), else \c true; for more
cannam@90 1447 * information about the decoder, check the decoder state with
cannam@90 1448 * FLAC__stream_decoder_get_state().
cannam@90 1449 */
cannam@90 1450 FLAC_API FLAC__bool FLAC__stream_decoder_process_single(FLAC__StreamDecoder *decoder);
cannam@90 1451
cannam@90 1452 /** Decode until the end of the metadata.
cannam@90 1453 * This version instructs the decoder to decode from the current position
cannam@90 1454 * and continue until all the metadata has been read, or until the
cannam@90 1455 * callbacks return a fatal error or the read callback returns
cannam@90 1456 * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
cannam@90 1457 *
cannam@90 1458 * As the decoder needs more input it will call the read callback.
cannam@90 1459 * As each metadata block is decoded, the metadata callback will be called
cannam@90 1460 * with the decoded metadata.
cannam@90 1461 *
cannam@90 1462 * \param decoder An initialized decoder instance.
cannam@90 1463 * \assert
cannam@90 1464 * \code decoder != NULL \endcode
cannam@90 1465 * \retval FLAC__bool
cannam@90 1466 * \c false if any fatal read, write, or memory allocation error
cannam@90 1467 * occurred (meaning decoding must stop), else \c true; for more
cannam@90 1468 * information about the decoder, check the decoder state with
cannam@90 1469 * FLAC__stream_decoder_get_state().
cannam@90 1470 */
cannam@90 1471 FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_metadata(FLAC__StreamDecoder *decoder);
cannam@90 1472
cannam@90 1473 /** Decode until the end of the stream.
cannam@90 1474 * This version instructs the decoder to decode from the current position
cannam@90 1475 * and continue until the end of stream (the read callback returns
cannam@90 1476 * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM), or until the
cannam@90 1477 * callbacks return a fatal error.
cannam@90 1478 *
cannam@90 1479 * As the decoder needs more input it will call the read callback.
cannam@90 1480 * As each metadata block and frame is decoded, the metadata or write
cannam@90 1481 * callback will be called with the decoded metadata or frame.
cannam@90 1482 *
cannam@90 1483 * \param decoder An initialized decoder instance.
cannam@90 1484 * \assert
cannam@90 1485 * \code decoder != NULL \endcode
cannam@90 1486 * \retval FLAC__bool
cannam@90 1487 * \c false if any fatal read, write, or memory allocation error
cannam@90 1488 * occurred (meaning decoding must stop), else \c true; for more
cannam@90 1489 * information about the decoder, check the decoder state with
cannam@90 1490 * FLAC__stream_decoder_get_state().
cannam@90 1491 */
cannam@90 1492 FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_stream(FLAC__StreamDecoder *decoder);
cannam@90 1493
cannam@90 1494 /** Skip one audio frame.
cannam@90 1495 * This version instructs the decoder to 'skip' a single frame and stop,
cannam@90 1496 * unless the callbacks return a fatal error or the read callback returns
cannam@90 1497 * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
cannam@90 1498 *
cannam@90 1499 * The decoding flow is the same as what occurs when
cannam@90 1500 * FLAC__stream_decoder_process_single() is called to process an audio
cannam@90 1501 * frame, except that this function does not decode the parsed data into
cannam@90 1502 * PCM or call the write callback. The integrity of the frame is still
cannam@90 1503 * checked the same way as in the other process functions.
cannam@90 1504 *
cannam@90 1505 * This function will return once one whole frame is skipped, in the
cannam@90 1506 * same way that FLAC__stream_decoder_process_single() will return once
cannam@90 1507 * one whole frame is decoded.
cannam@90 1508 *
cannam@90 1509 * This function can be used in more quickly determining FLAC frame
cannam@90 1510 * boundaries when decoding of the actual data is not needed, for
cannam@90 1511 * example when an application is separating a FLAC stream into frames
cannam@90 1512 * for editing or storing in a container. To do this, the application
cannam@90 1513 * can use FLAC__stream_decoder_skip_single_frame() to quickly advance
cannam@90 1514 * to the next frame, then use
cannam@90 1515 * FLAC__stream_decoder_get_decode_position() to find the new frame
cannam@90 1516 * boundary.
cannam@90 1517 *
cannam@90 1518 * This function should only be called when the stream has advanced
cannam@90 1519 * past all the metadata, otherwise it will return \c false.
cannam@90 1520 *
cannam@90 1521 * \param decoder An initialized decoder instance not in a metadata
cannam@90 1522 * state.
cannam@90 1523 * \assert
cannam@90 1524 * \code decoder != NULL \endcode
cannam@90 1525 * \retval FLAC__bool
cannam@90 1526 * \c false if any fatal read, write, or memory allocation error
cannam@90 1527 * occurred (meaning decoding must stop), or if the decoder
cannam@90 1528 * is in the FLAC__STREAM_DECODER_SEARCH_FOR_METADATA or
cannam@90 1529 * FLAC__STREAM_DECODER_READ_METADATA state, else \c true; for more
cannam@90 1530 * information about the decoder, check the decoder state with
cannam@90 1531 * FLAC__stream_decoder_get_state().
cannam@90 1532 */
cannam@90 1533 FLAC_API FLAC__bool FLAC__stream_decoder_skip_single_frame(FLAC__StreamDecoder *decoder);
cannam@90 1534
cannam@90 1535 /** Flush the input and seek to an absolute sample.
cannam@90 1536 * Decoding will resume at the given sample. Note that because of
cannam@90 1537 * this, the next write callback may contain a partial block. The
cannam@90 1538 * client must support seeking the input or this function will fail
cannam@90 1539 * and return \c false. Furthermore, if the decoder state is
cannam@90 1540 * \c FLAC__STREAM_DECODER_SEEK_ERROR, then the decoder must be flushed
cannam@90 1541 * with FLAC__stream_decoder_flush() or reset with
cannam@90 1542 * FLAC__stream_decoder_reset() before decoding can continue.
cannam@90 1543 *
cannam@90 1544 * \param decoder A decoder instance.
cannam@90 1545 * \param sample The target sample number to seek to.
cannam@90 1546 * \assert
cannam@90 1547 * \code decoder != NULL \endcode
cannam@90 1548 * \retval FLAC__bool
cannam@90 1549 * \c true if successful, else \c false.
cannam@90 1550 */
cannam@90 1551 FLAC_API FLAC__bool FLAC__stream_decoder_seek_absolute(FLAC__StreamDecoder *decoder, FLAC__uint64 sample);
cannam@90 1552
cannam@90 1553 /* \} */
cannam@90 1554
cannam@90 1555 #ifdef __cplusplus
cannam@90 1556 }
cannam@90 1557 #endif
cannam@90 1558
cannam@90 1559 #endif