file_decoder.h - vx32 - Local 9vx git repository for patches.
(HTM) git clone git://r-36.net/vx32
(DIR) Log
(DIR) Files
(DIR) Refs
---
file_decoder.h (24554B)
---
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