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