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