From 463a22cc3af7b288be03e565668ea5dc6944019a Mon Sep 17 00:00:00 2001 From: Josh Coalson Date: Sun, 11 Jul 2004 06:41:00 +0000 Subject: add callback-based versions of chain writing: FLAC__metadata_chain_check_if_tempfile_needed(), FLAC__metadata_chain_write_with_callbacks(), FLAC__metadata_chain_write_with_callbacks_and_tempfile() --- include/FLAC/metadata.h | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) (limited to 'include/FLAC') diff --git a/include/FLAC/metadata.h b/include/FLAC/metadata.h index 71646782..48e7b294 100644 --- a/include/FLAC/metadata.h +++ b/include/FLAC/metadata.h @@ -588,9 +588,27 @@ typedef enum { FLAC__METADATA_CHAIN_STATUS_INTERNAL_ERROR, /**< The caller violated an assertion or an unexpected error occurred */ - FLAC__METADATA_CHAIN_STATUS_INVALID_CALLBACKS + FLAC__METADATA_CHAIN_STATUS_INVALID_CALLBACKS, /**< One or more of the required callbacks was NULL */ + FLAC__METADATA_CHAIN_STATUS_READ_WRITE_MISMATCH, + /**< FLAC__metadata_chain_write() was called on a chain read by + * FLAC__metadata_chain_read_with_callbacks(), or + * FLAC__metadata_chain_write_with_callbacks() or + * FLAC__metadata_chain_write_with_callbacks_and_tempfile() was + * called on a chain read by FLAC__metadata_chain_read(). Matching + * read/write methods must always be used. */ + + FLAC__METADATA_CHAIN_STATUS_WRONG_WRITE_CALL + /**< FLAC__metadata_chain_write_with_callbacks() was called when the + * chain write requires a tempfile; use + * FLAC__metadata_chain_write_with_callbacks_and_tempfile() instead. + * Or, FLAC__metadata_chain_write_with_callbacks_and_tempfile() was + * called when the chain write does not require a tempfile; use + * FLAC__metadata_chain_write_with_callbacks() instead. + * Always check FLAC__metadata_chain_check_if_tempfile_needed() + * before writing via callbacks. */ + } FLAC__Metadata_ChainStatus; /** Maps a FLAC__Metadata_ChainStatus to a C string. @@ -644,6 +662,10 @@ FLAC_API FLAC__Metadata_ChainStatus FLAC__metadata_chain_status(FLAC__Metadata_C FLAC_API FLAC__bool FLAC__metadata_chain_read(FLAC__Metadata_Chain *chain, const char *filename); /** Read all metadata from a FLAC stream into the chain via I/O callbacks. + * + * The \a handle need only be open for reading, but must be seekable. + * The equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb" + * for Windows). * * \param chain A pointer to an existing chain. * \param handle The I/O handle of the FLAC stream to read. The @@ -661,6 +683,9 @@ FLAC_API FLAC__bool FLAC__metadata_chain_read(FLAC__Metadata_Chain *chain, const */ FLAC_API FLAC__bool FLAC__metadata_chain_read_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks); +/* @@@@@@ document */ +FLAC_API FLAC__bool FLAC__metadata_chain_check_if_tempfile_needed(FLAC__Metadata_Chain *chain, FLAC__bool use_padding); + /** Write all metadata out to the FLAC file. This function tries to be as * efficient as possible; how the metadata is actually written is shown by * the following: @@ -703,6 +728,12 @@ FLAC_API FLAC__bool FLAC__metadata_chain_read_with_callbacks(FLAC__Metadata_Chai */ FLAC_API FLAC__bool FLAC__metadata_chain_write(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__bool preserve_file_stats); +/* @@@@@@ document */ +FLAC_API FLAC__bool FLAC__metadata_chain_write_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks); + +/* @@@@@@ document */ +FLAC_API FLAC__bool FLAC__metadata_chain_write_with_callbacks_and_tempfile(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks, FLAC__IOHandle temp_handle, FLAC__IOCallbacks temp_callbacks); + /** Merge adjacent PADDING blocks into a single block. * * \note This function does not write to the FLAC file, it only -- cgit v1.2.1