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:
If the current chain is the same size as the existing metadata, the new
data is written in place.
If the current chain is longer than the existing metadata, and
\a use_padding is \c true, and the last block is a PADDING block of
sufficient length, the function will truncate the final padding block
so that the overall size of the metadata is the same as the existing
metadata, and then just rewrite the metadata. Otherwise, if not all of
the above conditions are met, the entire FLAC file must be rewritten.
If you want to use padding this way it is a good idea to call
FLAC__metadata_chain_sort_padding() first so that you have the maximum
amount of padding to work with, unless you need to preserve ordering
of the PADDING blocks for some reason.
If the current chain is shorter than the existing metadata, and
\a use_padding is \c true, and the final block is a PADDING block, the padding
is extended to make the overall size the same as the existing data. If
\a use_padding is \c true and the last block is not a PADDING block, a new
PADDING block is added to the end of the new data to make it the same
size as the existing data (if possible, see the note to
FLAC__metadata_simple_iterator_set_block() about the four byte limit)
and the new data is written in place. If none of the above apply or
\a use_padding is \c false, the entire FLAC file is rewritten.
If \a preserve_file_stats is \c true, the owner and modification time will
be preserved even if the FLAC file is written.
For this write function to be used, the chain must have been read with
FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg(), not
FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks().
\param chain A pointer to an existing chain.
\param use_padding See above.
\param preserve_file_stats See above.
\assert
\code chain != NULL \endcode
\retval FLAC__bool
\c true if the write succeeded, else \c false. On failure,
check the status with FLAC__metadata_chain_status().
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:
If the current chain is the same size as the existing metadata, the new data is written in place.
If the current chain is longer than the existing metadata, and \a use_padding is \c true, and the last block is a PADDING block of sufficient length, the function will truncate the final padding block so that the overall size of the metadata is the same as the existing metadata, and then just rewrite the metadata. Otherwise, if not all of the above conditions are met, the entire FLAC file must be rewritten. If you want to use padding this way it is a good idea to call FLAC__metadata_chain_sort_padding() first so that you have the maximum amount of padding to work with, unless you need to preserve ordering of the PADDING blocks for some reason.
If the current chain is shorter than the existing metadata, and \a use_padding is \c true, and the final block is a PADDING block, the padding is extended to make the overall size the same as the existing data. If \a use_padding is \c true and the last block is not a PADDING block, a new PADDING block is added to the end of the new data to make it the same size as the existing data (if possible, see the note to FLAC__metadata_simple_iterator_set_block() about the four byte limit) and the new data is written in place. If none of the above apply or \a use_padding is \c false, the entire FLAC file is rewritten.
If \a preserve_file_stats is \c true, the owner and modification time will be preserved even if the FLAC file is written.
For this write function to be used, the chain must have been read with FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg(), not FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks().
\param chain A pointer to an existing chain. \param use_padding See above. \param preserve_file_stats See above. \assert \code chain != NULL \endcode \retval FLAC__bool \c true if the write succeeded, else \c false. On failure, check the status with FLAC__metadata_chain_status().