struct FLAC__FileDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
} FLAC__FileDecoder;
-/* @@@@ document */
+/** Signature for the write callback.
+ * See FLAC__file_decoder_set_write_callback()
+ * and FLAC__SeekableStreamDecoderWriteCallback for more info.
+ *
+ * \param decoder The decoder instance calling the callback.
+ * \param frame The description of the decoded frame.
+ * \param buffer An array of pointers to decoded channels of data.
+ * \param client_data The callee's client data set through
+ * FLAC__file_decoder_set_client_data().
+ * \retval FLAC__StreamDecoderWriteStatus
+ * The callee's return status.
+ */
typedef FLAC__StreamDecoderWriteStatus (*FLAC__FileDecoderWriteCallback)(const FLAC__FileDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
+
+/** Signature for the metadata callback.
+ * See FLAC__file_decoder_set_metadata_callback()
+ * and FLAC__SeekableStreamDecoderMetadataCallback for more info.
+ *
+ * \param decoder The decoder instance calling the callback.
+ * \param metadata The decoded metadata block.
+ * \param client_data The callee's client data set through
+ * FLAC__file_decoder_set_client_data().
+ */
typedef void (*FLAC__FileDecoderMetadataCallback)(const FLAC__FileDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
+
+/** Signature for the error callback.
+ * See FLAC__file_decoder_set_error_callback()
+ * and FLAC__SeekableStreamDecoderErrorCallback for more info.
+ *
+ * \param decoder The decoder instance calling the callback.
+ * \param status The error encountered by the decoder.
+ * \param client_data The callee's client data set through
+ * FLAC__file_decoder_set_client_data().
+ */
typedef void (*FLAC__FileDecoderErrorCallback)(const FLAC__FileDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
* Using a FLAC__FileEncoderState as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
-/* @@@@ double-check mapping */
extern const char * const FLAC__FileEncoderStateString[];
struct FLAC__FileEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
} FLAC__FileEncoder;
-/*@@@ document: */
+/** Signature for the progress callback.
+ * See FLAC__file_encoder_set_progress_callback() for more info.
+ *
+ * \param encoder The encoder instance calling the callback.
+ * \param bytes_written Bytes written so far.
+ * \param samples_written Samples written so far.
+ * \param frames_written Frames written so far.
+ * \param total_frames_estimate The estimate of the total number of
+ * frames to be written.
+ * \param client_data The callee's client data set through
+ * FLAC__file_encoder_set_client_data().
+ */
typedef void (*FLAC__FileEncoderProgressCallback)(const FLAC__FileEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data);
*/
FLAC__bool FLAC__format_sample_rate_is_valid(unsigned sample_rate);
-/** Check a seektable to see if it conforms to the FLAC specification.
+/** Check a seek table to see if it conforms to the FLAC specification.
* See the format specification for limits on the contents of the
- * seektable.
+ * seek table.
*
- * \param object A pointer to a seek table to be checked.
+ * \param seek_table A pointer to a seek table to be checked.
* \assert
- * \code object != NULL \endcode
+ * \code seek_table != NULL \endcode
* \retval FLAC__bool
* \c false if seek table is illegal, else \c true.
*/
-FLAC__bool FLAC__format_seektable_is_legal(const FLAC__StreamMetadata_SeekTable *object);
+FLAC__bool FLAC__format_seektable_is_legal(const FLAC__StreamMetadata_SeekTable *seek_table);
-/* @@@@ document */
+/** Sort a seek table's seek points according to the format specification.
+ * This includes a "unique-ification" step to remove duplicates, i.e.
+ * seek points with identical \a sample_number values. Duplicate seek
+ * points are converted into placeholder points and sorted to the end of
+ * the table.
+ *
+ * \param seek_table A pointer to a seek table to be sorted.
+ * \assert
+ * \code seek_table != NULL \endcode
+ * \retval unsigned
+ * The number of duplicate seek points converted into placeholders.
+ */
unsigned FLAC__format_seektable_sort(FLAC__StreamMetadata_SeekTable *seek_table);
/* \} */
*/
FLAC__bool FLAC__metadata_object_seektable_is_legal(const FLAC__StreamMetadata *object);
-/* @@@@ document */
+/** Append a number of placeholder points to the end of a seek table.
+ *
+ * \note
+ * As with the other ..._seektable_template_... functions, you should
+ * call FLAC__metadata_object_seektable_template_sort() when finished
+ * to make the seek table legal.
+ *
+ * \param object A pointer to an existing SEEKTABLE object.
+ * \param num The number of placeholder points to append.
+ * \assert
+ * \code object != NULL \endcode
+ * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
+ * \retval FLAC__bool
+ * \c false if memory allocation fails, else \c true.
+ */
FLAC__bool FLAC__metadata_object_seektable_template_append_placeholders(FLAC__StreamMetadata *object, unsigned num);
+
+/** Append a specific seek point template to the end of a seek table.
+ *
+ * \note
+ * As with the other ..._seektable_template_... functions, you should
+ * call FLAC__metadata_object_seektable_template_sort() when finished
+ * to make the seek table legal.
+ *
+ * \param object A pointer to an existing SEEKTABLE object.
+ * \param sample_number The sample number of the seek point template.
+ * \assert
+ * \code object != NULL \endcode
+ * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
+ * \retval FLAC__bool
+ * \c false if memory allocation fails, else \c true.
+ */
FLAC__bool FLAC__metadata_object_seektable_template_append_point(FLAC__StreamMetadata *object, FLAC__uint64 sample_number);
+
+/** Append specific seek point templates to the end of a seek table.
+ *
+ * \note
+ * As with the other ..._seektable_template_... functions, you should
+ * call FLAC__metadata_object_seektable_template_sort() when finished
+ * to make the seek table legal.
+ *
+ * \param object A pointer to an existing SEEKTABLE object.
+ * \param sample_numbers An array of sample numbers for the seek points.
+ * \param num The number of seek point templates to append.
+ * \assert
+ * \code object != NULL \endcode
+ * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
+ * \retval FLAC__bool
+ * \c false if memory allocation fails, else \c true.
+ */
FLAC__bool FLAC__metadata_object_seektable_template_append_points(FLAC__StreamMetadata *object, FLAC__uint64 sample_numbers[], unsigned num);
+
+/** Append a set of evenly-spaced seek point templates to the end of a
+ * seek table.
+ *
+ * \note
+ * As with the other ..._seektable_template_... functions, you should
+ * call FLAC__metadata_object_seektable_template_sort() when finished
+ * to make the seek table legal.
+ *
+ * \param object A pointer to an existing SEEKTABLE object.
+ * \param num The number of placeholder points to append.
+ * \param total_samples The total number of samples to be encoded;
+ * the seekpoints will be spaced approximately
+ * \a total_samples / \a num samples apart.
+ * \assert
+ * \code object != NULL \endcode
+ * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
+ * \retval FLAC__bool
+ * \c false if memory allocation fails, else \c true.
+ */
FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points(FLAC__StreamMetadata *object, unsigned num, FLAC__uint64 total_samples);
+
+/** Sort a seek table's seek points according to the format specification,
+ * removing duplicates.
+ *
+ * \param object A pointer to a seek table to be sorted.
+ * \param compact If \c false, behaves like FLAC__format_seektable_sort().
+ * If \c true, duplicates are deleted and the seek table is
+ * shrunk appropriately; the number of placeholder points
+ * present in the seek table will be the same after the call
+ * as before.
+ * \assert
+ * \code object != NULL \endcode
+ * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
+ * \retval FLAC__bool
+ * \c false if realloc fails, else \c true.
+ */
FLAC__bool FLAC__metadata_object_seektable_template_sort(FLAC__StreamMetadata *object, FLAC__bool compact);
/** Sets the vendor string in a VORBIS_COMMENT block.
struct FLAC__SeekableStreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
} FLAC__SeekableStreamDecoder;
-/*@@@ document */
+/** Signature for the read callback.
+ * See FLAC__seekable_stream_decoder_set_read_callback()
+ * and FLAC__StreamDecoderReadCallback for more info.
+ *
+ * \param decoder The decoder instance calling the callback.
+ * \param buffer A pointer to a location for the callee to store
+ * data to be decoded.
+ * \param bytes A pointer to the size of the buffer.
+ * \param client_data The callee's client data set through
+ * FLAC__seekable_stream_decoder_set_client_data().
+ * \retval FLAC__SeekableStreamDecoderReadStatus
+ * The callee's return status.
+ */
typedef FLAC__SeekableStreamDecoderReadStatus (*FLAC__SeekableStreamDecoderReadCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
+
+/** Signature for the seek callback.
+ * See FLAC__seekable_stream_decoder_set_seek_callback() for more info.
+ *
+ * \param decoder The decoder instance calling the callback.
+ * \param absolute_byte_offset The offset from the beginning of the stream
+ * to seek to.
+ * \param client_data The callee's client data set through
+ * FLAC__seekable_stream_decoder_set_client_data().
+ * \retval FLAC__SeekableStreamDecoderSeekStatus
+ * The callee's return status.
+ */
typedef FLAC__SeekableStreamDecoderSeekStatus (*FLAC__SeekableStreamDecoderSeekCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
+
+/** Signature for the tell callback.
+ * See FLAC__seekable_stream_decoder_set_tell_callback() for more info.
+ *
+ * \param decoder The decoder instance calling the callback.
+ * \param absolute_byte_offset A pointer to storage for the current offset
+ * from the beginning of the stream.
+ * \param client_data The callee's client data set through
+ * FLAC__seekable_stream_decoder_set_client_data().
+ * \retval FLAC__SeekableStreamDecoderTellStatus
+ * The callee's return status.
+ */
typedef FLAC__SeekableStreamDecoderTellStatus (*FLAC__SeekableStreamDecoderTellCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
+
+/** Signature for the length callback.
+ * See FLAC__seekable_stream_decoder_set_length_callback() for more info.
+ *
+ * \param decoder The decoder instance calling the callback.
+ * \param stream_length A pointer to storage for the length of the stream
+ * in bytes.
+ * \param client_data The callee's client data set through
+ * FLAC__seekable_stream_decoder_set_client_data().
+ * \retval FLAC__SeekableStreamDecoderLengthStatus
+ * The callee's return status.
+ */
typedef FLAC__SeekableStreamDecoderLengthStatus (*FLAC__SeekableStreamDecoderLengthCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
+
+/** Signature for the EOF callback.
+ * See FLAC__seekable_stream_decoder_set_eof_callback() for more info.
+ *
+ * \param decoder The decoder instance calling the callback.
+ * \param client_data The callee's client data set through
+ * FLAC__seekable_stream_decoder_set_client_data().
+ * \retval FLAC__bool
+ * \c true if the currently at the end of the stream, else \c false.
+ */
typedef FLAC__bool (*FLAC__SeekableStreamDecoderEofCallback)(const FLAC__SeekableStreamDecoder *decoder, void *client_data);
+
+/** Signature for the write callback.
+ * See FLAC__seekable_stream_decoder_set_write_callback()
+ * and FLAC__StreamDecoderWriteCallback for more info.
+ *
+ * \param decoder The decoder instance calling the callback.
+ * \param frame The description of the decoded frame.
+ * \param buffer An array of pointers to decoded channels of data.
+ * \param client_data The callee's client data set through
+ * FLAC__seekable_stream_decoder_set_client_data().
+ * \retval FLAC__StreamDecoderWriteStatus
+ * The callee's return status.
+ */
typedef FLAC__StreamDecoderWriteStatus (*FLAC__SeekableStreamDecoderWriteCallback)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
+
+/** Signature for the metadata callback.
+ * See FLAC__seekable_stream_decoder_set_metadata_callback()
+ * and FLAC__StreamDecoderMetadataCallback for more info.
+ *
+ * \param decoder The decoder instance calling the callback.
+ * \param metadata The decoded metadata block.
+ * \param client_data The callee's client data set through
+ * FLAC__seekable_stream_decoder_set_client_data().
+ */
typedef void (*FLAC__SeekableStreamDecoderMetadataCallback)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
+
+/** Signature for the error callback.
+ * See FLAC__seekable_stream_decoder_set_error_callback()
+ * and FLAC__StreamDecoderErrorCallback for more info.
+ *
+ * \param decoder The decoder instance calling the callback.
+ * \param status The error encountered by the decoder.
+ * \param client_data The callee's client data set through
+ * FLAC__seekable_stream_decoder_set_client_data().
+ */
typedef void (*FLAC__SeekableStreamDecoderErrorCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
* Using a FLAC__SeekableStreamEncoderState as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
-/* @@@@ double-check mapping */
extern const char * const FLAC__SeekableStreamEncoderStateString[];
struct FLAC__SeekableStreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
} FLAC__SeekableStreamEncoder;
-/*@@@ document: */
+/** Signature for the seek callback.
+ * See FLAC__seekable_stream_encoder_set_seek_callback() for more info.
+ *
+ * \param encoder The encoder instance calling the callback.
+ * \param absolute_byte_offset The offset from the beginning of the stream
+ * to seek to.
+ * \param client_data The callee's client data set through
+ * FLAC__seekable_stream_encoder_set_client_data().
+ * \retval FLAC__SeekableStreamEncoderSeekStatus
+ * The callee's return status.
+ */
typedef FLAC__SeekableStreamEncoderSeekStatus (*FLAC__SeekableStreamEncoderSeekCallback)(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
+
+/** Signature for the write callback.
+ * See FLAC__seekable_stream_encoder_set_write_callback()
+ * and FLAC__StreamEncoderWriteCallback for more info.
+ *
+ * \param encoder The encoder instance calling the callback.
+ * \param buffer An array of encoded data of length \a bytes.
+ * \param bytes The byte length of \a buffer.
+ * \param samples The number of samples encoded by \a buffer.
+ * \c 0 has a special meaning; see
+ * FLAC__stream_encoder_set_write_callback().
+ * \param current_frame The number of current frame being encoded.
+ * \param client_data The callee's client data set through
+ * FLAC__seekable_stream_encoder_set_client_data().
+ * \retval FLAC__StreamEncoderWriteStatus
+ * The callee's return status.
+ */
typedef FLAC__StreamEncoderWriteStatus (*FLAC__SeekableStreamEncoderWriteCallback)(const FLAC__SeekableStreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
struct FLAC__StreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
} FLAC__StreamDecoder;
+/** Signature for the read callback.
+ * See FLAC__stream_decoder_set_read_callback() for more info.
+ *
+ * \param decoder The decoder instance calling the callback.
+ * \param buffer A pointer to a location for the callee to store
+ * data to be decoded.
+ * \param bytes A pointer to the size of the buffer. On entry
+ * to the callback, it contains the maximum number
+ * of bytes that may be stored in \a buffer. The
+ * callee must set it to the actual number of bytes
+ * stored before returning.
+ * \param client_data The callee's client data set through
+ * FLAC__stream_decoder_set_client_data().
+ * \retval FLAC__StreamDecoderReadStatus
+ * The callee's return status.
+ */
typedef FLAC__StreamDecoderReadStatus (*FLAC__StreamDecoderReadCallback)(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
+
+/** Signature for the write callback.
+ * See FLAC__stream_decoder_set_write_callback() for more info.
+ *
+ * \param decoder The decoder instance calling the callback.
+ * \param frame The description of the decoded frame. See
+ * FLAC__Frame.
+ * \param buffer An array of pointers to decoded channels of data.
+ * Each pointer will point to an array of signed
+ * samples of length \a frame->header.blocksize.
+ * Currently, the channel order has no meaning
+ * except for stereo streams; in this case channel
+ * 0 is left and 1 is right.
+ * \param client_data The callee's client data set through
+ * FLAC__stream_decoder_set_client_data().
+ * \retval FLAC__StreamDecoderWriteStatus
+ * The callee's return status.
+ */
typedef FLAC__StreamDecoderWriteStatus (*FLAC__StreamDecoderWriteCallback)(const FLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
+
+/** Signature for the metadata callback.
+ * See FLAC__stream_decoder_set_metadata_callback() for more info.
+ *
+ * \param decoder The decoder instance calling the callback.
+ * \param metadata The decoded metadata block.
+ * \param client_data The callee's client data set through
+ * FLAC__stream_decoder_set_client_data().
+ */
typedef void (*FLAC__StreamDecoderMetadataCallback)(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
+
+/** Signature for the error callback.
+ * See FLAC__stream_decoder_set_error_callback() for more info.
+ *
+ * \param decoder The decoder instance calling the callback.
+ * \param status The error encountered by the decoder.
+ * \param client_data The callee's client data set through
+ * FLAC__stream_decoder_set_client_data().
+ */
typedef void (*FLAC__StreamDecoderErrorCallback)(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
-FLAC__bool FLAC__stream_decoder_set_read_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderReadCallback);
+FLAC__bool FLAC__stream_decoder_set_read_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderReadCallback value);
/** Set the write callback.
* The supplied function will be called when the decoder has decoded a
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
-FLAC__bool FLAC__stream_decoder_set_write_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderWriteCallback);
+FLAC__bool FLAC__stream_decoder_set_write_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderWriteCallback value);
/** Set the metadata callback.
* The supplied function will be called when the decoder has decoded a
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
-FLAC__bool FLAC__stream_decoder_set_metadata_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderMetadataCallback);
+FLAC__bool FLAC__stream_decoder_set_metadata_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderMetadataCallback value);
/** Set the error callback.
* The supplied function will be called whenever an error occurs during
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
-FLAC__bool FLAC__stream_decoder_set_error_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorCallback);
+FLAC__bool FLAC__stream_decoder_set_error_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorCallback value);
/** Set the client data to be passed back to callbacks.
* This value will be supplied to callbacks in their \a client_data
* \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC \endcode
* \retval FLAC__bool
* \c false if any read or write error occurred (except
- * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c false;
+ * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
* in any case, check the decoder state with
* FLAC__stream_decoder_get_state() to see what went wrong or to
* check for lost synchronization (a sign of stream corruption).
* \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_METADATA \endcode
* \retval FLAC__bool
* \c false if any read or write error occurred (except
- * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c false;
+ * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
* in any case, check the decoder state with
* FLAC__stream_decoder_get_state() to see what went wrong or to
* check for lost synchronization (a sign of stream corruption).
* \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_METADATA \endcode
* \retval FLAC__bool
* \c false if any read or write error occurred (except
- * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c false;
+ * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
* in any case, check the decoder state with
* FLAC__stream_decoder_get_state() to see what went wrong or to
* check for lost synchronization (a sign of stream corruption).
struct FLAC__StreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
} FLAC__StreamEncoder;
-/*@@@@ document: */
+/** Signature for the write callback.
+ * See FLAC__stream_encoder_set_write_callback() for more info.
+ *
+ * \param encoder The encoder instance calling the callback.
+ * \param buffer An array of encoded data of length \a bytes.
+ * \param bytes The byte length of \a buffer.
+ * \param samples The number of samples encoded by \a buffer.
+ * \c 0 has a special meaning; see
+ * FLAC__stream_encoder_set_write_callback().
+ * \param current_frame The number of the current frame being encoded.
+ * \param client_data The callee's client data set through
+ * FLAC__stream_encoder_set_client_data().
+ * \retval FLAC__StreamDecoderWriteStatus
+ * The callee's return status.
+ */
typedef FLAC__StreamEncoderWriteStatus (*FLAC__StreamEncoderWriteCallback)(const FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
+
+/** Signature for the metadata callback.
+ * See FLAC__stream_encoder_set_metadata_callback() for more info.
+ *
+ * \param encoder The encoder instance calling the callback.
+ * \param metadata The final populated STREAMINFO block.
+ * \param client_data The callee's client data set through
+ * FLAC__stream_encoder_set_client_data().
+ */
typedef void (*FLAC__StreamEncoderMetadataCallback)(const FLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data);
/** \defgroup oggflacpp OggFLAC C++ API
*
* The OggFLAC C++ API is the interface to libOggFLAC++, a set of classes
- * that encapsulate the encoders and decoders interfaces in libOggFLAC.
+ * that encapsulate the encoders and decoders in libOggFLAC.
*
*/
* Using an OggFLAC__FileDecoderState as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
-/* @@@@ double-check mapping */
extern const char * const OggFLAC__FileDecoderStateString[];
struct OggFLAC__FileDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
} OggFLAC__FileDecoder;
-/* @@@@ document */
typedef FLAC__StreamDecoderWriteStatus (*OggFLAC__FileDecoderWriteCallback)(const OggFLAC__FileDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
typedef void (*OggFLAC__FileDecoderMetadataCallback)(const OggFLAC__FileDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
typedef void (*OggFLAC__FileDecoderErrorCallback)(const OggFLAC__FileDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
* \ingroup oggflac
*
* \brief
- * This module describes the three decoder layers provided by libOggFLAC.
+ * This module describes the decoder layers provided by libOggFLAC.
*
- * libOggFLAC provides the same three layers of access as libFLAC and the
- * interface is identical. See the \link flac_decoder FLAC decoder module
- * \endlink for full documentation.
+ * libOggFLAC currently provides the same stream layer access as libFLAC;
+ * the interface is identical. See the \link flac_decoder FLAC
+ * decoder module \endlink for full documentation.
*/
/** \defgroup oggflac_stream_decoder OggFLAC/stream_decoder.h: stream decoder interface
* This module contains the functions which implement the stream
* decoder.
*
- * The interface here is identical to FLAC's stream decoder. See the
- * defaults, including the callbacks. See the \link flac_stream_decoder
+ * The interface here is identical to FLAC's stream decoder,
+ * including the callbacks. See the \link flac_stream_decoder
* FLAC stream decoder module \endlink for full documentation.
*
* \{
struct OggFLAC__StreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
} OggFLAC__StreamDecoder;
+/** Signature for the read callback.
+ * See OggFLAC__stream_decoder_set_read_callback()
+ * and FLAC__StreamDecoderReadCallback for more info.
+ *
+ * \param decoder The decoder instance calling the callback.
+ * \param buffer A pointer to a location for the callee to store
+ * data to be decoded.
+ * \param bytes A pointer to the size of the buffer.
+ * \param client_data The callee's client data set through
+ * OggFLAC__stream_decoder_set_client_data().
+ * \retval FLAC__StreamDecoderReadStatus
+ * The callee's return status.
+ */
typedef FLAC__StreamDecoderReadStatus (*OggFLAC__StreamDecoderReadCallback)(const OggFLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
+
+/** Signature for the write callback.
+ * See OggFLAC__stream_decoder_set_write_callback()
+ * and FLAC__StreamDecoderWriteCallback for more info.
+ *
+ * \param decoder The decoder instance calling the callback.
+ * \param frame The description of the decoded frame.
+ * \param buffer An array of pointers to decoded channels of data.
+ * \param client_data The callee's client data set through
+ * OggFLAC__stream_decoder_set_client_data().
+ * \retval FLAC__StreamDecoderWriteStatus
+ * The callee's return status.
+ */
typedef FLAC__StreamDecoderWriteStatus (*OggFLAC__StreamDecoderWriteCallback)(const OggFLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
+
+/** Signature for the metadata callback.
+ * See OggFLAC__stream_decoder_set_metadata_callback()
+ * and FLAC__StreamDecoderMetadataCallback for more info.
+ *
+ * \param decoder The decoder instance calling the callback.
+ * \param metadata The decoded metadata block.
+ * \param client_data The callee's client data set through
+ * OggFLAC__stream_decoder_set_client_data().
+ */
typedef void (*OggFLAC__StreamDecoderMetadataCallback)(const OggFLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
+
+/** Signature for the error callback.
+ * See OggFLAC__stream_decoder_set_error_callback()
+ * and FLAC__StreamDecoderErrorCallback for more info.
+ *
+ * \param decoder The decoder instance calling the callback.
+ * \param status The error encountered by the decoder.
+ * \param client_data The callee's client data set through
+ * OggFLAC__stream_decoder_set_client_data().
+ */
typedef void (*OggFLAC__StreamDecoderErrorCallback)(const OggFLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
-FLAC__bool OggFLAC__stream_decoder_set_read_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderReadCallback);
+FLAC__bool OggFLAC__stream_decoder_set_read_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderReadCallback value);
/** Set the write callback.
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_write_callback()
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
-FLAC__bool OggFLAC__stream_decoder_set_write_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderWriteCallback);
+FLAC__bool OggFLAC__stream_decoder_set_write_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderWriteCallback value);
/** Set the metadata callback.
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_callback()
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
-FLAC__bool OggFLAC__stream_decoder_set_metadata_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderMetadataCallback);
+FLAC__bool OggFLAC__stream_decoder_set_metadata_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderMetadataCallback value);
/** Set the error callback.
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_error_callback()
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
-FLAC__bool OggFLAC__stream_decoder_set_error_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderErrorCallback);
+FLAC__bool OggFLAC__stream_decoder_set_error_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderErrorCallback value);
/** Set the client data to be passed back to callbacks.
* This value will be supplied to callbacks in their \a client_data
* \code OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_OK \endcode
* \retval FLAC__bool
* \c false if any read or write error occurred (except
- * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c false;
+ * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
* in any case, check the decoder state with
* OggFLAC__stream_decoder_get_state() to see what went wrong or to
* check for lost synchronization (a sign of stream corruption).
* \code OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_OK \endcode
* \retval FLAC__bool
* \c false if any read or write error occurred (except
- * \c OggFLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c false;
+ * \c OggFLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
* in any case, check the decoder state with
* OggFLAC__stream_decoder_get_state() to see what went wrong or to
* check for lost synchronization (a sign of stream corruption).
* \code OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_OK \endcode
* \retval FLAC__bool
* \c false if any read or write error occurred (except
- * \c OggFLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c false;
+ * \c OggFLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
* in any case, check the decoder state with
* OggFLAC__stream_decoder_get_state() to see what went wrong or to
* check for lost synchronization (a sign of stream corruption).
* \ingroup oggflac
*
* \brief
- * This module describes the three encoder layers provided by libOggFLAC.
+ * This module describes the encoder layers provided by libOggFLAC.
*
- * libOggFLAC provides the same three layers of access as libFLAC and the
- * interface is identical. See the \link flac_encoder FLAC encoder module
- * \endlink for full documentation.
+ * libOggFLAC currently provides the same stream layer access as libFLAC;
+ * the interface is nearly identical. See the \link flac_encoder FLAC
+ * encoder module \endlink for full documentation.
*/
/** \defgroup oggflac_stream_encoder OggFLAC/stream_encoder.h: stream encoder interface
* This module contains the functions which implement the stream
* encoder.
*
- * The interface here is identical to FLAC's stream encoder. See the
- * defaults, including the callbacks. See the \link flac_stream_encoder
+ * The interface here is nearly identical to FLAC's stream encoder,
+ * including the callbacks. See the \link flac_stream_encoder
* FLAC stream encoder module \endlink for full documentation.
*
* \{
struct OggFLAC__StreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
} OggFLAC__StreamEncoder;
-/*@@@@ document: */
+/** Signature for the write callback.
+ * See OggFLAC__stream_encoder_set_write_callback()
+ * and FLAC__StreamEncoderWriteCallback for more info.
+ *
+ * \param encoder The encoder instance calling the callback.
+ * \param buffer An array of encoded data of length \a bytes.
+ * \param bytes The byte length of \a buffer.
+ * \param samples The number of samples encoded by \a buffer.
+ * \c 0 has a special meaning; see
+ * OggFLAC__stream_encoder_set_write_callback().
+ * \param current_frame The number of current frame being encoded.
+ * \param client_data The callee's client data set through
+ * OggFLAC__stream_encoder_set_client_data().
+ * \retval FLAC__StreamEncoderWriteStatus
+ * The callee's return status.
+ */
typedef FLAC__StreamEncoderWriteStatus (*OggFLAC__StreamEncoderWriteCallback)(const OggFLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
FLAC__bool OggFLAC__stream_encoder_set_metadata(OggFLAC__StreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
/** Set the write callback.
+ * This is inherited from FLAC__StreamEncoder; see
+ * FLAC__stream_encoder_set_write_callback().
*
* \note
* Unlike the FLAC stream encoder write callback, the Ogg stream
* \param got The actual value returned by the decoder.
* \assert
* \code encoder != NULL \endcode
- * \code absolute_sample != NULL \encode
- * \code frame_number != NULL \encode
- * \code channel != NULL \encode
- * \code sample != NULL \encode
- * \code expected != NULL \encode
+ * \code absolute_sample != NULL \endcode
+ * \code frame_number != NULL \endcode
+ * \code channel != NULL \endcode
+ * \code sample != NULL \endcode
+ * \code expected != NULL \endcode
*/
void OggFLAC__stream_encoder_get_verify_decoder_error_stats(const OggFLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
projects / platform / upstream / flac.git / commitdiff