more doxygen comments
[flac.git] / include / OggFLAC / file_decoder.h
1 /* libOggFLAC - Free Lossless Audio Codec + Ogg library
2  * Copyright (C) 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 OggFLAC__FILE_DECODER_H
21 #define OggFLAC__FILE_DECODER_H
22
23 #include "FLAC/file_decoder.h"
24
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28
29
30 /** \file include/OggFLAC/file_decoder.h
31  *
32  *  \brief
33  *  This module contains the functions which implement the file
34  *  decoder.
35  *
36  *  See the detailed documentation in the
37  *  \link oggflac_file_decoder file decoder \endlink module.
38  */
39
40 /** \defgroup oggflac_file_decoder OggFLAC/file_decoder.h: file decoder interface
41  *  \ingroup oggflac_decoder
42  *
43  *  \brief
44  *  This module contains the functions which implement the file
45  *  decoder.
46  *
47  * The interface here is identical to FLAC's file decoder.  See the
48  * defaults, including the callbacks.  See the \link flac_file_decoder
49  * FLAC file decoder module \endlink for full documentation.
50  *
51  * \{
52  */
53
54
55 /** State values for an OggFLAC__FileDecoder
56  *
57  *  The decoder's state can be obtained by calling OggFLAC__file_decoder_get_state().
58  */
59 typedef enum {
60
61         OggFLAC__FILE_DECODER_OK = 0,
62         /**< The decoder is in the normal OK state. */
63
64         OggFLAC__FILE_DECODER_FLAC_FILE_DECODER_ERROR,
65         /**< An error occurred in the underlying FLAC file decoder;
66          * check OggFLAC__file_decoder_get_FLAC_file_decoder_state().
67          */
68
69         OggFLAC__FILE_DECODER_INVALID_CALLBACK,
70         /**< The decoder was initialized before setting all the required callbacks. */
71
72         OggFLAC__FILE_DECODER_MEMORY_ALLOCATION_ERROR,
73         /**< Memory allocation failed. */
74
75         OggFLAC__FILE_DECODER_ALREADY_INITIALIZED,
76         /**< OggFLAC__file_decoder_init() was called when the decoder was
77          * already initialized, usually because
78          * OggFLAC__file_decoder_finish() was not called.
79          */
80
81         OggFLAC__FILE_DECODER_UNINITIALIZED
82         /**< The decoder is in the uninitialized state. */
83
84 } OggFLAC__FileDecoderState;
85
86 /** Maps an OggFLAC__FileDecoderState to a C string.
87  *
88  *  Using an OggFLAC__FileDecoderState as the index to this array
89  *  will give the string equivalent.  The contents should not be modified.
90  */
91 extern const char * const OggFLAC__FileDecoderStateString[];
92
93
94 /***********************************************************************
95  *
96  * class OggFLAC__FileDecoder : public FLAC__FileDecoder
97  *
98  ***********************************************************************/
99
100 struct OggFLAC__FileDecoderProtected;
101 struct OggFLAC__FileDecoderPrivate;
102 /** The opaque structure definition for the file decoder type.  See the
103  *  \link oggflac_file_decoder file decoder module \endlink for a detailed
104  *  description.
105  */
106 typedef struct {
107         struct OggFLAC__FileDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
108         struct OggFLAC__FileDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
109 } OggFLAC__FileDecoder;
110
111 typedef FLAC__StreamDecoderWriteStatus (*OggFLAC__FileDecoderWriteCallback)(const OggFLAC__FileDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
112 typedef void (*OggFLAC__FileDecoderMetadataCallback)(const OggFLAC__FileDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
113 typedef void (*OggFLAC__FileDecoderErrorCallback)(const OggFLAC__FileDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
114
115
116 /***********************************************************************
117  *
118  * Class constructor/destructor
119  *
120  ***********************************************************************/
121
122 /** Create a new file decoder instance.  The instance is created with
123  *  default settings; see the individual OggFLAC__file_decoder_set_*()
124  *  functions for each setting's default.
125  *
126  * \retval OggFLAC__FileDecoder*
127  *    \c NULL if there was an error allocating memory, else the new instance.
128  */
129 OggFLAC__FileDecoder *OggFLAC__file_decoder_new();
130
131 /** Free a decoder instance.  Deletes the object pointed to by \a decoder.
132  *
133  * \param decoder  A pointer to an existing decoder.
134  * \assert
135  *    \code decoder != NULL \endcode
136  */
137 void OggFLAC__file_decoder_delete(OggFLAC__FileDecoder *decoder);
138
139
140 /***********************************************************************
141  *
142  * Public class method prototypes
143  *
144  ***********************************************************************/
145
146 /** Set the "MD5 signature checking" flag.
147  *  This is inherited from FLAC__FileDecoder; see
148  *  FLAC__file_decoder_set_md5_checking().
149  *
150  * \default \c false
151  * \param  decoder  A decoder instance to set.
152  * \param  value    See above.
153  * \assert
154  *    \code decoder != NULL \endcode
155  * \retval FLAC__bool
156  *    \c false if the decoder is already initialized, else \c true.
157  */
158 FLAC__bool OggFLAC__file_decoder_set_md5_checking(OggFLAC__FileDecoder *decoder, FLAC__bool value);
159
160 /** Set the input file name to decode.
161  *  This is inherited from FLAC__FileDecoder; see
162  *  FLAC__file_decoder_set_filename().
163  *
164  * \default \c "-"
165  * \param  decoder  A decoder instance to set.
166  * \param  value    The input file name, or "-" for \c stdin.
167  * \assert
168  *    \code decoder != NULL \endcode
169  *    \code value != NULL \endcode
170  * \retval FLAC__bool
171  *    \c false if the decoder is already initialized, or there was a memory
172  *    allocation error, else \c true.
173  */
174 FLAC__bool OggFLAC__file_decoder_set_filename(OggFLAC__FileDecoder *decoder, const char *value);
175
176 /** Set the write callback.
177  *  This is inherited from FLAC__FileDecoder; see
178  *  FLAC__file_decoder_set_write_callback().
179  *
180  * \note
181  * The callback is mandatory and must be set before initialization.
182  *
183  * \default \c NULL
184  * \param  decoder  A decoder instance to set.
185  * \param  value    See above.
186  * \assert
187  *    \code decoder != NULL \endcode
188  *    \code value != NULL \endcode
189  * \retval FLAC__bool
190  *    \c false if the decoder is already initialized, else \c true.
191  */
192 FLAC__bool OggFLAC__file_decoder_set_write_callback(OggFLAC__FileDecoder *decoder, OggFLAC__FileDecoderWriteCallback value);
193
194 /** Set the metadata callback.
195  *  This is inherited from FLAC__FileDecoder; see
196  *  FLAC__file_decoder_set_metadata_callback().
197  *
198  * \note
199  * The callback is mandatory and must be set before initialization.
200  *
201  * \default \c NULL
202  * \param  decoder  A decoder instance to set.
203  * \param  value    See above.
204  * \assert
205  *    \code decoder != NULL \endcode
206  *    \code value != NULL \endcode
207  * \retval FLAC__bool
208  *    \c false if the decoder is already initialized, else \c true.
209  */
210 FLAC__bool OggFLAC__file_decoder_set_metadata_callback(OggFLAC__FileDecoder *decoder, OggFLAC__FileDecoderMetadataCallback value);
211
212 /** Set the error callback.
213  *  This is inherited from FLAC__FileDecoder; see
214  *  FLAC__file_decoder_set_error_callback().
215  *
216  * \note
217  * The callback is mandatory and must be set before initialization.
218  *
219  * \default \c NULL
220  * \param  decoder  A decoder instance to set.
221  * \param  value    See above.
222  * \assert
223  *    \code decoder != NULL \endcode
224  *    \code value != NULL \endcode
225  * \retval FLAC__bool
226  *    \c false if the decoder is already initialized, else \c true.
227  */
228 FLAC__bool OggFLAC__file_decoder_set_error_callback(OggFLAC__FileDecoder *decoder, OggFLAC__FileDecoderErrorCallback value);
229
230 /** Set the client data to be passed back to callbacks.
231  *  This value will be supplied to callbacks in their \a client_data
232  *  argument.
233  *
234  * \default \c NULL
235  * \param  decoder  An decoder instance to set.
236  * \param  value    See above.
237  * \assert
238  *    \code decoder != NULL \endcode
239  * \retval FLAC__bool
240  *    \c false if the decoder is already initialized, else \c true.
241  */
242 FLAC__bool OggFLAC__file_decoder_set_client_data(OggFLAC__FileDecoder *decoder, void *value);
243
244 /** This is inherited from FLAC__FileDecoder; see
245  *  FLAC__file_decoder_set_metadata_respond().
246  *
247  * \default By default, only the \c STREAMINFO block is returned via the
248  *          metadata callback.
249  * \param  decoder  A decoder instance to set.
250  * \param  type     See above.
251  * \assert
252  *    \code decoder != NULL \endcode
253  *    \a type is valid
254  * \retval FLAC__bool
255  *    \c false if the decoder is already initialized, else \c true.
256  */
257 FLAC__bool OggFLAC__file_decoder_set_metadata_respond(OggFLAC__FileDecoder *decoder, OggFLAC__MetadataType type);
258
259 /** This is inherited from FLAC__FileDecoder; see
260  *  FLAC__file_decoder_set_metadata_respond_application().
261  *
262  * \default By default, only the \c STREAMINFO block is returned via the
263  *          metadata callback.
264  * \param  decoder  A decoder instance to set.
265  * \param  id       See above.
266  * \assert
267  *    \code decoder != NULL \endcode
268  *    \code id != NULL \endcode
269  * \retval FLAC__bool
270  *    \c false if the decoder is already initialized, else \c true.
271  */
272 FLAC__bool OggFLAC__file_decoder_set_metadata_respond_application(OggFLAC__FileDecoder *decoder, const FLAC__byte id[4]);
273
274 /** This is inherited from FLAC__FileDecoder; see
275  *  FLAC__file_decoder_set_metadata_respond_all().
276  *
277  * \default By default, only the \c STREAMINFO block is returned via the
278  *          metadata callback.
279  * \param  decoder  A decoder instance to set.
280  * \assert
281  *    \code decoder != NULL \endcode
282  * \retval FLAC__bool
283  *    \c false if the decoder is already initialized, else \c true.
284  */
285 FLAC__bool OggFLAC__file_decoder_set_metadata_respond_all(OggFLAC__FileDecoder *decoder);
286
287 /** This is inherited from FLAC__FileDecoder; see
288  *  FLAC__file_decoder_set_metadata_ignore().
289  *
290  * \default By default, only the \c STREAMINFO block is returned via the
291  *          metadata callback.
292  * \param  decoder  A decoder instance to set.
293  * \param  type     See above.
294  * \assert
295  *    \code decoder != NULL \endcode
296  *    \a type is valid
297  * \retval FLAC__bool
298  *    \c false if the decoder is already initialized, else \c true.
299  */
300 FLAC__bool OggFLAC__file_decoder_set_metadata_ignore(OggFLAC__FileDecoder *decoder, OggFLAC__MetadataType type);
301
302 /** This is inherited from FLAC__FileDecoder; see
303  *  FLAC__file_decoder_set_metadata_ignore_application().
304  *
305  * \default By default, only the \c STREAMINFO block is returned via the
306  *          metadata callback.
307  * \param  decoder  A decoder instance to set.
308  * \param  id       See above.
309  * \assert
310  *    \code decoder != NULL \endcode
311  *    \code id != NULL \endcode
312  * \retval FLAC__bool
313  *    \c false if the decoder is already initialized, else \c true.
314  */
315 FLAC__bool OggFLAC__file_decoder_set_metadata_ignore_application(OggFLAC__FileDecoder *decoder, const FLAC__byte id[4]);
316
317 /** This is inherited from FLAC__FileDecoder; see
318  *  FLAC__file_decoder_set_metadata_ignore_all().
319  *
320  * \default By default, only the \c STREAMINFO block is returned via the
321  *          metadata callback.
322  * \param  decoder  A decoder instance to set.
323  * \assert
324  *    \code decoder != NULL \endcode
325  * \retval FLAC__bool
326  *    \c false if the decoder is already initialized, else \c true.
327  */
328 FLAC__bool OggFLAC__file_decoder_set_metadata_ignore_all(OggFLAC__FileDecoder *decoder);
329
330 /** Get the current decoder state.
331  *
332  * \param  decoder  A decoder instance to query.
333  * \assert
334  *    \code decoder != NULL \endcode
335  * \retval OggFLAC__FileDecoderState
336  *    The current decoder state.
337  */
338 OggFLAC__FileDecoderState OggFLAC__file_decoder_get_state(const OggFLAC__FileDecoder *decoder);
339
340 /** Get the state of the underlying FLAC file decoder.
341  *  Useful when the file decoder state is
342  *  \c OggFLAC__FILE_DECODER_FLAC_FILE_DECODER_ERROR.
343  *
344  * \param  decoder  An decoder instance to query.
345  * \assert
346  *    \code decoder != NULL \endcode
347  * \retval FLAC__FileDecoderState
348  *    The FLAC file decoder state.
349  */
350 FLAC__FileDecoderState OggFLAC__file_decoder_get_FLAC_file_decoder_state(const OggFLAC__FileDecoder *decoder);
351
352 /** Get the state of the underlying FLAC file decoder's seekable stream decoder.
353  *  Useful when the file decoder state is
354  *  \c OggFLAC__FILE_DECODER_FLAC_FILE_DECODER_ERROR and the FLAC file decoder state is
355  *  \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR.
356  *
357  * \param  decoder  An decoder instance to query.
358  * \assert
359  *    \code decoder != NULL \endcode
360  * \retval FLAC__SeekableStreamDecoderState
361  *    The FLAC seekable stream decoder state.
362  */
363 FLAC__SeekableStreamDecoderState OggFLAC__file_decoder_get_FLAC_seekable_stream_decoder_state(const OggFLAC__FileDecoder *decoder);
364
365 /** Get the state of the underlying FLAC file decoder's stream decoder.
366  *  Useful when the file decoder state is
367  *  \c OggFLAC__FILE_DECODER_FLAC_FILE_DECODER_ERROR and the FLAC file decoder state is
368  *  \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR and the
369  *  FLAC seekable stream decoder state is \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
370  *
371  * \param  decoder  An decoder instance to query.
372  * \assert
373  *    \code decoder != NULL \endcode
374  * \retval FLAC__StreamDecoderState
375  *    The FLAC stream decoder state.
376  */
377 FLAC__StreamDecoderState OggFLAC__file_decoder_get_FLAC_stream_decoder_state(const OggFLAC__FileDecoder *decoder);
378
379 /** This is inherited from FLAC__FileDecoder; see
380  *  FLAC__file_decoder_get_md5_checking().
381  *
382  * \param  decoder  A decoder instance to query.
383  * \assert
384  *    \code decoder != NULL \endcode
385  * \retval FLAC__bool
386  *    See above.
387  */
388 FLAC__bool OggFLAC__file_decoder_get_md5_checking(const OggFLAC__FileDecoder *decoder);
389
390 /** This is inherited from FLAC__FileDecoder; see
391  *  FLAC__file_decoder_get_channels().
392  *
393  * \param  decoder  A decoder instance to query.
394  * \assert
395  *    \code decoder != NULL \endcode
396  * \retval unsigned
397  *    See above.
398  */
399 unsigned OggFLAC__file_decoder_get_channels(const OggFLAC__FileDecoder *decoder);
400
401 /** This is inherited from FLAC__FileDecoder; see
402  *  FLAC__file_decoder_get_channel_assignment().
403  *
404  * \param  decoder  A decoder instance to query.
405  * \assert
406  *    \code decoder != NULL \endcode
407  * \retval OggFLAC__ChannelAssignment
408  *    See above.
409  */
410 OggFLAC__ChannelAssignment OggFLAC__file_decoder_get_channel_assignment(const OggFLAC__FileDecoder *decoder);
411
412 /** This is inherited from FLAC__FileDecoder; see
413  *  FLAC__file_decoder_get_bits_per_sample().
414  *
415  * \param  decoder  A decoder instance to query.
416  * \assert
417  *    \code decoder != NULL \endcode
418  * \retval unsigned
419  *    See above.
420  */
421 unsigned OggFLAC__file_decoder_get_bits_per_sample(const OggFLAC__FileDecoder *decoder);
422
423 /** This is inherited from FLAC__FileDecoder; see
424  *  FLAC__file_decoder_get_sample_rate().
425  *
426  * \param  decoder  A decoder instance to query.
427  * \assert
428  *    \code decoder != NULL \endcode
429  * \retval unsigned
430  *    See above.
431  */
432 unsigned OggFLAC__file_decoder_get_sample_rate(const OggFLAC__FileDecoder *decoder);
433
434 /** This is inherited from FLAC__FileDecoder; see
435  *  FLAC__file_decoder_get_blocksize().
436  *
437  * \param  decoder  A decoder instance to query.
438  * \assert
439  *    \code decoder != NULL \endcode
440  * \retval unsigned
441  *    See above.
442  */
443 unsigned OggFLAC__file_decoder_get_blocksize(const OggFLAC__FileDecoder *decoder);
444
445 /** Initialize the decoder instance.
446  *  Should be called after OggFLAC__file_decoder_new() and
447  *  OggFLAC__file_decoder_set_*() but before any of the
448  *  OggFLAC__file_decoder_process_*() functions.  Will set and return
449  *  the decoder state, which will be OggFLAC__FILE_DECODER_OK if
450  *  initialization succeeded.
451  *
452  * \param  decoder  An uninitialized decoder instance.
453  * \assert
454  *    \code decoder != NULL \endcode
455  * \retval OggFLAC__FileDecoderState
456  *    \c OggFLAC__FILE_DECODER_OK if initialization was successful; see
457  *    OggFLAC__FileDecoderState for the meanings of other return values.
458  */
459 OggFLAC__FileDecoderState OggFLAC__file_decoder_init(OggFLAC__FileDecoder *decoder);
460
461 /** Finish the decoding process.
462  *  Flushes the decoding buffer, releases resources, resets the decoder
463  *  settings to their defaults, and returns the decoder state to
464  *  OggFLAC__FILE_DECODER_UNINITIALIZED.
465  *
466  *  In the event of a prematurely-terminated decode, it is not strictly
467  *  necessary to call this immediately before OggFLAC__file_decoder_delete()
468  *  but it is good practice to match every OggFLAC__file_decoder_init() with
469  *  an OggFLAC__file_decoder_finish().
470  *
471  * \param  decoder  An uninitialized decoder instance.
472  * \assert
473  *    \code decoder != NULL \endcode
474  * \retval FLAC__bool
475  *    \c false if MD5 checking is on AND a STREAMINFO block was available
476  *    AND the MD5 signature in the STREAMINFO block was non-zero AND the
477  *    signature does not match the one computed by the decoder; else
478  *    \c true.
479  */
480 FLAC__bool OggFLAC__file_decoder_finish(OggFLAC__FileDecoder *decoder);
481
482 /** This is inherited from FLAC__FileDecoder; see
483  *  FLAC__file_decoder_process_single().
484  *
485  * \param  decoder  A decoder instance.
486  * \assert
487  *    \code decoder != NULL \endcode
488  * \retval FLAC__bool
489  *    See above.
490  */
491 FLAC__bool OggFLAC__file_decoder_process_single(OggFLAC__FileDecoder *decoder);
492
493 /** This is inherited from FLAC__FileDecoder; see
494  *  FLAC__file_decoder_process_until_end_of_metadata().
495  *
496  * \param  decoder  A decoder instance.
497  * \assert
498  *    \code decoder != NULL \endcode
499  * \retval FLAC__bool
500  *    See above.
501  */
502 FLAC__bool OggFLAC__file_decoder_process_until_end_of_metadata(OggFLAC__FileDecoder *decoder);
503
504 /** This is inherited from FLAC__FileDecoder; see
505  *  FLAC__file_decoder_process_until_end_of_stream().
506  *
507  * \param  decoder  A decoder instance.
508  * \assert
509  *    \code decoder != NULL \endcode
510  * \retval FLAC__bool
511  *    See above.
512  */
513 FLAC__bool OggFLAC__file_decoder_process_until_end_of_file(OggFLAC__FileDecoder *decoder);
514
515 /** This is inherited from FLAC__FileDecoder; see
516  *  FLAC__file_decoder_process_remaining_frames().
517  *
518  * \param  decoder  A decoder instance.
519  * \assert
520  *    \code decoder != NULL \endcode
521  * \retval FLAC__bool
522  *    See above.
523  */
524 FLAC__bool OggFLAC__file_decoder_process_remaining_frames(OggFLAC__FileDecoder *decoder);
525
526 /** This is inherited from FLAC__FileDecoder; see
527  *  FLAC__file_decoder_seek_absolute().
528  *
529  * \param  decoder  A decoder instance.
530  * \param  sample   The target sample number to seek to.
531  * \assert
532  *    \code decoder != NULL \endcode
533  * \retval FLAC__bool
534  *    \c true if successful, else \c false.
535  */
536 FLAC__bool OggFLAC__file_decoder_seek_absolute(OggFLAC__FileDecoder *decoder, FLAC__uint64 sample);
537
538 /* \} */
539
540 #ifdef __cplusplus
541 }
542 #endif
543
544 #endif