minor comments
[flac.git] / include / OggFLAC / stream_decoder.h
1 /* libOggFLAC - Free Lossless Audio Codec + Ogg library
2  * Copyright (C) 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 OggFLAC__STREAM_DECODER_H
33 #define OggFLAC__STREAM_DECODER_H
34
35 #include "export.h"
36
37 #include "FLAC/stream_decoder.h"
38
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42
43
44 /** \file include/OggFLAC/stream_decoder.h
45  *
46  *  \brief
47  *  This module contains the functions which implement the stream
48  *  decoder.
49  *
50  *  See the detailed documentation in the
51  *  \link oggflac_stream_decoder stream decoder \endlink module.
52  */
53
54 /** \defgroup oggflac_decoder OggFLAC/ *_decoder.h: decoder interfaces
55  *  \ingroup oggflac
56  *
57  *  \brief
58  *  This module describes the three decoder layers provided by libOggFLAC.
59  *
60  * libOggFLAC currently provides the same three layers of access as
61  * libFLAC; the interfaces are nearly identical, with th addition of a
62  * method for specifying the Ogg serial number.  See the
63  * \link flac_decoder FLAC decoder module \endlink for full documentation.
64  */
65
66 /** \defgroup oggflac_stream_decoder OggFLAC/stream_decoder.h: stream decoder interface
67  *  \ingroup oggflac_decoder
68  *
69  *  \brief
70  *  This module contains the functions which implement the stream
71  *  decoder.
72  *
73  * The interface here is nearly identical to FLAC's stream decoder,
74  * including the callbacks, with the addition of
75  * OggFLAC__stream_decoder_set_serial_number().  See the
76  * \link flac_stream_decoder FLAC stream decoder module \endlink
77  * for full documentation.
78  *
79  * \{
80  */
81
82
83 /** State values for an OggFLAC__StreamDecoder
84  *
85  *  The decoder's state can be obtained by calling OggFLAC__stream_decoder_get_state().
86  */
87 typedef enum {
88
89         OggFLAC__STREAM_DECODER_OK = 0,
90         /**< The decoder is in the normal OK state. */
91
92         OggFLAC__STREAM_DECODER_OGG_ERROR,
93         /**< An error occurred in the underlying Ogg layer.  */
94
95         OggFLAC__STREAM_DECODER_READ_ERROR,
96         /**< The read callback returned an error. */
97
98         OggFLAC__STREAM_DECODER_FLAC_STREAM_DECODER_ERROR,
99         /**< An error occurred in the underlying FLAC stream decoder;
100          * check OggFLAC__stream_decoder_get_FLAC_stream_decoder_state().
101          */
102
103         OggFLAC__STREAM_DECODER_INVALID_CALLBACK,
104         /**< The decoder was initialized before setting all the required callbacks. */
105
106         OggFLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
107         /**< Memory allocation failed. */
108
109         OggFLAC__STREAM_DECODER_ALREADY_INITIALIZED,
110         /**< OggFLAC__stream_decoder_init() was called when the decoder was
111          * already initialized, usually because
112          * OggFLAC__stream_decoder_finish() was not called.
113          */
114
115         OggFLAC__STREAM_DECODER_UNINITIALIZED
116         /**< The decoder is in the uninitialized state. */
117
118 } OggFLAC__StreamDecoderState;
119
120 /** Maps an OggFLAC__StreamDecoderState to a C string.
121  *
122  *  Using an OggFLAC__StreamDecoderState as the index to this array
123  *  will give the string equivalent.  The contents should not be modified.
124  */
125 extern OggFLAC_API const char * const OggFLAC__StreamDecoderStateString[];
126
127
128 /***********************************************************************
129  *
130  * class OggFLAC__StreamDecoder
131  *
132  ***********************************************************************/
133
134 struct OggFLAC__StreamDecoderProtected;
135 struct OggFLAC__StreamDecoderPrivate;
136 /** The opaque structure definition for the stream decoder type.
137  *  See the \link oggflac_stream_decoder stream decoder module \endlink
138  *  for a detailed description.
139  */
140 typedef struct {
141         struct OggFLAC__StreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
142         struct OggFLAC__StreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
143 } OggFLAC__StreamDecoder;
144
145 /** Signature for the read callback.
146  *  See OggFLAC__stream_decoder_set_read_callback()
147  *  and FLAC__StreamDecoderReadCallback for more info.
148  *
149  * \param  decoder  The decoder instance calling the callback.
150  * \param  buffer   A pointer to a location for the callee to store
151  *                  data to be decoded.
152  * \param  bytes    A pointer to the size of the buffer.  On entry
153  *                  to the callback, it contains the maximum number
154  *                  of bytes that may be stored in \a buffer.  The
155  *                  callee must set it to the actual number of bytes
156  *                  stored before returning.
157  * \param  client_data  The callee's client data set through
158  *                      OggFLAC__stream_decoder_set_client_data().
159  * \retval FLAC__StreamDecoderReadStatus
160  *    The callee's return status.
161  */
162 typedef FLAC__StreamDecoderReadStatus (*OggFLAC__StreamDecoderReadCallback)(const OggFLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
163
164 /** Signature for the write callback.
165  *  See OggFLAC__stream_decoder_set_write_callback()
166  *  and FLAC__StreamDecoderWriteCallback for more info.
167  *
168  * \param  decoder  The decoder instance calling the callback.
169  * \param  frame    The description of the decoded frame.  See
170  *                  FLAC__Frame.
171  * \param  buffer   An array of pointers to decoded channels of data.
172  *                  Each pointer will point to an array of signed
173  *                  samples of length \a frame->header.blocksize.
174  *                  Currently, the channel order has no meaning
175  *                  except for stereo streams; in this case channel
176  *                  0 is left and 1 is right.
177  * \param  client_data  The callee's client data set through
178  *                      OggFLAC__stream_decoder_set_client_data().
179  * \retval FLAC__StreamDecoderWriteStatus
180  *    The callee's return status.
181  */
182 typedef FLAC__StreamDecoderWriteStatus (*OggFLAC__StreamDecoderWriteCallback)(const OggFLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
183
184 /** Signature for the metadata callback.
185  *  See OggFLAC__stream_decoder_set_metadata_callback()
186  *  and FLAC__StreamDecoderMetadataCallback for more info.
187  *
188  * \param  decoder  The decoder instance calling the callback.
189  * \param  metadata The decoded metadata block.
190  * \param  client_data  The callee's client data set through
191  *                      OggFLAC__stream_decoder_set_client_data().
192  */
193 typedef void (*OggFLAC__StreamDecoderMetadataCallback)(const OggFLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
194
195 /** Signature for the error callback.
196  *  See OggFLAC__stream_decoder_set_error_callback()
197  *  and FLAC__StreamDecoderErrorCallback for more info.
198  *
199  * \param  decoder  The decoder instance calling the callback.
200  * \param  status   The error encountered by the decoder.
201  * \param  client_data  The callee's client data set through
202  *                      OggFLAC__stream_decoder_set_client_data().
203  */
204 typedef void (*OggFLAC__StreamDecoderErrorCallback)(const OggFLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
205
206
207 /***********************************************************************
208  *
209  * Class constructor/destructor
210  *
211  ***********************************************************************/
212
213 /** Create a new stream decoder instance.  The instance is created with
214  *  default settings; see the individual OggFLAC__stream_decoder_set_*()
215  *  functions for each setting's default.
216  *
217  * \retval OggFLAC__StreamDecoder*
218  *    \c NULL if there was an error allocating memory, else the new instance.
219  */
220 OggFLAC_API OggFLAC__StreamDecoder *OggFLAC__stream_decoder_new();
221
222 /** Free a decoder instance.  Deletes the object pointed to by \a decoder.
223  *
224  * \param decoder  A pointer to an existing decoder.
225  * \assert
226  *    \code decoder != NULL \endcode
227  */
228 OggFLAC_API void OggFLAC__stream_decoder_delete(OggFLAC__StreamDecoder *decoder);
229
230
231 /***********************************************************************
232  *
233  * Public class method prototypes
234  *
235  ***********************************************************************/
236
237 /** Set the read callback.
238  * This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_read_callback()
239  *
240  * \note
241  * The callback is mandatory and must be set before initialization.
242  *
243  * \default \c NULL
244  * \param  decoder  A decoder instance to set.
245  * \param  value    See above.
246  * \assert
247  *    \code decoder != NULL \endcode
248  *    \code value != NULL \endcode
249  * \retval FLAC__bool
250  *    \c false if the decoder is already initialized, else \c true.
251  */
252 OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_read_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderReadCallback value);
253
254 /** Set the write callback.
255  * This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_write_callback()
256  *
257  * \note
258  * The callback is mandatory and must be set before initialization.
259  *
260  * \default \c NULL
261  * \param  decoder  A decoder instance to set.
262  * \param  value    See above.
263  * \assert
264  *    \code decoder != NULL \endcode
265  *    \code value != NULL \endcode
266  * \retval FLAC__bool
267  *    \c false if the decoder is already initialized, else \c true.
268  */
269 OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_write_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderWriteCallback value);
270
271 /** Set the metadata callback.
272  * This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_callback()
273  *
274  * \note
275  * The callback is mandatory and must be set before initialization.
276  *
277  * \default \c NULL
278  * \param  decoder  A decoder instance to set.
279  * \param  value    See above.
280  * \assert
281  *    \code decoder != NULL \endcode
282  *    \code value != NULL \endcode
283  * \retval FLAC__bool
284  *    \c false if the decoder is already initialized, else \c true.
285  */
286 OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderMetadataCallback value);
287
288 /** Set the error callback.
289  * This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_error_callback()
290  *
291  * \note
292  * The callback is mandatory and must be set before initialization.
293  *
294  * \default \c NULL
295  * \param  decoder  A decoder instance to set.
296  * \param  value    See above.
297  * \assert
298  *    \code decoder != NULL \endcode
299  *    \code value != NULL \endcode
300  * \retval FLAC__bool
301  *    \c false if the decoder is already initialized, else \c true.
302  */
303 OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_error_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderErrorCallback value);
304
305 /** Set the client data to be passed back to callbacks.
306  *  This value will be supplied to callbacks in their \a client_data
307  *  argument.
308  *
309  * \default \c NULL
310  * \param  decoder  A decoder instance to set.
311  * \param  value    See above.
312  * \assert
313  *    \code decoder != NULL \endcode
314  * \retval FLAC__bool
315  *    \c false if the decoder is already initialized, else \c true.
316  */
317 OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_client_data(OggFLAC__StreamDecoder *decoder, void *value);
318
319 /** Set the serial number for the Ogg stream.
320  * The default behavior is to use the serial number of the first Ogg
321  * page.  Setting a serial number here will explicitly specify which
322  * stream is to be decoded.
323  *
324  * \default \c use serial number of first page
325  * \param  decoder        A decoder instance to set.
326  * \param  serial_number  See above.
327  * \assert
328  *    \code decoder != NULL \endcode
329  * \retval FLAC__bool
330  *    \c false if the decoder is already initialized, else \c true.
331  */
332 OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_serial_number(OggFLAC__StreamDecoder *decoder, long serial_number);
333
334 /** Direct the decoder to pass on all metadata blocks of type \a type.
335  * This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_respond()
336  *
337  * \default By default, only the \c STREAMINFO block is returned via the
338  *          metadata callback.
339  * \param  decoder  A decoder instance to set.
340  * \param  type     See above.
341  * \assert
342  *    \code decoder != NULL \endcode
343  *    \a type is valid
344  * \retval FLAC__bool
345  *    \c false if the decoder is already initialized, else \c true.
346  */
347 OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_respond(OggFLAC__StreamDecoder *decoder, FLAC__MetadataType type);
348
349 /** Direct the decoder to pass on all APPLICATION metadata blocks of the
350  *  given \a id.
351  * This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_respond_application()
352  *
353  * \default By default, only the \c STREAMINFO block is returned via the
354  *          metadata callback.
355  * \param  decoder  A decoder instance to set.
356  * \param  id       See above.
357  * \assert
358  *    \code decoder != NULL \endcode
359  *    \code id != NULL \endcode
360  * \retval FLAC__bool
361  *    \c false if the decoder is already initialized, else \c true.
362  */
363 OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_respond_application(OggFLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
364
365 /** Direct the decoder to pass on all metadata blocks of any type.
366  * This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_respond_all()
367  *
368  * \default By default, only the \c STREAMINFO block is returned via the
369  *          metadata callback.
370  * \param  decoder  A decoder instance to set.
371  * \assert
372  *    \code decoder != NULL \endcode
373  * \retval FLAC__bool
374  *    \c false if the decoder is already initialized, else \c true.
375  */
376 OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_respond_all(OggFLAC__StreamDecoder *decoder);
377
378 /** Direct the decoder to filter out all metadata blocks of type \a type.
379  * This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_ignore()
380  *
381  * \default By default, only the \c STREAMINFO block is returned via the
382  *          metadata callback.
383  * \param  decoder  A decoder instance to set.
384  * \param  type     See above.
385  * \assert
386  *    \code decoder != NULL \endcode
387  *    \a type is valid
388  * \retval FLAC__bool
389  *    \c false if the decoder is already initialized, else \c true.
390  */
391 OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_ignore(OggFLAC__StreamDecoder *decoder, FLAC__MetadataType type);
392
393 /** Direct the decoder to filter out all APPLICATION metadata blocks of
394  *  the given \a id.
395  * This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_ignore_application()
396  *
397  * \default By default, only the \c STREAMINFO block is returned via the
398  *          metadata callback.
399  * \param  decoder  A decoder instance to set.
400  * \param  id       See above.
401  * \assert
402  *    \code decoder != NULL \endcode
403  *    \code id != NULL \endcode
404  * \retval FLAC__bool
405  *    \c false if the decoder is already initialized, else \c true.
406  */
407 OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_ignore_application(OggFLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
408
409 /** Direct the decoder to filter out all metadata blocks of any type.
410  * This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_ignore_all()
411  *
412  * \default By default, only the \c STREAMINFO block is returned via the
413  *          metadata callback.
414  * \param  decoder  A decoder instance to set.
415  * \assert
416  *    \code decoder != NULL \endcode
417  * \retval FLAC__bool
418  *    \c false if the decoder is already initialized, else \c true.
419  */
420 OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_ignore_all(OggFLAC__StreamDecoder *decoder);
421
422 /** Get the current decoder state.
423  *
424  * \param  decoder  A decoder instance to query.
425  * \assert
426  *    \code decoder != NULL \endcode
427  * \retval OggFLAC__StreamDecoderState
428  *    The current decoder state.
429  */
430 OggFLAC_API OggFLAC__StreamDecoderState OggFLAC__stream_decoder_get_state(const OggFLAC__StreamDecoder *decoder);
431
432 /** Get the state of the underlying FLAC stream decoder.
433  *  Useful when the stream decoder state is
434  *  \c OggFLAC__STREAM_DECODER_FLAC_STREAM_DECODER_ERROR.
435  *
436  * \param  decoder  A decoder instance to query.
437  * \assert
438  *    \code decoder != NULL \endcode
439  * \retval FLAC__StreamDecoderState
440  *    The FLAC stream decoder state.
441  */
442 OggFLAC_API FLAC__StreamDecoderState OggFLAC__stream_decoder_get_FLAC_stream_decoder_state(const OggFLAC__StreamDecoder *decoder);
443
444 /** Get the current decoder state as a C string.
445  *  This version automatically resolves
446  *  \c OggFLAC__STREAM_DECODER_FLAC_STREAM_DECODER_ERROR
447  *  by getting the FLAC stream decoder's state.
448  *
449  * \param  decoder  A decoder instance to query.
450  * \assert
451  *    \code decoder != NULL \endcode
452  * \retval const char *
453  *    The decoder state as a C string.  Do not modify the contents.
454  */
455 OggFLAC_API const char *OggFLAC__stream_decoder_get_resolved_state_string(const OggFLAC__StreamDecoder *decoder);
456
457 /** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_channels()
458  *
459  * \param  decoder  A decoder instance to query.
460  * \assert
461  *    \code decoder != NULL \endcode
462  * \retval unsigned
463  *    See above.
464  */
465 OggFLAC_API unsigned OggFLAC__stream_decoder_get_channels(const OggFLAC__StreamDecoder *decoder);
466
467 /** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_channel_assignment()
468  *
469  * \param  decoder  A decoder instance to query.
470  * \assert
471  *    \code decoder != NULL \endcode
472  * \retval OggFLAC__ChannelAssignment
473  *    See above.
474  */
475 OggFLAC_API FLAC__ChannelAssignment OggFLAC__stream_decoder_get_channel_assignment(const OggFLAC__StreamDecoder *decoder);
476
477 /** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_bits_per_sample()
478  *
479  * \param  decoder  A decoder instance to query.
480  * \assert
481  *    \code decoder != NULL \endcode
482  * \retval unsigned
483  *    See above.
484  */
485 OggFLAC_API unsigned OggFLAC__stream_decoder_get_bits_per_sample(const OggFLAC__StreamDecoder *decoder);
486
487 /** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_sample_rate()
488  *
489  * \param  decoder  A decoder instance to query.
490  * \assert
491  *    \code decoder != NULL \endcode
492  * \retval unsigned
493  *    See above.
494  */
495 OggFLAC_API unsigned OggFLAC__stream_decoder_get_sample_rate(const OggFLAC__StreamDecoder *decoder);
496
497 /** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_blocksize()
498  *
499  * \param  decoder  A decoder instance to query.
500  * \assert
501  *    \code decoder != NULL \endcode
502  * \retval unsigned
503  *    See above.
504  */
505 OggFLAC_API unsigned OggFLAC__stream_decoder_get_blocksize(const OggFLAC__StreamDecoder *decoder);
506
507 /** Initialize the decoder instance.
508  *  Should be called after OggFLAC__stream_decoder_new() and
509  *  OggFLAC__stream_decoder_set_*() but before any of the
510  *  OggFLAC__stream_decoder_process_*() functions.  Will set and return the
511  *  decoder state, which will be OggFLAC__STREAM_DECODER_OK
512  *  if initialization succeeded.
513  *
514  * \param  decoder  An uninitialized decoder instance.
515  * \assert
516  *    \code decoder != NULL \endcode
517  * \retval OggFLAC__StreamDecoderState
518  *    \c OggFLAC__STREAM_DECODER_OK if initialization was
519  *    successful; see OggFLAC__StreamDecoderState for the meanings of other
520  *    return values.
521  */
522 OggFLAC_API OggFLAC__StreamDecoderState OggFLAC__stream_decoder_init(OggFLAC__StreamDecoder *decoder);
523
524 /** Finish the decoding process.
525  *  Flushes the decoding buffer, releases resources, resets the decoder
526  *  settings to their defaults, and returns the decoder state to
527  *  OggFLAC__STREAM_DECODER_UNINITIALIZED.
528  *
529  *  In the event of a prematurely-terminated decode, it is not strictly
530  *  necessary to call this immediately before OggFLAC__stream_decoder_delete()
531  *  but it is good practice to match every OggFLAC__stream_decoder_init()
532  *  with an OggFLAC__stream_decoder_finish().
533  *
534  * \param  decoder  An uninitialized decoder instance.
535  * \assert
536  *    \code decoder != NULL \endcode
537  */
538 OggFLAC_API void OggFLAC__stream_decoder_finish(OggFLAC__StreamDecoder *decoder);
539
540 /** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_flush()
541  *
542  * \param  decoder  A decoder instance.
543  * \assert
544  *    \code decoder != NULL \endcode
545  * \retval FLAC__bool
546  *    \c true if successful, else \c false if a memory allocation
547  *    error occurs.
548  */
549 OggFLAC_API FLAC__bool OggFLAC__stream_decoder_flush(OggFLAC__StreamDecoder *decoder);
550
551 /** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_reset()
552  *
553  * \param  decoder  A decoder instance.
554  * \assert
555  *    \code decoder != NULL \endcode
556  * \retval FLAC__bool
557  *    \c true if successful, else \c false if a memory allocation
558  *    error occurs.
559  */
560 OggFLAC_API FLAC__bool OggFLAC__stream_decoder_reset(OggFLAC__StreamDecoder *decoder);
561
562 /** Decode one metadata block or audio frame.
563  *  This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_process_single()
564  *
565  * \param  decoder  An initialized decoder instance in the state
566  *                  \c OggFLAC__STREAM_DECODER_OK.
567  * \assert
568  *    \code decoder != NULL \endcode
569  *    \code OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_OK \endcode
570  * \retval FLAC__bool
571  *    \c false if any read or write error occurred (except
572  *    \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
573  *    in any case, check the decoder state with
574  *    OggFLAC__stream_decoder_get_state() to see what went wrong or to
575  *    check for lost synchronization (a sign of stream corruption).
576  */
577 OggFLAC_API FLAC__bool OggFLAC__stream_decoder_process_single(OggFLAC__StreamDecoder *decoder);
578
579 /** Decode until the end of the metadata.
580  *  This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_process_until_end_of_metadata()
581  *
582  * \param  decoder  An initialized decoder instance in the state
583  *                  \c OggFLAC__STREAM_DECODER_OK.
584  * \assert
585  *    \code decoder != NULL \endcode
586  *    \code OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_OK \endcode
587  * \retval FLAC__bool
588  *    \c false if any read or write error occurred (except
589  *    \c OggFLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
590  *    in any case, check the decoder state with
591  *    OggFLAC__stream_decoder_get_state() to see what went wrong or to
592  *    check for lost synchronization (a sign of stream corruption).
593  */
594 OggFLAC_API FLAC__bool OggFLAC__stream_decoder_process_until_end_of_metadata(OggFLAC__StreamDecoder *decoder);
595
596 /** Decode until the end of the stream.
597  *  This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_process_until_end_of_stream()
598  *
599  * \param  decoder  An initialized decoder instance in the state
600  *                  \c OggFLAC__STREAM_DECODER_OK.
601  * \assert
602  *    \code decoder != NULL \endcode
603  *    \code OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_OK \endcode
604  * \retval FLAC__bool
605  *    \c false if any read or write error occurred (except
606  *    \c OggFLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
607  *    in any case, check the decoder state with
608  *    OggFLAC__stream_decoder_get_state() to see what went wrong or to
609  *    check for lost synchronization (a sign of stream corruption).
610  */
611 OggFLAC_API FLAC__bool OggFLAC__stream_decoder_process_until_end_of_stream(OggFLAC__StreamDecoder *decoder);
612
613 /* \} */
614
615 #ifdef __cplusplus
616 }
617 #endif
618
619 #endif