remove leftover and unimplemented proto FLAC__file_decoder_process_remaining_frames()
[flac.git] / include / FLAC / seekable_stream_decoder.h
1 /* libFLAC - Free Lossless Audio Codec library
2  * Copyright (C) 2000,2001,2002,2003  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 /** Flush the input and seek to an absolute sample.
902  *  Decoding will resume at the given sample.  Note that because of
903  *  this, the next write callback may contain a partial block.
904  *
905  * \param  decoder  A decoder instance.
906  * \param  sample   The target sample number to seek to.
907  * \assert
908  *    \code decoder != NULL \endcode
909  * \retval FLAC__bool
910  *    \c true if successful, else \c false.
911  */
912 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_seek_absolute(FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 sample);
913
914 /* \} */
915
916 #ifdef __cplusplus
917 }
918 #endif
919
920 #endif