1
/* libOggFLAC - Free Lossless Audio Codec + Ogg library
2
* Copyright (C) 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 OggFLAC__FILE_DECODER_H
33
#define OggFLAC__FILE_DECODER_H
37
#include "seekable_stream_decoder.h"
44
/** \file include/OggFLAC/file_decoder.h
47
* This module contains the functions which implement the file
50
* See the detailed documentation in the
51
* \link oggflac_file_decoder file decoder \endlink module.
54
/** \defgroup oggflac_file_decoder OggFLAC/file_decoder.h: file decoder interface
55
* \ingroup oggflac_decoder
58
* This module contains the functions which implement the file
61
* The interface here is nearly identical to FLAC's file decoder,
62
* including the callbacks, with the addition of
63
* OggFLAC__file_decoder_set_serial_number(). See the
64
* \link flac_file_decoder FLAC file decoder module \endlink
65
* for full documentation.
71
/** State values for an OggFLAC__FileDecoder
73
* The decoder's state can be obtained by calling OggFLAC__file_decoder_get_state().
77
OggFLAC__FILE_DECODER_OK = 0,
78
/**< The decoder is in the normal OK state. */
80
OggFLAC__FILE_DECODER_END_OF_FILE,
81
/**< The decoder has reached the end of the file. */
83
OggFLAC__FILE_DECODER_ERROR_OPENING_FILE,
84
/**< An error occurred opening the input file. */
86
OggFLAC__FILE_DECODER_SEEK_ERROR,
87
/**< An error occurred while seeking. */
89
OggFLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR,
90
/**< An error occurred in the underlying seekable stream decoder;
91
* check OggFLAC__file_decoder_get_seekable_stream_decoder_state().
94
OggFLAC__FILE_DECODER_MEMORY_ALLOCATION_ERROR,
95
/**< Memory allocation failed. */
97
OggFLAC__FILE_DECODER_ALREADY_INITIALIZED,
98
/**< OggFLAC__file_decoder_init() was called when the decoder was
99
* already initialized, usually because
100
* OggFLAC__file_decoder_finish() was not called.
103
OggFLAC__FILE_DECODER_INVALID_CALLBACK,
104
/**< The decoder was initialized before setting all the required callbacks. */
106
OggFLAC__FILE_DECODER_UNINITIALIZED
107
/**< The decoder is in the uninitialized state. */
109
} OggFLAC__FileDecoderState;
111
/** Maps an OggFLAC__FileDecoderState to a C string.
113
* Using an OggFLAC__FileDecoderState as the index to this array
114
* will give the string equivalent. The contents should not be modified.
116
extern OggFLAC_API const char * const OggFLAC__FileDecoderStateString[];
119
/***********************************************************************
121
* class OggFLAC__FileDecoder : public OggFLAC__SeekableStreamDecoder
123
***********************************************************************/
125
struct OggFLAC__FileDecoderProtected;
126
struct OggFLAC__FileDecoderPrivate;
127
/** The opaque structure definition for the file decoder type. See the
128
* \link oggflac_file_decoder file decoder module \endlink for a detailed
132
struct OggFLAC__FileDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
133
struct OggFLAC__FileDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
134
} OggFLAC__FileDecoder;
136
/** Signature for the write callback.
137
* See OggFLAC__file_decoder_set_write_callback()
138
* and OggFLAC__SeekableStreamDecoderWriteCallback for more info.
140
* \param decoder The decoder instance calling the callback.
141
* \param frame The description of the decoded frame.
142
* \param buffer An array of pointers to decoded channels of data.
143
* \param client_data The callee's client data set through
144
* OggFLAC__file_decoder_set_client_data().
145
* \retval FLAC__StreamDecoderWriteStatus
146
* The callee's return status.
148
typedef FLAC__StreamDecoderWriteStatus (*OggFLAC__FileDecoderWriteCallback)(const OggFLAC__FileDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
150
/** Signature for the metadata callback.
151
* See OggFLAC__file_decoder_set_metadata_callback()
152
* and OggFLAC__SeekableStreamDecoderMetadataCallback for more info.
154
* \param decoder The decoder instance calling the callback.
155
* \param metadata The decoded metadata block.
156
* \param client_data The callee's client data set through
157
* OggFLAC__file_decoder_set_client_data().
159
typedef void (*OggFLAC__FileDecoderMetadataCallback)(const OggFLAC__FileDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
161
/** Signature for the error callback.
162
* See OggFLAC__file_decoder_set_error_callback()
163
* and OggFLAC__SeekableStreamDecoderErrorCallback for more info.
165
* \param decoder The decoder instance calling the callback.
166
* \param status The error encountered by the decoder.
167
* \param client_data The callee's client data set through
168
* OggFLAC__file_decoder_set_client_data().
170
typedef void (*OggFLAC__FileDecoderErrorCallback)(const OggFLAC__FileDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
173
/***********************************************************************
175
* Class constructor/destructor
177
***********************************************************************/
179
/** Create a new file decoder instance. The instance is created with
180
* default settings; see the individual OggFLAC__file_decoder_set_*()
181
* functions for each setting's default.
183
* \retval OggFLAC__FileDecoder*
184
* \c NULL if there was an error allocating memory, else the new instance.
186
OggFLAC_API OggFLAC__FileDecoder *OggFLAC__file_decoder_new();
188
/** Free a decoder instance. Deletes the object pointed to by \a decoder.
190
* \param decoder A pointer to an existing decoder.
192
* \code decoder != NULL \endcode
194
OggFLAC_API void OggFLAC__file_decoder_delete(OggFLAC__FileDecoder *decoder);
197
/***********************************************************************
199
* Public class method prototypes
201
***********************************************************************/
203
/** Set the "MD5 signature checking" flag.
204
* This is inherited from FLAC__FileDecoder; see
205
* FLAC__file_decoder_set_md5_checking().
208
* \param decoder A decoder instance to set.
209
* \param value See above.
211
* \code decoder != NULL \endcode
213
* \c false if the decoder is already initialized, else \c true.
215
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_md5_checking(OggFLAC__FileDecoder *decoder, FLAC__bool value);
217
/** Set the input file name to decode.
218
* This is inherited from FLAC__FileDecoder; see
219
* FLAC__file_decoder_set_filename().
222
* \param decoder A decoder instance to set.
223
* \param value The input file name, or "-" for \c stdin.
225
* \code decoder != NULL \endcode
226
* \code value != NULL \endcode
228
* \c false if the decoder is already initialized, or there was a memory
229
* allocation error, else \c true.
231
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_filename(OggFLAC__FileDecoder *decoder, const char *value);
233
/** Set the write callback.
234
* This is inherited from FLAC__FileDecoder; see
235
* FLAC__file_decoder_set_write_callback().
238
* The callback is mandatory and must be set before initialization.
241
* \param decoder A decoder instance to set.
242
* \param value See above.
244
* \code decoder != NULL \endcode
245
* \code value != NULL \endcode
247
* \c false if the decoder is already initialized, else \c true.
249
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_write_callback(OggFLAC__FileDecoder *decoder, OggFLAC__FileDecoderWriteCallback value);
251
/** Set the metadata callback.
252
* This is inherited from FLAC__FileDecoder; see
253
* FLAC__file_decoder_set_metadata_callback().
256
* The callback is mandatory and must be set before initialization.
259
* \param decoder A decoder instance to set.
260
* \param value See above.
262
* \code decoder != NULL \endcode
263
* \code value != NULL \endcode
265
* \c false if the decoder is already initialized, else \c true.
267
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_metadata_callback(OggFLAC__FileDecoder *decoder, OggFLAC__FileDecoderMetadataCallback value);
269
/** Set the error callback.
270
* This is inherited from FLAC__FileDecoder; see
271
* FLAC__file_decoder_set_error_callback().
274
* The callback is mandatory and must be set before initialization.
277
* \param decoder A decoder instance to set.
278
* \param value See above.
280
* \code decoder != NULL \endcode
281
* \code value != NULL \endcode
283
* \c false if the decoder is already initialized, else \c true.
285
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_error_callback(OggFLAC__FileDecoder *decoder, OggFLAC__FileDecoderErrorCallback value);
287
/** Set the client data to be passed back to callbacks.
288
* This value will be supplied to callbacks in their \a client_data
292
* \param decoder A decoder instance to set.
293
* \param value See above.
295
* \code decoder != NULL \endcode
297
* \c false if the decoder is already initialized, else \c true.
299
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_client_data(OggFLAC__FileDecoder *decoder, void *value);
301
/** Set the serial number for the Ogg stream.
302
* The default behavior is to use the serial number of the first Ogg
303
* page. Setting a serial number here will explicitly specify which
304
* stream is to be decoded.
306
* \default \c use serial number of first page
307
* \param decoder A decoder instance to set.
308
* \param serial_number See above.
310
* \code decoder != NULL \endcode
312
* \c false if the decoder is already initialized, else \c true.
314
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_serial_number(OggFLAC__FileDecoder *decoder, long serial_number);
316
/** This is inherited from FLAC__FileDecoder; see
317
* FLAC__file_decoder_set_metadata_respond().
319
* \default By default, only the \c STREAMINFO block is returned via the
321
* \param decoder A decoder instance to set.
322
* \param type See above.
324
* \code decoder != NULL \endcode
327
* \c false if the decoder is already initialized, else \c true.
329
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_metadata_respond(OggFLAC__FileDecoder *decoder, FLAC__MetadataType type);
331
/** This is inherited from FLAC__FileDecoder; see
332
* FLAC__file_decoder_set_metadata_respond_application().
334
* \default By default, only the \c STREAMINFO block is returned via the
336
* \param decoder A decoder instance to set.
337
* \param id See above.
339
* \code decoder != NULL \endcode
340
* \code id != NULL \endcode
342
* \c false if the decoder is already initialized, else \c true.
344
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_metadata_respond_application(OggFLAC__FileDecoder *decoder, const FLAC__byte id[4]);
346
/** This is inherited from FLAC__FileDecoder; see
347
* FLAC__file_decoder_set_metadata_respond_all().
349
* \default By default, only the \c STREAMINFO block is returned via the
351
* \param decoder A decoder instance to set.
353
* \code decoder != NULL \endcode
355
* \c false if the decoder is already initialized, else \c true.
357
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_metadata_respond_all(OggFLAC__FileDecoder *decoder);
359
/** This is inherited from FLAC__FileDecoder; see
360
* FLAC__file_decoder_set_metadata_ignore().
362
* \default By default, only the \c STREAMINFO block is returned via the
364
* \param decoder A decoder instance to set.
365
* \param type See above.
367
* \code decoder != NULL \endcode
370
* \c false if the decoder is already initialized, else \c true.
372
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_metadata_ignore(OggFLAC__FileDecoder *decoder, FLAC__MetadataType type);
374
/** This is inherited from FLAC__FileDecoder; see
375
* FLAC__file_decoder_set_metadata_ignore_application().
377
* \default By default, only the \c STREAMINFO block is returned via the
379
* \param decoder A decoder instance to set.
380
* \param id See above.
382
* \code decoder != NULL \endcode
383
* \code id != NULL \endcode
385
* \c false if the decoder is already initialized, else \c true.
387
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_metadata_ignore_application(OggFLAC__FileDecoder *decoder, const FLAC__byte id[4]);
389
/** This is inherited from FLAC__FileDecoder; see
390
* FLAC__file_decoder_set_metadata_ignore_all().
392
* \default By default, only the \c STREAMINFO block is returned via the
394
* \param decoder A decoder instance to set.
396
* \code decoder != NULL \endcode
398
* \c false if the decoder is already initialized, else \c true.
400
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_metadata_ignore_all(OggFLAC__FileDecoder *decoder);
402
/** Get the current decoder state.
404
* \param decoder A decoder instance to query.
406
* \code decoder != NULL \endcode
407
* \retval OggFLAC__FileDecoderState
408
* The current decoder state.
410
OggFLAC_API OggFLAC__FileDecoderState OggFLAC__file_decoder_get_state(const OggFLAC__FileDecoder *decoder);
412
/** Get the state of the underlying seekable stream decoder.
413
* Useful when the file decoder state is
414
* \c OggFLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR.
416
* \param decoder A decoder instance to query.
418
* \code decoder != NULL \endcode
419
* \retval FLAC__FileDecoderState
420
* The seekable stream decoder state.
422
OggFLAC_API OggFLAC__SeekableStreamDecoderState OggFLAC__file_decoder_get_seekable_stream_decoder_state(const OggFLAC__FileDecoder *decoder);
424
/** Get the state of the underlying stream decoder.
425
* Useful when the file decoder state is
426
* \c OggFLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR
427
* and the seekable stream decoder state is
428
* \c OggFLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
430
* \param decoder A decoder instance to query.
432
* \code decoder != NULL \endcode
433
* \retval OggFLAC__StreamDecoderState
434
* The stream decoder state.
436
OggFLAC_API OggFLAC__StreamDecoderState OggFLAC__file_decoder_get_stream_decoder_state(const OggFLAC__FileDecoder *decoder);
438
/** Get the state of the underlying FLAC stream decoder.
439
* Useful when the file decoder state is
440
* \c OggFLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR
441
* and the seekable stream decoder state is
442
* \c OggFLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR
443
* and the stream decoder state is
444
* \c OggFLAC__STREAM_DECODER_FLAC_STREAM_DECODER_ERROR.
446
* \param decoder A decoder instance to query.
448
* \code decoder != NULL \endcode
449
* \retval FLAC__StreamDecoderState
450
* The FLAC stream decoder state.
452
OggFLAC_API FLAC__StreamDecoderState OggFLAC__file_decoder_get_FLAC_stream_decoder_state(const OggFLAC__FileDecoder *decoder);
454
/** Get the current decoder state as a C string.
455
* This version automatically resolves
456
* \c OggFLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR
457
* by getting the seekable stream decoder's state.
459
* \param decoder A decoder instance to query.
461
* \code decoder != NULL \endcode
462
* \retval const char *
463
* The decoder state as a C string. Do not modify the contents.
465
OggFLAC_API const char *OggFLAC__file_decoder_get_resolved_state_string(const OggFLAC__FileDecoder *decoder);
467
/** This is inherited from FLAC__FileDecoder; see
468
* FLAC__file_decoder_get_md5_checking().
470
* \param decoder A decoder instance to query.
472
* \code decoder != NULL \endcode
476
OggFLAC_API FLAC__bool OggFLAC__file_decoder_get_md5_checking(const OggFLAC__FileDecoder *decoder);
478
/** This is inherited from FLAC__FileDecoder; see
479
* FLAC__file_decoder_get_channels().
481
* \param decoder A decoder instance to query.
483
* \code decoder != NULL \endcode
487
OggFLAC_API unsigned OggFLAC__file_decoder_get_channels(const OggFLAC__FileDecoder *decoder);
489
/** This is inherited from FLAC__FileDecoder; see
490
* FLAC__file_decoder_get_channel_assignment().
492
* \param decoder A decoder instance to query.
494
* \code decoder != NULL \endcode
495
* \retval OggFLAC__ChannelAssignment
498
OggFLAC_API FLAC__ChannelAssignment OggFLAC__file_decoder_get_channel_assignment(const OggFLAC__FileDecoder *decoder);
500
/** This is inherited from FLAC__FileDecoder; see
501
* FLAC__file_decoder_get_bits_per_sample().
503
* \param decoder A decoder instance to query.
505
* \code decoder != NULL \endcode
509
OggFLAC_API unsigned OggFLAC__file_decoder_get_bits_per_sample(const OggFLAC__FileDecoder *decoder);
511
/** This is inherited from FLAC__FileDecoder; see
512
* FLAC__file_decoder_get_sample_rate().
514
* \param decoder A decoder instance to query.
516
* \code decoder != NULL \endcode
520
OggFLAC_API unsigned OggFLAC__file_decoder_get_sample_rate(const OggFLAC__FileDecoder *decoder);
522
/** This is inherited from FLAC__FileDecoder; see
523
* FLAC__file_decoder_get_blocksize().
525
* \param decoder A decoder instance to query.
527
* \code decoder != NULL \endcode
531
OggFLAC_API unsigned OggFLAC__file_decoder_get_blocksize(const OggFLAC__FileDecoder *decoder);
533
/** Initialize the decoder instance.
534
* Should be called after OggFLAC__file_decoder_new() and
535
* OggFLAC__file_decoder_set_*() but before any of the
536
* OggFLAC__file_decoder_process_*() functions. Will set and return
537
* the decoder state, which will be OggFLAC__FILE_DECODER_OK if
538
* initialization succeeded.
540
* \param decoder An uninitialized decoder instance.
542
* \code decoder != NULL \endcode
543
* \retval OggFLAC__FileDecoderState
544
* \c OggFLAC__FILE_DECODER_OK if initialization was successful; see
545
* OggFLAC__FileDecoderState for the meanings of other return values.
547
OggFLAC_API OggFLAC__FileDecoderState OggFLAC__file_decoder_init(OggFLAC__FileDecoder *decoder);
549
/** Finish the decoding process.
550
* Flushes the decoding buffer, releases resources, resets the decoder
551
* settings to their defaults, and returns the decoder state to
552
* OggFLAC__FILE_DECODER_UNINITIALIZED.
554
* In the event of a prematurely-terminated decode, it is not strictly
555
* necessary to call this immediately before OggFLAC__file_decoder_delete()
556
* but it is good practice to match every OggFLAC__file_decoder_init() with
557
* an OggFLAC__file_decoder_finish().
559
* \param decoder An uninitialized decoder instance.
561
* \code decoder != NULL \endcode
563
* \c false if MD5 checking is on AND a STREAMINFO block was available
564
* AND the MD5 signature in the STREAMINFO block was non-zero AND the
565
* signature does not match the one computed by the decoder; else
568
OggFLAC_API FLAC__bool OggFLAC__file_decoder_finish(OggFLAC__FileDecoder *decoder);
570
/** This is inherited from FLAC__FileDecoder; see
571
* FLAC__file_decoder_process_single().
573
* \param decoder A decoder instance.
575
* \code decoder != NULL \endcode
579
OggFLAC_API FLAC__bool OggFLAC__file_decoder_process_single(OggFLAC__FileDecoder *decoder);
581
/** This is inherited from FLAC__FileDecoder; see
582
* FLAC__file_decoder_process_until_end_of_metadata().
584
* \param decoder A decoder instance.
586
* \code decoder != NULL \endcode
590
OggFLAC_API FLAC__bool OggFLAC__file_decoder_process_until_end_of_metadata(OggFLAC__FileDecoder *decoder);
592
/** This is inherited from FLAC__FileDecoder; see
593
* FLAC__file_decoder_process_until_end_of_stream().
595
* \param decoder A decoder instance.
597
* \code decoder != NULL \endcode
601
OggFLAC_API FLAC__bool OggFLAC__file_decoder_process_until_end_of_file(OggFLAC__FileDecoder *decoder);
603
/** This is inherited from OggFLAC__SeekableStreamDecoder; see
604
* OggFLAC__seekable_stream_decoder_seek_absolute().
606
* \param decoder A decoder instance.
607
* \param sample The target sample number to seek to.
609
* \code decoder != NULL \endcode
611
* \c true if successful, else \c false.
613
OggFLAC_API FLAC__bool OggFLAC__file_decoder_seek_absolute(OggFLAC__FileDecoder *decoder, FLAC__uint64 sample);
added
removed
include/OggFLAC/file_decoder.h
