seekable_stream_decoder.h
Upload User: wstnjxml
Upload Date: 2014-04-03
Package Size: 7248k
Code Size: 33k
Category:

Windows CE

Development Platform:

C/C++

  1. /* libOggFLAC - Free Lossless Audio Codec + Ogg library
  2.  * Copyright (C) 2002,2003,2004,2005  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. #ifndef OggFLAC__SEEKABLE_STREAM_DECODER_H
  32. #define OggFLAC__SEEKABLE_STREAM_DECODER_H
  33. #include "export.h"
  34. #include "stream_decoder.h"
  35. #ifdef __cplusplus
  36. extern "C" {
  37. #endif
  38. /** file include/OggFLAC/seekable_stream_decoder.h
  39.  *
  40.  *  brief
  41.  *  This module contains the functions which implement the seekable stream
  42.  *  decoder.
  43.  *
  44.  *  See the detailed documentation in the
  45.  *  link oggflac_seekable_stream_decoder seekable stream decoder endlink module.
  46.  */
  47. /** defgroup oggflac_seekable_stream_decoder OggFLAC/seekable_stream_decoder.h: seekable stream decoder interface
  48.  *  ingroup oggflac_decoder
  49.  *
  50.  *  brief
  51.  *  This module contains the functions which implement the seekable stream
  52.  *  decoder.
  53.  *
  54.  * The interface here is nearly identical to FLAC's seekable stream decoder,
  55.  * including the callbacks, with the addition of
  56.  * OggFLAC__seekable_stream_decoder_set_serial_number().  See the
  57.  * link flac_seekable_stream_decoder FLAC seekable stream decoder module endlink
  58.  * for full documentation.
  59.  *
  60.  * {
  61.  */
  62. /** State values for an OggFLAC__SeekableStreamDecoder
  63.  *
  64.  *  The decoder's state can be obtained by calling OggFLAC__seekable_stream_decoder_get_state().
  65.  */
  66. typedef enum {
  67. OggFLAC__SEEKABLE_STREAM_DECODER_OK = 0,
  68. /**< The decoder is in the normal OK state. */
  69. OggFLAC__SEEKABLE_STREAM_DECODER_SEEKING,
  70. /**< The decoder is in the process of seeking. */
  71. OggFLAC__SEEKABLE_STREAM_DECODER_END_OF_STREAM,
  72. /**< The decoder has reached the end of the stream. */
  73. OggFLAC__SEEKABLE_STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
  74. /**< Memory allocation failed. */
  75. OggFLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR,
  76. /**< An error occurred in the underlying stream decoder;
  77.  * check OggFLAC__seekable_stream_decoder_get_stream_decoder_state().
  78.  */
  79. OggFLAC__SEEKABLE_STREAM_DECODER_READ_ERROR,
  80. /**< The read callback returned an error. */
  81. OggFLAC__SEEKABLE_STREAM_DECODER_SEEK_ERROR,
  82. /**< An error occurred while seeking or the seek or tell
  83.  * callback returned an error.
  84.  */
  85. OggFLAC__SEEKABLE_STREAM_DECODER_ALREADY_INITIALIZED,
  86. /**< OggFLAC__seekable_stream_decoder_init() was called when the decoder was
  87.  * already initialized, usually because
  88.  * OggFLAC__seekable_stream_decoder_finish() was not called.
  89.  */
  90. OggFLAC__SEEKABLE_STREAM_DECODER_INVALID_CALLBACK,
  91. /**< The decoder was initialized before setting all the required callbacks. */
  92. OggFLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED
  93. /**< The decoder is in the uninitialized state. */
  94. } OggFLAC__SeekableStreamDecoderState;
  95. /** Maps an OggFLAC__SeekableStreamDecoderState to a C string.
  96.  *
  97.  *  Using an OggFLAC__SeekableStreamDecoderState as the index to this array
  98.  *  will give the string equivalent.  The contents should not be modified.
  99.  */
  100. extern OggFLAC_API const char * const OggFLAC__SeekableStreamDecoderStateString[];
  101. /** Return values for the OggFLAC__SeekableStreamDecoder read callback.
  102.  */
  103. typedef enum {
  104. OggFLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_OK,
  105. /**< The read was OK and decoding can continue. */
  106. OggFLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_ERROR
  107. /**< An unrecoverable error occurred.  The decoder will return from the process call. */
  108. } OggFLAC__SeekableStreamDecoderReadStatus;
  109. /** Maps a OggFLAC__SeekableStreamDecoderReadStatus to a C string.
  110.  *
  111.  *  Using a OggFLAC__SeekableStreamDecoderReadStatus as the index to this array
  112.  *  will give the string equivalent.  The contents should not be modified.
  113.  */
  114. extern OggFLAC_API const char * const OggFLAC__SeekableStreamDecoderReadStatusString[];
  115. /** Return values for the OggFLAC__SeekableStreamDecoder seek callback.
  116.  */
  117. typedef enum {
  118. OggFLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_OK,
  119. /**< The seek was OK and decoding can continue. */
  120. OggFLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_ERROR
  121. /**< An unrecoverable error occurred.  The decoder will return from the process call. */
  122. } OggFLAC__SeekableStreamDecoderSeekStatus;
  123. /** Maps a OggFLAC__SeekableStreamDecoderSeekStatus to a C string.
  124.  *
  125.  *  Using a OggFLAC__SeekableStreamDecoderSeekStatus as the index to this array
  126.  *  will give the string equivalent.  The contents should not be modified.
  127.  */
  128. extern OggFLAC_API const char * const OggFLAC__SeekableStreamDecoderSeekStatusString[];
  129. /** Return values for the OggFLAC__SeekableStreamDecoder tell callback.
  130.  */
  131. typedef enum {
  132. OggFLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_OK,
  133. /**< The tell was OK and decoding can continue. */
  134. OggFLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_ERROR
  135. /**< An unrecoverable error occurred.  The decoder will return from the process call. */
  136. } OggFLAC__SeekableStreamDecoderTellStatus;
  137. /** Maps a OggFLAC__SeekableStreamDecoderTellStatus to a C string.
  138.  *
  139.  *  Using a OggFLAC__SeekableStreamDecoderTellStatus as the index to this array
  140.  *  will give the string equivalent.  The contents should not be modified.
  141.  */
  142. extern OggFLAC_API const char * const OggFLAC__SeekableStreamDecoderTellStatusString[];
  143. /** Return values for the OggFLAC__SeekableStreamDecoder length callback.
  144.  */
  145. typedef enum {
  146. OggFLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_OK,
  147. /**< The length call was OK and decoding can continue. */
  148. OggFLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_ERROR
  149. /**< An unrecoverable error occurred.  The decoder will return from the process call. */
  150. } OggFLAC__SeekableStreamDecoderLengthStatus;
  151. /** Maps a OggFLAC__SeekableStreamDecoderLengthStatus to a C string.
  152.  *
  153.  *  Using a OggFLAC__SeekableStreamDecoderLengthStatus as the index to this array
  154.  *  will give the string equivalent.  The contents should not be modified.
  155.  */
  156. extern OggFLAC_API const char * const OggFLAC__SeekableStreamDecoderLengthStatusString[];
  157. /***********************************************************************
  158.  *
  159.  * class OggFLAC__SeekableStreamDecoder : public FLAC__StreamDecoder
  160.  *
  161.  ***********************************************************************/
  162. struct OggFLAC__SeekableStreamDecoderProtected;
  163. struct OggFLAC__SeekableStreamDecoderPrivate;
  164. /** The opaque structure definition for the seekable stream decoder type.
  165.  *  See the
  166.  *  link oggflac_seekable_stream_decoder seekable stream decoder module endlink
  167.  *  for a detailed description.
  168.  */
  169. typedef struct {
  170. struct OggFLAC__SeekableStreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
  171. struct OggFLAC__SeekableStreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
  172. } OggFLAC__SeekableStreamDecoder;
  173. /** Signature for the read callback.
  174.  *  See OggFLAC__seekable_stream_decoder_set_read_callback()
  175.  *  and OggFLAC__StreamDecoderReadCallback for more info.
  176.  *
  177.  * param  decoder  The decoder instance calling the callback.
  178.  * param  buffer   A pointer to a location for the callee to store
  179.  *                  data to be decoded.
  180.  * param  bytes    A pointer to the size of the buffer.
  181.  * param  client_data  The callee's client data set through
  182.  *                      OggFLAC__seekable_stream_decoder_set_client_data().
  183.  * retval FLAC__SeekableStreamDecoderReadStatus
  184.  *    The callee's return status.
  185.  */
  186. typedef OggFLAC__SeekableStreamDecoderReadStatus (*OggFLAC__SeekableStreamDecoderReadCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
  187. /** Signature for the seek callback.
  188.  *  See OggFLAC__seekable_stream_decoder_set_seek_callback() for more info.
  189.  *
  190.  * param  decoder  The decoder instance calling the callback.
  191.  * param  absolute_byte_offset  The offset from the beginning of the stream
  192.  *                               to seek to.
  193.  * param  client_data  The callee's client data set through
  194.  *                      OggFLAC__seekable_stream_decoder_set_client_data().
  195.  * retval FLAC__SeekableStreamDecoderSeekStatus
  196.  *    The callee's return status.
  197.  */
  198. typedef OggFLAC__SeekableStreamDecoderSeekStatus (*OggFLAC__SeekableStreamDecoderSeekCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
  199. /** Signature for the tell callback.
  200.  *  See OggFLAC__seekable_stream_decoder_set_tell_callback() for more info.
  201.  *
  202.  * param  decoder  The decoder instance calling the callback.
  203.  * param  absolute_byte_offset  A pointer to storage for the current offset
  204.  *                               from the beginning of the stream.
  205.  * param  client_data  The callee's client data set through
  206.  *                      OggFLAC__seekable_stream_decoder_set_client_data().
  207.  * retval FLAC__SeekableStreamDecoderTellStatus
  208.  *    The callee's return status.
  209.  */
  210. typedef OggFLAC__SeekableStreamDecoderTellStatus (*OggFLAC__SeekableStreamDecoderTellCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
  211. /** Signature for the length callback.
  212.  *  See OggFLAC__seekable_stream_decoder_set_length_callback() for more info.
  213.  *
  214.  * param  decoder  The decoder instance calling the callback.
  215.  * param  stream_length  A pointer to storage for the length of the stream
  216.  *                        in bytes.
  217.  * param  client_data  The callee's client data set through
  218.  *                      OggFLAC__seekable_stream_decoder_set_client_data().
  219.  * retval FLAC__SeekableStreamDecoderLengthStatus
  220.  *    The callee's return status.
  221.  */
  222. typedef OggFLAC__SeekableStreamDecoderLengthStatus (*OggFLAC__SeekableStreamDecoderLengthCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
  223. /** Signature for the EOF callback.
  224.  *  See OggFLAC__seekable_stream_decoder_set_eof_callback() for more info.
  225.  *
  226.  * param  decoder  The decoder instance calling the callback.
  227.  * param  client_data  The callee's client data set through
  228.  *                      OggFLAC__seekable_stream_decoder_set_client_data().
  229.  * retval FLAC__bool
  230.  *    c true if the currently at the end of the stream, else c false.
  231.  */
  232. typedef FLAC__bool (*OggFLAC__SeekableStreamDecoderEofCallback)(const OggFLAC__SeekableStreamDecoder *decoder, void *client_data);
  233. /** Signature for the write callback.
  234.  *  See OggFLAC__seekable_stream_decoder_set_write_callback()
  235.  *  and OggFLAC__StreamDecoderWriteCallback for more info.
  236.  *
  237.  * param  decoder  The decoder instance calling the callback.
  238.  * param  frame    The description of the decoded frame.
  239.  * param  buffer   An array of pointers to decoded channels of data.
  240.  * param  client_data  The callee's client data set through
  241.  *                      OggFLAC__seekable_stream_decoder_set_client_data().
  242.  * retval FLAC__StreamDecoderWriteStatus
  243.  *    The callee's return status.
  244.  */
  245. typedef FLAC__StreamDecoderWriteStatus (*OggFLAC__SeekableStreamDecoderWriteCallback)(const OggFLAC__SeekableStreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
  246. /** Signature for the metadata callback.
  247.  *  See OggFLAC__seekable_stream_decoder_set_metadata_callback()
  248.  *  and OggFLAC__StreamDecoderMetadataCallback for more info.
  249.  *
  250.  * param  decoder  The decoder instance calling the callback.
  251.  * param  metadata The decoded metadata block.
  252.  * param  client_data  The callee's client data set through
  253.  *                      OggFLAC__seekable_stream_decoder_set_client_data().
  254.  */
  255. typedef void (*OggFLAC__SeekableStreamDecoderMetadataCallback)(const OggFLAC__SeekableStreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
  256. /** Signature for the error callback.
  257.  *  See OggFLAC__seekable_stream_decoder_set_error_callback()
  258.  *  and OggFLAC__StreamDecoderErrorCallback for more info.
  259.  *
  260.  * param  decoder  The decoder instance calling the callback.
  261.  * param  status   The error encountered by the decoder.
  262.  * param  client_data  The callee's client data set through
  263.  *                      OggFLAC__seekable_stream_decoder_set_client_data().
  264.  */
  265. typedef void (*OggFLAC__SeekableStreamDecoderErrorCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
  266. /***********************************************************************
  267.  *
  268.  * Class constructor/destructor
  269.  *
  270.  ***********************************************************************/
  271. /** Create a new seekable stream decoder instance.  The instance is created
  272.  *  with default settings; see the individual
  273.  *  OggFLAC__seekable_stream_decoder_set_*() functions for each setting's
  274.  *  default.
  275.  *
  276.  * retval OggFLAC__SeekableStreamDecoder*
  277.  *    c NULL if there was an error allocating memory, else the new instance.
  278.  */
  279. OggFLAC_API OggFLAC__SeekableStreamDecoder *OggFLAC__seekable_stream_decoder_new();
  280. /** Free a decoder instance.  Deletes the object pointed to by a decoder.
  281.  *
  282.  * param decoder  A pointer to an existing decoder.
  283.  * assert
  284.  *    code decoder != NULL endcode
  285.  */
  286. OggFLAC_API void OggFLAC__seekable_stream_decoder_delete(OggFLAC__SeekableStreamDecoder *decoder);
  287. /***********************************************************************
  288.  *
  289.  * Public class method prototypes
  290.  *
  291.  ***********************************************************************/
  292. /** Set the "MD5 signature checking" flag.
  293.  *  This is inherited from FLAC__SeekableStreamDecoder; see
  294.  *  FLAC__seekable_stream_decoder_set_md5_checking().
  295.  *
  296.  * default c false
  297.  * param  decoder  A decoder instance to set.
  298.  * param  value    Flag value (see above).
  299.  * assert
  300.  *    code decoder != NULL endcode
  301.  * retval FLAC__bool
  302.  *    c false if the decoder is already initialized, else c true.
  303.  */
  304. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_md5_checking(OggFLAC__SeekableStreamDecoder *decoder, FLAC__bool value);
  305. /** Set the read callback.
  306.  *  This is inherited from FLAC__SeekableStreamDecoder; see
  307.  *  FLAC__seekable_stream_decoder_set_read_callback().
  308.  *
  309.  * note
  310.  * The callback is mandatory and must be set before initialization.
  311.  *
  312.  * default c NULL
  313.  * param  decoder  A decoder instance to set.
  314.  * param  value    See above.
  315.  * assert
  316.  *    code decoder != NULL endcode
  317.  *    code value != NULL endcode
  318.  * retval FLAC__bool
  319.  *    c false if the decoder is already initialized, else c true.
  320.  */
  321. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_read_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderReadCallback value);
  322. /** Set the seek callback.
  323.  *  This is inherited from FLAC__SeekableStreamDecoder; see
  324.  *  FLAC__seekable_stream_decoder_set_seek_callback().
  325.  *
  326.  * note
  327.  * The callback is mandatory and must be set before initialization.
  328.  *
  329.  * default c NULL
  330.  * param  decoder  A decoder instance to set.
  331.  * param  value    See above.
  332.  * assert
  333.  *    code decoder != NULL endcode
  334.  *    code value != NULL endcode
  335.  * retval FLAC__bool
  336.  *    c false if the decoder is already initialized, else c true.
  337.  */
  338. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_seek_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderSeekCallback value);
  339. /** Set the tell callback.
  340.  *  This is inherited from FLAC__SeekableStreamDecoder; see
  341.  *  FLAC__seekable_stream_decoder_set_tell_callback().
  342.  *
  343.  * note
  344.  * The callback is mandatory and must be set before initialization.
  345.  *
  346.  * default c NULL
  347.  * param  decoder  A decoder instance to set.
  348.  * param  value    See above.
  349.  * assert
  350.  *    code decoder != NULL endcode
  351.  *    code value != NULL endcode
  352.  * retval FLAC__bool
  353.  *    c false if the decoder is already initialized, else c true.
  354.  */
  355. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_tell_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderTellCallback value);
  356. /** Set the length callback.
  357.  *  This is inherited from FLAC__SeekableStreamDecoder; see
  358.  *  FLAC__seekable_stream_decoder_set_length_callback().
  359.  *
  360.  * note
  361.  * The callback is mandatory and must be set before initialization.
  362.  *
  363.  * default c NULL
  364.  * param  decoder  A decoder instance to set.
  365.  * param  value    See above.
  366.  * assert
  367.  *    code decoder != NULL endcode
  368.  *    code value != NULL endcode
  369.  * retval FLAC__bool
  370.  *    c false if the decoder is already initialized, else c true.
  371.  */
  372. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_length_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderLengthCallback value);
  373. /** Set the eof callback.
  374.  *  This is inherited from FLAC__SeekableStreamDecoder; see
  375.  *  FLAC__seekable_stream_decoder_set_eof_callback().
  376.  *
  377.  * note
  378.  * The callback is mandatory and must be set before initialization.
  379.  *
  380.  * default c NULL
  381.  * param  decoder  A decoder instance to set.
  382.  * param  value    See above.
  383.  * assert
  384.  *    code decoder != NULL endcode
  385.  *    code value != NULL endcode
  386.  * retval FLAC__bool
  387.  *    c false if the decoder is already initialized, else c true.
  388.  */
  389. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_eof_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderEofCallback value);
  390. /** Set the write callback.
  391.  *  This is inherited from FLAC__SeekableStreamDecoder; see
  392.  *  FLAC__seekable_stream_decoder_set_write_callback().
  393.  *
  394.  * note
  395.  * The callback is mandatory and must be set before initialization.
  396.  *
  397.  * default c NULL
  398.  * param  decoder  A decoder instance to set.
  399.  * param  value    See above.
  400.  * assert
  401.  *    code decoder != NULL endcode
  402.  *    code value != 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__seekable_stream_decoder_set_write_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderWriteCallback value);
  407. /** Set the metadata callback.
  408.  *  This is inherited from FLAC__SeekableStreamDecoder; see
  409.  *  FLAC__seekable_stream_decoder_set_metadata_callback().
  410.  *
  411.  * note
  412.  * The callback is mandatory and must be set before initialization.
  413.  *
  414.  * default c NULL
  415.  * param  decoder  A decoder instance to set.
  416.  * param  value    See above.
  417.  * assert
  418.  *    code decoder != NULL endcode
  419.  *    code value != NULL endcode
  420.  * retval FLAC__bool
  421.  *    c false if the decoder is already initialized, else c true.
  422.  */
  423. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderMetadataCallback value);
  424. /** Set the error callback.
  425.  *  This is inherited from FLAC__SeekableStreamDecoder; see
  426.  *  FLAC__seekable_stream_decoder_set_error_callback().
  427.  *
  428.  * note
  429.  * The callback is mandatory and must be set before initialization.
  430.  *
  431.  * default c NULL
  432.  * param  decoder  A decoder instance to set.
  433.  * param  value    See above.
  434.  * assert
  435.  *    code decoder != NULL endcode
  436.  *    code value != NULL endcode
  437.  * retval FLAC__bool
  438.  *    c false if the decoder is already initialized, else c true.
  439.  */
  440. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_error_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderErrorCallback value);
  441. /** Set the client data to be passed back to callbacks.
  442.  *  This value will be supplied to callbacks in their a client_data
  443.  *  argument.
  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.  * retval FLAC__bool
  451.  *    c false if the decoder is already initialized, else c true.
  452.  */
  453. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_client_data(OggFLAC__SeekableStreamDecoder *decoder, void *value);
  454. /** Set the serial number for the Ogg stream.
  455.  * The default behavior is to use the serial number of the first Ogg
  456.  * page.  Setting a serial number here will explicitly specify which
  457.  * stream is to be decoded.
  458.  *
  459.  * default c use serial number of first page
  460.  * param  decoder        A decoder instance to set.
  461.  * param  serial_number  See above.
  462.  * assert
  463.  *    code decoder != NULL endcode
  464.  * retval FLAC__bool
  465.  *    c false if the decoder is already initialized, else c true.
  466.  */
  467. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_serial_number(OggFLAC__SeekableStreamDecoder *decoder, long serial_number);
  468. /** This is inherited from FLAC__SeekableStreamDecoder; see
  469.  *  FLAC__seekable_stream_decoder_set_metadata_respond().
  470.  *
  471.  * default By default, only the c STREAMINFO block is returned via the
  472.  *          metadata callback.
  473.  * param  decoder  A decoder instance to set.
  474.  * param  type     See above.
  475.  * assert
  476.  *    code decoder != NULL endcode
  477.  *    a type is valid
  478.  * retval FLAC__bool
  479.  *    c false if the decoder is already initialized, else c true.
  480.  */
  481. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond(OggFLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type);
  482. /** This is inherited from FLAC__SeekableStreamDecoder; see
  483.  *  FLAC__seekable_stream_decoder_set_metadata_respond_application().
  484.  *
  485.  * default By default, only the c STREAMINFO block is returned via the
  486.  *          metadata callback.
  487.  * param  decoder  A decoder instance to set.
  488.  * param  id       See above.
  489.  * assert
  490.  *    code decoder != NULL endcode
  491.  *    code id != NULL endcode
  492.  * retval FLAC__bool
  493.  *    c false if the decoder is already initialized, else c true.
  494.  */
  495. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond_application(OggFLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
  496. /** This is inherited from FLAC__SeekableStreamDecoder; see
  497.  *  FLAC__seekable_stream_decoder_set_metadata_respond_all().
  498.  *
  499.  * default By default, only the c STREAMINFO block is returned via the
  500.  *          metadata callback.
  501.  * param  decoder  A decoder instance to set.
  502.  * assert
  503.  *    code decoder != NULL endcode
  504.  * retval FLAC__bool
  505.  *    c false if the decoder is already initialized, else c true.
  506.  */
  507. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond_all(OggFLAC__SeekableStreamDecoder *decoder);
  508. /** This is inherited from FLAC__SeekableStreamDecoder; see
  509.  *  FLAC__seekable_stream_decoder_set_metadata_ignore().
  510.  *
  511.  * default By default, only the c STREAMINFO block is returned via the
  512.  *          metadata callback.
  513.  * param  decoder  A decoder instance to set.
  514.  * param  type     See above.
  515.  * assert
  516.  *    code decoder != NULL endcode
  517.  *    a type is valid
  518.  * retval FLAC__bool
  519.  *    c false if the decoder is already initialized, else c true.
  520.  */
  521. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_ignore(OggFLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type);
  522. /** This is inherited from FLAC__SeekableStreamDecoder; see
  523.  *  FLAC__seekable_stream_decoder_set_metadata_ignore_application().
  524.  *
  525.  * default By default, only the c STREAMINFO block is returned via the
  526.  *          metadata callback.
  527.  * param  decoder  A decoder instance to set.
  528.  * param  id       See above.
  529.  * assert
  530.  *    code decoder != NULL endcode
  531.  *    code id != NULL endcode
  532.  * retval FLAC__bool
  533.  *    c false if the decoder is already initialized, else c true.
  534.  */
  535. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_ignore_application(OggFLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
  536. /** This is inherited from FLAC__SeekableStreamDecoder; see
  537.  *  FLAC__seekable_stream_decoder_set_metadata_ignore_all().
  538.  *
  539.  * default By default, only the c STREAMINFO block is returned via the
  540.  *          metadata callback.
  541.  * param  decoder  A decoder instance to set.
  542.  * assert
  543.  *    code decoder != NULL endcode
  544.  * retval FLAC__bool
  545.  *    c false if the decoder is already initialized, else c true.
  546.  */
  547. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_ignore_all(OggFLAC__SeekableStreamDecoder *decoder);
  548. /** Get the current decoder state.
  549.  *
  550.  * param  decoder  A decoder instance to query.
  551.  * assert
  552.  *    code decoder != NULL endcode
  553.  * retval OggFLAC__SeekableStreamDecoderState
  554.  *    The current decoder state.
  555.  */
  556. OggFLAC_API OggFLAC__SeekableStreamDecoderState OggFLAC__seekable_stream_decoder_get_state(const OggFLAC__SeekableStreamDecoder *decoder);
  557. /** Get the state of the underlying stream decoder.
  558.  *  Useful when the seekable stream decoder state is
  559.  *  c OggFLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
  560.  *
  561.  * param  decoder  A decoder instance to query.
  562.  * assert
  563.  *    code decoder != NULL endcode
  564.  * retval OggFLAC__StreamDecoderState
  565.  *    The stream decoder state.
  566.  */
  567. OggFLAC_API OggFLAC__StreamDecoderState OggFLAC__seekable_stream_decoder_get_stream_decoder_state(const OggFLAC__SeekableStreamDecoder *decoder);
  568. /** Get the state of the underlying stream decoder's FLAC stream decoder.
  569.  *  Useful when the seekable stream decoder state is
  570.  *  c OggFLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR and the
  571.  *  stream decoder state is c OggFLAC__STREAM_DECODER_FLAC_STREAM_DECODER_ERROR
  572.  *
  573.  * param  decoder  A decoder instance to query.
  574.  * assert
  575.  *    code decoder != NULL endcode
  576.  * retval FLAC__StreamDecoderState
  577.  *    The FLAC stream decoder state.
  578.  */
  579. OggFLAC_API FLAC__StreamDecoderState OggFLAC__seekable_stream_decoder_get_FLAC_stream_decoder_state(const OggFLAC__SeekableStreamDecoder *decoder);
  580. /** Get the current decoder state as a C string.
  581.  *  This version automatically resolves
  582.  *  c OggFLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR
  583.  *  by getting the stream decoder's state.
  584.  *
  585.  * param  decoder  A decoder instance to query.
  586.  * assert
  587.  *    code decoder != NULL endcode
  588.  * retval const char *
  589.  *    The decoder state as a C string.  Do not modify the contents.
  590.  */
  591. OggFLAC_API const char *OggFLAC__seekable_stream_decoder_get_resolved_state_string(const OggFLAC__SeekableStreamDecoder *decoder);
  592. /** This is inherited from FLAC__SeekableStreamDecoder; see
  593.  *  FLAC__seekable_stream_decoder_get_md5_checking().
  594.  *
  595.  * param  decoder  A decoder instance to query.
  596.  * assert
  597.  *    code decoder != NULL endcode
  598.  * retval FLAC__bool
  599.  *    See above.
  600.  */
  601. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_get_md5_checking(const OggFLAC__SeekableStreamDecoder *decoder);
  602. /** This is inherited from FLAC__SeekableStreamDecoder; see
  603.  *  FLAC__seekable_stream_decoder_get_channels().
  604.  *
  605.  * param  decoder  A decoder instance to query.
  606.  * assert
  607.  *    code decoder != NULL endcode
  608.  * retval unsigned
  609.  *    See above.
  610.  */
  611. OggFLAC_API unsigned OggFLAC__seekable_stream_decoder_get_channels(const OggFLAC__SeekableStreamDecoder *decoder);
  612. /** This is inherited from FLAC__SeekableStreamDecoder; see
  613.  *  FLAC__seekable_stream_decoder_get_channel_assignment().
  614.  *
  615.  * param  decoder  A decoder instance to query.
  616.  * assert
  617.  *    code decoder != NULL endcode
  618.  * retval OggFLAC__ChannelAssignment
  619.  *    See above.
  620.  */
  621. OggFLAC_API FLAC__ChannelAssignment OggFLAC__seekable_stream_decoder_get_channel_assignment(const OggFLAC__SeekableStreamDecoder *decoder);
  622. /** This is inherited from FLAC__SeekableStreamDecoder; see
  623.  *  FLAC__seekable_stream_decoder_get_bits_per_sample().
  624.  *
  625.  * param  decoder  A decoder instance to query.
  626.  * assert
  627.  *    code decoder != NULL endcode
  628.  * retval unsigned
  629.  *    See above.
  630.  */
  631. OggFLAC_API unsigned OggFLAC__seekable_stream_decoder_get_bits_per_sample(const OggFLAC__SeekableStreamDecoder *decoder);
  632. /** This is inherited from FLAC__SeekableStreamDecoder; see
  633.  *  FLAC__seekable_stream_decoder_get_sample_rate().
  634.  *
  635.  * param  decoder  A decoder instance to query.
  636.  * assert
  637.  *    code decoder != NULL endcode
  638.  * retval unsigned
  639.  *    See above.
  640.  */
  641. OggFLAC_API unsigned OggFLAC__seekable_stream_decoder_get_sample_rate(const OggFLAC__SeekableStreamDecoder *decoder);
  642. /** This is inherited from FLAC__SeekableStreamDecoder; see
  643.  *  FLAC__seekable_stream_decoder_get_blocksize().
  644.  *
  645.  * param  decoder  A decoder instance to query.
  646.  * assert
  647.  *    code decoder != NULL endcode
  648.  * retval unsigned
  649.  *    See above.
  650.  */
  651. OggFLAC_API unsigned OggFLAC__seekable_stream_decoder_get_blocksize(const OggFLAC__SeekableStreamDecoder *decoder);
  652. /** Initialize the decoder instance.
  653.  *  Should be called after OggFLAC__seekable_stream_decoder_new() and
  654.  *  OggFLAC__seekable_stream_decoder_set_*() but before any of the
  655.  *  OggFLAC__seekable_stream_decoder_process_*() functions.  Will set and return
  656.  *  the decoder state, which will be OggFLAC__SEEKABLE_STREAM_DECODER_OK
  657.  *  if initialization succeeded.
  658.  *
  659.  * param  decoder  An uninitialized decoder instance.
  660.  * assert
  661.  *    code decoder != NULL endcode
  662.  * retval OggFLAC__SeekableStreamDecoderState
  663.  *    c OggFLAC__SEEKABLE_STREAM_DECODER_OK if initialization was
  664.  *    successful; see OggFLAC__SeekableStreamDecoderState for the meanings
  665.  *    of other return values.
  666.  */
  667. OggFLAC_API OggFLAC__SeekableStreamDecoderState OggFLAC__seekable_stream_decoder_init(OggFLAC__SeekableStreamDecoder *decoder);
  668. /** Finish the decoding process.
  669.  *  Flushes the decoding buffer, releases resources, resets the decoder
  670.  *  settings to their defaults, and returns the decoder state to
  671.  *  OggFLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED.
  672.  *
  673.  *  In the event of a prematurely-terminated decode, it is not strictly
  674.  *  necessary to call this immediately before
  675.  *  OggFLAC__seekable_stream_decoder_delete() but it is good practice to match
  676.  *  every OggFLAC__seekable_stream_decoder_init() with a
  677.  *  OggFLAC__seekable_stream_decoder_finish().
  678.  *
  679.  * param  decoder  An uninitialized decoder instance.
  680.  * assert
  681.  *    code decoder != NULL endcode
  682.  * retval FLAC__bool
  683.  *    c false if MD5 checking is on AND a STREAMINFO block was available
  684.  *    AND the MD5 signature in the STREAMINFO block was non-zero AND the
  685.  *    signature does not match the one computed by the decoder; else
  686.  *    c true.
  687.  */
  688. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_finish(OggFLAC__SeekableStreamDecoder *decoder);
  689. /** This is inherited from FLAC__SeekableStreamDecoder; see
  690.  *  FLAC__seekable_stream_decoder_flush().
  691.  *
  692.  * param  decoder  A decoder instance.
  693.  * assert
  694.  *    code decoder != NULL endcode
  695.  * retval FLAC__bool
  696.  *    c true if successful, else c false if a memory allocation
  697.  *    or stream decoder error occurs.
  698.  */
  699. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_flush(OggFLAC__SeekableStreamDecoder *decoder);
  700. /** This is inherited from FLAC__SeekableStreamDecoder; see
  701.  *  FLAC__seekable_stream_decoder_reset().
  702.  *
  703.  * param  decoder  A decoder instance.
  704.  * assert
  705.  *    code decoder != NULL endcode
  706.  * retval FLAC__bool
  707.  *    c true if successful, else c false if a memory allocation
  708.  *    or stream decoder error occurs.
  709.  */
  710. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_reset(OggFLAC__SeekableStreamDecoder *decoder);
  711. /** This is inherited from FLAC__SeekableStreamDecoder; see
  712.  *  FLAC__seekable_stream_decoder_process_single().
  713.  *
  714.  * param  decoder  A decoder instance.
  715.  * assert
  716.  *    code decoder != NULL endcode
  717.  * retval FLAC__bool
  718.  *    See above.
  719.  */
  720. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_process_single(OggFLAC__SeekableStreamDecoder *decoder);
  721. /** This is inherited from FLAC__SeekableStreamDecoder; see
  722.  *  FLAC__seekable_stream_decoder_process_until_end_of_metadata().
  723.  *
  724.  * param  decoder  A decoder instance.
  725.  * assert
  726.  *    code decoder != NULL endcode
  727.  * retval FLAC__bool
  728.  *    See above.
  729.  */
  730. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_process_until_end_of_metadata(OggFLAC__SeekableStreamDecoder *decoder);
  731. /** This is inherited from FLAC__SeekableStreamDecoder; see
  732.  *  FLAC__seekable_stream_decoder_process_until_end_of_stream().
  733.  *
  734.  * param  decoder  A decoder instance.
  735.  * assert
  736.  *    code decoder != NULL endcode
  737.  * retval FLAC__bool
  738.  *    See above.
  739.  */
  740. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_process_until_end_of_stream(OggFLAC__SeekableStreamDecoder *decoder);
  741. /** This is inherited from FLAC__SeekableStreamDecoder; see
  742.  *  FLAC__seekable_stream_decoder_seek_absolute().
  743.  *
  744.  * param  decoder  A decoder instance.
  745.  * param  sample   The target sample number to seek to.
  746.  * assert
  747.  *    code decoder != NULL endcode
  748.  * retval FLAC__bool
  749.  *    c true if successful, else c false.
  750.  */
  751. OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_seek_absolute(OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 sample);
  752. /* } */
  753. #ifdef __cplusplus
  754. }
  755. #endif
  756. #endif