\brief
The level 2 interface provides read-write access to FLAC file metadata;
all metadata is read into memory, operated on in memory, and then written
to file, which is more efficient than level 1 when editing multiple blocks.
Currently Ogg FLAC is supported for read only, via
FLAC__metadata_chain_read_ogg() but a subsequent
FLAC__metadata_chain_write() will fail.
The general usage of this interface is:
- Create a new chain using FLAC__metadata_chain_new(). A chain is a
linked list of FLAC metadata blocks.
- Read all metadata into the the chain from a FLAC file using
FLAC__metadata_chain_read() or FLAC__metadata_chain_read_ogg() and
check the status.
- Optionally, consolidate the padding using
FLAC__metadata_chain_merge_padding() or
FLAC__metadata_chain_sort_padding().
- Create a new iterator using FLAC__metadata_iterator_new()
- Initialize the iterator to point to the first element in the chain
using FLAC__metadata_iterator_init()
- Traverse the chain using FLAC__metadata_iterator_next and
FLAC__metadata_iterator_prev().
- Get a block for reading or modification using
FLAC__metadata_iterator_get_block(). The pointer to the object
inside the chain is returned, so the block is yours to modify.
Changes will be reflected in the FLAC file when you write the
chain. You can also add and delete blocks (see functions below).
- When done, write out the chain using FLAC__metadata_chain_write().
Make sure to read the whole comment to the function below.
- Delete the chain using FLAC__metadata_chain_delete().
\note
Even though the FLAC file is not open while the chain is being
manipulated, you must not alter the file externally during
this time. The chain assumes the FLAC file will not change
between the time of FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg()
and FLAC__metadata_chain_write().
\note
Do not modify the is_last, length, or type fields of returned
FLAC__StreamMetadata objects. These are managed automatically.
\note
The metadata objects returned by FLAC__metadata_iterator_get_block()
are owned by the chain; do not FLAC__metadata_object_delete() them.
In the same way, blocks passed to FLAC__metadata_iterator_set_block()
become owned by the chain and they will be deleted when the chain is
deleted.
\defgroup flac_metadata_level2 FLAC/metadata.h: metadata level 2 interface \ingroup flac_metadata
\brief The level 2 interface provides read-write access to FLAC file metadata; all metadata is read into memory, operated on in memory, and then written to file, which is more efficient than level 1 when editing multiple blocks.
Currently Ogg FLAC is supported for read only, via FLAC__metadata_chain_read_ogg() but a subsequent FLAC__metadata_chain_write() will fail.
The general usage of this interface is:
- Create a new chain using FLAC__metadata_chain_new(). A chain is a linked list of FLAC metadata blocks. - Read all metadata into the the chain from a FLAC file using FLAC__metadata_chain_read() or FLAC__metadata_chain_read_ogg() and check the status. - Optionally, consolidate the padding using FLAC__metadata_chain_merge_padding() or FLAC__metadata_chain_sort_padding(). - Create a new iterator using FLAC__metadata_iterator_new() - Initialize the iterator to point to the first element in the chain using FLAC__metadata_iterator_init() - Traverse the chain using FLAC__metadata_iterator_next and FLAC__metadata_iterator_prev(). - Get a block for reading or modification using FLAC__metadata_iterator_get_block(). The pointer to the object inside the chain is returned, so the block is yours to modify. Changes will be reflected in the FLAC file when you write the chain. You can also add and delete blocks (see functions below). - When done, write out the chain using FLAC__metadata_chain_write(). Make sure to read the whole comment to the function below. - Delete the chain using FLAC__metadata_chain_delete().
\note Even though the FLAC file is not open while the chain is being manipulated, you must not alter the file externally during this time. The chain assumes the FLAC file will not change between the time of FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg() and FLAC__metadata_chain_write().
\note Do not modify the is_last, length, or type fields of returned FLAC__StreamMetadata objects. These are managed automatically.
\note The metadata objects returned by FLAC__metadata_iterator_get_block() are owned by the chain; do not FLAC__metadata_object_delete() them. In the same way, blocks passed to FLAC__metadata_iterator_set_block() become owned by the chain and they will be deleted when the chain is deleted.
\{