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
23 #include "seekable_stream_decoder.h"
30 /** \file include/FLAC/file_decoder.h
33 * This module contains the functions which implement the file
36 * See the detailed documentation in the
37 * \link flac_file_decoder file decoder \endlink module.
40 /** \defgroup flac_file_decoder FLAC/file_decoder.h: file decoder interface
41 * \ingroup flac_decoder
44 * This module contains the functions which implement the file
47 * The basic usage of this decoder is as follows:
48 * - The program creates an instance of a decoder using
49 * FLAC__file_decoder_new().
50 * - The program overrides the default settings and sets callbacks for
51 * writing, error reporting, and metadata reporting using
52 * FLAC__file_decoder_set_*() functions.
53 * - The program initializes the instance to validate the settings and
54 * prepare for decoding using FLAC__file_decoder_init().
55 * - The program calls the FLAC__file_decoder_process_*() functions
56 * to decode data, which subsequently calls the callbacks.
57 * - The program finishes the decoding with FLAC__file_decoder_finish(),
58 * which flushes the input and output and resets the decoder to the
59 * uninitialized state.
60 * - The instance may be used again or deleted with
61 * FLAC__file_decoder_delete().
63 * The file decoder is a trivial wrapper around the
64 * \link flac_seekable_stream_decoder seekable stream decoder \endlink
65 * meant to simplfy the process of decoding from a standard file. The
66 * file decoder supplies all but the Write/Metadata/Error callbacks.
67 * The user needs only to provide the path to the file and the file
68 * decoder handles the rest.
70 * Like the seekable stream decoder, seeking is exposed through the
71 * FLAC__file_decoder_seek_absolute() method. At any point after the file
72 * decoder has been initialized, the user can call this function to seek to
73 * an exact sample within the file. Subsequently, the first time the write
74 * callback is called it will be passed a (possibly partial) block starting
77 * The file decoder also inherits MD5 signature checking from the seekable
78 * stream decoder. If this is turned on before initialization,
79 * FLAC__file_decoder_finish() will report when the decoded MD5 signature
80 * does not match the one stored in the STREAMINFO block. MD5 checking is
81 * automatically turned off if there is no signature in the STREAMINFO
82 * block or when a seek is attempted.
84 * Make sure to read the detailed descriptions of the
85 * \link flac_seekable_stream_decoder seekable stream decoder module \endlink
86 * and \link flac_stream_decoder stream decoder module \endlink
87 * since the file decoder inherits much of its behavior from them.
90 * The "set" functions may only be called when the decoder is in the
91 * state FLAC__FILE_DECODER_UNINITIALIZED, i.e. after
92 * FLAC__file_decoder_new() or FLAC__file_decoder_finish(), but
93 * before FLAC__file_decoder_init(). If this is the case they will
94 * return \c true, otherwise \c false.
97 * FLAC__file_decoder_finish() resets all settings to the constructor
98 * defaults, including the callbacks.
104 /** State values for a FLAC__FileDecoder
106 * The decoder's state can be obtained by calling FLAC__file_decoder_get_state().
110 FLAC__FILE_DECODER_OK = 0,
111 /**< The decoder is in the normal OK state. */
113 FLAC__FILE_DECODER_END_OF_FILE,
114 /**< The decoder has reached the end of the file. */
116 FLAC__FILE_DECODER_ERROR_OPENING_FILE,
117 /**< An error occurred opening the input file. */
119 FLAC__FILE_DECODER_MEMORY_ALLOCATION_ERROR,
120 /**< An error occurred allocating memory. */
122 FLAC__FILE_DECODER_SEEK_ERROR,
123 /**< An error occurred while seeking. */
125 FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR,
126 /**< An error occurred in the underlying seekable stream decoder. */
128 FLAC__FILE_DECODER_ALREADY_INITIALIZED,
129 /**< FLAC__file_decoder_init() was called when the decoder was already
130 * initialized, usually because FLAC__file_decoder_finish() was not
134 FLAC__FILE_DECODER_INVALID_CALLBACK,
135 /**< FLAC__file_decoder_init() was called without all callbacks
139 FLAC__FILE_DECODER_UNINITIALIZED
140 /**< The decoder is in the uninitialized state. */
142 } FLAC__FileDecoderState;
144 /** Maps a FLAC__FileDecoderState to a C string.
146 * Using a FLAC__FileDecoderState as the index to this array
147 * will give the string equivalent. The contents should not be modified.
149 extern const char * const FLAC__FileDecoderStateString[];
152 /***********************************************************************
154 * class FLAC__FileDecoder : public FLAC__StreamDecoder
156 ***********************************************************************/
158 struct FLAC__FileDecoderProtected;
159 struct FLAC__FileDecoderPrivate;
160 /** The opaque structure definition for the file decoder type. See the
161 * \link flac_file_decoder file decoder module \endlink for a detailed
165 struct FLAC__FileDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
166 struct FLAC__FileDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
169 /** Signature for the write callback.
170 * See FLAC__file_decoder_set_write_callback()
171 * and FLAC__SeekableStreamDecoderWriteCallback for more info.
173 * \param decoder The decoder instance calling the callback.
174 * \param frame The description of the decoded frame.
175 * \param buffer An array of pointers to decoded channels of data.
176 * \param client_data The callee's client data set through
177 * FLAC__file_decoder_set_client_data().
178 * \retval FLAC__StreamDecoderWriteStatus
179 * The callee's return status.
181 typedef FLAC__StreamDecoderWriteStatus (*FLAC__FileDecoderWriteCallback)(const FLAC__FileDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
183 /** Signature for the metadata callback.
184 * See FLAC__file_decoder_set_metadata_callback()
185 * and FLAC__SeekableStreamDecoderMetadataCallback for more info.
187 * \param decoder The decoder instance calling the callback.
188 * \param metadata The decoded metadata block.
189 * \param client_data The callee's client data set through
190 * FLAC__file_decoder_set_client_data().
192 typedef void (*FLAC__FileDecoderMetadataCallback)(const FLAC__FileDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
194 /** Signature for the error callback.
195 * See FLAC__file_decoder_set_error_callback()
196 * and FLAC__SeekableStreamDecoderErrorCallback for more info.
198 * \param decoder The decoder instance calling the callback.
199 * \param status The error encountered by the decoder.
200 * \param client_data The callee's client data set through
201 * FLAC__file_decoder_set_client_data().
203 typedef void (*FLAC__FileDecoderErrorCallback)(const FLAC__FileDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
206 /***********************************************************************
208 * Class constructor/destructor
210 ***********************************************************************/
212 /** Create a new file decoder instance. The instance is created with
213 * default settings; see the individual FLAC__file_decoder_set_*()
214 * functions for each setting's default.
216 * \retval FLAC__FileDecoder*
217 * \c NULL if there was an error allocating memory, else the new instance.
219 FLAC__FileDecoder *FLAC__file_decoder_new();
221 /** Free a decoder instance. Deletes the object pointed to by \a decoder.
223 * \param decoder A pointer to an existing decoder.
225 * \code decoder != NULL \endcode
227 void FLAC__file_decoder_delete(FLAC__FileDecoder *decoder);
230 /***********************************************************************
232 * Public class method prototypes
234 ***********************************************************************/
236 /** Set the "MD5 signature checking" flag.
237 * This is inherited from FLAC__SeekableStreamDecoder; see
238 * FLAC__seekable_stream_decoder_set_md5_checking().
241 * \param decoder A decoder instance to set.
242 * \param value See above.
244 * \code decoder != NULL \endcode
246 * \c false if the decoder is already initialized, else \c true.
248 FLAC__bool FLAC__file_decoder_set_md5_checking(FLAC__FileDecoder *decoder, FLAC__bool value);
250 /** Set the input file name to decode.
253 * \param decoder A decoder instance to set.
254 * \param value The input file name, or "-" for \c stdin.
256 * \code decoder != NULL \endcode
257 * \code value != NULL \endcode
259 * \c false if the decoder is already initialized, or there was a memory
260 * allocation error, else \c true.
262 FLAC__bool FLAC__file_decoder_set_filename(FLAC__FileDecoder *decoder, const char *value);
264 /** Set the write callback.
265 * This is inherited from FLAC__SeekableStreamDecoder; see
266 * FLAC__seekable_stream_decoder_set_write_callback().
269 * The callback is mandatory and must be set before initialization.
272 * \param decoder A decoder instance to set.
273 * \param value See above.
275 * \code decoder != NULL \endcode
276 * \code value != NULL \endcode
278 * \c false if the decoder is already initialized, else \c true.
280 FLAC__bool FLAC__file_decoder_set_write_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderWriteCallback value);
282 /** Set the metadata callback.
283 * This is inherited from FLAC__SeekableStreamDecoder; see
284 * FLAC__seekable_stream_decoder_set_metadata_callback().
287 * The callback is mandatory and must be set before initialization.
290 * \param decoder A decoder instance to set.
291 * \param value See above.
293 * \code decoder != NULL \endcode
294 * \code value != NULL \endcode
296 * \c false if the decoder is already initialized, else \c true.
298 FLAC__bool FLAC__file_decoder_set_metadata_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderMetadataCallback value);
300 /** Set the error callback.
301 * This is inherited from FLAC__SeekableStreamDecoder; see
302 * FLAC__seekable_stream_decoder_set_error_callback().
305 * The callback is mandatory and must be set before initialization.
308 * \param decoder A decoder instance to set.
309 * \param value See above.
311 * \code decoder != NULL \endcode
312 * \code value != NULL \endcode
314 * \c false if the decoder is already initialized, else \c true.
316 FLAC__bool FLAC__file_decoder_set_error_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderErrorCallback value);
318 /** Set the client data to be passed back to callbacks.
319 * This value will be supplied to callbacks in their \a client_data
323 * \param decoder A decoder instance to set.
324 * \param value See above.
326 * \code decoder != NULL \endcode
328 * \c false if the decoder is already initialized, else \c true.
330 FLAC__bool FLAC__file_decoder_set_client_data(FLAC__FileDecoder *decoder, void *value);
332 /** This is inherited from FLAC__SeekableStreamDecoder; see
333 * FLAC__seekable_stream_decoder_set_metadata_respond().
335 * \default By default, only the \c STREAMINFO block is returned via the
337 * \param decoder A decoder instance to set.
338 * \param type See above.
340 * \code decoder != NULL \endcode
343 * \c false if the decoder is already initialized, else \c true.
345 FLAC__bool FLAC__file_decoder_set_metadata_respond(FLAC__FileDecoder *decoder, FLAC__MetadataType type);
347 /** This is inherited from FLAC__SeekableStreamDecoder; see
348 * FLAC__seekable_stream_decoder_set_metadata_respond_application().
350 * \default By default, only the \c STREAMINFO block is returned via the
352 * \param decoder A decoder instance to set.
353 * \param id See above.
355 * \code decoder != NULL \endcode
356 * \code id != NULL \endcode
358 * \c false if the decoder is already initialized, else \c true.
360 FLAC__bool FLAC__file_decoder_set_metadata_respond_application(FLAC__FileDecoder *decoder, const FLAC__byte id[4]);
362 /** This is inherited from FLAC__SeekableStreamDecoder; see
363 * FLAC__seekable_stream_decoder_set_metadata_respond_all().
365 * \default By default, only the \c STREAMINFO block is returned via the
367 * \param decoder A decoder instance to set.
369 * \code decoder != NULL \endcode
371 * \c false if the decoder is already initialized, else \c true.
373 FLAC__bool FLAC__file_decoder_set_metadata_respond_all(FLAC__FileDecoder *decoder);
375 /** This is inherited from FLAC__SeekableStreamDecoder; see
376 * FLAC__seekable_stream_decoder_set_metadata_ignore().
378 * \default By default, only the \c STREAMINFO block is returned via the
380 * \param decoder A decoder instance to set.
381 * \param type See above.
383 * \code decoder != NULL \endcode
386 * \c false if the decoder is already initialized, else \c true.
388 FLAC__bool FLAC__file_decoder_set_metadata_ignore(FLAC__FileDecoder *decoder, FLAC__MetadataType type);
390 /** This is inherited from FLAC__SeekableStreamDecoder; see
391 * FLAC__seekable_stream_decoder_set_metadata_ignore_application().
393 * \default By default, only the \c STREAMINFO block is returned via the
395 * \param decoder A decoder instance to set.
396 * \param id See above.
398 * \code decoder != NULL \endcode
399 * \code id != NULL \endcode
401 * \c false if the decoder is already initialized, else \c true.
403 FLAC__bool FLAC__file_decoder_set_metadata_ignore_application(FLAC__FileDecoder *decoder, const FLAC__byte id[4]);
405 /** This is inherited from FLAC__SeekableStreamDecoder; see
406 * FLAC__seekable_stream_decoder_set_metadata_ignore_all().
408 * \default By default, only the \c STREAMINFO block is returned via the
410 * \param decoder A decoder instance to set.
412 * \code decoder != NULL \endcode
414 * \c false if the decoder is already initialized, else \c true.
416 FLAC__bool FLAC__file_decoder_set_metadata_ignore_all(FLAC__FileDecoder *decoder);
418 /** Get the current decoder state.
420 * \param decoder A decoder instance to query.
422 * \code decoder != NULL \endcode
423 * \retval FLAC__FileDecoderState
424 * The current decoder state.
426 FLAC__FileDecoderState FLAC__file_decoder_get_state(const FLAC__FileDecoder *decoder);
428 /** Get the state of the underlying seekable stream decoder.
429 * Useful when the file decoder state is
430 * \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR.
432 * \param decoder A decoder instance to query.
434 * \code decoder != NULL \endcode
435 * \retval FLAC__SeekableStreamDecoderState
436 * The seekable stream decoder state.
438 FLAC__SeekableStreamDecoderState FLAC__file_decoder_get_seekable_stream_decoder_state(const FLAC__FileDecoder *decoder);
440 /** Get the state of the underlying stream decoder.
441 * Useful when the file decoder state is
442 * \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR and the seekable stream
443 * decoder state is \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
445 * \param decoder A decoder instance to query.
447 * \code decoder != NULL \endcode
448 * \retval FLAC__StreamDecoderState
449 * The seekable stream decoder state.
451 FLAC__StreamDecoderState FLAC__file_decoder_get_stream_decoder_state(const FLAC__FileDecoder *decoder);
453 /** Get the "MD5 signature checking" flag.
454 * This is inherited from FLAC__SeekableStreamDecoder; see
455 * FLAC__seekable_stream_decoder_get_md5_checking().
457 * \param decoder A decoder instance to query.
459 * \code decoder != NULL \endcode
463 FLAC__bool FLAC__file_decoder_get_md5_checking(const FLAC__FileDecoder *decoder);
465 /** This is inherited from FLAC__SeekableStreamDecoder; see
466 * FLAC__seekable_stream_decoder_get_channels().
468 * \param decoder A decoder instance to query.
470 * \code decoder != NULL \endcode
474 unsigned FLAC__file_decoder_get_channels(const FLAC__FileDecoder *decoder);
476 /** This is inherited from FLAC__SeekableStreamDecoder; see
477 * FLAC__seekable_stream_decoder_get_channel_assignment().
479 * \param decoder A decoder instance to query.
481 * \code decoder != NULL \endcode
482 * \retval FLAC__ChannelAssignment
485 FLAC__ChannelAssignment FLAC__file_decoder_get_channel_assignment(const FLAC__FileDecoder *decoder);
487 /** This is inherited from FLAC__SeekableStreamDecoder; see
488 * FLAC__seekable_stream_decoder_get_bits_per_sample().
490 * \param decoder A decoder instance to query.
492 * \code decoder != NULL \endcode
496 unsigned FLAC__file_decoder_get_bits_per_sample(const FLAC__FileDecoder *decoder);
498 /** This is inherited from FLAC__SeekableStreamDecoder; see
499 * FLAC__seekable_stream_decoder_get_sample_rate().
501 * \param decoder A decoder instance to query.
503 * \code decoder != NULL \endcode
507 unsigned FLAC__file_decoder_get_sample_rate(const FLAC__FileDecoder *decoder);
509 /** This is inherited from FLAC__SeekableStreamDecoder; see
510 * FLAC__seekable_stream_decoder_get_blocksize().
512 * \param decoder A decoder instance to query.
514 * \code decoder != NULL \endcode
518 unsigned FLAC__file_decoder_get_blocksize(const FLAC__FileDecoder *decoder);
520 /** Initialize the decoder instance.
521 * Should be called after FLAC__file_decoder_new() and
522 * FLAC__file_decoder_set_*() but before any of the
523 * FLAC__file_decoder_process_*() functions. Will set and return
524 * the decoder state, which will be FLAC__FILE_DECODER_OK if
525 * initialization succeeded.
527 * \param decoder An uninitialized decoder instance.
529 * \code decoder != NULL \endcode
530 * \retval FLAC__FileDecoderState
531 * \c FLAC__FILE_DECODER_OK if initialization was successful; see
532 * FLAC__FileDecoderState for the meanings of other return values.
534 FLAC__FileDecoderState FLAC__file_decoder_init(FLAC__FileDecoder *decoder);
536 /** Finish the decoding process.
537 * Flushes the decoding buffer, releases resources, resets the decoder
538 * settings to their defaults, and returns the decoder state to
539 * FLAC__FILE_DECODER_UNINITIALIZED.
541 * In the event of a prematurely-terminated decode, it is not strictly
542 * necessary to call this immediately before FLAC__file_decoder_delete()
543 * but it is good practice to match every FLAC__file_decoder_init() with
544 * a FLAC__file_decoder_finish().
546 * \param decoder An uninitialized decoder instance.
548 * \code decoder != NULL \endcode
550 * \c false if MD5 checking is on AND a STREAMINFO block was available
551 * AND the MD5 signature in the STREAMINFO block was non-zero AND the
552 * signature does not match the one computed by the decoder; else
555 FLAC__bool FLAC__file_decoder_finish(FLAC__FileDecoder *decoder);
557 /** This is inherited from FLAC__SeekableStreamDecoder; see
558 * FLAC__seekable_stream_decoder_process_single().
560 * \param decoder A decoder instance.
562 * \code decoder != NULL \endcode
566 FLAC__bool FLAC__file_decoder_process_single(FLAC__FileDecoder *decoder);
568 /** This is inherited from FLAC__SeekableStreamDecoder; see
569 * FLAC__seekable_stream_decoder_process_until_end_of_metadata().
571 * \param decoder A decoder instance.
573 * \code decoder != NULL \endcode
577 FLAC__bool FLAC__file_decoder_process_until_end_of_metadata(FLAC__FileDecoder *decoder);
579 /** This is inherited from FLAC__SeekableStreamDecoder; see
580 * FLAC__seekable_stream_decoder_process_until_end_of_stream().
582 * \param decoder A decoder instance.
584 * \code decoder != NULL \endcode
588 FLAC__bool FLAC__file_decoder_process_until_end_of_file(FLAC__FileDecoder *decoder);
590 /** This is inherited from FLAC__SeekableStreamDecoder; see
591 * FLAC__seekable_stream_decoder_process_remaining_frames().
593 * \param decoder A decoder instance.
595 * \code decoder != NULL \endcode
599 FLAC__bool FLAC__file_decoder_process_remaining_frames(FLAC__FileDecoder *decoder);
601 /** Flush the input and seek to an absolute sample.
602 * This is inherited from FLAC__SeekableStreamDecoder; see
603 * FLAC__seekable_stream_decoder_seek_absolute().
605 * \param decoder A decoder instance.
606 * \param sample The target sample number to seek to.
608 * \code decoder != NULL \endcode
610 * \c true if successful, else \c false.
612 FLAC__bool FLAC__file_decoder_seek_absolute(FLAC__FileDecoder *decoder, FLAC__uint64 sample);