1 /* libFLAC - Free Lossless Audio Codec library
2 * Copyright (C) 2000,2001,2002 Josh Coalson
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.
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.
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.
20 #ifndef FLAC__FILE_DECODER_H
21 #define FLAC__FILE_DECODER_H
24 #include "seekable_stream_decoder.h"
31 /** \file include/FLAC/file_decoder.h
34 * This module contains the functions which implement the file
37 * See the detailed documentation in the
38 * \link flac_file_decoder file decoder \endlink module.
41 /** \defgroup flac_file_decoder FLAC/file_decoder.h: file decoder interface
42 * \ingroup flac_decoder
45 * This module contains the functions which implement the file
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().
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.
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
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.
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.
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.
98 * FLAC__file_decoder_finish() resets all settings to the constructor
99 * defaults, including the callbacks.
105 /** State values for a FLAC__FileDecoder
107 * The decoder's state can be obtained by calling FLAC__file_decoder_get_state().
111 FLAC__FILE_DECODER_OK = 0,
112 /**< The decoder is in the normal OK state. */
114 FLAC__FILE_DECODER_END_OF_FILE,
115 /**< The decoder has reached the end of the file. */
117 FLAC__FILE_DECODER_ERROR_OPENING_FILE,
118 /**< An error occurred opening the input file. */
120 FLAC__FILE_DECODER_MEMORY_ALLOCATION_ERROR,
121 /**< An error occurred allocating memory. */
123 FLAC__FILE_DECODER_SEEK_ERROR,
124 /**< An error occurred while seeking. */
126 FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR,
127 /**< An error occurred in the underlying seekable stream decoder. */
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
135 FLAC__FILE_DECODER_INVALID_CALLBACK,
136 /**< FLAC__file_decoder_init() was called without all callbacks
140 FLAC__FILE_DECODER_UNINITIALIZED
141 /**< The decoder is in the uninitialized state. */
143 } FLAC__FileDecoderState;
145 /** Maps a FLAC__FileDecoderState to a C string.
147 * Using a FLAC__FileDecoderState as the index to this array
148 * will give the string equivalent. The contents should not be modified.
150 extern FLAC_API const char * const FLAC__FileDecoderStateString[];
153 /***********************************************************************
155 * class FLAC__FileDecoder : public FLAC__StreamDecoder
157 ***********************************************************************/
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
166 struct FLAC__FileDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
167 struct FLAC__FileDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
170 /** Signature for the write callback.
171 * See FLAC__file_decoder_set_write_callback()
172 * and FLAC__SeekableStreamDecoderWriteCallback for more info.
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.
182 typedef FLAC__StreamDecoderWriteStatus (*FLAC__FileDecoderWriteCallback)(const FLAC__FileDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
184 /** Signature for the metadata callback.
185 * See FLAC__file_decoder_set_metadata_callback()
186 * and FLAC__SeekableStreamDecoderMetadataCallback for more info.
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().
193 typedef void (*FLAC__FileDecoderMetadataCallback)(const FLAC__FileDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
195 /** Signature for the error callback.
196 * See FLAC__file_decoder_set_error_callback()
197 * and FLAC__SeekableStreamDecoderErrorCallback for more info.
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().
204 typedef void (*FLAC__FileDecoderErrorCallback)(const FLAC__FileDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
207 /***********************************************************************
209 * Class constructor/destructor
211 ***********************************************************************/
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.
217 * \retval FLAC__FileDecoder*
218 * \c NULL if there was an error allocating memory, else the new instance.
220 FLAC_API FLAC__FileDecoder *FLAC__file_decoder_new();
222 /** Free a decoder instance. Deletes the object pointed to by \a decoder.
224 * \param decoder A pointer to an existing decoder.
226 * \code decoder != NULL \endcode
228 FLAC_API void FLAC__file_decoder_delete(FLAC__FileDecoder *decoder);
231 /***********************************************************************
233 * Public class method prototypes
235 ***********************************************************************/
237 /** Set the "MD5 signature checking" flag.
238 * This is inherited from FLAC__SeekableStreamDecoder; see
239 * FLAC__seekable_stream_decoder_set_md5_checking().
242 * \param decoder A decoder instance to set.
243 * \param value See above.
245 * \code decoder != NULL \endcode
247 * \c false if the decoder is already initialized, else \c true.
249 FLAC_API FLAC__bool FLAC__file_decoder_set_md5_checking(FLAC__FileDecoder *decoder, FLAC__bool value);
251 /** Set the input file name to decode.
254 * \param decoder A decoder instance to set.
255 * \param value The input file name, or "-" for \c stdin.
257 * \code decoder != NULL \endcode
258 * \code value != NULL \endcode
260 * \c false if the decoder is already initialized, or there was a memory
261 * allocation error, else \c true.
263 FLAC_API FLAC__bool FLAC__file_decoder_set_filename(FLAC__FileDecoder *decoder, const char *value);
265 /** Set the write callback.
266 * This is inherited from FLAC__SeekableStreamDecoder; see
267 * FLAC__seekable_stream_decoder_set_write_callback().
270 * The callback is mandatory and must be set before initialization.
273 * \param decoder A decoder instance to set.
274 * \param value See above.
276 * \code decoder != NULL \endcode
277 * \code value != NULL \endcode
279 * \c false if the decoder is already initialized, else \c true.
281 FLAC_API FLAC__bool FLAC__file_decoder_set_write_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderWriteCallback value);
283 /** Set the metadata callback.
284 * This is inherited from FLAC__SeekableStreamDecoder; see
285 * FLAC__seekable_stream_decoder_set_metadata_callback().
288 * The callback is mandatory and must be set before initialization.
291 * \param decoder A decoder instance to set.
292 * \param value See above.
294 * \code decoder != NULL \endcode
295 * \code value != NULL \endcode
297 * \c false if the decoder is already initialized, else \c true.
299 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderMetadataCallback value);
301 /** Set the error callback.
302 * This is inherited from FLAC__SeekableStreamDecoder; see
303 * FLAC__seekable_stream_decoder_set_error_callback().
306 * The callback is mandatory and must be set before initialization.
309 * \param decoder A decoder instance to set.
310 * \param value See above.
312 * \code decoder != NULL \endcode
313 * \code value != NULL \endcode
315 * \c false if the decoder is already initialized, else \c true.
317 FLAC_API FLAC__bool FLAC__file_decoder_set_error_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderErrorCallback value);
319 /** Set the client data to be passed back to callbacks.
320 * This value will be supplied to callbacks in their \a client_data
324 * \param decoder A decoder instance to set.
325 * \param value See above.
327 * \code decoder != NULL \endcode
329 * \c false if the decoder is already initialized, else \c true.
331 FLAC_API FLAC__bool FLAC__file_decoder_set_client_data(FLAC__FileDecoder *decoder, void *value);
333 /** This is inherited from FLAC__SeekableStreamDecoder; see
334 * FLAC__seekable_stream_decoder_set_metadata_respond().
336 * \default By default, only the \c STREAMINFO block is returned via the
338 * \param decoder A decoder instance to set.
339 * \param type See above.
341 * \code decoder != NULL \endcode
344 * \c false if the decoder is already initialized, else \c true.
346 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond(FLAC__FileDecoder *decoder, FLAC__MetadataType type);
348 /** This is inherited from FLAC__SeekableStreamDecoder; see
349 * FLAC__seekable_stream_decoder_set_metadata_respond_application().
351 * \default By default, only the \c STREAMINFO block is returned via the
353 * \param decoder A decoder instance to set.
354 * \param id See above.
356 * \code decoder != NULL \endcode
357 * \code id != NULL \endcode
359 * \c false if the decoder is already initialized, else \c true.
361 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond_application(FLAC__FileDecoder *decoder, const FLAC__byte id[4]);
363 /** This is inherited from FLAC__SeekableStreamDecoder; see
364 * FLAC__seekable_stream_decoder_set_metadata_respond_all().
366 * \default By default, only the \c STREAMINFO block is returned via the
368 * \param decoder A decoder instance to set.
370 * \code decoder != NULL \endcode
372 * \c false if the decoder is already initialized, else \c true.
374 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond_all(FLAC__FileDecoder *decoder);
376 /** This is inherited from FLAC__SeekableStreamDecoder; see
377 * FLAC__seekable_stream_decoder_set_metadata_ignore().
379 * \default By default, only the \c STREAMINFO block is returned via the
381 * \param decoder A decoder instance to set.
382 * \param type See above.
384 * \code decoder != NULL \endcode
387 * \c false if the decoder is already initialized, else \c true.
389 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore(FLAC__FileDecoder *decoder, FLAC__MetadataType type);
391 /** This is inherited from FLAC__SeekableStreamDecoder; see
392 * FLAC__seekable_stream_decoder_set_metadata_ignore_application().
394 * \default By default, only the \c STREAMINFO block is returned via the
396 * \param decoder A decoder instance to set.
397 * \param id See above.
399 * \code decoder != NULL \endcode
400 * \code id != NULL \endcode
402 * \c false if the decoder is already initialized, else \c true.
404 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore_application(FLAC__FileDecoder *decoder, const FLAC__byte id[4]);
406 /** This is inherited from FLAC__SeekableStreamDecoder; see
407 * FLAC__seekable_stream_decoder_set_metadata_ignore_all().
409 * \default By default, only the \c STREAMINFO block is returned via the
411 * \param decoder A decoder instance to set.
413 * \code decoder != NULL \endcode
415 * \c false if the decoder is already initialized, else \c true.
417 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore_all(FLAC__FileDecoder *decoder);
419 /** Get the current decoder state.
421 * \param decoder A decoder instance to query.
423 * \code decoder != NULL \endcode
424 * \retval FLAC__FileDecoderState
425 * The current decoder state.
427 FLAC_API FLAC__FileDecoderState FLAC__file_decoder_get_state(const FLAC__FileDecoder *decoder);
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.
433 * \param decoder A decoder instance to query.
435 * \code decoder != NULL \endcode
436 * \retval FLAC__SeekableStreamDecoderState
437 * The seekable stream decoder state.
439 FLAC_API FLAC__SeekableStreamDecoderState FLAC__file_decoder_get_seekable_stream_decoder_state(const FLAC__FileDecoder *decoder);
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.
446 * \param decoder A decoder instance to query.
448 * \code decoder != NULL \endcode
449 * \retval FLAC__StreamDecoderState
450 * The seekable stream decoder state.
452 FLAC_API FLAC__StreamDecoderState FLAC__file_decoder_get_stream_decoder_state(const FLAC__FileDecoder *decoder);
455 FLAC_API const char *FLAC__file_decoder_get_resolved_state_string(const FLAC__FileDecoder *decoder);
457 /** Get the "MD5 signature checking" flag.
458 * This is inherited from FLAC__SeekableStreamDecoder; see
459 * FLAC__seekable_stream_decoder_get_md5_checking().
461 * \param decoder A decoder instance to query.
463 * \code decoder != NULL \endcode
467 FLAC_API FLAC__bool FLAC__file_decoder_get_md5_checking(const FLAC__FileDecoder *decoder);
469 /** This is inherited from FLAC__SeekableStreamDecoder; see
470 * FLAC__seekable_stream_decoder_get_channels().
472 * \param decoder A decoder instance to query.
474 * \code decoder != NULL \endcode
478 FLAC_API unsigned FLAC__file_decoder_get_channels(const FLAC__FileDecoder *decoder);
480 /** This is inherited from FLAC__SeekableStreamDecoder; see
481 * FLAC__seekable_stream_decoder_get_channel_assignment().
483 * \param decoder A decoder instance to query.
485 * \code decoder != NULL \endcode
486 * \retval FLAC__ChannelAssignment
489 FLAC_API FLAC__ChannelAssignment FLAC__file_decoder_get_channel_assignment(const FLAC__FileDecoder *decoder);
491 /** This is inherited from FLAC__SeekableStreamDecoder; see
492 * FLAC__seekable_stream_decoder_get_bits_per_sample().
494 * \param decoder A decoder instance to query.
496 * \code decoder != NULL \endcode
500 FLAC_API unsigned FLAC__file_decoder_get_bits_per_sample(const FLAC__FileDecoder *decoder);
502 /** This is inherited from FLAC__SeekableStreamDecoder; see
503 * FLAC__seekable_stream_decoder_get_sample_rate().
505 * \param decoder A decoder instance to query.
507 * \code decoder != NULL \endcode
511 FLAC_API unsigned FLAC__file_decoder_get_sample_rate(const FLAC__FileDecoder *decoder);
513 /** This is inherited from FLAC__SeekableStreamDecoder; see
514 * FLAC__seekable_stream_decoder_get_blocksize().
516 * \param decoder A decoder instance to query.
518 * \code decoder != NULL \endcode
522 FLAC_API unsigned FLAC__file_decoder_get_blocksize(const FLAC__FileDecoder *decoder);
525 FLAC_API FLAC__bool FLAC__file_decoder_get_decode_position(const FLAC__FileDecoder *decoder, FLAC__uint64 *position);
527 /** Initialize the decoder instance.
528 * Should be called after FLAC__file_decoder_new() and
529 * FLAC__file_decoder_set_*() but before any of the
530 * FLAC__file_decoder_process_*() functions. Will set and return
531 * the decoder state, which will be FLAC__FILE_DECODER_OK if
532 * initialization succeeded.
534 * \param decoder An uninitialized decoder instance.
536 * \code decoder != NULL \endcode
537 * \retval FLAC__FileDecoderState
538 * \c FLAC__FILE_DECODER_OK if initialization was successful; see
539 * FLAC__FileDecoderState for the meanings of other return values.
541 FLAC_API FLAC__FileDecoderState FLAC__file_decoder_init(FLAC__FileDecoder *decoder);
543 /** Finish the decoding process.
544 * Flushes the decoding buffer, releases resources, resets the decoder
545 * settings to their defaults, and returns the decoder state to
546 * FLAC__FILE_DECODER_UNINITIALIZED.
548 * In the event of a prematurely-terminated decode, it is not strictly
549 * necessary to call this immediately before FLAC__file_decoder_delete()
550 * but it is good practice to match every FLAC__file_decoder_init() with
551 * a FLAC__file_decoder_finish().
553 * \param decoder An uninitialized decoder instance.
555 * \code decoder != NULL \endcode
557 * \c false if MD5 checking is on AND a STREAMINFO block was available
558 * AND the MD5 signature in the STREAMINFO block was non-zero AND the
559 * signature does not match the one computed by the decoder; else
562 FLAC_API FLAC__bool FLAC__file_decoder_finish(FLAC__FileDecoder *decoder);
564 /** This is inherited from FLAC__SeekableStreamDecoder; see
565 * FLAC__seekable_stream_decoder_process_single().
567 * \param decoder A decoder instance.
569 * \code decoder != NULL \endcode
573 FLAC_API FLAC__bool FLAC__file_decoder_process_single(FLAC__FileDecoder *decoder);
575 /** This is inherited from FLAC__SeekableStreamDecoder; see
576 * FLAC__seekable_stream_decoder_process_until_end_of_metadata().
578 * \param decoder A decoder instance.
580 * \code decoder != NULL \endcode
584 FLAC_API FLAC__bool FLAC__file_decoder_process_until_end_of_metadata(FLAC__FileDecoder *decoder);
586 /** This is inherited from FLAC__SeekableStreamDecoder; see
587 * FLAC__seekable_stream_decoder_process_until_end_of_stream().
589 * \param decoder A decoder instance.
591 * \code decoder != NULL \endcode
595 FLAC_API FLAC__bool FLAC__file_decoder_process_until_end_of_file(FLAC__FileDecoder *decoder);
597 /** This is inherited from FLAC__SeekableStreamDecoder; see
598 * FLAC__seekable_stream_decoder_process_remaining_frames().
600 * \param decoder A decoder instance.
602 * \code decoder != NULL \endcode
606 FLAC_API FLAC__bool FLAC__file_decoder_process_remaining_frames(FLAC__FileDecoder *decoder);
608 /** Flush the input and seek to an absolute sample.
609 * This is inherited from FLAC__SeekableStreamDecoder; see
610 * FLAC__seekable_stream_decoder_seek_absolute().
612 * \param decoder A decoder instance.
613 * \param sample The target sample number to seek to.
615 * \code decoder != NULL \endcode
617 * \c true if successful, else \c false.
619 FLAC_API FLAC__bool FLAC__file_decoder_seek_absolute(FLAC__FileDecoder *decoder, FLAC__uint64 sample);