seekable_stream_decoder.h - vx32 - Local 9vx git repository for patches.
(HTM) git clone git://r-36.net/vx32
(DIR) Log
(DIR) Files
(DIR) Refs
---
seekable_stream_decoder.h (36903B)
---
1 /* libFLAC - Free Lossless Audio Codec library
2 * Copyright (C) 2000,2001,2002,2003,2004,2005 Josh Coalson
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
6 * are met:
7 *
8 * - Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
10 *
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.
14 *
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.
18 *
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.
30 */
31
32 #ifndef FLAC__SEEKABLE_STREAM_DECODER_H
33 #define FLAC__SEEKABLE_STREAM_DECODER_H
34
35 #include "export.h"
36 #include "stream_decoder.h"
37
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41
42
43 /** \file include/FLAC/seekable_stream_decoder.h
44 *
45 * \brief
46 * This module contains the functions which implement the seekable stream
47 * decoder.
48 *
49 * See the detailed documentation in the
50 * \link flac_seekable_stream_decoder seekable stream decoder \endlink module.
51 */
52
53 /** \defgroup flac_seekable_stream_decoder FLAC/seekable_stream_decoder.h: seekable stream decoder interface
54 * \ingroup flac_decoder
55 *
56 * \brief
57 * This module contains the functions which implement the seekable stream
58 * decoder.
59 *
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().
75 *
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:
80 *
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.
92 *
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.
99 *
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.
107 *
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.
111 *
112 * \note
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.
119 *
120 * \note
121 * FLAC__stream_decoder_finish() resets all settings to the constructor
122 * defaults, including the callbacks.
123 *
124 * \{
125 */
126
127
128 /** State values for a FLAC__SeekableStreamDecoder
129 *
130 * The decoder's state can be obtained by calling FLAC__seekable_stream_decoder_get_state().
131 */
132 typedef enum {
133
134 FLAC__SEEKABLE_STREAM_DECODER_OK = 0,
135 /**< The decoder is in the normal OK state. */
136
137 FLAC__SEEKABLE_STREAM_DECODER_SEEKING,
138 /**< The decoder is in the process of seeking. */
139
140 FLAC__SEEKABLE_STREAM_DECODER_END_OF_STREAM,
141 /**< The decoder has reached the end of the stream. */
142
143 FLAC__SEEKABLE_STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
144 /**< An error occurred allocating memory. */
145
146 FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR,
147 /**< An error occurred in the underlying stream decoder. */
148
149 FLAC__SEEKABLE_STREAM_DECODER_READ_ERROR,
150 /**< The read callback returned an error. */
151
152 FLAC__SEEKABLE_STREAM_DECODER_SEEK_ERROR,
153 /**< An error occurred while seeking or the seek or tell
154 * callback returned an error.
155 */
156
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.
161 */
162
163 FLAC__SEEKABLE_STREAM_DECODER_INVALID_CALLBACK,
164 /**< FLAC__seekable_stream_decoder_init() was called without all
165 * callbacks being set.
166 */
167
168 FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED
169 /**< The decoder is in the uninitialized state. */
170
171 } FLAC__SeekableStreamDecoderState;
172
173 /** Maps a FLAC__SeekableStreamDecoderState to a C string.
174 *
175 * Using a FLAC__SeekableStreamDecoderState as the index to this array
176 * will give the string equivalent. The contents should not be modified.
177 */
178 extern FLAC_API const char * const FLAC__SeekableStreamDecoderStateString[];
179
180
181 /** Return values for the FLAC__SeekableStreamDecoder read callback.
182 */
183 typedef enum {
184
185 FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_OK,
186 /**< The read was OK and decoding can continue. */
187
188 FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_ERROR
189 /**< An unrecoverable error occurred. The decoder will return from the process call. */
190
191 } FLAC__SeekableStreamDecoderReadStatus;
192
193 /** Maps a FLAC__SeekableStreamDecoderReadStatus to a C string.
194 *
195 * Using a FLAC__SeekableStreamDecoderReadStatus as the index to this array
196 * will give the string equivalent. The contents should not be modified.
197 */
198 extern FLAC_API const char * const FLAC__SeekableStreamDecoderReadStatusString[];
199
200
201 /** Return values for the FLAC__SeekableStreamDecoder seek callback.
202 */
203 typedef enum {
204
205 FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_OK,
206 /**< The seek was OK and decoding can continue. */
207
208 FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_ERROR
209 /**< An unrecoverable error occurred. The decoder will return from the process call. */
210
211 } FLAC__SeekableStreamDecoderSeekStatus;
212
213 /** Maps a FLAC__SeekableStreamDecoderSeekStatus to a C string.
214 *
215 * Using a FLAC__SeekableStreamDecoderSeekStatus as the index to this array
216 * will give the string equivalent. The contents should not be modified.
217 */
218 extern FLAC_API const char * const FLAC__SeekableStreamDecoderSeekStatusString[];
219
220
221 /** Return values for the FLAC__SeekableStreamDecoder tell callback.
222 */
223 typedef enum {
224
225 FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_OK,
226 /**< The tell was OK and decoding can continue. */
227
228 FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_ERROR
229 /**< An unrecoverable error occurred. The decoder will return from the process call. */
230
231 } FLAC__SeekableStreamDecoderTellStatus;
232
233 /** Maps a FLAC__SeekableStreamDecoderTellStatus to a C string.
234 *
235 * Using a FLAC__SeekableStreamDecoderTellStatus as the index to this array
236 * will give the string equivalent. The contents should not be modified.
237 */
238 extern FLAC_API const char * const FLAC__SeekableStreamDecoderTellStatusString[];
239
240
241 /** Return values for the FLAC__SeekableStreamDecoder length callback.
242 */
243 typedef enum {
244
245 FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_OK,
246 /**< The length call was OK and decoding can continue. */
247
248 FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_ERROR
249 /**< An unrecoverable error occurred. The decoder will return from the process call. */
250
251 } FLAC__SeekableStreamDecoderLengthStatus;
252
253 /** Maps a FLAC__SeekableStreamDecoderLengthStatus to a C string.
254 *
255 * Using a FLAC__SeekableStreamDecoderLengthStatus as the index to this array
256 * will give the string equivalent. The contents should not be modified.
257 */
258 extern FLAC_API const char * const FLAC__SeekableStreamDecoderLengthStatusString[];
259
260
261 /***********************************************************************
262 *
263 * class FLAC__SeekableStreamDecoder : public FLAC__StreamDecoder
264 *
265 ***********************************************************************/
266
267 struct FLAC__SeekableStreamDecoderProtected;
268 struct FLAC__SeekableStreamDecoderPrivate;
269 /** The opaque structure definition for the seekable stream decoder type.
270 * See the
271 * \link flac_seekable_stream_decoder seekable stream decoder module \endlink
272 * for a detailed description.
273 */
274 typedef struct {
275 struct FLAC__SeekableStreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
276 struct FLAC__SeekableStreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
277 } FLAC__SeekableStreamDecoder;
278
279 /** Signature for the read callback.
280 * See FLAC__seekable_stream_decoder_set_read_callback()
281 * and FLAC__StreamDecoderReadCallback for more info.
282 *
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.
291 */
292 typedef FLAC__SeekableStreamDecoderReadStatus (*FLAC__SeekableStreamDecoderReadCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
293
294 /** Signature for the seek callback.
295 * See FLAC__seekable_stream_decoder_set_seek_callback() for more info.
296 *
297 * \param decoder The decoder instance calling the callback.
298 * \param absolute_byte_offset The offset from the beginning of the stream
299 * to seek to.
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.
304 */
305 typedef FLAC__SeekableStreamDecoderSeekStatus (*FLAC__SeekableStreamDecoderSeekCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
306
307 /** Signature for the tell callback.
308 * See FLAC__seekable_stream_decoder_set_tell_callback() for more info.
309 *
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.
317 */
318 typedef FLAC__SeekableStreamDecoderTellStatus (*FLAC__SeekableStreamDecoderTellCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
319
320 /** Signature for the length callback.
321 * See FLAC__seekable_stream_decoder_set_length_callback() for more info.
322 *
323 * \param decoder The decoder instance calling the callback.
324 * \param stream_length A pointer to storage for the length of the stream
325 * in bytes.
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.
330 */
331 typedef FLAC__SeekableStreamDecoderLengthStatus (*FLAC__SeekableStreamDecoderLengthCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
332
333 /** Signature for the EOF callback.
334 * See FLAC__seekable_stream_decoder_set_eof_callback() for more info.
335 *
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().
339 * \retval FLAC__bool
340 * \c true if the currently at the end of the stream, else \c false.
341 */
342 typedef FLAC__bool (*FLAC__SeekableStreamDecoderEofCallback)(const FLAC__SeekableStreamDecoder *decoder, void *client_data);
343
344 /** Signature for the write callback.
345 * See FLAC__seekable_stream_decoder_set_write_callback()
346 * and FLAC__StreamDecoderWriteCallback for more info.
347 *
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.
355 */
356 typedef FLAC__StreamDecoderWriteStatus (*FLAC__SeekableStreamDecoderWriteCallback)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
357
358 /** Signature for the metadata callback.
359 * See FLAC__seekable_stream_decoder_set_metadata_callback()
360 * and FLAC__StreamDecoderMetadataCallback for more info.
361 *
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().
366 */
367 typedef void (*FLAC__SeekableStreamDecoderMetadataCallback)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
368
369 /** Signature for the error callback.
370 * See FLAC__seekable_stream_decoder_set_error_callback()
371 * and FLAC__StreamDecoderErrorCallback for more info.
372 *
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().
377 */
378 typedef void (*FLAC__SeekableStreamDecoderErrorCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
379
380
381 /***********************************************************************
382 *
383 * Class constructor/destructor
384 *
385 ***********************************************************************/
386
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
390 * default.
391 *
392 * \retval FLAC__SeekableStreamDecoder*
393 * \c NULL if there was an error allocating memory, else the new instance.
394 */
395 FLAC_API FLAC__SeekableStreamDecoder *FLAC__seekable_stream_decoder_new();
396
397 /** Free a decoder instance. Deletes the object pointed to by \a decoder.
398 *
399 * \param decoder A pointer to an existing decoder.
400 * \assert
401 * \code decoder != NULL \endcode
402 */
403 FLAC_API void FLAC__seekable_stream_decoder_delete(FLAC__SeekableStreamDecoder *decoder);
404
405
406 /***********************************************************************
407 *
408 * Public class method prototypes
409 *
410 ***********************************************************************/
411
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().
416 *
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.
420 *
421 * \default \c false
422 * \param decoder A decoder instance to set.
423 * \param value Flag value (see above).
424 * \assert
425 * \code decoder != NULL \endcode
426 * \retval FLAC__bool
427 * \c false if the decoder is already initialized, else \c true.
428 */
429 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_md5_checking(FLAC__SeekableStreamDecoder *decoder, FLAC__bool value);
430
431 /** Set the read callback.
432 * This is inherited from FLAC__StreamDecoder; see
433 * FLAC__stream_decoder_set_read_callback().
434 *
435 * \note
436 * The callback is mandatory and must be set before initialization.
437 *
438 * \default \c NULL
439 * \param decoder A decoder instance to set.
440 * \param value See above.
441 * \assert
442 * \code decoder != NULL \endcode
443 * \code value != NULL \endcode
444 * \retval FLAC__bool
445 * \c false if the decoder is already initialized, else \c true.
446 */
447 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_read_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderReadCallback value);
448
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.
453 *
454 * \note
455 * The callback is mandatory and must be set before initialization.
456 *
457 * \default \c NULL
458 * \param decoder A decoder instance to set.
459 * \param value See above.
460 * \assert
461 * \code decoder != NULL \endcode
462 * \code value != NULL \endcode
463 * \retval FLAC__bool
464 * \c false if the decoder is already initialized, else \c true.
465 */
466 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_seek_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderSeekCallback value);
467
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.
472 *
473 * \note
474 * The callback is mandatory and must be set before initialization.
475 *
476 * \default \c NULL
477 * \param decoder A decoder instance to set.
478 * \param value See above.
479 * \assert
480 * \code decoder != NULL \endcode
481 * \code value != NULL \endcode
482 * \retval FLAC__bool
483 * \c false if the decoder is already initialized, else \c true.
484 */
485 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_tell_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderTellCallback value);
486
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.
490 *
491 * \note
492 * The callback is mandatory and must be set before initialization.
493 *
494 * \default \c NULL
495 * \param decoder A decoder instance to set.
496 * \param value See above.
497 * \assert
498 * \code decoder != NULL \endcode
499 * \code value != NULL \endcode
500 * \retval FLAC__bool
501 * \c false if the decoder is already initialized, else \c true.
502 */
503 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_length_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderLengthCallback value);
504
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.
508 *
509 * \note
510 * The callback is mandatory and must be set before initialization.
511 *
512 * \default \c NULL
513 * \param decoder A decoder instance to set.
514 * \param value See above.
515 * \assert
516 * \code decoder != NULL \endcode
517 * \code value != NULL \endcode
518 * \retval FLAC__bool
519 * \c false if the decoder is already initialized, else \c true.
520 */
521 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_eof_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderEofCallback value);
522
523 /** Set the write callback.
524 * This is inherited from FLAC__StreamDecoder; see
525 * FLAC__stream_decoder_set_write_callback().
526 *
527 * \note
528 * The callback is mandatory and must be set before initialization.
529 *
530 * \default \c NULL
531 * \param decoder A decoder instance to set.
532 * \param value See above.
533 * \assert
534 * \code decoder != NULL \endcode
535 * \code value != NULL \endcode
536 * \retval FLAC__bool
537 * \c false if the decoder is already initialized, else \c true.
538 */
539 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_write_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderWriteCallback value);
540
541 /** Set the metadata callback.
542 * This is inherited from FLAC__StreamDecoder; see
543 * FLAC__stream_decoder_set_metadata_callback().
544 *
545 * \note
546 * The callback is mandatory and must be set before initialization.
547 *
548 * \default \c NULL
549 * \param decoder A decoder instance to set.
550 * \param value See above.
551 * \assert
552 * \code decoder != NULL \endcode
553 * \code value != NULL \endcode
554 * \retval FLAC__bool
555 * \c false if the decoder is already initialized, else \c true.
556 */
557 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderMetadataCallback value);
558
559 /** Set the error callback.
560 * This is inherited from FLAC__StreamDecoder; see
561 * FLAC__stream_decoder_set_error_callback().
562 *
563 * \note
564 * The callback is mandatory and must be set before initialization.
565 *
566 * \default \c NULL
567 * \param decoder A decoder instance to set.
568 * \param value See above.
569 * \assert
570 * \code decoder != NULL \endcode
571 * \code value != NULL \endcode
572 * \retval FLAC__bool
573 * \c false if the decoder is already initialized, else \c true.
574 */
575 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_error_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderErrorCallback value);
576
577 /** Set the client data to be passed back to callbacks.
578 * This value will be supplied to callbacks in their \a client_data
579 * argument.
580 *
581 * \default \c NULL
582 * \param decoder A decoder instance to set.
583 * \param value See above.
584 * \assert
585 * \code decoder != NULL \endcode
586 * \retval FLAC__bool
587 * \c false if the decoder is already initialized, else \c true.
588 */
589 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_client_data(FLAC__SeekableStreamDecoder *decoder, void *value);
590
591 /** This is inherited from FLAC__StreamDecoder; see
592 * FLAC__stream_decoder_set_metadata_respond().
593 *
594 * \default By default, only the \c STREAMINFO block is returned via the
595 * metadata callback.
596 * \param decoder A decoder instance to set.
597 * \param type See above.
598 * \assert
599 * \code decoder != NULL \endcode
600 * \a type is valid
601 * \retval FLAC__bool
602 * \c false if the decoder is already initialized, else \c true.
603 */
604 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond(FLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type);
605
606 /** This is inherited from FLAC__StreamDecoder; see
607 * FLAC__stream_decoder_set_metadata_respond_application().
608 *
609 * \default By default, only the \c STREAMINFO block is returned via the
610 * metadata callback.
611 * \param decoder A decoder instance to set.
612 * \param id See above.
613 * \assert
614 * \code decoder != NULL \endcode
615 * \code id != NULL \endcode
616 * \retval FLAC__bool
617 * \c false if the decoder is already initialized, else \c true.
618 */
619 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond_application(FLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
620
621 /** This is inherited from FLAC__StreamDecoder; see
622 * FLAC__stream_decoder_set_metadata_respond_all().
623 *
624 * \default By default, only the \c STREAMINFO block is returned via the
625 * metadata callback.
626 * \param decoder A decoder instance to set.
627 * \assert
628 * \code decoder != NULL \endcode
629 * \retval FLAC__bool
630 * \c false if the decoder is already initialized, else \c true.
631 */
632 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond_all(FLAC__SeekableStreamDecoder *decoder);
633
634 /** This is inherited from FLAC__StreamDecoder; see
635 * FLAC__stream_decoder_set_metadata_ignore().
636 *
637 * \default By default, only the \c STREAMINFO block is returned via the
638 * metadata callback.
639 * \param decoder A decoder instance to set.
640 * \param type See above.
641 * \assert
642 * \code decoder != NULL \endcode
643 * \a type is valid
644 * \retval FLAC__bool
645 * \c false if the decoder is already initialized, else \c true.
646 */
647 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore(FLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type);
648
649 /** This is inherited from FLAC__StreamDecoder; see
650 * FLAC__stream_decoder_set_metadata_ignore_application().
651 *
652 * \default By default, only the \c STREAMINFO block is returned via the
653 * metadata callback.
654 * \param decoder A decoder instance to set.
655 * \param id See above.
656 * \assert
657 * \code decoder != NULL \endcode
658 * \code id != NULL \endcode
659 * \retval FLAC__bool
660 * \c false if the decoder is already initialized, else \c true.
661 */
662 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore_application(FLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
663
664 /** This is inherited from FLAC__StreamDecoder; see
665 * FLAC__stream_decoder_set_metadata_ignore_all().
666 *
667 * \default By default, only the \c STREAMINFO block is returned via the
668 * metadata callback.
669 * \param decoder A decoder instance to set.
670 * \assert
671 * \code decoder != NULL \endcode
672 * \retval FLAC__bool
673 * \c false if the decoder is already initialized, else \c true.
674 */
675 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore_all(FLAC__SeekableStreamDecoder *decoder);
676
677 /** Get the current decoder state.
678 *
679 * \param decoder A decoder instance to query.
680 * \assert
681 * \code decoder != NULL \endcode
682 * \retval FLAC__SeekableStreamDecoderState
683 * The current decoder state.
684 */
685 FLAC_API FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_get_state(const FLAC__SeekableStreamDecoder *decoder);
686
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.
690 *
691 * \param decoder A decoder instance to query.
692 * \assert
693 * \code decoder != NULL \endcode
694 * \retval FLAC__StreamDecoderState
695 * The stream decoder state.
696 */
697 FLAC_API FLAC__StreamDecoderState FLAC__seekable_stream_decoder_get_stream_decoder_state(const FLAC__SeekableStreamDecoder *decoder);
698
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.
703 *
704 * \param decoder A decoder instance to query.
705 * \assert
706 * \code decoder != NULL \endcode
707 * \retval const char *
708 * The decoder state as a C string. Do not modify the contents.
709 */
710 FLAC_API const char *FLAC__seekable_stream_decoder_get_resolved_state_string(const FLAC__SeekableStreamDecoder *decoder);
711
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.
717 *
718 * \param decoder A decoder instance to query.
719 * \assert
720 * \code decoder != NULL \endcode
721 * \retval FLAC__bool
722 * See above.
723 */
724 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_get_md5_checking(const FLAC__SeekableStreamDecoder *decoder);
725
726 /** This is inherited from FLAC__StreamDecoder; see
727 * FLAC__stream_decoder_get_channels().
728 *
729 * \param decoder A decoder instance to query.
730 * \assert
731 * \code decoder != NULL \endcode
732 * \retval unsigned
733 * See above.
734 */
735 FLAC_API unsigned FLAC__seekable_stream_decoder_get_channels(const FLAC__SeekableStreamDecoder *decoder);
736
737 /** This is inherited from FLAC__StreamDecoder; see
738 * FLAC__stream_decoder_get_channel_assignment().
739 *
740 * \param decoder A decoder instance to query.
741 * \assert
742 * \code decoder != NULL \endcode
743 * \retval FLAC__ChannelAssignment
744 * See above.
745 */
746 FLAC_API FLAC__ChannelAssignment FLAC__seekable_stream_decoder_get_channel_assignment(const FLAC__SeekableStreamDecoder *decoder);
747
748 /** This is inherited from FLAC__StreamDecoder; see
749 * FLAC__stream_decoder_get_bits_per_sample().
750 *
751 * \param decoder A decoder instance to query.
752 * \assert
753 * \code decoder != NULL \endcode
754 * \retval unsigned
755 * See above.
756 */
757 FLAC_API unsigned FLAC__seekable_stream_decoder_get_bits_per_sample(const FLAC__SeekableStreamDecoder *decoder);
758
759 /** This is inherited from FLAC__StreamDecoder; see
760 * FLAC__stream_decoder_get_sample_rate().
761 *
762 * \param decoder A decoder instance to query.
763 * \assert
764 * \code decoder != NULL \endcode
765 * \retval unsigned
766 * See above.
767 */
768 FLAC_API unsigned FLAC__seekable_stream_decoder_get_sample_rate(const FLAC__SeekableStreamDecoder *decoder);
769
770 /** This is inherited from FLAC__StreamDecoder; see
771 * FLAC__stream_decoder_get_blocksize().
772 *
773 * \param decoder A decoder instance to query.
774 * \assert
775 * \code decoder != NULL \endcode
776 * \retval unsigned
777 * See above.
778 */
779 FLAC_API unsigned FLAC__seekable_stream_decoder_get_blocksize(const FLAC__SeekableStreamDecoder *decoder);
780
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.
786 *
787 * \param decoder A decoder instance to query.
788 * \param position Address at which to return the desired position.
789 * \assert
790 * \code decoder != NULL \endcode
791 * \code position != NULL \endcode
792 * \retval FLAC__bool
793 * \c true if successful, \c false if there was an error from
794 * the 'tell' callback.
795 */
796 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_get_decode_position(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *position);
797
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.
804 *
805 * \param decoder An uninitialized decoder instance.
806 * \assert
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.
812 */
813 FLAC_API FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_init(FLAC__SeekableStreamDecoder *decoder);
814
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.
819 *
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().
825 *
826 * \param decoder An uninitialized decoder instance.
827 * \assert
828 * \code decoder != NULL \endcode
829 * \retval FLAC__bool
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
833 * \c true.
834 */
835 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_finish(FLAC__SeekableStreamDecoder *decoder);
836
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
840 * checking.
841 *
842 * \param decoder A decoder instance.
843 * \assert
844 * \code decoder != NULL \endcode
845 * \retval FLAC__bool
846 * \c true if successful, else \c false if a memory allocation
847 * or stream decoder error occurs.
848 */
849 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_flush(FLAC__SeekableStreamDecoder *decoder);
850
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
857 * setting.
858 *
859 * \param decoder A decoder instance.
860 * \assert
861 * \code decoder != NULL \endcode
862 * \retval FLAC__bool
863 * \c true if successful, else \c false if a memory allocation
864 * or stream decoder error occurs.
865 */
866 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_reset(FLAC__SeekableStreamDecoder *decoder);
867
868 /** This is inherited from FLAC__StreamDecoder; see
869 * FLAC__stream_decoder_process_single().
870 *
871 * \param decoder A decoder instance.
872 * \assert
873 * \code decoder != NULL \endcode
874 * \retval FLAC__bool
875 * See above.
876 */
877 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_single(FLAC__SeekableStreamDecoder *decoder);
878
879 /** This is inherited from FLAC__StreamDecoder; see
880 * FLAC__stream_decoder_process_until_end_of_metadata().
881 *
882 * \param decoder A decoder instance.
883 * \assert
884 * \code decoder != NULL \endcode
885 * \retval FLAC__bool
886 * See above.
887 */
888 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_metadata(FLAC__SeekableStreamDecoder *decoder);
889
890 /** This is inherited from FLAC__StreamDecoder; see
891 * FLAC__stream_decoder_process_until_end_of_stream().
892 *
893 * \param decoder A decoder instance.
894 * \assert
895 * \code decoder != NULL \endcode
896 * \retval FLAC__bool
897 * See above.
898 */
899 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_stream(FLAC__SeekableStreamDecoder *decoder);
900
901 /** This is inherited from FLAC__StreamDecoder; see
902 * FLAC__stream_decoder_skip_single_frame().
903 *
904 * \param decoder A decoder instance.
905 * \assert
906 * \code decoder != NULL \endcode
907 * \retval FLAC__bool
908 * See above.
909 */
910 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_skip_single_frame(FLAC__SeekableStreamDecoder *decoder);
911
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.
915 *
916 * \param decoder A decoder instance.
917 * \param sample The target sample number to seek to.
918 * \assert
919 * \code decoder != NULL \endcode
920 * \retval FLAC__bool
921 * \c true if successful, else \c false.
922 */
923 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_seek_absolute(FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 sample);
924
925 /* \} */
926
927 #ifdef __cplusplus
928 }
929 #endif
930
931 #endif