Write a block back to the FLAC file. This function tries to be
as efficient as possible; how the block is actually written is
shown by the following:
Existing block is a STREAMINFO block and the new block is a
STREAMINFO block: the new block is written in place. Make sure
you know what you're doing when changing the values of a
STREAMINFO block.
Existing block is a STREAMINFO block and the new block is a
not a STREAMINFO block: this is an error since the first block
must be a STREAMINFO block. Returns \c false without altering the
file.
Existing block is not a STREAMINFO block and the new block is a
STREAMINFO block: this is an error since there may be only one
STREAMINFO block. Returns \c false without altering the file.
Existing block and new block are the same length: the existing
block will be replaced by the new block, written in place.
Existing block is longer than new block: if use_padding is \c true,
the existing block will be overwritten in place with the new
block followed by a PADDING block, if possible, to make the total
size the same as the existing block. Remember that a padding
block requires at least four bytes so if the difference in size
between the new block and existing block is less than that, the
entire file will have to be rewritten, using the new block's
exact size. If use_padding is \c false, the entire file will be
rewritten, replacing the existing block by the new block.
Existing block is shorter than new block: if use_padding is \c true,
the function will try and expand the new block into the following
PADDING block, if it exists and doing so won't shrink the PADDING
block to less than 4 bytes. If there is no following PADDING
block, or it will shrink to less than 4 bytes, or use_padding is
\c false, the entire file is rewritten, replacing the existing block
with the new block. Note that in this case any following PADDING
block is preserved as is.
After writing the block, the iterator will remain in the same
place, i.e. pointing to the new block.
\param iterator A pointer to an existing initialized iterator.
\param block The block to set.
\param use_padding See above.
\assert
\code iterator != NULL \endcode
\a iterator has been successfully initialized with
FLAC__metadata_simple_iterator_init()
\code block != NULL \endcode
\retval FLAC__bool
\c true if successful, else \c false.
Write a block back to the FLAC file. This function tries to be as efficient as possible; how the block is actually written is shown by the following:
Existing block is a STREAMINFO block and the new block is a STREAMINFO block: the new block is written in place. Make sure you know what you're doing when changing the values of a STREAMINFO block.
Existing block is a STREAMINFO block and the new block is a not a STREAMINFO block: this is an error since the first block must be a STREAMINFO block. Returns \c false without altering the file.
Existing block is not a STREAMINFO block and the new block is a STREAMINFO block: this is an error since there may be only one STREAMINFO block. Returns \c false without altering the file.
Existing block and new block are the same length: the existing block will be replaced by the new block, written in place.
Existing block is longer than new block: if use_padding is \c true, the existing block will be overwritten in place with the new block followed by a PADDING block, if possible, to make the total size the same as the existing block. Remember that a padding block requires at least four bytes so if the difference in size between the new block and existing block is less than that, the entire file will have to be rewritten, using the new block's exact size. If use_padding is \c false, the entire file will be rewritten, replacing the existing block by the new block.
Existing block is shorter than new block: if use_padding is \c true, the function will try and expand the new block into the following PADDING block, if it exists and doing so won't shrink the PADDING block to less than 4 bytes. If there is no following PADDING block, or it will shrink to less than 4 bytes, or use_padding is \c false, the entire file is rewritten, replacing the existing block with the new block. Note that in this case any following PADDING block is preserved as is.
After writing the block, the iterator will remain in the same place, i.e. pointing to the new block.
\param iterator A pointer to an existing initialized iterator. \param block The block to set. \param use_padding See above. \assert \code iterator != NULL \endcode \a iterator has been successfully initialized with FLAC__metadata_simple_iterator_init() \code block != NULL \endcode \retval FLAC__bool \c true if successful, else \c false.