Add 2003 to copyright notice
[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  * This library is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Library General Public
6  * License as published by the Free Software Foundation; either
7  * version 2 of the License, or (at your option) any later version.
8  *
9  * This library is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12  * Library General Public License for more details.
13  *
14  * You should have received a copy of the GNU Library General Public
15  * License along with this library; if not, write to the
16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17  * Boston, MA  02111-1307, USA.
18  */
19
20 #ifndef FLAC__SEEKABLE_STREAM_DECODER_H
21 #define FLAC__SEEKABLE_STREAM_DECODER_H
22
23 #include "export.h"
24 #include "stream_decoder.h"
25
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29
30
31 /** \file include/FLAC/seekable_stream_decoder.h
32  *
33  *  \brief
34  *  This module contains the functions which implement the seekable stream
35  *  decoder.
36  *
37  *  See the detailed documentation in the
38  *  \link flac_seekable_stream_decoder seekable stream decoder \endlink module.
39  */
40
41 /** \defgroup flac_seekable_stream_decoder FLAC/seekable_stream_decoder.h: seekable stream decoder interface
42  *  \ingroup flac_decoder
43  *
44  *  \brief
45  *  This module contains the functions which implement the seekable stream
46  *  decoder.
47  *
48  * The basic usage of this decoder is as follows:
49  * - The program creates an instance of a decoder using
50  *   FLAC__seekable_stream_decoder_new().
51  * - The program overrides the default settings and sets callbacks for
52  *   reading, writing, seeking, error reporting, and metadata reporting
53  *   using FLAC__seekable_stream_decoder_set_*() functions.
54  * - The program initializes the instance to validate the settings and
55  *   prepare for decoding using FLAC__seekable_stream_decoder_init().
56  * - The program calls the FLAC__seekable_stream_decoder_process_*()
57  *   functions to decode data, which subsequently calls the callbacks.
58  * - The program finishes the decoding with
59  *   FLAC__seekable_stream_decoder_finish(), which flushes the input and
60  *   output and resets the decoder to the uninitialized state.
61  * - The instance may be used again or deleted with
62  *   FLAC__seekable_stream_decoder_delete().
63  *
64  * The seekable stream decoder is a wrapper around the
65  * \link flac_stream_decoder stream decoder \endlink which also provides
66  * seeking capability.  In addition to the Read/Write/Metadata/Error
67  * callbacks of the stream decoder, the user must also provide the following:
68  *
69  * - Seek callback - This function will be called when the decoder wants to
70  *   seek to an absolute position in the stream.
71  * - Tell callback - This function will be called when the decoder wants to
72  *   know the current absolute position of the stream.
73  * - Length callback - This function will be called when the decoder wants
74  *   to know length of the stream.  The seeking algorithm currently requires
75  *   that the overall stream length be known.
76  * - EOF callback - This function will be called when the decoder wants to
77  *   know if it is at the end of the stream.  This could be synthesized from
78  *   the tell and length callbacks but it may be more expensive that way, so
79  *   there is a separate callback for it.
80  *
81  * Seeking is exposed through the
82  * FLAC__seekable_stream_decoder_seek_absolute() method.  At any point after
83  * the seekable stream decoder has been initialized, the user can call this
84  * function to seek to an exact sample within the stream.  Subsequently, the
85  * first time the write callback is called it will be passed a (possibly
86  * partial) block starting at that sample.
87  *
88  * The seekable stream decoder also provides MD5 signature checking.  If
89  * this is turned on before initialization,
90  * FLAC__seekable_stream_decoder_finish() will report when the decoded MD5
91  * signature does not match the one stored in the STREAMINFO block.  MD5
92  * checking is automatically turned off (until the next
93  * FLAC__seekable_stream_decoder_reset()) if there is no signature in the
94  * STREAMINFO block or when a seek is attempted.
95  *
96  * Make sure to read the detailed description of the
97  * \link flac_stream_decoder stream decoder module \endlink since the
98  * seekable stream decoder inherits much of its behavior.
99  *
100  * \note
101  * The "set" functions may only be called when the decoder is in the
102  * state FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED, i.e. after
103  * FLAC__seekable_stream_decoder_new() or
104  * FLAC__seekable_stream_decoder_finish(), but before
105  * FLAC__seekable_stream_decoder_init().  If this is the case they will
106  * return \c true, otherwise \c false.
107  *
108  * \note
109  * FLAC__stream_decoder_finish() resets all settings to the constructor
110  * defaults, including the callbacks.
111  *
112  * \{
113  */
114
115
116 /** State values for a FLAC__SeekableStreamDecoder
117  *
118  *  The decoder's state can be obtained by calling FLAC__seekable_stream_decoder_get_state().
119  */
120 typedef enum {
121
122         FLAC__SEEKABLE_STREAM_DECODER_OK = 0,
123         /**< The decoder is in the normal OK state. */
124
125         FLAC__SEEKABLE_STREAM_DECODER_SEEKING,
126         /**< The decoder is in the process of seeking. */
127
128         FLAC__SEEKABLE_STREAM_DECODER_END_OF_STREAM,
129         /**< The decoder has reached the end of the stream. */
130
131         FLAC__SEEKABLE_STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
132         /**< An error occurred allocating memory. */
133
134         FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR,
135         /**< An error occurred in the underlying stream decoder. */
136
137         FLAC__SEEKABLE_STREAM_DECODER_READ_ERROR,
138         /**< The read callback returned an error. */
139
140         FLAC__SEEKABLE_STREAM_DECODER_SEEK_ERROR,
141         /**< An error occurred while seeking or the seek or tell
142          * callback returned an error.
143          */
144
145         FLAC__SEEKABLE_STREAM_DECODER_ALREADY_INITIALIZED,
146         /**< FLAC__seekable_stream_decoder_init() was called when the
147          * decoder was already initialized, usually because
148          * FLAC__seekable_stream_decoder_finish() was not called.
149          */
150
151         FLAC__SEEKABLE_STREAM_DECODER_INVALID_CALLBACK,
152         /**< FLAC__seekable_stream_decoder_init() was called without all
153          * callbacks being set.
154          */
155
156         FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED
157         /**< The decoder is in the uninitialized state. */
158
159 } FLAC__SeekableStreamDecoderState;
160
161 /** Maps a FLAC__SeekableStreamDecoderState to a C string.
162  *
163  *  Using a FLAC__SeekableStreamDecoderState as the index to this array
164  *  will give the string equivalent.  The contents should not be modified.
165  */
166 extern FLAC_API const char * const FLAC__SeekableStreamDecoderStateString[];
167
168
169 /** Return values for the FLAC__SeekableStreamDecoder read callback.
170  */
171 typedef enum {
172
173         FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_OK,
174         /**< The read was OK and decoding can continue. */
175
176         FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_ERROR
177         /**< An unrecoverable error occurred.  The decoder will return from the process call. */
178
179 } FLAC__SeekableStreamDecoderReadStatus;
180
181 /** Maps a FLAC__SeekableStreamDecoderReadStatus to a C string.
182  *
183  *  Using a FLAC__SeekableStreamDecoderReadStatus as the index to this array
184  *  will give the string equivalent.  The contents should not be modified.
185  */
186 extern FLAC_API const char * const FLAC__SeekableStreamDecoderReadStatusString[];
187
188
189 /** Return values for the FLAC__SeekableStreamDecoder seek callback.
190  */
191 typedef enum {
192
193         FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_OK,
194         /**< The seek was OK and decoding can continue. */
195
196         FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_ERROR
197         /**< An unrecoverable error occurred.  The decoder will return from the process call. */
198
199 } FLAC__SeekableStreamDecoderSeekStatus;
200
201 /** Maps a FLAC__SeekableStreamDecoderSeekStatus to a C string.
202  *
203  *  Using a FLAC__SeekableStreamDecoderSeekStatus as the index to this array
204  *  will give the string equivalent.  The contents should not be modified.
205  */
206 extern FLAC_API const char * const FLAC__SeekableStreamDecoderSeekStatusString[];
207
208
209 /** Return values for the FLAC__SeekableStreamDecoder tell callback.
210  */
211 typedef enum {
212
213         FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_OK,
214         /**< The tell was OK and decoding can continue. */
215
216         FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_ERROR
217         /**< An unrecoverable error occurred.  The decoder will return from the process call. */
218
219 } FLAC__SeekableStreamDecoderTellStatus;
220
221 /** Maps a FLAC__SeekableStreamDecoderTellStatus to a C string.
222  *
223  *  Using a FLAC__SeekableStreamDecoderTellStatus as the index to this array
224  *  will give the string equivalent.  The contents should not be modified.
225  */
226 extern FLAC_API const char * const FLAC__SeekableStreamDecoderTellStatusString[];
227
228
229 /** Return values for the FLAC__SeekableStreamDecoder length callback.
230  */
231 typedef enum {
232
233         FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_OK,
234         /**< The length call was OK and decoding can continue. */
235
236         FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_ERROR
237         /**< An unrecoverable error occurred.  The decoder will return from the process call. */
238
239 } FLAC__SeekableStreamDecoderLengthStatus;
240
241 /** Maps a FLAC__SeekableStreamDecoderLengthStatus to a C string.
242  *
243  *  Using a FLAC__SeekableStreamDecoderLengthStatus as the index to this array
244  *  will give the string equivalent.  The contents should not be modified.
245  */
246 extern FLAC_API const char * const FLAC__SeekableStreamDecoderLengthStatusString[];
247
248
249 /***********************************************************************
250  *
251  * class FLAC__SeekableStreamDecoder : public FLAC__StreamDecoder
252  *
253  ***********************************************************************/
254
255 struct FLAC__SeekableStreamDecoderProtected;
256 struct FLAC__SeekableStreamDecoderPrivate;
257 /** The opaque structure definition for the seekable stream decoder type.
258  *  See the
259  *  \link flac_seekable_stream_decoder seekable stream decoder module \endlink
260  *  for a detailed description.
261  */
262 typedef struct {
263         struct FLAC__SeekableStreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
264         struct FLAC__SeekableStreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
265 } FLAC__SeekableStreamDecoder;
266
267 /** Signature for the read callback.
268  *  See FLAC__seekable_stream_decoder_set_read_callback()
269  *  and FLAC__StreamDecoderReadCallback for more info.
270  *
271  * \param  decoder  The decoder instance calling the callback.
272  * \param  buffer   A pointer to a location for the callee to store
273  *                  data to be decoded.
274  * \param  bytes    A pointer to the size of the buffer.
275  * \param  client_data  The callee's client data set through
276  *                      FLAC__seekable_stream_decoder_set_client_data().
277  * \retval FLAC__SeekableStreamDecoderReadStatus
278  *    The callee's return status.
279  */
280 typedef FLAC__SeekableStreamDecoderReadStatus (*FLAC__SeekableStreamDecoderReadCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
281
282 /** Signature for the seek callback.
283  *  See FLAC__seekable_stream_decoder_set_seek_callback() for more info.
284  *
285  * \param  decoder  The decoder instance calling the callback.
286  * \param  absolute_byte_offset  The offset from the beginning of the stream
287  *                               to seek to.
288  * \param  client_data  The callee's client data set through
289  *                      FLAC__seekable_stream_decoder_set_client_data().
290  * \retval FLAC__SeekableStreamDecoderSeekStatus
291  *    The callee's return status.
292  */
293 typedef FLAC__SeekableStreamDecoderSeekStatus (*FLAC__SeekableStreamDecoderSeekCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
294
295 /** Signature for the tell callback.
296  *  See FLAC__seekable_stream_decoder_set_tell_callback() for more info.
297  *
298  * \param  decoder  The decoder instance calling the callback.
299  * \param  absolute_byte_offset  A pointer to storage for the current offset
300  *                               from the beginning of the stream.
301  * \param  client_data  The callee's client data set through
302  *                      FLAC__seekable_stream_decoder_set_client_data().
303  * \retval FLAC__SeekableStreamDecoderTellStatus
304  *    The callee's return status.
305  */
306 typedef FLAC__SeekableStreamDecoderTellStatus (*FLAC__SeekableStreamDecoderTellCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
307
308 /** Signature for the length callback.
309  *  See FLAC__seekable_stream_decoder_set_length_callback() for more info.
310  *
311  * \param  decoder  The decoder instance calling the callback.
312  * \param  stream_length  A pointer to storage for the length of the stream
313  *                        in bytes.
314  * \param  client_data  The callee's client data set through
315  *                      FLAC__seekable_stream_decoder_set_client_data().
316  * \retval FLAC__SeekableStreamDecoderLengthStatus
317  *    The callee's return status.
318  */
319 typedef FLAC__SeekableStreamDecoderLengthStatus (*FLAC__SeekableStreamDecoderLengthCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
320
321 /** Signature for the EOF callback.
322  *  See FLAC__seekable_stream_decoder_set_eof_callback() for more info.
323  *
324  * \param  decoder  The decoder instance calling the callback.
325  * \param  client_data  The callee's client data set through
326  *                      FLAC__seekable_stream_decoder_set_client_data().
327  * \retval FLAC__bool
328  *    \c true if the currently at the end of the stream, else \c false.
329  */
330 typedef FLAC__bool (*FLAC__SeekableStreamDecoderEofCallback)(const FLAC__SeekableStreamDecoder *decoder, void *client_data);
331
332 /** Signature for the write callback.
333  *  See FLAC__seekable_stream_decoder_set_write_callback()
334  *  and FLAC__StreamDecoderWriteCallback for more info.
335  *
336  * \param  decoder  The decoder instance calling the callback.
337  * \param  frame    The description of the decoded frame.
338  * \param  buffer   An array of pointers to decoded channels of data.
339  * \param  client_data  The callee's client data set through
340  *                      FLAC__seekable_stream_decoder_set_client_data().
341  * \retval FLAC__StreamDecoderWriteStatus
342  *    The callee's return status.
343  */
344 typedef FLAC__StreamDecoderWriteStatus (*FLAC__SeekableStreamDecoderWriteCallback)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
345
346 /** Signature for the metadata callback.
347  *  See FLAC__seekable_stream_decoder_set_metadata_callback()
348  *  and FLAC__StreamDecoderMetadataCallback for more info.
349  *
350  * \param  decoder  The decoder instance calling the callback.
351  * \param  metadata The decoded metadata block.
352  * \param  client_data  The callee's client data set through
353  *                      FLAC__seekable_stream_decoder_set_client_data().
354  */
355 typedef void (*FLAC__SeekableStreamDecoderMetadataCallback)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
356
357 /** Signature for the error callback.
358  *  See FLAC__seekable_stream_decoder_set_error_callback()
359  *  and FLAC__StreamDecoderErrorCallback for more info.
360  *
361  * \param  decoder  The decoder instance calling the callback.
362  * \param  status   The error encountered by the decoder.
363  * \param  client_data  The callee's client data set through
364  *                      FLAC__seekable_stream_decoder_set_client_data().
365  */
366 typedef void (*FLAC__SeekableStreamDecoderErrorCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
367
368
369 /***********************************************************************
370  *
371  * Class constructor/destructor
372  *
373  ***********************************************************************/
374
375 /** Create a new seekable stream decoder instance.  The instance is created
376  *  with default settings; see the individual
377  *  FLAC__seekable_stream_decoder_set_*() functions for each setting's
378  *  default.
379  *
380  * \retval FLAC__SeekableStreamDecoder*
381  *    \c NULL if there was an error allocating memory, else the new instance.
382  */
383 FLAC_API FLAC__SeekableStreamDecoder *FLAC__seekable_stream_decoder_new();
384
385 /** Free a decoder instance.  Deletes the object pointed to by \a decoder.
386  *
387  * \param decoder  A pointer to an existing decoder.
388  * \assert
389  *    \code decoder != NULL \endcode
390  */
391 FLAC_API void FLAC__seekable_stream_decoder_delete(FLAC__SeekableStreamDecoder *decoder);
392
393
394 /***********************************************************************
395  *
396  * Public class method prototypes
397  *
398  ***********************************************************************/
399
400 /** Set the "MD5 signature checking" flag.  If \c true, the decoder will
401  *  compute the MD5 signature of the unencoded audio data while decoding
402  *  and compare it to the signature from the STREAMINFO block, if it
403  *  exists, during FLAC__seekable_stream_decoder_finish().
404  *
405  *  MD5 signature checking will be turned off (until the next
406  *  FLAC__seekable_stream_decoder_reset()) if there is no signature in
407  *  the STREAMINFO block or when a seek is attempted.
408  *
409  * \default \c false
410  * \param  decoder  A decoder instance to set.
411  * \param  value    Flag value (see above).
412  * \assert
413  *    \code decoder != NULL \endcode
414  * \retval FLAC__bool
415  *    \c false if the decoder is already initialized, else \c true.
416  */
417 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_md5_checking(FLAC__SeekableStreamDecoder *decoder, FLAC__bool value);
418
419 /** Set the read callback.
420  *  This is inherited from FLAC__StreamDecoder; see
421  *  FLAC__stream_decoder_set_read_callback().
422  *
423  * \note
424  * The callback is mandatory and must be set before initialization.
425  *
426  * \default \c NULL
427  * \param  decoder  A decoder instance to set.
428  * \param  value    See above.
429  * \assert
430  *    \code decoder != NULL \endcode
431  *    \code value != NULL \endcode
432  * \retval FLAC__bool
433  *    \c false if the decoder is already initialized, else \c true.
434  */
435 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_read_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderReadCallback value);
436
437 /** Set the seek callback.
438  *  The supplied function will be called when the decoder needs to seek
439  *  the input stream.  The decoder will pass the absolute byte offset
440  *  to seek to, 0 meaning the beginning of the stream.
441  *
442  * \note
443  * The callback is mandatory and must be set before initialization.
444  *
445  * \default \c NULL
446  * \param  decoder  A decoder instance to set.
447  * \param  value    See above.
448  * \assert
449  *    \code decoder != NULL \endcode
450  *    \code value != NULL \endcode
451  * \retval FLAC__bool
452  *    \c false if the decoder is already initialized, else \c true.
453  */
454 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_seek_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderSeekCallback value);
455
456 /** Set the tell callback.
457  *  The supplied function will be called when the decoder wants to know
458  *  the current position of the stream.  The callback should return the
459  *  byte offset from the beginning of the stream.
460  *
461  * \note
462  * The callback is mandatory and must be set before initialization.
463  *
464  * \default \c NULL
465  * \param  decoder  A decoder instance to set.
466  * \param  value    See above.
467  * \assert
468  *    \code decoder != NULL \endcode
469  *    \code value != NULL \endcode
470  * \retval FLAC__bool
471  *    \c false if the decoder is already initialized, else \c true.
472  */
473 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_tell_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderTellCallback value);
474
475 /** Set the length callback.
476  *  The supplied function will be called when the decoder wants to know
477  *  the total length of the stream in bytes.
478  *
479  * \note
480  * The callback is mandatory and must be set before initialization.
481  *
482  * \default \c NULL
483  * \param  decoder  A decoder instance to set.
484  * \param  value    See above.
485  * \assert
486  *    \code decoder != NULL \endcode
487  *    \code value != NULL \endcode
488  * \retval FLAC__bool
489  *    \c false if the decoder is already initialized, else \c true.
490  */
491 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_length_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderLengthCallback value);
492
493 /** Set the eof callback.
494  *  The supplied function will be called when the decoder needs to know
495  *  if the end of the stream has been reached.
496  *
497  * \note
498  * The callback is mandatory and must be set before initialization.
499  *
500  * \default \c NULL
501  * \param  decoder  A decoder instance to set.
502  * \param  value    See above.
503  * \assert
504  *    \code decoder != NULL \endcode
505  *    \code value != NULL \endcode
506  * \retval FLAC__bool
507  *    \c false if the decoder is already initialized, else \c true.
508  */
509 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_eof_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderEofCallback value);
510
511 /** Set the write callback.
512  *  This is inherited from FLAC__StreamDecoder; see
513  *  FLAC__stream_decoder_set_write_callback().
514  *
515  * \note
516  * The callback is mandatory and must be set before initialization.
517  *
518  * \default \c NULL
519  * \param  decoder  A decoder instance to set.
520  * \param  value    See above.
521  * \assert
522  *    \code decoder != NULL \endcode
523  *    \code value != NULL \endcode
524  * \retval FLAC__bool
525  *    \c false if the decoder is already initialized, else \c true.
526  */
527 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_write_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderWriteCallback value);
528
529 /** Set the metadata callback.
530  *  This is inherited from FLAC__StreamDecoder; see
531  *  FLAC__stream_decoder_set_metadata_callback().
532  *
533  * \note
534  * The callback is mandatory and must be set before initialization.
535  *
536  * \default \c NULL
537  * \param  decoder  A decoder instance to set.
538  * \param  value    See above.
539  * \assert
540  *    \code decoder != NULL \endcode
541  *    \code value != NULL \endcode
542  * \retval FLAC__bool
543  *    \c false if the decoder is already initialized, else \c true.
544  */
545 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderMetadataCallback value);
546
547 /** Set the error callback.
548  *  This is inherited from FLAC__StreamDecoder; see
549  *  FLAC__stream_decoder_set_error_callback().
550  *
551  * \note
552  * The callback is mandatory and must be set before initialization.
553  *
554  * \default \c NULL
555  * \param  decoder  A decoder instance to set.
556  * \param  value    See above.
557  * \assert
558  *    \code decoder != NULL \endcode
559  *    \code value != NULL \endcode
560  * \retval FLAC__bool
561  *    \c false if the decoder is already initialized, else \c true.
562  */
563 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_error_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderErrorCallback value);
564
565 /** Set the client data to be passed back to callbacks.
566  *  This value will be supplied to callbacks in their \a client_data
567  *  argument.
568  *
569  * \default \c NULL
570  * \param  decoder  A decoder instance to set.
571  * \param  value    See above.
572  * \assert
573  *    \code decoder != NULL \endcode
574  * \retval FLAC__bool
575  *    \c false if the decoder is already initialized, else \c true.
576  */
577 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_client_data(FLAC__SeekableStreamDecoder *decoder, void *value);
578
579 /** This is inherited from FLAC__StreamDecoder; see
580  *  FLAC__stream_decoder_set_metadata_respond().
581  *
582  * \default By default, only the \c STREAMINFO block is returned via the
583  *          metadata callback.
584  * \param  decoder  A decoder instance to set.
585  * \param  type     See above.
586  * \assert
587  *    \code decoder != NULL \endcode
588  *    \a type is valid
589  * \retval FLAC__bool
590  *    \c false if the decoder is already initialized, else \c true.
591  */
592 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond(FLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type);
593
594 /** This is inherited from FLAC__StreamDecoder; see
595  *  FLAC__stream_decoder_set_metadata_respond_application().
596  *
597  * \default By default, only the \c STREAMINFO block is returned via the
598  *          metadata callback.
599  * \param  decoder  A decoder instance to set.
600  * \param  id       See above.
601  * \assert
602  *    \code decoder != NULL \endcode
603  *    \code id != NULL \endcode
604  * \retval FLAC__bool
605  *    \c false if the decoder is already initialized, else \c true.
606  */
607 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond_application(FLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
608
609 /** This is inherited from FLAC__StreamDecoder; see
610  *  FLAC__stream_decoder_set_metadata_respond_all().
611  *
612  * \default By default, only the \c STREAMINFO block is returned via the
613  *          metadata callback.
614  * \param  decoder  A decoder instance to set.
615  * \assert
616  *    \code decoder != NULL \endcode
617  * \retval FLAC__bool
618  *    \c false if the decoder is already initialized, else \c true.
619  */
620 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond_all(FLAC__SeekableStreamDecoder *decoder);
621
622 /** This is inherited from FLAC__StreamDecoder; see
623  *  FLAC__stream_decoder_set_metadata_ignore().
624  *
625  * \default By default, only the \c STREAMINFO block is returned via the
626  *          metadata callback.
627  * \param  decoder  A decoder instance to set.
628  * \param  type     See above.
629  * \assert
630  *    \code decoder != NULL \endcode
631  *    \a type is valid
632  * \retval FLAC__bool
633  *    \c false if the decoder is already initialized, else \c true.
634  */
635 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore(FLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type);
636
637 /** This is inherited from FLAC__StreamDecoder; see
638  *  FLAC__stream_decoder_set_metadata_ignore_application().
639  *
640  * \default By default, only the \c STREAMINFO block is returned via the
641  *          metadata callback.
642  * \param  decoder  A decoder instance to set.
643  * \param  id       See above.
644  * \assert
645  *    \code decoder != NULL \endcode
646  *    \code id != NULL \endcode
647  * \retval FLAC__bool
648  *    \c false if the decoder is already initialized, else \c true.
649  */
650 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore_application(FLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
651
652 /** This is inherited from FLAC__StreamDecoder; see
653  *  FLAC__stream_decoder_set_metadata_ignore_all().
654  *
655  * \default By default, only the \c STREAMINFO block is returned via the
656  *          metadata callback.
657  * \param  decoder  A decoder instance to set.
658  * \assert
659  *    \code decoder != NULL \endcode
660  * \retval FLAC__bool
661  *    \c false if the decoder is already initialized, else \c true.
662  */
663 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore_all(FLAC__SeekableStreamDecoder *decoder);
664
665 /** Get the current decoder state.
666  *
667  * \param  decoder  A decoder instance to query.
668  * \assert
669  *    \code decoder != NULL \endcode
670  * \retval FLAC__SeekableStreamDecoderState
671  *    The current decoder state.
672  */
673 FLAC_API FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_get_state(const FLAC__SeekableStreamDecoder *decoder);
674
675 /** Get the state of the underlying stream decoder.
676  *  Useful when the seekable stream decoder state is
677  *  \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
678  *
679  * \param  decoder  A decoder instance to query.
680  * \assert
681  *    \code decoder != NULL \endcode
682  * \retval FLAC__StreamDecoderState
683  *    The stream decoder state.
684  */
685 FLAC_API FLAC__StreamDecoderState FLAC__seekable_stream_decoder_get_stream_decoder_state(const FLAC__SeekableStreamDecoder *decoder);
686
687 /** Get the current decoder state as a C string.
688  *  This version automatically resolves
689  *  \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR by getting the
690  *  stream decoder's state.
691  *
692  * \param  decoder  A decoder instance to query.
693  * \assert
694  *    \code decoder != NULL \endcode
695  * \retval const char *
696  *    The decoder state as a C string.  Do not modify the contents.
697  */
698 FLAC_API const char *FLAC__seekable_stream_decoder_get_resolved_state_string(const FLAC__SeekableStreamDecoder *decoder);
699
700 /** Get the "MD5 signature checking" flag.
701  *  This is the value of the setting, not whether or not the decoder is
702  *  currently checking the MD5 (remember, it can be turned off automatically
703  *  by a seek).  When the decoder is reset the flag will be restored to the
704  *  value returned by this function.
705  *
706  * \param  decoder  A decoder instance to query.
707  * \assert
708  *    \code decoder != NULL \endcode
709  * \retval FLAC__bool
710  *    See above.
711  */
712 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_get_md5_checking(const FLAC__SeekableStreamDecoder *decoder);
713
714 /** This is inherited from FLAC__StreamDecoder; see
715  *  FLAC__stream_decoder_get_channels().
716  *
717  * \param  decoder  A decoder instance to query.
718  * \assert
719  *    \code decoder != NULL \endcode
720  * \retval unsigned
721  *    See above.
722  */
723 FLAC_API unsigned FLAC__seekable_stream_decoder_get_channels(const FLAC__SeekableStreamDecoder *decoder);
724
725 /** This is inherited from FLAC__StreamDecoder; see
726  *  FLAC__stream_decoder_get_channel_assignment().
727  *
728  * \param  decoder  A decoder instance to query.
729  * \assert
730  *    \code decoder != NULL \endcode
731  * \retval FLAC__ChannelAssignment
732  *    See above.
733  */
734 FLAC_API FLAC__ChannelAssignment FLAC__seekable_stream_decoder_get_channel_assignment(const FLAC__SeekableStreamDecoder *decoder);
735
736 /** This is inherited from FLAC__StreamDecoder; see
737  *  FLAC__stream_decoder_get_bits_per_sample().
738  *
739  * \param  decoder  A decoder instance to query.
740  * \assert
741  *    \code decoder != NULL \endcode
742  * \retval unsigned
743  *    See above.
744  */
745 FLAC_API unsigned FLAC__seekable_stream_decoder_get_bits_per_sample(const FLAC__SeekableStreamDecoder *decoder);
746
747 /** This is inherited from FLAC__StreamDecoder; see
748  *  FLAC__stream_decoder_get_sample_rate().
749  *
750  * \param  decoder  A decoder instance to query.
751  * \assert
752  *    \code decoder != NULL \endcode
753  * \retval unsigned
754  *    See above.
755  */
756 FLAC_API unsigned FLAC__seekable_stream_decoder_get_sample_rate(const FLAC__SeekableStreamDecoder *decoder);
757
758 /** This is inherited from FLAC__StreamDecoder; see
759  *  FLAC__stream_decoder_get_blocksize().
760  *
761  * \param  decoder  A decoder instance to query.
762  * \assert
763  *    \code decoder != NULL \endcode
764  * \retval unsigned
765  *    See above.
766  */
767 FLAC_API unsigned FLAC__seekable_stream_decoder_get_blocksize(const FLAC__SeekableStreamDecoder *decoder);
768
769 /** Returns the decoder's current read position within the stream.
770  *  The position is the byte offset from the start of the stream.
771  *  Bytes before this position have been fully decoded.  Note that
772  *  there may still be undecoded bytes in the decoder's read FIFO.
773  *  The returned position is correct even after a seek.
774  *
775  * \param  decoder   A decoder instance to query.
776  * \param  position  Address at which to return the desired position.
777  * \assert
778  *    \code decoder != NULL \endcode
779  *    \code position != NULL \endcode
780  * \retval FLAC__bool
781  *    \c true if successful, \c false if there was an error from
782  *    the 'tell' callback.
783  */
784 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_get_decode_position(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *position);
785
786 /** Initialize the decoder instance.
787  *  Should be called after FLAC__seekable_stream_decoder_new() and
788  *  FLAC__seekable_stream_decoder_set_*() but before any of the
789  *  FLAC__seekable_stream_decoder_process_*() functions.  Will set and return
790  *  the decoder state, which will be FLAC__SEEKABLE_STREAM_DECODER_OK
791  *  if initialization succeeded.
792  *
793  * \param  decoder  An uninitialized decoder instance.
794  * \assert
795  *    \code decoder != NULL \endcode
796  * \retval FLAC__SeekableStreamDecoderState
797  *    \c FLAC__SEEKABLE_STREAM_DECODER_OK if initialization was
798  *    successful; see FLAC__SeekableStreamDecoderState for the meanings
799  *    of other return values.
800  */
801 FLAC_API FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_init(FLAC__SeekableStreamDecoder *decoder);
802
803 /** Finish the decoding process.
804  *  Flushes the decoding buffer, releases resources, resets the decoder
805  *  settings to their defaults, and returns the decoder state to
806  *  FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED.
807  *
808  *  In the event of a prematurely-terminated decode, it is not strictly
809  *  necessary to call this immediately before
810  *  FLAC__seekable_stream_decoder_delete() but it is good practice to match
811  *  every FLAC__seekable_stream_decoder_init() with a
812  *  FLAC__seekable_stream_decoder_finish().
813  *
814  * \param  decoder  An uninitialized decoder instance.
815  * \assert
816  *    \code decoder != NULL \endcode
817  * \retval FLAC__bool
818  *    \c false if MD5 checking is on AND a STREAMINFO block was available
819  *    AND the MD5 signature in the STREAMINFO block was non-zero AND the
820  *    signature does not match the one computed by the decoder; else
821  *    \c true.
822  */
823 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_finish(FLAC__SeekableStreamDecoder *decoder);
824
825 /** Flush the stream input.
826  *  The decoder's input buffer will be cleared and the state set to
827  *  \c FLAC__SEEKABLE_STREAM_DECODER_OK.  This will also turn off MD5
828  *  checking.
829  *
830  * \param  decoder  A decoder instance.
831  * \assert
832  *    \code decoder != NULL \endcode
833  * \retval FLAC__bool
834  *    \c true if successful, else \c false if a memory allocation
835  *    or stream decoder error occurs.
836  */
837 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_flush(FLAC__SeekableStreamDecoder *decoder);
838
839 /** Reset the decoding process.
840  *  The decoder's input buffer will be cleared and the state set to
841  *  \c FLAC__SEEKABLE_STREAM_DECODER_OK.  This is similar to
842  *  FLAC__seekable_stream_decoder_finish() except that the settings are
843  *  preserved; there is no need to call FLAC__seekable_stream_decoder_init()
844  *  before decoding again.  MD5 checking will be restored to its original
845  *  setting.
846  *
847  * \param  decoder  A decoder instance.
848  * \assert
849  *    \code decoder != NULL \endcode
850  * \retval FLAC__bool
851  *    \c true if successful, else \c false if a memory allocation
852  *    or stream decoder error occurs.
853  */
854 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_reset(FLAC__SeekableStreamDecoder *decoder);
855
856 /** This is inherited from FLAC__StreamDecoder; see
857  *  FLAC__stream_decoder_process_single().
858  *
859  * \param  decoder  A decoder instance.
860  * \assert
861  *    \code decoder != NULL \endcode
862  * \retval FLAC__bool
863  *    See above.
864  */
865 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_single(FLAC__SeekableStreamDecoder *decoder);
866
867 /** This is inherited from FLAC__StreamDecoder; see
868  *  FLAC__stream_decoder_process_until_end_of_metadata().
869  *
870  * \param  decoder  A decoder instance.
871  * \assert
872  *    \code decoder != NULL \endcode
873  * \retval FLAC__bool
874  *    See above.
875  */
876 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_metadata(FLAC__SeekableStreamDecoder *decoder);
877
878 /** This is inherited from FLAC__StreamDecoder; see
879  *  FLAC__stream_decoder_process_until_end_of_stream().
880  *
881  * \param  decoder  A decoder instance.
882  * \assert
883  *    \code decoder != NULL \endcode
884  * \retval FLAC__bool
885  *    See above.
886  */
887 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_stream(FLAC__SeekableStreamDecoder *decoder);
888
889 /** Flush the input and seek to an absolute sample.
890  *  Decoding will resume at the given sample.  Note that because of
891  *  this, the next write callback may contain a partial block.
892  *
893  * \param  decoder  A decoder instance.
894  * \param  sample   The target sample number to seek to.
895  * \assert
896  *    \code decoder != NULL \endcode
897  * \retval FLAC__bool
898  *    \c true if successful, else \c false.
899  */
900 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_seek_absolute(FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 sample);
901
902 /* \} */
903
904 #ifdef __cplusplus
905 }
906 #endif
907
908 #endif