add 2005 to copyright notices
[flac.git] / include / FLAC / file_decoder.h
1 /* libFLAC - Free Lossless Audio Codec library
2  * Copyright (C) 2000,2001,2002,2003,2004,2005  Josh Coalson
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions
6  * are met:
7  *
8  * - Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  *
11  * - Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in the
13  * documentation and/or other materials provided with the distribution.
14  *
15  * - Neither the name of the Xiph.org Foundation nor the names of its
16  * contributors may be used to endorse or promote products derived from
17  * this software without specific prior written permission.
18  *
19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22  * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
23  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
24  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
25  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
26  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
27  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
28  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
29  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30  */
31
32 #ifndef FLAC__FILE_DECODER_H
33 #define FLAC__FILE_DECODER_H
34
35 #include "export.h"
36 #include "seekable_stream_decoder.h"
37
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41
42
43 /** \file include/FLAC/file_decoder.h
44  *
45  *  \brief
46  *  This module contains the functions which implement the file
47  *  decoder.
48  *
49  *  See the detailed documentation in the
50  *  \link flac_file_decoder file decoder \endlink module.
51  */
52
53 /** \defgroup flac_file_decoder FLAC/file_decoder.h: file decoder interface
54  *  \ingroup flac_decoder
55  *
56  *  \brief
57  *  This module contains the functions which implement the file
58  *  decoder.
59  *
60  * The basic usage of this decoder is as follows:
61  * - The program creates an instance of a decoder using
62  *   FLAC__file_decoder_new().
63  * - The program overrides the default settings and sets callbacks for
64  *   writing, error reporting, and metadata reporting using
65  *   FLAC__file_decoder_set_*() functions.
66  * - The program initializes the instance to validate the settings and
67  *   prepare for decoding using FLAC__file_decoder_init().
68  * - The program calls the FLAC__file_decoder_process_*() functions
69  *   to decode data, which subsequently calls the callbacks.
70  * - The program finishes the decoding with FLAC__file_decoder_finish(),
71  *   which flushes the input and output and resets the decoder to the
72  *   uninitialized state.
73  * - The instance may be used again or deleted with
74  *   FLAC__file_decoder_delete().
75  *
76  * The file decoder is a trivial wrapper around the
77  * \link flac_seekable_stream_decoder seekable stream decoder \endlink
78  * meant to simplfy the process of decoding from a standard file.  The
79  * file decoder supplies all but the Write/Metadata/Error callbacks.
80  * The user needs only to provide the path to the file and the file
81  * decoder handles the rest.
82  *
83  * Like the seekable stream decoder, seeking is exposed through the
84  * FLAC__file_decoder_seek_absolute() method.  At any point after the file
85  * decoder has been initialized, the user can call this function to seek to
86  * an exact sample within the file.  Subsequently, the first time the write
87  * callback is called it will be passed a (possibly partial) block starting
88  * at that sample.
89  *
90  * The file decoder also inherits MD5 signature checking from the seekable
91  * stream decoder.  If this is turned on before initialization,
92  * FLAC__file_decoder_finish() will report when the decoded MD5 signature
93  * does not match the one stored in the STREAMINFO block.  MD5 checking is
94  * automatically turned off if there is no signature in the STREAMINFO
95  * block or when a seek is attempted.
96  *
97  * Make sure to read the detailed descriptions of the
98  * \link flac_seekable_stream_decoder seekable stream decoder module \endlink
99  * and \link flac_stream_decoder stream decoder module \endlink
100  * since the file decoder inherits much of its behavior from them.
101  *
102  * \note
103  * The "set" functions may only be called when the decoder is in the
104  * state FLAC__FILE_DECODER_UNINITIALIZED, i.e. after
105  * FLAC__file_decoder_new() or FLAC__file_decoder_finish(), but
106  * before FLAC__file_decoder_init().  If this is the case they will
107  * return \c true, otherwise \c false.
108  *
109  * \note
110  * FLAC__file_decoder_finish() resets all settings to the constructor
111  * defaults, including the callbacks.
112  *
113  * \{
114  */
115
116
117 /** State values for a FLAC__FileDecoder
118  *
119  *  The decoder's state can be obtained by calling FLAC__file_decoder_get_state().
120  */
121 typedef enum {
122
123         FLAC__FILE_DECODER_OK = 0,
124         /**< The decoder is in the normal OK state. */
125
126         FLAC__FILE_DECODER_END_OF_FILE,
127         /**< The decoder has reached the end of the file. */
128
129         FLAC__FILE_DECODER_ERROR_OPENING_FILE,
130         /**< An error occurred opening the input file. */
131
132         FLAC__FILE_DECODER_MEMORY_ALLOCATION_ERROR,
133         /**< An error occurred allocating memory. */
134
135         FLAC__FILE_DECODER_SEEK_ERROR,
136         /**< An error occurred while seeking. */
137
138         FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR,
139         /**< An error occurred in the underlying seekable stream decoder. */
140
141         FLAC__FILE_DECODER_ALREADY_INITIALIZED,
142         /**< FLAC__file_decoder_init() was called when the decoder was already
143          * initialized, usually because FLAC__file_decoder_finish() was not
144          * called.
145          */
146
147         FLAC__FILE_DECODER_INVALID_CALLBACK,
148         /**< FLAC__file_decoder_init() was called without all callbacks
149          * being set.
150          */
151
152         FLAC__FILE_DECODER_UNINITIALIZED
153         /**< The decoder is in the uninitialized state. */
154
155 } FLAC__FileDecoderState;
156
157 /** Maps a FLAC__FileDecoderState to a C string.
158  *
159  *  Using a FLAC__FileDecoderState as the index to this array
160  *  will give the string equivalent.  The contents should not be modified.
161  */
162 extern FLAC_API const char * const FLAC__FileDecoderStateString[];
163
164
165 /***********************************************************************
166  *
167  * class FLAC__FileDecoder : public FLAC__StreamDecoder
168  *
169  ***********************************************************************/
170
171 struct FLAC__FileDecoderProtected;
172 struct FLAC__FileDecoderPrivate;
173 /** The opaque structure definition for the file decoder type.  See the
174  *  \link flac_file_decoder file decoder module \endlink for a detailed
175  *  description.
176  */
177 typedef struct {
178         struct FLAC__FileDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
179         struct FLAC__FileDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
180 } FLAC__FileDecoder;
181
182 /** Signature for the write callback.
183  *  See FLAC__file_decoder_set_write_callback()
184  *  and FLAC__SeekableStreamDecoderWriteCallback for more info.
185  *
186  * \param  decoder  The decoder instance calling the callback.
187  * \param  frame    The description of the decoded frame.
188  * \param  buffer   An array of pointers to decoded channels of data.
189  * \param  client_data  The callee's client data set through
190  *                      FLAC__file_decoder_set_client_data().
191  * \retval FLAC__StreamDecoderWriteStatus
192  *    The callee's return status.
193  */
194 typedef FLAC__StreamDecoderWriteStatus (*FLAC__FileDecoderWriteCallback)(const FLAC__FileDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
195
196 /** Signature for the metadata callback.
197  *  See FLAC__file_decoder_set_metadata_callback()
198  *  and FLAC__SeekableStreamDecoderMetadataCallback for more info.
199  *
200  * \param  decoder  The decoder instance calling the callback.
201  * \param  metadata The decoded metadata block.
202  * \param  client_data  The callee's client data set through
203  *                      FLAC__file_decoder_set_client_data().
204  */
205 typedef void (*FLAC__FileDecoderMetadataCallback)(const FLAC__FileDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
206
207 /** Signature for the error callback.
208  *  See FLAC__file_decoder_set_error_callback()
209  *  and FLAC__SeekableStreamDecoderErrorCallback for more info.
210  *
211  * \param  decoder  The decoder instance calling the callback.
212  * \param  status   The error encountered by the decoder.
213  * \param  client_data  The callee's client data set through
214  *                      FLAC__file_decoder_set_client_data().
215  */
216 typedef void (*FLAC__FileDecoderErrorCallback)(const FLAC__FileDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
217
218
219 /***********************************************************************
220  *
221  * Class constructor/destructor
222  *
223  ***********************************************************************/
224
225 /** Create a new file decoder instance.  The instance is created with
226  *  default settings; see the individual FLAC__file_decoder_set_*()
227  *  functions for each setting's default.
228  *
229  * \retval FLAC__FileDecoder*
230  *    \c NULL if there was an error allocating memory, else the new instance.
231  */
232 FLAC_API FLAC__FileDecoder *FLAC__file_decoder_new();
233
234 /** Free a decoder instance.  Deletes the object pointed to by \a decoder.
235  *
236  * \param decoder  A pointer to an existing decoder.
237  * \assert
238  *    \code decoder != NULL \endcode
239  */
240 FLAC_API void FLAC__file_decoder_delete(FLAC__FileDecoder *decoder);
241
242
243 /***********************************************************************
244  *
245  * Public class method prototypes
246  *
247  ***********************************************************************/
248
249 /** Set the "MD5 signature checking" flag.
250  *  This is inherited from FLAC__SeekableStreamDecoder; see
251  *  FLAC__seekable_stream_decoder_set_md5_checking().
252  *
253  * \default \c false
254  * \param  decoder  A decoder instance to set.
255  * \param  value    See above.
256  * \assert
257  *    \code decoder != NULL \endcode
258  * \retval FLAC__bool
259  *    \c false if the decoder is already initialized, else \c true.
260  */
261 FLAC_API FLAC__bool FLAC__file_decoder_set_md5_checking(FLAC__FileDecoder *decoder, FLAC__bool value);
262
263 /** Set the input file name to decode.
264  *
265  * \default \c "-"
266  * \param  decoder  A decoder instance to set.
267  * \param  value    The input file name, or "-" for \c stdin.
268  * \assert
269  *    \code decoder != NULL \endcode
270  *    \code value != NULL \endcode
271  * \retval FLAC__bool
272  *    \c false if the decoder is already initialized, or there was a memory
273  *    allocation error, else \c true.
274  */
275 FLAC_API FLAC__bool FLAC__file_decoder_set_filename(FLAC__FileDecoder *decoder, const char *value);
276
277 /** Set the write callback.
278  *  This is inherited from FLAC__SeekableStreamDecoder; see
279  *  FLAC__seekable_stream_decoder_set_write_callback().
280  *
281  * \note
282  * The callback is mandatory and must be set before initialization.
283  *
284  * \default \c NULL
285  * \param  decoder  A decoder instance to set.
286  * \param  value    See above.
287  * \assert
288  *    \code decoder != NULL \endcode
289  *    \code value != NULL \endcode
290  * \retval FLAC__bool
291  *    \c false if the decoder is already initialized, else \c true.
292  */
293 FLAC_API FLAC__bool FLAC__file_decoder_set_write_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderWriteCallback value);
294
295 /** Set the metadata callback.
296  *  This is inherited from FLAC__SeekableStreamDecoder; see
297  *  FLAC__seekable_stream_decoder_set_metadata_callback().
298  *
299  * \note
300  * The callback is mandatory and must be set before initialization.
301  *
302  * \default \c NULL
303  * \param  decoder  A decoder instance to set.
304  * \param  value    See above.
305  * \assert
306  *    \code decoder != NULL \endcode
307  *    \code value != NULL \endcode
308  * \retval FLAC__bool
309  *    \c false if the decoder is already initialized, else \c true.
310  */
311 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderMetadataCallback value);
312
313 /** Set the error callback.
314  *  This is inherited from FLAC__SeekableStreamDecoder; see
315  *  FLAC__seekable_stream_decoder_set_error_callback().
316  *
317  * \note
318  * The callback is mandatory and must be set before initialization.
319  *
320  * \default \c NULL
321  * \param  decoder  A decoder instance to set.
322  * \param  value    See above.
323  * \assert
324  *    \code decoder != NULL \endcode
325  *    \code value != NULL \endcode
326  * \retval FLAC__bool
327  *    \c false if the decoder is already initialized, else \c true.
328  */
329 FLAC_API FLAC__bool FLAC__file_decoder_set_error_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderErrorCallback value);
330
331 /** Set the client data to be passed back to callbacks.
332  *  This value will be supplied to callbacks in their \a client_data
333  *  argument.
334  *
335  * \default \c NULL
336  * \param  decoder  A decoder instance to set.
337  * \param  value    See above.
338  * \assert
339  *    \code decoder != NULL \endcode
340  * \retval FLAC__bool
341  *    \c false if the decoder is already initialized, else \c true.
342  */
343 FLAC_API FLAC__bool FLAC__file_decoder_set_client_data(FLAC__FileDecoder *decoder, void *value);
344
345 /** This is inherited from FLAC__SeekableStreamDecoder; see
346  *  FLAC__seekable_stream_decoder_set_metadata_respond().
347  *
348  * \default By default, only the \c STREAMINFO block is returned via the
349  *          metadata callback.
350  * \param  decoder  A decoder instance to set.
351  * \param  type     See above.
352  * \assert
353  *    \code decoder != NULL \endcode
354  *    \a type is valid
355  * \retval FLAC__bool
356  *    \c false if the decoder is already initialized, else \c true.
357  */
358 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond(FLAC__FileDecoder *decoder, FLAC__MetadataType type);
359
360 /** This is inherited from FLAC__SeekableStreamDecoder; see
361  *  FLAC__seekable_stream_decoder_set_metadata_respond_application().
362  *
363  * \default By default, only the \c STREAMINFO block is returned via the
364  *          metadata callback.
365  * \param  decoder  A decoder instance to set.
366  * \param  id       See above.
367  * \assert
368  *    \code decoder != NULL \endcode
369  *    \code id != NULL \endcode
370  * \retval FLAC__bool
371  *    \c false if the decoder is already initialized, else \c true.
372  */
373 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond_application(FLAC__FileDecoder *decoder, const FLAC__byte id[4]);
374
375 /** This is inherited from FLAC__SeekableStreamDecoder; see
376  *  FLAC__seekable_stream_decoder_set_metadata_respond_all().
377  *
378  * \default By default, only the \c STREAMINFO block is returned via the
379  *          metadata callback.
380  * \param  decoder  A decoder instance to set.
381  * \assert
382  *    \code decoder != NULL \endcode
383  * \retval FLAC__bool
384  *    \c false if the decoder is already initialized, else \c true.
385  */
386 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond_all(FLAC__FileDecoder *decoder);
387
388 /** This is inherited from FLAC__SeekableStreamDecoder; see
389  *  FLAC__seekable_stream_decoder_set_metadata_ignore().
390  *
391  * \default By default, only the \c STREAMINFO block is returned via the
392  *          metadata callback.
393  * \param  decoder  A decoder instance to set.
394  * \param  type     See above.
395  * \assert
396  *    \code decoder != NULL \endcode
397  *    \a type is valid
398  * \retval FLAC__bool
399  *    \c false if the decoder is already initialized, else \c true.
400  */
401 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore(FLAC__FileDecoder *decoder, FLAC__MetadataType type);
402
403 /** This is inherited from FLAC__SeekableStreamDecoder; see
404  *  FLAC__seekable_stream_decoder_set_metadata_ignore_application().
405  *
406  * \default By default, only the \c STREAMINFO block is returned via the
407  *          metadata callback.
408  * \param  decoder  A decoder instance to set.
409  * \param  id       See above.
410  * \assert
411  *    \code decoder != NULL \endcode
412  *    \code id != NULL \endcode
413  * \retval FLAC__bool
414  *    \c false if the decoder is already initialized, else \c true.
415  */
416 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore_application(FLAC__FileDecoder *decoder, const FLAC__byte id[4]);
417
418 /** This is inherited from FLAC__SeekableStreamDecoder; see
419  *  FLAC__seekable_stream_decoder_set_metadata_ignore_all().
420  *
421  * \default By default, only the \c STREAMINFO block is returned via the
422  *          metadata callback.
423  * \param  decoder  A decoder instance to set.
424  * \assert
425  *    \code decoder != NULL \endcode
426  * \retval FLAC__bool
427  *    \c false if the decoder is already initialized, else \c true.
428  */
429 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore_all(FLAC__FileDecoder *decoder);
430
431 /** Get the current decoder state.
432  *
433  * \param  decoder  A decoder instance to query.
434  * \assert
435  *    \code decoder != NULL \endcode
436  * \retval FLAC__FileDecoderState
437  *    The current decoder state.
438  */
439 FLAC_API FLAC__FileDecoderState FLAC__file_decoder_get_state(const FLAC__FileDecoder *decoder);
440
441 /** Get the state of the underlying seekable stream decoder.
442  *  Useful when the file decoder state is
443  *  \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR.
444  *
445  * \param  decoder  A decoder instance to query.
446  * \assert
447  *    \code decoder != NULL \endcode
448  * \retval FLAC__SeekableStreamDecoderState
449  *    The seekable stream decoder state.
450  */
451 FLAC_API FLAC__SeekableStreamDecoderState FLAC__file_decoder_get_seekable_stream_decoder_state(const FLAC__FileDecoder *decoder);
452
453 /** Get the state of the underlying stream decoder.
454  *  Useful when the file decoder state is
455  *  \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR and the seekable stream
456  *  decoder state is \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
457  *
458  * \param  decoder  A decoder instance to query.
459  * \assert
460  *    \code decoder != NULL \endcode
461  * \retval FLAC__StreamDecoderState
462  *    The seekable stream decoder state.
463  */
464 FLAC_API FLAC__StreamDecoderState FLAC__file_decoder_get_stream_decoder_state(const FLAC__FileDecoder *decoder);
465
466 /** Get the current decoder state as a C string.
467  *  This version automatically resolves
468  *  \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR by getting the
469  *  seekable stream decoder's state.
470  *
471  * \param  decoder  A decoder instance to query.
472  * \assert
473  *    \code decoder != NULL \endcode
474  * \retval const char *
475  *    The decoder state as a C string.  Do not modify the contents.
476  */
477 FLAC_API const char *FLAC__file_decoder_get_resolved_state_string(const FLAC__FileDecoder *decoder);
478
479 /** Get the "MD5 signature checking" flag.
480  *  This is inherited from FLAC__SeekableStreamDecoder; see
481  *  FLAC__seekable_stream_decoder_get_md5_checking().
482  *
483  * \param  decoder  A decoder instance to query.
484  * \assert
485  *    \code decoder != NULL \endcode
486  * \retval FLAC__bool
487  *    See above.
488  */
489 FLAC_API FLAC__bool FLAC__file_decoder_get_md5_checking(const FLAC__FileDecoder *decoder);
490
491 /** This is inherited from FLAC__SeekableStreamDecoder; see
492  *  FLAC__seekable_stream_decoder_get_channels().
493  *
494  * \param  decoder  A decoder instance to query.
495  * \assert
496  *    \code decoder != NULL \endcode
497  * \retval unsigned
498  *    See above.
499  */
500 FLAC_API unsigned FLAC__file_decoder_get_channels(const FLAC__FileDecoder *decoder);
501
502 /** This is inherited from FLAC__SeekableStreamDecoder; see
503  *  FLAC__seekable_stream_decoder_get_channel_assignment().
504  *
505  * \param  decoder  A decoder instance to query.
506  * \assert
507  *    \code decoder != NULL \endcode
508  * \retval FLAC__ChannelAssignment
509  *    See above.
510  */
511 FLAC_API FLAC__ChannelAssignment FLAC__file_decoder_get_channel_assignment(const FLAC__FileDecoder *decoder);
512
513 /** This is inherited from FLAC__SeekableStreamDecoder; see
514  *  FLAC__seekable_stream_decoder_get_bits_per_sample().
515  *
516  * \param  decoder  A decoder instance to query.
517  * \assert
518  *    \code decoder != NULL \endcode
519  * \retval unsigned
520  *    See above.
521  */
522 FLAC_API unsigned FLAC__file_decoder_get_bits_per_sample(const FLAC__FileDecoder *decoder);
523
524 /** This is inherited from FLAC__SeekableStreamDecoder; see
525  *  FLAC__seekable_stream_decoder_get_sample_rate().
526  *
527  * \param  decoder  A decoder instance to query.
528  * \assert
529  *    \code decoder != NULL \endcode
530  * \retval unsigned
531  *    See above.
532  */
533 FLAC_API unsigned FLAC__file_decoder_get_sample_rate(const FLAC__FileDecoder *decoder);
534
535 /** This is inherited from FLAC__SeekableStreamDecoder; see
536  *  FLAC__seekable_stream_decoder_get_blocksize().
537  *
538  * \param  decoder  A decoder instance to query.
539  * \assert
540  *    \code decoder != NULL \endcode
541  * \retval unsigned
542  *    See above.
543  */
544 FLAC_API unsigned FLAC__file_decoder_get_blocksize(const FLAC__FileDecoder *decoder);
545
546 /** This is inherited from FLAC__SeekableStreamDecoder; see
547  *  FLAC__seekable_stream_decoder_get_decode_position().
548  *
549  * \param  decoder   A decoder instance to query.
550  * \param  position  Address at which to return the desired position.
551  * \assert
552  *    \code decoder != NULL \endcode
553  *    \code position != NULL \endcode
554  * \retval FLAC__bool
555  *    \c true if successful, \c false if there was an error from
556  *    the 'tell' callback.
557  */
558 FLAC_API FLAC__bool FLAC__file_decoder_get_decode_position(const FLAC__FileDecoder *decoder, FLAC__uint64 *position);
559
560 /** Initialize the decoder instance.
561  *  Should be called after FLAC__file_decoder_new() and
562  *  FLAC__file_decoder_set_*() but before any of the
563  *  FLAC__file_decoder_process_*() functions.  Will set and return
564  *  the decoder state, which will be FLAC__FILE_DECODER_OK if
565  *  initialization succeeded.
566  *
567  * \param  decoder  An uninitialized decoder instance.
568  * \assert
569  *    \code decoder != NULL \endcode
570  * \retval FLAC__FileDecoderState
571  *    \c FLAC__FILE_DECODER_OK if initialization was successful; see
572  *    FLAC__FileDecoderState for the meanings of other return values.
573  */
574 FLAC_API FLAC__FileDecoderState FLAC__file_decoder_init(FLAC__FileDecoder *decoder);
575
576 /** Finish the decoding process.
577  *  Flushes the decoding buffer, releases resources, resets the decoder
578  *  settings to their defaults, and returns the decoder state to
579  *  FLAC__FILE_DECODER_UNINITIALIZED.
580  *
581  *  In the event of a prematurely-terminated decode, it is not strictly
582  *  necessary to call this immediately before FLAC__file_decoder_delete()
583  *  but it is good practice to match every FLAC__file_decoder_init() with
584  *  a FLAC__file_decoder_finish().
585  *
586  * \param  decoder  An uninitialized decoder instance.
587  * \assert
588  *    \code decoder != NULL \endcode
589  * \retval FLAC__bool
590  *    \c false if MD5 checking is on AND a STREAMINFO block was available
591  *    AND the MD5 signature in the STREAMINFO block was non-zero AND the
592  *    signature does not match the one computed by the decoder; else
593  *    \c true.
594  */
595 FLAC_API FLAC__bool FLAC__file_decoder_finish(FLAC__FileDecoder *decoder);
596
597 /** This is inherited from FLAC__SeekableStreamDecoder; see
598  *  FLAC__seekable_stream_decoder_process_single().
599  *
600  * \param  decoder  A decoder instance.
601  * \assert
602  *    \code decoder != NULL \endcode
603  * \retval FLAC__bool
604  *    See above.
605  */
606 FLAC_API FLAC__bool FLAC__file_decoder_process_single(FLAC__FileDecoder *decoder);
607
608 /** This is inherited from FLAC__SeekableStreamDecoder; see
609  *  FLAC__seekable_stream_decoder_process_until_end_of_metadata().
610  *
611  * \param  decoder  A decoder instance.
612  * \assert
613  *    \code decoder != NULL \endcode
614  * \retval FLAC__bool
615  *    See above.
616  */
617 FLAC_API FLAC__bool FLAC__file_decoder_process_until_end_of_metadata(FLAC__FileDecoder *decoder);
618
619 /** This is inherited from FLAC__SeekableStreamDecoder; see
620  *  FLAC__seekable_stream_decoder_process_until_end_of_stream().
621  *
622  * \param  decoder  A decoder instance.
623  * \assert
624  *    \code decoder != NULL \endcode
625  * \retval FLAC__bool
626  *    See above.
627  */
628 FLAC_API FLAC__bool FLAC__file_decoder_process_until_end_of_file(FLAC__FileDecoder *decoder);
629
630 /** This is inherited from FLAC__SeekableStreamDecoder; see
631  *  FLAC__seekable_stream_decoder_skip_single_frame().
632  *
633  * \param  decoder  A decoder instance.
634  * \assert
635  *    \code decoder != NULL \endcode
636  * \retval FLAC__bool
637  *    See above.
638  */
639 FLAC_API FLAC__bool FLAC__file_decoder_skip_single_frame(FLAC__FileDecoder *decoder);
640
641 /** Flush the input and seek to an absolute sample.
642  *  This is inherited from FLAC__SeekableStreamDecoder; see
643  *  FLAC__seekable_stream_decoder_seek_absolute().
644  *
645  * \param  decoder  A decoder instance.
646  * \param  sample   The target sample number to seek to.
647  * \assert
648  *    \code decoder != NULL \endcode
649  * \retval FLAC__bool
650  *    \c true if successful, else \c false.
651  */
652 FLAC_API FLAC__bool FLAC__file_decoder_seek_absolute(FLAC__FileDecoder *decoder, FLAC__uint64 sample);
653
654 /* \} */
655
656 #ifdef __cplusplus
657 }
658 #endif
659
660 #endif