diff --git a/include/FLAC/file_decoder.h b/include/FLAC/file_decoder.h index 522513d7..f6a44437 100644 --- a/include/FLAC/file_decoder.h +++ b/include/FLAC/file_decoder.h @@ -166,9 +166,40 @@ typedef struct { 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); diff --git a/include/FLAC/file_encoder.h b/include/FLAC/file_encoder.h index 8a4a1272..a5b017ce 100644 --- a/include/FLAC/file_encoder.h +++ b/include/FLAC/file_encoder.h @@ -129,7 +129,6 @@ typedef enum { * 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[]; @@ -150,7 +149,18 @@ typedef struct { 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); diff --git a/include/FLAC/format.h b/include/FLAC/format.h index 441ba0b1..5f971dc4 100644 --- a/include/FLAC/format.h +++ b/include/FLAC/format.h @@ -614,19 +614,30 @@ extern const unsigned FLAC__STREAM_METADATA_LENGTH_LEN; /**< == 24 (bits) */ */ 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); /* \} */ diff --git a/include/FLAC/metadata.h b/include/FLAC/metadata.h index 111cc1ae..2c9fe843 100644 --- a/include/FLAC/metadata.h +++ b/include/FLAC/metadata.h @@ -1034,11 +1034,94 @@ FLAC__bool FLAC__metadata_object_seektable_delete_point(FLAC__StreamMetadata *ob */ 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. diff --git a/include/FLAC/seekable_stream_decoder.h b/include/FLAC/seekable_stream_decoder.h index 1b6f17fe..5624512d 100644 --- a/include/FLAC/seekable_stream_decoder.h +++ b/include/FLAC/seekable_stream_decoder.h @@ -263,14 +263,105 @@ typedef struct { 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); diff --git a/include/FLAC/seekable_stream_encoder.h b/include/FLAC/seekable_stream_encoder.h index a6062a95..1751817e 100644 --- a/include/FLAC/seekable_stream_encoder.h +++ b/include/FLAC/seekable_stream_encoder.h @@ -120,7 +120,6 @@ typedef enum { * 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[]; @@ -161,8 +160,35 @@ typedef struct { 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); diff --git a/include/FLAC/stream_decoder.h b/include/FLAC/stream_decoder.h index c6ebbdd6..d2a21206 100644 --- a/include/FLAC/stream_decoder.h +++ b/include/FLAC/stream_decoder.h @@ -311,9 +311,61 @@ typedef struct { 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); @@ -367,7 +419,7 @@ void FLAC__stream_decoder_delete(FLAC__StreamDecoder *decoder); * \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 @@ -387,7 +439,7 @@ FLAC__bool FLAC__stream_decoder_set_read_callback(FLAC__StreamDecoder *decoder, * \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 @@ -415,7 +467,7 @@ FLAC__bool FLAC__stream_decoder_set_write_callback(FLAC__StreamDecoder *decoder, * \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 @@ -433,7 +485,7 @@ FLAC__bool FLAC__stream_decoder_set_metadata_callback(FLAC__StreamDecoder *decod * \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 @@ -682,7 +734,7 @@ FLAC__bool FLAC__stream_decoder_reset(FLAC__StreamDecoder *decoder); * \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). @@ -707,7 +759,7 @@ FLAC__bool FLAC__stream_decoder_process_single(FLAC__StreamDecoder *decoder); * \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). @@ -732,7 +784,7 @@ FLAC__bool FLAC__stream_decoder_process_until_end_of_metadata(FLAC__StreamDecode * \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). diff --git a/include/FLAC/stream_encoder.h b/include/FLAC/stream_encoder.h index 1a01f4a6..0813d6fa 100644 --- a/include/FLAC/stream_encoder.h +++ b/include/FLAC/stream_encoder.h @@ -293,8 +293,31 @@ typedef struct { 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); diff --git a/include/OggFLAC++/all.h b/include/OggFLAC++/all.h index b5e3007c..6360f734 100644 --- a/include/OggFLAC++/all.h +++ b/include/OggFLAC++/all.h @@ -26,7 +26,7 @@ /** \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. * */ diff --git a/include/OggFLAC/file_decoder.h b/include/OggFLAC/file_decoder.h index c5cadea3..246c8191 100644 --- a/include/OggFLAC/file_decoder.h +++ b/include/OggFLAC/file_decoder.h @@ -88,7 +88,6 @@ typedef enum { * 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[]; @@ -109,7 +108,6 @@ typedef struct { 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); diff --git a/include/OggFLAC/stream_decoder.h b/include/OggFLAC/stream_decoder.h index 57212eeb..6de28972 100644 --- a/include/OggFLAC/stream_decoder.h +++ b/include/OggFLAC/stream_decoder.h @@ -41,11 +41,11 @@ extern "C" { * \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 @@ -55,8 +55,8 @@ extern "C" { * 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. * * \{ @@ -125,9 +125,55 @@ typedef struct { 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); @@ -176,7 +222,7 @@ void OggFLAC__stream_decoder_delete(OggFLAC__StreamDecoder *decoder); * \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() @@ -193,7 +239,7 @@ FLAC__bool OggFLAC__stream_decoder_set_read_callback(OggFLAC__StreamDecoder *dec * \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() @@ -210,7 +256,7 @@ FLAC__bool OggFLAC__stream_decoder_set_write_callback(OggFLAC__StreamDecoder *de * \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() @@ -227,7 +273,7 @@ FLAC__bool OggFLAC__stream_decoder_set_metadata_callback(OggFLAC__StreamDecoder * \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 @@ -468,7 +514,7 @@ FLAC__bool OggFLAC__stream_decoder_reset(OggFLAC__StreamDecoder *decoder); * \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). @@ -485,7 +531,7 @@ FLAC__bool OggFLAC__stream_decoder_process_single(OggFLAC__StreamDecoder *decode * \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). @@ -502,7 +548,7 @@ FLAC__bool OggFLAC__stream_decoder_process_until_end_of_metadata(OggFLAC__Stream * \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). diff --git a/include/OggFLAC/stream_encoder.h b/include/OggFLAC/stream_encoder.h index eec216bf..28c11071 100644 --- a/include/OggFLAC/stream_encoder.h +++ b/include/OggFLAC/stream_encoder.h @@ -41,11 +41,11 @@ extern "C" { * \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 @@ -55,8 +55,8 @@ extern "C" { * 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. * * \{ @@ -122,7 +122,22 @@ typedef struct { 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); @@ -374,6 +389,8 @@ FLAC__bool OggFLAC__stream_encoder_set_total_samples_estimate(OggFLAC__StreamEnc 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 @@ -462,11 +479,11 @@ FLAC__StreamDecoderState OggFLAC__stream_encoder_get_verify_decoder_state(const * \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);