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