claunia/flac
1
0
Fork 0
mirror of https://github.com/claunia/flac.git synced 2025-12-16 18:54:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

add code examples for some of the callbacks to the docs

Browse Source
This commit is contained in:
Josh Coalson
2006-11-04 03:51:01 +00:00
parent c28efe2294
commit 99abf3e70a
2 changed files with 127 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
include/FLAC/stream_decoder.h
View File

@@ -475,6 +475,25 @@ typedef struct {
* The callback then returns a status code chosen from
* FLAC__StreamDecoderReadStatus.
*
* Here is an example of a read callback for stdio streams:
* \code
* FLAC__StreamDecoderReadStatus read_cb(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], size_t *bytes, void *client_data)
* {
* FILE *file = ((MyClientData*)client_data)->file;
* if(*bytes > 0) {
* *bytes = fread(buffer, sizeof(FLAC__byte), *bytes, file);
* if(ferror(file))
* return FLAC__STREAM_DECODER_READ_STATUS_ABORT;
* else if(*bytes == 0)
* return FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM;
* else
* return FLAC__STREAM_DECODER_READ_STATUS_CONTINUE;
* }
* else
* return FLAC__STREAM_DECODER_READ_STATUS_ABORT;
* }
* \endcode
*
* \note In general, FLAC__StreamDecoder functions which change the
* state should not be called on the \a decoder while in the callback.
*
@@ -504,6 +523,20 @@ typedef FLAC__StreamDecoderReadStatus (*FLAC__StreamDecoderReadCallback)(const F
* will pass the absolute byte offset to seek to, 0 meaning the
* beginning of the stream.
*
* Here is an example of a seek callback for stdio streams:
* \code
* FLAC__StreamDecoderSeekStatus seek_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data)
* {
* FILE *file = ((MyClientData*)client_data)->file;
* if(file == stdin)
* return FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED;
* else if(fseeko(file, (off_t)absolute_byte_offset, SEEK_SET) < 0)
* return FLAC__STREAM_DECODER_SEEK_STATUS_ERROR;
* else
* return FLAC__STREAM_DECODER_SEEK_STATUS_OK;
* }
* \endcode
*
* \note In general, FLAC__StreamDecoder functions which change the
* state should not be called on the \a decoder while in the callback.
*
@@ -525,6 +558,23 @@ typedef FLAC__StreamDecoderSeekStatus (*FLAC__StreamDecoderSeekCallback)(const F
* stream. The callback should return the byte offset from the
* beginning of the stream.
*
* Here is an example of a tell callback for stdio streams:
* \code
* FLAC__StreamDecoderTellStatus tell_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data)
* {
* FILE *file = ((MyClientData*)client_data)->file;
* off_t pos;
* if(file == stdin)
* return FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED;
* else if((pos = ftello(file)) < 0)
* return FLAC__STREAM_DECODER_TELL_STATUS_ERROR;
* else {
* *absolute_byte_offset = (FLAC__uint64)pos;
* return FLAC__STREAM_DECODER_TELL_STATUS_OK;
* }
* }
* \endcode
*
* \note In general, FLAC__StreamDecoder functions which change the
* state should not be called on the \a decoder while in the callback.
*
@@ -545,6 +595,24 @@ typedef FLAC__StreamDecoderTellStatus (*FLAC__StreamDecoderTellCallback)(const F
* called when the decoder wants to know the total length of the stream
* in bytes.
*
* Here is an example of a length callback for stdio streams:
* \code
* FLAC__StreamDecoderLengthStatus length_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data)
* {
* FILE *file = ((MyClientData*)client_data)->file;
* struct stat filestats;
*
* if(file == stdin)
* return FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED;
* else if(fstat(fileno(file), &filestats) != 0)
* return FLAC__STREAM_DECODER_LENGTH_STATUS_ERROR;
* else {
* *stream_length = (FLAC__uint64)filestats.st_size;
* return FLAC__STREAM_DECODER_LENGTH_STATUS_OK;
* }
* }
* \endcode
*
* \note In general, FLAC__StreamDecoder functions which change the
* state should not be called on the \a decoder while in the callback.
*
@@ -565,6 +633,15 @@ typedef FLAC__StreamDecoderLengthStatus (*FLAC__StreamDecoderLengthCallback)(con
* called when the decoder needs to know if the end of the stream has
* been reached.
*
* Here is an example of a EOF callback for stdio streams:
* FLAC__bool eof_cb(const FLAC__StreamDecoder *decoder, void *client_data)
* \code
* {
* FILE *file = ((MyClientData*)client_data)->file;
* return feof(file)? true : false;
* }
* \endcode
*
* \note In general, FLAC__StreamDecoder functions which change the
* state should not be called on the \a decoder while in the callback.
*

50
include/FLAC/stream_encoder.h
View File

@@ -474,6 +474,25 @@ typedef struct {
* overflow the buffer. The callback then returns a status code chosen from
* FLAC__StreamEncoderReadStatus.
*
* Here is an example of a read callback for stdio streams:
* \code
* FLAC__StreamEncoderReadStatus read_cb(const FLAC__StreamEncoder *encoder, FLAC__byte buffer[], size_t *bytes, void *client_data)
* {
* FILE *file = ((MyClientData*)client_data)->file;
* if(*bytes > 0) {
* *bytes = fread(buffer, sizeof(FLAC__byte), *bytes, file);
* if(ferror(file))
* return FLAC__STREAM_ENCODER_READ_STATUS_ABORT;
* else if(*bytes == 0)
* return FLAC__STREAM_ENCODER_READ_STATUS_END_OF_STREAM;
* else
* return FLAC__STREAM_ENCODER_READ_STATUS_CONTINUE;
* }
* else
* return FLAC__STREAM_ENCODER_READ_STATUS_ABORT;
* }
* \endcode
*
* \note In general, FLAC__StreamEncoder functions which change the
* state should not be called on the \a encoder while in the callback.
*
@@ -538,6 +557,20 @@ typedef FLAC__StreamEncoderWriteStatus (*FLAC__StreamEncoderWriteCallback)(const
* when the encoder needs to seek the output stream. The encoder will pass
* the absolute byte offset to seek to, 0 meaning the beginning of the stream.
*
* Here is an example of a seek callback for stdio streams:
* \code
* FLAC__StreamEncoderSeekStatus seek_cb(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data)
* {
* FILE *file = ((MyClientData*)client_data)->file;
* if(file == stdin)
* return FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED;
* else if(fseeko(file, (off_t)absolute_byte_offset, SEEK_SET) < 0)
* return FLAC__STREAM_ENCODER_SEEK_STATUS_ERROR;
* else
* return FLAC__STREAM_ENCODER_SEEK_STATUS_OK;
* }
* \endcode
*
* \note In general, FLAC__StreamEncoder functions which change the
* state should not be called on the \a encoder while in the callback.
*
@@ -566,6 +599,23 @@ typedef FLAC__StreamEncoderSeekStatus (*FLAC__StreamEncoderSeekCallback)(const F
* can use lseek(fd, SEEK_CUR, 0). The encoder may later seek back to
* these points to rewrite metadata after encoding.
*
* Here is an example of a tell callback for stdio streams:
* \code
* FLAC__StreamEncoderTellStatus tell_cb(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data)
* {
* FILE *file = ((MyClientData*)client_data)->file;
* off_t pos;
* if(file == stdin)
* return FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED;
* else if((pos = ftello(file)) < 0)
* return FLAC__STREAM_ENCODER_TELL_STATUS_ERROR;
* else {
* *absolute_byte_offset = (FLAC__uint64)pos;
* return FLAC__STREAM_ENCODER_TELL_STATUS_OK;
* }
* }
* \endcode
*
* \note In general, FLAC__StreamEncoder functions which change the
* state should not be called on the \a encoder while in the callback.
*