← Back to branch summary

~ubuntu-branches/ubuntu/raring/flac/raring

« back to all changes in this revision

Viewing changes to include/FLAC/stream_decoder.h

  • Committer: Bazaar Package Importer
  • Author(s): Joshua Kwan
  • Date: 2007-05-29 22:56:36 UTC
  • mfrom: (1.1.4 upstream)
  • Revision ID: james.westby@ubuntu.com-20070529225636-ljeff8xxip09qaap
Tags: 1.1.4-1
http://bugs.debian.org/405167
http://bugs.debian.org/411311
* New upstream release. closes: #405167, #411311
  - libOggFLAC and libOggFLAC++ have been merged into libFLAC, so
    remove their corresponding packages.
  - Because of the API changes required to effect the above, there has
    been yet another soname bump. libflac7 -> libflac8 and
    libflac++5 -> libflac++6. Emails have been dispatched to the
    maintainers of dependent packages.
* Some notes on patches that were removed:
  - 02_stdin_stdout, 06_manpage_mention_utf8_convert: merged upstream
  - 08_manpage_warnings: Upstream has changed the manpage so it defintely
    can't fit in in 80 cols, so just forget about it. We'll live.
  - 05_eof_warnings_are_errors: Upstream decided to add a -w option to
    flac to treat all warnings as errors. I am going to defer to that
    for now, but if people think it's stupid let me know and I'll port
    the patch forward.
  - 04_stack_smasher: was a backport from 1.1.3, so it's obsolete.

Show diffs side-by-side

added added

removed removed

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