1
/* libFLAC - Free Lossless Audio Codec library
2
* Copyright (C) 2000,2001,2002,2003,2004,2005 Josh Coalson
4
* Redistribution and use in source and binary forms, with or without
5
* modification, are permitted provided that the following conditions
8
* - Redistributions of source code must retain the above copyright
9
* notice, this list of conditions and the following disclaimer.
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.
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.
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.
32
#ifndef FLAC__FILE_DECODER_H
33
#define FLAC__FILE_DECODER_H
36
#include "seekable_stream_decoder.h"
43
/** \file include/FLAC/file_decoder.h
46
* This module contains the functions which implement the file
49
* See the detailed documentation in the
50
* \link flac_file_decoder file decoder \endlink module.
53
/** \defgroup flac_file_decoder FLAC/file_decoder.h: file decoder interface
54
* \ingroup flac_decoder
57
* This module contains the functions which implement the file
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().
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.
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
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.
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.
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.
110
* FLAC__file_decoder_finish() resets all settings to the constructor
111
* defaults, including the callbacks.
117
/** State values for a FLAC__FileDecoder
119
* The decoder's state can be obtained by calling FLAC__file_decoder_get_state().
123
FLAC__FILE_DECODER_OK = 0,
124
/**< The decoder is in the normal OK state. */
126
FLAC__FILE_DECODER_END_OF_FILE,
127
/**< The decoder has reached the end of the file. */
129
FLAC__FILE_DECODER_ERROR_OPENING_FILE,
130
/**< An error occurred opening the input file. */
132
FLAC__FILE_DECODER_MEMORY_ALLOCATION_ERROR,
133
/**< An error occurred allocating memory. */
135
FLAC__FILE_DECODER_SEEK_ERROR,
136
/**< An error occurred while seeking. */
138
FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR,
139
/**< An error occurred in the underlying seekable stream decoder. */
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
147
FLAC__FILE_DECODER_INVALID_CALLBACK,
148
/**< FLAC__file_decoder_init() was called without all callbacks
152
FLAC__FILE_DECODER_UNINITIALIZED
153
/**< The decoder is in the uninitialized state. */
155
} FLAC__FileDecoderState;
157
/** Maps a FLAC__FileDecoderState to a C string.
159
* Using a FLAC__FileDecoderState as the index to this array
160
* will give the string equivalent. The contents should not be modified.
162
extern FLAC_API const char * const FLAC__FileDecoderStateString[];
165
/***********************************************************************
167
* class FLAC__FileDecoder : public FLAC__StreamDecoder
169
***********************************************************************/
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
178
struct FLAC__FileDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
179
struct FLAC__FileDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
182
/** Signature for the write callback.
183
* See FLAC__file_decoder_set_write_callback()
184
* and FLAC__SeekableStreamDecoderWriteCallback for more info.
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.
194
typedef FLAC__StreamDecoderWriteStatus (*FLAC__FileDecoderWriteCallback)(const FLAC__FileDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
196
/** Signature for the metadata callback.
197
* See FLAC__file_decoder_set_metadata_callback()
198
* and FLAC__SeekableStreamDecoderMetadataCallback for more info.
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().
205
typedef void (*FLAC__FileDecoderMetadataCallback)(const FLAC__FileDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
207
/** Signature for the error callback.
208
* See FLAC__file_decoder_set_error_callback()
209
* and FLAC__SeekableStreamDecoderErrorCallback for more info.
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().
216
typedef void (*FLAC__FileDecoderErrorCallback)(const FLAC__FileDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
219
/***********************************************************************
221
* Class constructor/destructor
223
***********************************************************************/
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.
229
* \retval FLAC__FileDecoder*
230
* \c NULL if there was an error allocating memory, else the new instance.
232
FLAC_API FLAC__FileDecoder *FLAC__file_decoder_new();
234
/** Free a decoder instance. Deletes the object pointed to by \a decoder.
236
* \param decoder A pointer to an existing decoder.
238
* \code decoder != NULL \endcode
240
FLAC_API void FLAC__file_decoder_delete(FLAC__FileDecoder *decoder);
243
/***********************************************************************
245
* Public class method prototypes
247
***********************************************************************/
249
/** Set the "MD5 signature checking" flag.
250
* This is inherited from FLAC__SeekableStreamDecoder; see
251
* FLAC__seekable_stream_decoder_set_md5_checking().
254
* \param decoder A decoder instance to set.
255
* \param value See above.
257
* \code decoder != NULL \endcode
259
* \c false if the decoder is already initialized, else \c true.
261
FLAC_API FLAC__bool FLAC__file_decoder_set_md5_checking(FLAC__FileDecoder *decoder, FLAC__bool value);
263
/** Set the input file name to decode.
266
* \param decoder A decoder instance to set.
267
* \param value The input file name, or "-" for \c stdin.
269
* \code decoder != NULL \endcode
270
* \code value != NULL \endcode
272
* \c false if the decoder is already initialized, or there was a memory
273
* allocation error, else \c true.
275
FLAC_API FLAC__bool FLAC__file_decoder_set_filename(FLAC__FileDecoder *decoder, const char *value);
277
/** Set the write callback.
278
* This is inherited from FLAC__SeekableStreamDecoder; see
279
* FLAC__seekable_stream_decoder_set_write_callback().
282
* The callback is mandatory and must be set before initialization.
285
* \param decoder A decoder instance to set.
286
* \param value See above.
288
* \code decoder != NULL \endcode
289
* \code value != NULL \endcode
291
* \c false if the decoder is already initialized, else \c true.
293
FLAC_API FLAC__bool FLAC__file_decoder_set_write_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderWriteCallback value);
295
/** Set the metadata callback.
296
* This is inherited from FLAC__SeekableStreamDecoder; see
297
* FLAC__seekable_stream_decoder_set_metadata_callback().
300
* The callback is mandatory and must be set before initialization.
303
* \param decoder A decoder instance to set.
304
* \param value See above.
306
* \code decoder != NULL \endcode
307
* \code value != NULL \endcode
309
* \c false if the decoder is already initialized, else \c true.
311
FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderMetadataCallback value);
313
/** Set the error callback.
314
* This is inherited from FLAC__SeekableStreamDecoder; see
315
* FLAC__seekable_stream_decoder_set_error_callback().
318
* The callback is mandatory and must be set before initialization.
321
* \param decoder A decoder instance to set.
322
* \param value See above.
324
* \code decoder != NULL \endcode
325
* \code value != NULL \endcode
327
* \c false if the decoder is already initialized, else \c true.
329
FLAC_API FLAC__bool FLAC__file_decoder_set_error_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderErrorCallback value);
331
/** Set the client data to be passed back to callbacks.
332
* This value will be supplied to callbacks in their \a client_data
336
* \param decoder A decoder instance to set.
337
* \param value See above.
339
* \code decoder != NULL \endcode
341
* \c false if the decoder is already initialized, else \c true.
343
FLAC_API FLAC__bool FLAC__file_decoder_set_client_data(FLAC__FileDecoder *decoder, void *value);
345
/** This is inherited from FLAC__SeekableStreamDecoder; see
346
* FLAC__seekable_stream_decoder_set_metadata_respond().
348
* \default By default, only the \c STREAMINFO block is returned via the
350
* \param decoder A decoder instance to set.
351
* \param type See above.
353
* \code decoder != NULL \endcode
356
* \c false if the decoder is already initialized, else \c true.
358
FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond(FLAC__FileDecoder *decoder, FLAC__MetadataType type);
360
/** This is inherited from FLAC__SeekableStreamDecoder; see
361
* FLAC__seekable_stream_decoder_set_metadata_respond_application().
363
* \default By default, only the \c STREAMINFO block is returned via the
365
* \param decoder A decoder instance to set.
366
* \param id See above.
368
* \code decoder != NULL \endcode
369
* \code id != NULL \endcode
371
* \c false if the decoder is already initialized, else \c true.
373
FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond_application(FLAC__FileDecoder *decoder, const FLAC__byte id[4]);
375
/** This is inherited from FLAC__SeekableStreamDecoder; see
376
* FLAC__seekable_stream_decoder_set_metadata_respond_all().
378
* \default By default, only the \c STREAMINFO block is returned via the
380
* \param decoder A decoder instance to set.
382
* \code decoder != NULL \endcode
384
* \c false if the decoder is already initialized, else \c true.
386
FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond_all(FLAC__FileDecoder *decoder);
388
/** This is inherited from FLAC__SeekableStreamDecoder; see
389
* FLAC__seekable_stream_decoder_set_metadata_ignore().
391
* \default By default, only the \c STREAMINFO block is returned via the
393
* \param decoder A decoder instance to set.
394
* \param type See above.
396
* \code decoder != NULL \endcode
399
* \c false if the decoder is already initialized, else \c true.
401
FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore(FLAC__FileDecoder *decoder, FLAC__MetadataType type);
403
/** This is inherited from FLAC__SeekableStreamDecoder; see
404
* FLAC__seekable_stream_decoder_set_metadata_ignore_application().
406
* \default By default, only the \c STREAMINFO block is returned via the
408
* \param decoder A decoder instance to set.
409
* \param id See above.
411
* \code decoder != NULL \endcode
412
* \code id != NULL \endcode
414
* \c false if the decoder is already initialized, else \c true.
416
FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore_application(FLAC__FileDecoder *decoder, const FLAC__byte id[4]);
418
/** This is inherited from FLAC__SeekableStreamDecoder; see
419
* FLAC__seekable_stream_decoder_set_metadata_ignore_all().
421
* \default By default, only the \c STREAMINFO block is returned via the
423
* \param decoder A decoder instance to set.
425
* \code decoder != NULL \endcode
427
* \c false if the decoder is already initialized, else \c true.
429
FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore_all(FLAC__FileDecoder *decoder);
431
/** Get the current decoder state.
433
* \param decoder A decoder instance to query.
435
* \code decoder != NULL \endcode
436
* \retval FLAC__FileDecoderState
437
* The current decoder state.
439
FLAC_API FLAC__FileDecoderState FLAC__file_decoder_get_state(const FLAC__FileDecoder *decoder);
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.
445
* \param decoder A decoder instance to query.
447
* \code decoder != NULL \endcode
448
* \retval FLAC__SeekableStreamDecoderState
449
* The seekable stream decoder state.
451
FLAC_API FLAC__SeekableStreamDecoderState FLAC__file_decoder_get_seekable_stream_decoder_state(const FLAC__FileDecoder *decoder);
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.
458
* \param decoder A decoder instance to query.
460
* \code decoder != NULL \endcode
461
* \retval FLAC__StreamDecoderState
462
* The seekable stream decoder state.
464
FLAC_API FLAC__StreamDecoderState FLAC__file_decoder_get_stream_decoder_state(const FLAC__FileDecoder *decoder);
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.
471
* \param decoder A decoder instance to query.
473
* \code decoder != NULL \endcode
474
* \retval const char *
475
* The decoder state as a C string. Do not modify the contents.
477
FLAC_API const char *FLAC__file_decoder_get_resolved_state_string(const FLAC__FileDecoder *decoder);
479
/** Get the "MD5 signature checking" flag.
480
* This is inherited from FLAC__SeekableStreamDecoder; see
481
* FLAC__seekable_stream_decoder_get_md5_checking().
483
* \param decoder A decoder instance to query.
485
* \code decoder != NULL \endcode
489
FLAC_API FLAC__bool FLAC__file_decoder_get_md5_checking(const FLAC__FileDecoder *decoder);
491
/** This is inherited from FLAC__SeekableStreamDecoder; see
492
* FLAC__seekable_stream_decoder_get_channels().
494
* \param decoder A decoder instance to query.
496
* \code decoder != NULL \endcode
500
FLAC_API unsigned FLAC__file_decoder_get_channels(const FLAC__FileDecoder *decoder);
502
/** This is inherited from FLAC__SeekableStreamDecoder; see
503
* FLAC__seekable_stream_decoder_get_channel_assignment().
505
* \param decoder A decoder instance to query.
507
* \code decoder != NULL \endcode
508
* \retval FLAC__ChannelAssignment
511
FLAC_API FLAC__ChannelAssignment FLAC__file_decoder_get_channel_assignment(const FLAC__FileDecoder *decoder);
513
/** This is inherited from FLAC__SeekableStreamDecoder; see
514
* FLAC__seekable_stream_decoder_get_bits_per_sample().
516
* \param decoder A decoder instance to query.
518
* \code decoder != NULL \endcode
522
FLAC_API unsigned FLAC__file_decoder_get_bits_per_sample(const FLAC__FileDecoder *decoder);
524
/** This is inherited from FLAC__SeekableStreamDecoder; see
525
* FLAC__seekable_stream_decoder_get_sample_rate().
527
* \param decoder A decoder instance to query.
529
* \code decoder != NULL \endcode
533
FLAC_API unsigned FLAC__file_decoder_get_sample_rate(const FLAC__FileDecoder *decoder);
535
/** This is inherited from FLAC__SeekableStreamDecoder; see
536
* FLAC__seekable_stream_decoder_get_blocksize().
538
* \param decoder A decoder instance to query.
540
* \code decoder != NULL \endcode
544
FLAC_API unsigned FLAC__file_decoder_get_blocksize(const FLAC__FileDecoder *decoder);
546
/** This is inherited from FLAC__SeekableStreamDecoder; see
547
* FLAC__seekable_stream_decoder_get_decode_position().
549
* \param decoder A decoder instance to query.
550
* \param position Address at which to return the desired position.
552
* \code decoder != NULL \endcode
553
* \code position != NULL \endcode
555
* \c true if successful, \c false if there was an error from
556
* the 'tell' callback.
558
FLAC_API FLAC__bool FLAC__file_decoder_get_decode_position(const FLAC__FileDecoder *decoder, FLAC__uint64 *position);
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.
567
* \param decoder An uninitialized decoder instance.
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.
574
FLAC_API FLAC__FileDecoderState FLAC__file_decoder_init(FLAC__FileDecoder *decoder);
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.
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().
586
* \param decoder An uninitialized decoder instance.
588
* \code decoder != NULL \endcode
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
595
FLAC_API FLAC__bool FLAC__file_decoder_finish(FLAC__FileDecoder *decoder);
597
/** This is inherited from FLAC__SeekableStreamDecoder; see
598
* FLAC__seekable_stream_decoder_process_single().
600
* \param decoder A decoder instance.
602
* \code decoder != NULL \endcode
606
FLAC_API FLAC__bool FLAC__file_decoder_process_single(FLAC__FileDecoder *decoder);
608
/** This is inherited from FLAC__SeekableStreamDecoder; see
609
* FLAC__seekable_stream_decoder_process_until_end_of_metadata().
611
* \param decoder A decoder instance.
613
* \code decoder != NULL \endcode
617
FLAC_API FLAC__bool FLAC__file_decoder_process_until_end_of_metadata(FLAC__FileDecoder *decoder);
619
/** This is inherited from FLAC__SeekableStreamDecoder; see
620
* FLAC__seekable_stream_decoder_process_until_end_of_stream().
622
* \param decoder A decoder instance.
624
* \code decoder != NULL \endcode
628
FLAC_API FLAC__bool FLAC__file_decoder_process_until_end_of_file(FLAC__FileDecoder *decoder);
630
/** This is inherited from FLAC__SeekableStreamDecoder; see
631
* FLAC__seekable_stream_decoder_skip_single_frame().
633
* \param decoder A decoder instance.
635
* \code decoder != NULL \endcode
639
FLAC_API FLAC__bool FLAC__file_decoder_skip_single_frame(FLAC__FileDecoder *decoder);
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().
645
* \param decoder A decoder instance.
646
* \param sample The target sample number to seek to.
648
* \code decoder != NULL \endcode
650
* \c true if successful, else \c false.
652
FLAC_API FLAC__bool FLAC__file_decoder_seek_absolute(FLAC__FileDecoder *decoder, FLAC__uint64 sample);
added
removed
include/FLAC/file_decoder.h
