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__SEEKABLE_STREAM_DECODER_H
33
#define FLAC__SEEKABLE_STREAM_DECODER_H
36
#include "stream_decoder.h"
43
/** \file include/FLAC/seekable_stream_decoder.h
46
* This module contains the functions which implement the seekable stream
49
* See the detailed documentation in the
50
* \link flac_seekable_stream_decoder seekable stream decoder \endlink module.
53
/** \defgroup flac_seekable_stream_decoder FLAC/seekable_stream_decoder.h: seekable stream decoder interface
54
* \ingroup flac_decoder
57
* This module contains the functions which implement the seekable stream
60
* The basic usage of this decoder is as follows:
61
* - The program creates an instance of a decoder using
62
* FLAC__seekable_stream_decoder_new().
63
* - The program overrides the default settings and sets callbacks for
64
* reading, writing, seeking, error reporting, and metadata reporting
65
* using FLAC__seekable_stream_decoder_set_*() functions.
66
* - The program initializes the instance to validate the settings and
67
* prepare for decoding using FLAC__seekable_stream_decoder_init().
68
* - The program calls the FLAC__seekable_stream_decoder_process_*()
69
* functions to decode data, which subsequently calls the callbacks.
70
* - The program finishes the decoding with
71
* FLAC__seekable_stream_decoder_finish(), which flushes the input and
72
* output and resets the decoder to the uninitialized state.
73
* - The instance may be used again or deleted with
74
* FLAC__seekable_stream_decoder_delete().
76
* The seekable stream decoder is a wrapper around the
77
* \link flac_stream_decoder stream decoder \endlink which also provides
78
* seeking capability. In addition to the Read/Write/Metadata/Error
79
* callbacks of the stream decoder, the user must also provide the following:
81
* - Seek callback - This function will be called when the decoder wants to
82
* seek to an absolute position in the stream.
83
* - Tell callback - This function will be called when the decoder wants to
84
* know the current absolute position of the stream.
85
* - Length callback - This function will be called when the decoder wants
86
* to know length of the stream. The seeking algorithm currently requires
87
* that the overall stream length be known.
88
* - EOF callback - This function will be called when the decoder wants to
89
* know if it is at the end of the stream. This could be synthesized from
90
* the tell and length callbacks but it may be more expensive that way, so
91
* there is a separate callback for it.
93
* Seeking is exposed through the
94
* FLAC__seekable_stream_decoder_seek_absolute() method. At any point after
95
* the seekable stream decoder has been initialized, the user can call this
96
* function to seek to an exact sample within the stream. Subsequently, the
97
* first time the write callback is called it will be passed a (possibly
98
* partial) block starting at that sample.
100
* The seekable stream decoder also provides MD5 signature checking. If
101
* this is turned on before initialization,
102
* FLAC__seekable_stream_decoder_finish() will report when the decoded MD5
103
* signature does not match the one stored in the STREAMINFO block. MD5
104
* checking is automatically turned off (until the next
105
* FLAC__seekable_stream_decoder_reset()) if there is no signature in the
106
* STREAMINFO block or when a seek is attempted.
108
* Make sure to read the detailed description of the
109
* \link flac_stream_decoder stream decoder module \endlink since the
110
* seekable stream decoder inherits much of its behavior.
113
* The "set" functions may only be called when the decoder is in the
114
* state FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED, i.e. after
115
* FLAC__seekable_stream_decoder_new() or
116
* FLAC__seekable_stream_decoder_finish(), but before
117
* FLAC__seekable_stream_decoder_init(). If this is the case they will
118
* return \c true, otherwise \c false.
121
* FLAC__stream_decoder_finish() resets all settings to the constructor
122
* defaults, including the callbacks.
128
/** State values for a FLAC__SeekableStreamDecoder
130
* The decoder's state can be obtained by calling FLAC__seekable_stream_decoder_get_state().
134
FLAC__SEEKABLE_STREAM_DECODER_OK = 0,
135
/**< The decoder is in the normal OK state. */
137
FLAC__SEEKABLE_STREAM_DECODER_SEEKING,
138
/**< The decoder is in the process of seeking. */
140
FLAC__SEEKABLE_STREAM_DECODER_END_OF_STREAM,
141
/**< The decoder has reached the end of the stream. */
143
FLAC__SEEKABLE_STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
144
/**< An error occurred allocating memory. */
146
FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR,
147
/**< An error occurred in the underlying stream decoder. */
149
FLAC__SEEKABLE_STREAM_DECODER_READ_ERROR,
150
/**< The read callback returned an error. */
152
FLAC__SEEKABLE_STREAM_DECODER_SEEK_ERROR,
153
/**< An error occurred while seeking or the seek or tell
154
* callback returned an error.
157
FLAC__SEEKABLE_STREAM_DECODER_ALREADY_INITIALIZED,
158
/**< FLAC__seekable_stream_decoder_init() was called when the
159
* decoder was already initialized, usually because
160
* FLAC__seekable_stream_decoder_finish() was not called.
163
FLAC__SEEKABLE_STREAM_DECODER_INVALID_CALLBACK,
164
/**< FLAC__seekable_stream_decoder_init() was called without all
165
* callbacks being set.
168
FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED
169
/**< The decoder is in the uninitialized state. */
171
} FLAC__SeekableStreamDecoderState;
173
/** Maps a FLAC__SeekableStreamDecoderState to a C string.
175
* Using a FLAC__SeekableStreamDecoderState as the index to this array
176
* will give the string equivalent. The contents should not be modified.
178
extern FLAC_API const char * const FLAC__SeekableStreamDecoderStateString[];
181
/** Return values for the FLAC__SeekableStreamDecoder read callback.
185
FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_OK,
186
/**< The read was OK and decoding can continue. */
188
FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_ERROR
189
/**< An unrecoverable error occurred. The decoder will return from the process call. */
191
} FLAC__SeekableStreamDecoderReadStatus;
193
/** Maps a FLAC__SeekableStreamDecoderReadStatus to a C string.
195
* Using a FLAC__SeekableStreamDecoderReadStatus as the index to this array
196
* will give the string equivalent. The contents should not be modified.
198
extern FLAC_API const char * const FLAC__SeekableStreamDecoderReadStatusString[];
201
/** Return values for the FLAC__SeekableStreamDecoder seek callback.
205
FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_OK,
206
/**< The seek was OK and decoding can continue. */
208
FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_ERROR
209
/**< An unrecoverable error occurred. The decoder will return from the process call. */
211
} FLAC__SeekableStreamDecoderSeekStatus;
213
/** Maps a FLAC__SeekableStreamDecoderSeekStatus to a C string.
215
* Using a FLAC__SeekableStreamDecoderSeekStatus as the index to this array
216
* will give the string equivalent. The contents should not be modified.
218
extern FLAC_API const char * const FLAC__SeekableStreamDecoderSeekStatusString[];
221
/** Return values for the FLAC__SeekableStreamDecoder tell callback.
225
FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_OK,
226
/**< The tell was OK and decoding can continue. */
228
FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_ERROR
229
/**< An unrecoverable error occurred. The decoder will return from the process call. */
231
} FLAC__SeekableStreamDecoderTellStatus;
233
/** Maps a FLAC__SeekableStreamDecoderTellStatus to a C string.
235
* Using a FLAC__SeekableStreamDecoderTellStatus as the index to this array
236
* will give the string equivalent. The contents should not be modified.
238
extern FLAC_API const char * const FLAC__SeekableStreamDecoderTellStatusString[];
241
/** Return values for the FLAC__SeekableStreamDecoder length callback.
245
FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_OK,
246
/**< The length call was OK and decoding can continue. */
248
FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_ERROR
249
/**< An unrecoverable error occurred. The decoder will return from the process call. */
251
} FLAC__SeekableStreamDecoderLengthStatus;
253
/** Maps a FLAC__SeekableStreamDecoderLengthStatus to a C string.
255
* Using a FLAC__SeekableStreamDecoderLengthStatus as the index to this array
256
* will give the string equivalent. The contents should not be modified.
258
extern FLAC_API const char * const FLAC__SeekableStreamDecoderLengthStatusString[];
261
/***********************************************************************
263
* class FLAC__SeekableStreamDecoder : public FLAC__StreamDecoder
265
***********************************************************************/
267
struct FLAC__SeekableStreamDecoderProtected;
268
struct FLAC__SeekableStreamDecoderPrivate;
269
/** The opaque structure definition for the seekable stream decoder type.
271
* \link flac_seekable_stream_decoder seekable stream decoder module \endlink
272
* for a detailed description.
275
struct FLAC__SeekableStreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
276
struct FLAC__SeekableStreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
277
} FLAC__SeekableStreamDecoder;
279
/** Signature for the read callback.
280
* See FLAC__seekable_stream_decoder_set_read_callback()
281
* and FLAC__StreamDecoderReadCallback for more info.
283
* \param decoder The decoder instance calling the callback.
284
* \param buffer A pointer to a location for the callee to store
285
* data to be decoded.
286
* \param bytes A pointer to the size of the buffer.
287
* \param client_data The callee's client data set through
288
* FLAC__seekable_stream_decoder_set_client_data().
289
* \retval FLAC__SeekableStreamDecoderReadStatus
290
* The callee's return status.
292
typedef FLAC__SeekableStreamDecoderReadStatus (*FLAC__SeekableStreamDecoderReadCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
294
/** Signature for the seek callback.
295
* See FLAC__seekable_stream_decoder_set_seek_callback() for more info.
297
* \param decoder The decoder instance calling the callback.
298
* \param absolute_byte_offset The offset from the beginning of the stream
300
* \param client_data The callee's client data set through
301
* FLAC__seekable_stream_decoder_set_client_data().
302
* \retval FLAC__SeekableStreamDecoderSeekStatus
303
* The callee's return status.
305
typedef FLAC__SeekableStreamDecoderSeekStatus (*FLAC__SeekableStreamDecoderSeekCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
307
/** Signature for the tell callback.
308
* See FLAC__seekable_stream_decoder_set_tell_callback() for more info.
310
* \param decoder The decoder instance calling the callback.
311
* \param absolute_byte_offset A pointer to storage for the current offset
312
* from the beginning of the stream.
313
* \param client_data The callee's client data set through
314
* FLAC__seekable_stream_decoder_set_client_data().
315
* \retval FLAC__SeekableStreamDecoderTellStatus
316
* The callee's return status.
318
typedef FLAC__SeekableStreamDecoderTellStatus (*FLAC__SeekableStreamDecoderTellCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
320
/** Signature for the length callback.
321
* See FLAC__seekable_stream_decoder_set_length_callback() for more info.
323
* \param decoder The decoder instance calling the callback.
324
* \param stream_length A pointer to storage for the length of the stream
326
* \param client_data The callee's client data set through
327
* FLAC__seekable_stream_decoder_set_client_data().
328
* \retval FLAC__SeekableStreamDecoderLengthStatus
329
* The callee's return status.
331
typedef FLAC__SeekableStreamDecoderLengthStatus (*FLAC__SeekableStreamDecoderLengthCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
333
/** Signature for the EOF callback.
334
* See FLAC__seekable_stream_decoder_set_eof_callback() for more info.
336
* \param decoder The decoder instance calling the callback.
337
* \param client_data The callee's client data set through
338
* FLAC__seekable_stream_decoder_set_client_data().
340
* \c true if the currently at the end of the stream, else \c false.
342
typedef FLAC__bool (*FLAC__SeekableStreamDecoderEofCallback)(const FLAC__SeekableStreamDecoder *decoder, void *client_data);
344
/** Signature for the write callback.
345
* See FLAC__seekable_stream_decoder_set_write_callback()
346
* and FLAC__StreamDecoderWriteCallback for more info.
348
* \param decoder The decoder instance calling the callback.
349
* \param frame The description of the decoded frame.
350
* \param buffer An array of pointers to decoded channels of data.
351
* \param client_data The callee's client data set through
352
* FLAC__seekable_stream_decoder_set_client_data().
353
* \retval FLAC__StreamDecoderWriteStatus
354
* The callee's return status.
356
typedef FLAC__StreamDecoderWriteStatus (*FLAC__SeekableStreamDecoderWriteCallback)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
358
/** Signature for the metadata callback.
359
* See FLAC__seekable_stream_decoder_set_metadata_callback()
360
* and FLAC__StreamDecoderMetadataCallback for more info.
362
* \param decoder The decoder instance calling the callback.
363
* \param metadata The decoded metadata block.
364
* \param client_data The callee's client data set through
365
* FLAC__seekable_stream_decoder_set_client_data().
367
typedef void (*FLAC__SeekableStreamDecoderMetadataCallback)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
369
/** Signature for the error callback.
370
* See FLAC__seekable_stream_decoder_set_error_callback()
371
* and FLAC__StreamDecoderErrorCallback for more info.
373
* \param decoder The decoder instance calling the callback.
374
* \param status The error encountered by the decoder.
375
* \param client_data The callee's client data set through
376
* FLAC__seekable_stream_decoder_set_client_data().
378
typedef void (*FLAC__SeekableStreamDecoderErrorCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
381
/***********************************************************************
383
* Class constructor/destructor
385
***********************************************************************/
387
/** Create a new seekable stream decoder instance. The instance is created
388
* with default settings; see the individual
389
* FLAC__seekable_stream_decoder_set_*() functions for each setting's
392
* \retval FLAC__SeekableStreamDecoder*
393
* \c NULL if there was an error allocating memory, else the new instance.
395
FLAC_API FLAC__SeekableStreamDecoder *FLAC__seekable_stream_decoder_new();
397
/** Free a decoder instance. Deletes the object pointed to by \a decoder.
399
* \param decoder A pointer to an existing decoder.
401
* \code decoder != NULL \endcode
403
FLAC_API void FLAC__seekable_stream_decoder_delete(FLAC__SeekableStreamDecoder *decoder);
406
/***********************************************************************
408
* Public class method prototypes
410
***********************************************************************/
412
/** Set the "MD5 signature checking" flag. If \c true, the decoder will
413
* compute the MD5 signature of the unencoded audio data while decoding
414
* and compare it to the signature from the STREAMINFO block, if it
415
* exists, during FLAC__seekable_stream_decoder_finish().
417
* MD5 signature checking will be turned off (until the next
418
* FLAC__seekable_stream_decoder_reset()) if there is no signature in
419
* the STREAMINFO block or when a seek is attempted.
422
* \param decoder A decoder instance to set.
423
* \param value Flag value (see above).
425
* \code decoder != NULL \endcode
427
* \c false if the decoder is already initialized, else \c true.
429
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_md5_checking(FLAC__SeekableStreamDecoder *decoder, FLAC__bool value);
431
/** Set the read callback.
432
* This is inherited from FLAC__StreamDecoder; see
433
* FLAC__stream_decoder_set_read_callback().
436
* The callback is mandatory and must be set before initialization.
439
* \param decoder A decoder instance to set.
440
* \param value See above.
442
* \code decoder != NULL \endcode
443
* \code value != NULL \endcode
445
* \c false if the decoder is already initialized, else \c true.
447
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_read_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderReadCallback value);
449
/** Set the seek callback.
450
* The supplied function will be called when the decoder needs to seek
451
* the input stream. The decoder will pass the absolute byte offset
452
* to seek to, 0 meaning the beginning of the stream.
455
* The callback is mandatory and must be set before initialization.
458
* \param decoder A decoder instance to set.
459
* \param value See above.
461
* \code decoder != NULL \endcode
462
* \code value != NULL \endcode
464
* \c false if the decoder is already initialized, else \c true.
466
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_seek_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderSeekCallback value);
468
/** Set the tell callback.
469
* The supplied function will be called when the decoder wants to know
470
* the current position of the stream. The callback should return the
471
* byte offset from the beginning of the stream.
474
* The callback is mandatory and must be set before initialization.
477
* \param decoder A decoder instance to set.
478
* \param value See above.
480
* \code decoder != NULL \endcode
481
* \code value != NULL \endcode
483
* \c false if the decoder is already initialized, else \c true.
485
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_tell_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderTellCallback value);
487
/** Set the length callback.
488
* The supplied function will be called when the decoder wants to know
489
* the total length of the stream in bytes.
492
* The callback is mandatory and must be set before initialization.
495
* \param decoder A decoder instance to set.
496
* \param value See above.
498
* \code decoder != NULL \endcode
499
* \code value != NULL \endcode
501
* \c false if the decoder is already initialized, else \c true.
503
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_length_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderLengthCallback value);
505
/** Set the eof callback.
506
* The supplied function will be called when the decoder needs to know
507
* if the end of the stream has been reached.
510
* The callback is mandatory and must be set before initialization.
513
* \param decoder A decoder instance to set.
514
* \param value See above.
516
* \code decoder != NULL \endcode
517
* \code value != NULL \endcode
519
* \c false if the decoder is already initialized, else \c true.
521
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_eof_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderEofCallback value);
523
/** Set the write callback.
524
* This is inherited from FLAC__StreamDecoder; see
525
* FLAC__stream_decoder_set_write_callback().
528
* The callback is mandatory and must be set before initialization.
531
* \param decoder A decoder instance to set.
532
* \param value See above.
534
* \code decoder != NULL \endcode
535
* \code value != NULL \endcode
537
* \c false if the decoder is already initialized, else \c true.
539
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_write_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderWriteCallback value);
541
/** Set the metadata callback.
542
* This is inherited from FLAC__StreamDecoder; see
543
* FLAC__stream_decoder_set_metadata_callback().
546
* The callback is mandatory and must be set before initialization.
549
* \param decoder A decoder instance to set.
550
* \param value See above.
552
* \code decoder != NULL \endcode
553
* \code value != NULL \endcode
555
* \c false if the decoder is already initialized, else \c true.
557
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderMetadataCallback value);
559
/** Set the error callback.
560
* This is inherited from FLAC__StreamDecoder; see
561
* FLAC__stream_decoder_set_error_callback().
564
* The callback is mandatory and must be set before initialization.
567
* \param decoder A decoder instance to set.
568
* \param value See above.
570
* \code decoder != NULL \endcode
571
* \code value != NULL \endcode
573
* \c false if the decoder is already initialized, else \c true.
575
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_error_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderErrorCallback value);
577
/** Set the client data to be passed back to callbacks.
578
* This value will be supplied to callbacks in their \a client_data
582
* \param decoder A decoder instance to set.
583
* \param value See above.
585
* \code decoder != NULL \endcode
587
* \c false if the decoder is already initialized, else \c true.
589
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_client_data(FLAC__SeekableStreamDecoder *decoder, void *value);
591
/** This is inherited from FLAC__StreamDecoder; see
592
* FLAC__stream_decoder_set_metadata_respond().
594
* \default By default, only the \c STREAMINFO block is returned via the
596
* \param decoder A decoder instance to set.
597
* \param type See above.
599
* \code decoder != NULL \endcode
602
* \c false if the decoder is already initialized, else \c true.
604
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond(FLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type);
606
/** This is inherited from FLAC__StreamDecoder; see
607
* FLAC__stream_decoder_set_metadata_respond_application().
609
* \default By default, only the \c STREAMINFO block is returned via the
611
* \param decoder A decoder instance to set.
612
* \param id See above.
614
* \code decoder != NULL \endcode
615
* \code id != NULL \endcode
617
* \c false if the decoder is already initialized, else \c true.
619
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond_application(FLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
621
/** This is inherited from FLAC__StreamDecoder; see
622
* FLAC__stream_decoder_set_metadata_respond_all().
624
* \default By default, only the \c STREAMINFO block is returned via the
626
* \param decoder A decoder instance to set.
628
* \code decoder != NULL \endcode
630
* \c false if the decoder is already initialized, else \c true.
632
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond_all(FLAC__SeekableStreamDecoder *decoder);
634
/** This is inherited from FLAC__StreamDecoder; see
635
* FLAC__stream_decoder_set_metadata_ignore().
637
* \default By default, only the \c STREAMINFO block is returned via the
639
* \param decoder A decoder instance to set.
640
* \param type See above.
642
* \code decoder != NULL \endcode
645
* \c false if the decoder is already initialized, else \c true.
647
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore(FLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type);
649
/** This is inherited from FLAC__StreamDecoder; see
650
* FLAC__stream_decoder_set_metadata_ignore_application().
652
* \default By default, only the \c STREAMINFO block is returned via the
654
* \param decoder A decoder instance to set.
655
* \param id See above.
657
* \code decoder != NULL \endcode
658
* \code id != NULL \endcode
660
* \c false if the decoder is already initialized, else \c true.
662
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore_application(FLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
664
/** This is inherited from FLAC__StreamDecoder; see
665
* FLAC__stream_decoder_set_metadata_ignore_all().
667
* \default By default, only the \c STREAMINFO block is returned via the
669
* \param decoder A decoder instance to set.
671
* \code decoder != NULL \endcode
673
* \c false if the decoder is already initialized, else \c true.
675
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore_all(FLAC__SeekableStreamDecoder *decoder);
677
/** Get the current decoder state.
679
* \param decoder A decoder instance to query.
681
* \code decoder != NULL \endcode
682
* \retval FLAC__SeekableStreamDecoderState
683
* The current decoder state.
685
FLAC_API FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_get_state(const FLAC__SeekableStreamDecoder *decoder);
687
/** Get the state of the underlying stream decoder.
688
* Useful when the seekable stream decoder state is
689
* \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
691
* \param decoder A decoder instance to query.
693
* \code decoder != NULL \endcode
694
* \retval FLAC__StreamDecoderState
695
* The stream decoder state.
697
FLAC_API FLAC__StreamDecoderState FLAC__seekable_stream_decoder_get_stream_decoder_state(const FLAC__SeekableStreamDecoder *decoder);
699
/** Get the current decoder state as a C string.
700
* This version automatically resolves
701
* \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR by getting the
702
* stream decoder's state.
704
* \param decoder A decoder instance to query.
706
* \code decoder != NULL \endcode
707
* \retval const char *
708
* The decoder state as a C string. Do not modify the contents.
710
FLAC_API const char *FLAC__seekable_stream_decoder_get_resolved_state_string(const FLAC__SeekableStreamDecoder *decoder);
712
/** Get the "MD5 signature checking" flag.
713
* This is the value of the setting, not whether or not the decoder is
714
* currently checking the MD5 (remember, it can be turned off automatically
715
* by a seek). When the decoder is reset the flag will be restored to the
716
* value returned by this function.
718
* \param decoder A decoder instance to query.
720
* \code decoder != NULL \endcode
724
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_get_md5_checking(const FLAC__SeekableStreamDecoder *decoder);
726
/** This is inherited from FLAC__StreamDecoder; see
727
* FLAC__stream_decoder_get_channels().
729
* \param decoder A decoder instance to query.
731
* \code decoder != NULL \endcode
735
FLAC_API unsigned FLAC__seekable_stream_decoder_get_channels(const FLAC__SeekableStreamDecoder *decoder);
737
/** This is inherited from FLAC__StreamDecoder; see
738
* FLAC__stream_decoder_get_channel_assignment().
740
* \param decoder A decoder instance to query.
742
* \code decoder != NULL \endcode
743
* \retval FLAC__ChannelAssignment
746
FLAC_API FLAC__ChannelAssignment FLAC__seekable_stream_decoder_get_channel_assignment(const FLAC__SeekableStreamDecoder *decoder);
748
/** This is inherited from FLAC__StreamDecoder; see
749
* FLAC__stream_decoder_get_bits_per_sample().
751
* \param decoder A decoder instance to query.
753
* \code decoder != NULL \endcode
757
FLAC_API unsigned FLAC__seekable_stream_decoder_get_bits_per_sample(const FLAC__SeekableStreamDecoder *decoder);
759
/** This is inherited from FLAC__StreamDecoder; see
760
* FLAC__stream_decoder_get_sample_rate().
762
* \param decoder A decoder instance to query.
764
* \code decoder != NULL \endcode
768
FLAC_API unsigned FLAC__seekable_stream_decoder_get_sample_rate(const FLAC__SeekableStreamDecoder *decoder);
770
/** This is inherited from FLAC__StreamDecoder; see
771
* FLAC__stream_decoder_get_blocksize().
773
* \param decoder A decoder instance to query.
775
* \code decoder != NULL \endcode
779
FLAC_API unsigned FLAC__seekable_stream_decoder_get_blocksize(const FLAC__SeekableStreamDecoder *decoder);
781
/** Returns the decoder's current read position within the stream.
782
* The position is the byte offset from the start of the stream.
783
* Bytes before this position have been fully decoded. Note that
784
* there may still be undecoded bytes in the decoder's read FIFO.
785
* The returned position is correct even after a seek.
787
* \param decoder A decoder instance to query.
788
* \param position Address at which to return the desired position.
790
* \code decoder != NULL \endcode
791
* \code position != NULL \endcode
793
* \c true if successful, \c false if there was an error from
794
* the 'tell' callback.
796
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_get_decode_position(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *position);
798
/** Initialize the decoder instance.
799
* Should be called after FLAC__seekable_stream_decoder_new() and
800
* FLAC__seekable_stream_decoder_set_*() but before any of the
801
* FLAC__seekable_stream_decoder_process_*() functions. Will set and return
802
* the decoder state, which will be FLAC__SEEKABLE_STREAM_DECODER_OK
803
* if initialization succeeded.
805
* \param decoder An uninitialized decoder instance.
807
* \code decoder != NULL \endcode
808
* \retval FLAC__SeekableStreamDecoderState
809
* \c FLAC__SEEKABLE_STREAM_DECODER_OK if initialization was
810
* successful; see FLAC__SeekableStreamDecoderState for the meanings
811
* of other return values.
813
FLAC_API FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_init(FLAC__SeekableStreamDecoder *decoder);
815
/** Finish the decoding process.
816
* Flushes the decoding buffer, releases resources, resets the decoder
817
* settings to their defaults, and returns the decoder state to
818
* FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED.
820
* In the event of a prematurely-terminated decode, it is not strictly
821
* necessary to call this immediately before
822
* FLAC__seekable_stream_decoder_delete() but it is good practice to match
823
* every FLAC__seekable_stream_decoder_init() with a
824
* FLAC__seekable_stream_decoder_finish().
826
* \param decoder An uninitialized decoder instance.
828
* \code decoder != NULL \endcode
830
* \c false if MD5 checking is on AND a STREAMINFO block was available
831
* AND the MD5 signature in the STREAMINFO block was non-zero AND the
832
* signature does not match the one computed by the decoder; else
835
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_finish(FLAC__SeekableStreamDecoder *decoder);
837
/** Flush the stream input.
838
* The decoder's input buffer will be cleared and the state set to
839
* \c FLAC__SEEKABLE_STREAM_DECODER_OK. This will also turn off MD5
842
* \param decoder A decoder instance.
844
* \code decoder != NULL \endcode
846
* \c true if successful, else \c false if a memory allocation
847
* or stream decoder error occurs.
849
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_flush(FLAC__SeekableStreamDecoder *decoder);
851
/** Reset the decoding process.
852
* The decoder's input buffer will be cleared and the state set to
853
* \c FLAC__SEEKABLE_STREAM_DECODER_OK. This is similar to
854
* FLAC__seekable_stream_decoder_finish() except that the settings are
855
* preserved; there is no need to call FLAC__seekable_stream_decoder_init()
856
* before decoding again. MD5 checking will be restored to its original
859
* \param decoder A decoder instance.
861
* \code decoder != NULL \endcode
863
* \c true if successful, else \c false if a memory allocation
864
* or stream decoder error occurs.
866
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_reset(FLAC__SeekableStreamDecoder *decoder);
868
/** This is inherited from FLAC__StreamDecoder; see
869
* FLAC__stream_decoder_process_single().
871
* \param decoder A decoder instance.
873
* \code decoder != NULL \endcode
877
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_single(FLAC__SeekableStreamDecoder *decoder);
879
/** This is inherited from FLAC__StreamDecoder; see
880
* FLAC__stream_decoder_process_until_end_of_metadata().
882
* \param decoder A decoder instance.
884
* \code decoder != NULL \endcode
888
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_metadata(FLAC__SeekableStreamDecoder *decoder);
890
/** This is inherited from FLAC__StreamDecoder; see
891
* FLAC__stream_decoder_process_until_end_of_stream().
893
* \param decoder A decoder instance.
895
* \code decoder != NULL \endcode
899
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_stream(FLAC__SeekableStreamDecoder *decoder);
901
/** This is inherited from FLAC__StreamDecoder; see
902
* FLAC__stream_decoder_skip_single_frame().
904
* \param decoder A decoder instance.
906
* \code decoder != NULL \endcode
910
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_skip_single_frame(FLAC__SeekableStreamDecoder *decoder);
912
/** Flush the input and seek to an absolute sample.
913
* Decoding will resume at the given sample. Note that because of
914
* this, the next write callback may contain a partial block.
916
* \param decoder A decoder instance.
917
* \param sample The target sample number to seek to.
919
* \code decoder != NULL \endcode
921
* \c true if successful, else \c false.
923
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_seek_absolute(FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 sample);
added
removed
include/FLAC/seekable_stream_decoder.h
