\brief
The level 1 interface provides read-write access to FLAC file metadata and
operates directly on the FLAC file.
The general usage of this interface is:
- Create an iterator using FLAC__metadata_simple_iterator_new()
- Attach it to a file using FLAC__metadata_simple_iterator_init() and check
the exit code. Call FLAC__metadata_simple_iterator_is_writable() to
see if the file is writable, or only read access is allowed.
- Use FLAC__metadata_simple_iterator_next() and
FLAC__metadata_simple_iterator_prev() to traverse the blocks.
This is does not read the actual blocks themselves.
FLAC__metadata_simple_iterator_next() is relatively fast.
FLAC__metadata_simple_iterator_prev() is slower since it needs to search
forward from the front of the file.
- Use FLAC__metadata_simple_iterator_get_block_type() or
FLAC__metadata_simple_iterator_get_block() to access the actual data at
the current iterator position. The returned object is yours to modify
and free.
- Use FLAC__metadata_simple_iterator_set_block() to write a modified block
back. You must have write permission to the original file. Make sure to
read the whole comment to FLAC__metadata_simple_iterator_set_block()
below.
- Use FLAC__metadata_simple_iterator_insert_block_after() to add new blocks.
Use the object creation functions from
\link flac_metadata_object here \endlink to generate new objects.
- Use FLAC__metadata_simple_iterator_delete_block() to remove the block
currently referred to by the iterator, or replace it with padding.
- Destroy the iterator with FLAC__metadata_simple_iterator_delete() when
finished.
\note
The FLAC file remains open the whole time between
FLAC__metadata_simple_iterator_init() and
FLAC__metadata_simple_iterator_delete(), so make sure you are not altering
the file during this time.
\note
Do not modify the \a is_last, \a length, or \a type fields of returned
FLAC__StreamMetadata objects. These are managed automatically.
\note
If any of the modification functions
(FLAC__metadata_simple_iterator_set_block(),
FLAC__metadata_simple_iterator_delete_block(),
FLAC__metadata_simple_iterator_insert_block_after(), etc.) return \c false,
you should delete the iterator as it may no longer be valid.
\defgroup flac_metadata_level1 FLAC/metadata.h: metadata level 1 interface \ingroup flac_metadata
\brief The level 1 interface provides read-write access to FLAC file metadata and operates directly on the FLAC file.
The general usage of this interface is:
- Create an iterator using FLAC__metadata_simple_iterator_new() - Attach it to a file using FLAC__metadata_simple_iterator_init() and check the exit code. Call FLAC__metadata_simple_iterator_is_writable() to see if the file is writable, or only read access is allowed. - Use FLAC__metadata_simple_iterator_next() and FLAC__metadata_simple_iterator_prev() to traverse the blocks. This is does not read the actual blocks themselves. FLAC__metadata_simple_iterator_next() is relatively fast. FLAC__metadata_simple_iterator_prev() is slower since it needs to search forward from the front of the file. - Use FLAC__metadata_simple_iterator_get_block_type() or FLAC__metadata_simple_iterator_get_block() to access the actual data at the current iterator position. The returned object is yours to modify and free. - Use FLAC__metadata_simple_iterator_set_block() to write a modified block back. You must have write permission to the original file. Make sure to read the whole comment to FLAC__metadata_simple_iterator_set_block() below. - Use FLAC__metadata_simple_iterator_insert_block_after() to add new blocks. Use the object creation functions from \link flac_metadata_object here \endlink to generate new objects. - Use FLAC__metadata_simple_iterator_delete_block() to remove the block currently referred to by the iterator, or replace it with padding. - Destroy the iterator with FLAC__metadata_simple_iterator_delete() when finished.
\note The FLAC file remains open the whole time between FLAC__metadata_simple_iterator_init() and FLAC__metadata_simple_iterator_delete(), so make sure you are not altering the file during this time.
\note Do not modify the \a is_last, \a length, or \a type fields of returned FLAC__StreamMetadata objects. These are managed automatically.
\note If any of the modification functions (FLAC__metadata_simple_iterator_set_block(), FLAC__metadata_simple_iterator_delete_block(), FLAC__metadata_simple_iterator_insert_block_after(), etc.) return \c false, you should delete the iterator as it may no longer be valid.
\{