tweaks to build libs as DLLs under windows
[flac.git] / include / FLAC / seekable_stream_decoder.h
1 /* libFLAC - Free Lossless Audio Codec library
2  * Copyright (C) 2000,2001,2002  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 "MD5 signature checking" flag.
688  *  This is the value of the setting, not whether or not the decoder is
689  *  currently checking the MD5 (remember, it can be turned off automatically
690  *  by a seek).  When the decoder is reset the flag will be restored to the
691  *  value returned by this function.
692  *
693  * \param  decoder  A decoder instance to query.
694  * \assert
695  *    \code decoder != NULL \endcode
696  * \retval FLAC__bool
697  *    See above.
698  */
699 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_get_md5_checking(const FLAC__SeekableStreamDecoder *decoder);
700
701 /** This is inherited from FLAC__StreamDecoder; see
702  *  FLAC__stream_decoder_get_channels().
703  *
704  * \param  decoder  A decoder instance to query.
705  * \assert
706  *    \code decoder != NULL \endcode
707  * \retval unsigned
708  *    See above.
709  */
710 FLAC_API unsigned FLAC__seekable_stream_decoder_get_channels(const FLAC__SeekableStreamDecoder *decoder);
711
712 /** This is inherited from FLAC__StreamDecoder; see
713  *  FLAC__stream_decoder_get_channel_assignment().
714  *
715  * \param  decoder  A decoder instance to query.
716  * \assert
717  *    \code decoder != NULL \endcode
718  * \retval FLAC__ChannelAssignment
719  *    See above.
720  */
721 FLAC_API FLAC__ChannelAssignment FLAC__seekable_stream_decoder_get_channel_assignment(const FLAC__SeekableStreamDecoder *decoder);
722
723 /** This is inherited from FLAC__StreamDecoder; see
724  *  FLAC__stream_decoder_get_bits_per_sample().
725  *
726  * \param  decoder  A decoder instance to query.
727  * \assert
728  *    \code decoder != NULL \endcode
729  * \retval unsigned
730  *    See above.
731  */
732 FLAC_API unsigned FLAC__seekable_stream_decoder_get_bits_per_sample(const FLAC__SeekableStreamDecoder *decoder);
733
734 /** This is inherited from FLAC__StreamDecoder; see
735  *  FLAC__stream_decoder_get_sample_rate().
736  *
737  * \param  decoder  A decoder instance to query.
738  * \assert
739  *    \code decoder != NULL \endcode
740  * \retval unsigned
741  *    See above.
742  */
743 FLAC_API unsigned FLAC__seekable_stream_decoder_get_sample_rate(const FLAC__SeekableStreamDecoder *decoder);
744
745 /** This is inherited from FLAC__StreamDecoder; see
746  *  FLAC__stream_decoder_get_blocksize().
747  *
748  * \param  decoder  A decoder instance to query.
749  * \assert
750  *    \code decoder != NULL \endcode
751  * \retval unsigned
752  *    See above.
753  */
754 FLAC_API unsigned FLAC__seekable_stream_decoder_get_blocksize(const FLAC__SeekableStreamDecoder *decoder);
755
756 /** Initialize the decoder instance.
757  *  Should be called after FLAC__seekable_stream_decoder_new() and
758  *  FLAC__seekable_stream_decoder_set_*() but before any of the
759  *  FLAC__seekable_stream_decoder_process_*() functions.  Will set and return
760  *  the decoder state, which will be FLAC__SEEKABLE_STREAM_DECODER_OK
761  *  if initialization succeeded.
762  *
763  * \param  decoder  An uninitialized decoder instance.
764  * \assert
765  *    \code decoder != NULL \endcode
766  * \retval FLAC__SeekableStreamDecoderState
767  *    \c FLAC__SEEKABLE_STREAM_DECODER_OK if initialization was
768  *    successful; see FLAC__SeekableStreamDecoderState for the meanings
769  *    of other return values.
770  */
771 FLAC_API FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_init(FLAC__SeekableStreamDecoder *decoder);
772
773 /** Finish the decoding process.
774  *  Flushes the decoding buffer, releases resources, resets the decoder
775  *  settings to their defaults, and returns the decoder state to
776  *  FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED.
777  *
778  *  In the event of a prematurely-terminated decode, it is not strictly
779  *  necessary to call this immediately before
780  *  FLAC__seekable_stream_decoder_delete() but it is good practice to match
781  *  every FLAC__seekable_stream_decoder_init() with a
782  *  FLAC__seekable_stream_decoder_finish().
783  *
784  * \param  decoder  An uninitialized decoder instance.
785  * \assert
786  *    \code decoder != NULL \endcode
787  * \retval FLAC__bool
788  *    \c false if MD5 checking is on AND a STREAMINFO block was available
789  *    AND the MD5 signature in the STREAMINFO block was non-zero AND the
790  *    signature does not match the one computed by the decoder; else
791  *    \c true.
792  */
793 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_finish(FLAC__SeekableStreamDecoder *decoder);
794
795 /** Flush the stream input.
796  *  The decoder's input buffer will be cleared and the state set to
797  *  \c FLAC__SEEKABLE_STREAM_DECODER_OK.  This will also turn off MD5
798  *  checking.
799  *
800  * \param  decoder  A decoder instance.
801  * \assert
802  *    \code decoder != NULL \endcode
803  * \retval FLAC__bool
804  *    \c true if successful, else \c false if a memory allocation
805  *    or stream decoder error occurs.
806  */
807 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_flush(FLAC__SeekableStreamDecoder *decoder);
808
809 /** Reset the decoding process.
810  *  The decoder's input buffer will be cleared and the state set to
811  *  \c FLAC__SEEKABLE_STREAM_DECODER_OK.  This is similar to
812  *  FLAC__seekable_stream_decoder_finish() except that the settings are
813  *  preserved; there is no need to call FLAC__seekable_stream_decoder_init()
814  *  before decoding again.  MD5 checking will be restored to its original
815  *  setting.
816  *
817  * \param  decoder  A decoder instance.
818  * \assert
819  *    \code decoder != NULL \endcode
820  * \retval FLAC__bool
821  *    \c true if successful, else \c false if a memory allocation
822  *    or stream decoder error occurs.
823  */
824 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_reset(FLAC__SeekableStreamDecoder *decoder);
825
826 /** This is inherited from FLAC__StreamDecoder; see
827  *  FLAC__stream_decoder_process_single().
828  *
829  * \param  decoder  A decoder instance.
830  * \assert
831  *    \code decoder != NULL \endcode
832  * \retval FLAC__bool
833  *    See above.
834  */
835 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_single(FLAC__SeekableStreamDecoder *decoder);
836
837 /** This is inherited from FLAC__StreamDecoder; see
838  *  FLAC__stream_decoder_process_until_end_of_metadata().
839  *
840  * \param  decoder  A decoder instance.
841  * \assert
842  *    \code decoder != NULL \endcode
843  * \retval FLAC__bool
844  *    See above.
845  */
846 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_metadata(FLAC__SeekableStreamDecoder *decoder);
847
848 /** This is inherited from FLAC__StreamDecoder; see
849  *  FLAC__stream_decoder_process_until_end_of_stream().
850  *
851  * \param  decoder  A decoder instance.
852  * \assert
853  *    \code decoder != NULL \endcode
854  * \retval FLAC__bool
855  *    See above.
856  */
857 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_stream(FLAC__SeekableStreamDecoder *decoder);
858
859 /** Flush the input and seek to an absolute sample.
860  *  Decoding will resume at the given sample.  Note that because of
861  *  this, the next write callback may contain a partial block.
862  *
863  * \param  decoder  A decoder instance.
864  * \param  sample   The target sample number to seek to.
865  * \assert
866  *    \code decoder != NULL \endcode
867  * \retval FLAC__bool
868  *    \c true if successful, else \c false.
869  */
870 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_seek_absolute(FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 sample);
871
872 /* \} */
873
874 #ifdef __cplusplus
875 }
876 #endif
877
878 #endif