add callback-based versions of chain writing:...

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

@@ -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