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