******************************************************************************/
/** \file include/FLAC/metadata.h
- This module provides read and write access to FLAC file metadata at
- three increasing levels of complexity.
+ \brief This module provides functions for creating and manipulating
+ FLAC metadata blocks in memory, and three progressively more powerful
+ interfaces for traversing and editing metadata in FLAC files.
- level 0:
- read-only access to the STREAMINFO block.
+ There are three metadata interfaces of increasing complexity:
- level 1:
- read-write access to all metadata blocks. This level is write-
+ Level 0:
+ Read-only access to the STREAMINFO block.
+
+ Level 1:
+ Read-write access to all metadata blocks. This level is write-
efficient in most cases (more on this later), and uses less memory
than level 2.
- level 2:
- read-write access to all metadata blocks. This level is write-
+ Level 2:
+ Read-write access to all metadata blocks. This level is write-
efficient in all cases, but uses more memory since all metadata for
the whole file is read into memory and manipulated before writing
out again.
All levels know how to skip over and not disturb an ID3v2 tag at the
front of the file.
-******************************************************************************/
-/******************************************************************************
- After the three interfaces, methods for creating and manipulating
- the various metadata blocks are defined. Unless you will be using
- level 1 or 2 to modify existing metadata you will not need these.
+ In addition to the three interfaces, this module defines functions for
+ creating and manipulating various metadata blocks. Unless you will be
+ using the level 1 or 2 interfaces to modify existing metadata you will
+ not need these.
******************************************************************************/
+/** \defgroup flac_metadata Metadata Interfaces
+ * \ingroup flac
+ */
+
#ifdef __cplusplus
extern "C" {
#endif
-/***********************************************************************
- * level 0
- * ---------------------------------------------------------------------
- * Only one routine to read the STREAMINFO. Skips any ID3v2 tag at the
- * head of the file. Useful for file-based player plugins.
+/** \defgroup flac_metadata_level0 Level 0
+ * \ingroup flac_metadata
+ *
+ * The level 0 interface is only one routine to read the STREAMINFO. It skips
+ * any ID3v2 tag at the head of the file.
+ *
+ * Provide the address of a FLAC__StreamMetadata object to fill.
*
- * Provide the address of a FLAC__StreamMetadata object to fill.
+ * \{
*/
+/** Read the STREAMINFO metadata block of the given FLAC file. This function
+ * will skip any ID3v2 tag at the head of the file.
+ *
+ * \param filename The path to the FLAC file to read.
+ * \param streaminfo A pointer to space for the STREAMINFO block.
+ * \pre \a filename != NULL
+ * \pre \a streaminfo != NULL
+ * \retval FLAC__bool
+ * \a true if a valid STREAMINFO block was read from \a filename. Returns
+ * \a false if there was a memory allocation error, a file decoder error,
+ * or the file contained no STREAMINFO block.
+ */
FLAC__bool FLAC__metadata_get_streaminfo(const char *filename, FLAC__StreamMetadata *streaminfo);
+/* \} */
+
-/***********************************************************************
- * level 1
- * ---------------------------------------------------------------------
+/** \defgroup flac_metadata_level1 Level 1
+ * \ingroup flac_metadata
+ *
* 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 read-only access is allowed.
- * Use _next() and _prev() to move around the blocks. This is does not
- * read the actual blocks themselves. _next() is relatively fast.
- * _prev() is slower since it needs to search forward from the front
- * of the file.
- * Use _get_block_type() or _get_block() to access the actual data at
- * the current iterator position. The returned object is yours to
- * modify and free.
- * Use _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 _set_block() below.
- * Use _insert_block_after() to add new blocks. Use the object creation
- * functions from the end of this header file to generate new objects.
- * Use _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 _init() and
- * _delete(), so make sure you are not altering the file during
- * this time.
- *
- * NOTE: Do not modify the is_last, length, or type fields of returned
- * FLAC__MetadataType objects. These are managed automatically.
- *
- * NOTE: If any of the modification functions (_set_block, _delete_block,
- * _insert_block_after, etc) return false, you should delete the
- * iterator as it may no longer be valid.
+ * - 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 read-only access is allowed.
+ * - Use FLAC__metadata_simple_iterator_next() and
+ * FLAC__metadata_simple_iterator_prev() to move around 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 to flac_metadata_object group@@@
+ * 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__MetadataType 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 \a false,
+ * you should delete the iterator as it may no longer be valid.
+ *
+ * \{
*/
/*
/**< The iterator is in the normal OK state */
FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT,
- /**< The data passed into the function violated the function's usage criteria */
+ /**< The data passed into a function violated the function's usage criteria */
FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ERROR_OPENING_FILE,
/**< The iterator could not open the target file */
/*
* Get the current status of the iterator. Call this after a function
- * returns false to get the reason for the error. Also resets the status
+ * returns \a false to get the reason for the error. Also resets the status
* to FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK
*/
FLAC__Metadata_SimpleIteratorStatus FLAC__metadata_simple_iterator_status(FLAC__Metadata_SimpleIterator *iterator);
/*
* Initialize the iterator to point to the first metadata block in the
- * given FLAC file. If 'preserve_file_stats' is true, the owner and
+ * given FLAC file. If \a preserve_file_stats is \a true, the owner and
* modification time will be preserved even if the FLAC file is written.
*/
FLAC__bool FLAC__metadata_simple_iterator_init(FLAC__Metadata_SimpleIterator *iterator, const char *filename, FLAC__bool preserve_file_stats);
/*
- * Returns true if the FLAC file is writable. If false, calls to
+ * Returns \a true if the FLAC file is writable. If \a false, calls to
* FLAC__metadata_simple_iterator_set_block() and
* FLAC__metadata_simple_iterator_insert_block_after() will fail.
*/
FLAC__bool FLAC__metadata_simple_iterator_is_writable(const FLAC__Metadata_SimpleIterator *iterator);
/*
- * These move the iterator forwards or backwards, returning false if
+ * These move the iterator forwards or backwards, returning \a false if
* already at the end.
*/
FLAC__bool FLAC__metadata_simple_iterator_next(FLAC__Metadata_SimpleIterator *iterator);
*
* 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 false without altering the
+ * must be a STREAMINFO block. Returns \a 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 false without altering the file.
+ * STREAMINFO block. Returns \a 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 true,
+ * Existing block is longer than new block: if use_padding is \a 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 false, the entire file will be
+ * exact size. If use_padding is \a 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 true,
+ * Existing block is shorter than new block: if use_padding is \a 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
- * false, the entire file is rewritten, replacing the existing block
+ * \a 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.
*
/*
* This is similar to FLAC__metadata_simple_iterator_set_block()
* except that instead of writing over an existing block, it appends
- * a block after the existing block. 'use_padding' is again used to
+ * a block after the existing block. \a use_padding is again used to
* tell the function to try an expand into following padding in an
* attempt to avoid rewriting the entire file.
*
- * This function will fail and return false if given a STREAMINFO
+ * This function will fail and return \a false if given a STREAMINFO
* block.
*
* After writing the block, the iterator will be pointing to the
/*
* Deletes the block at the current position. This will cause the
- * entire FLAC file to be rewritten, unless 'use_padding' is true,
+ * entire FLAC file to be rewritten, unless \a use_padding is \a true,
* in which case the block will be replaced by an equal-sized PADDING
* block. The iterator will be left pointing to the block before the
* one just deleted.
*/
FLAC__bool FLAC__metadata_simple_iterator_delete_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__bool use_padding);
+/* \} */
+
-/***********************************************************************
- * level 2
- * ---------------------------------------------------------------------
+/** \defgroup flac_metadata_level2 Level 2
+ * \ingroup flac_metadata
+ *
* The general usage of this interface is:
*
- * Create a new chain using FLAC__metadata_chain_new(). A chain is a
- * linked list of metadata blocks.
- * Read all metadata into the the chain from a FLAC file using
- * FLAC__metadata_chain_read() 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/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() and
- * FLAC__metadata_chain_write().
- *
- * NOTE: Do not modify the is_last, length, or type fields of returned
- * FLAC__MetadataType objects. These are managed automatically.
- *
- * NOTE: The metadata objects returned by _get_bloca()k are owned by the
- * chain; do not FLAC__metadata_object_delete() them. In the
- * same way, blocks passed to _set_block() become owned by the
- * chain and will be deleted when the chain is deleted.
+ * - 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() 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/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() and
+ * FLAC__metadata_chain_write().
+ *
+ * \note
+ * Do not modify the is_last, length, or type fields of returned
+ * FLAC__MetadataType 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 will be deleted when the chain is
+ * deleted.
+ *
+ * \{
*/
/*
typedef enum {
FLAC__METADATA_CHAIN_STATUS_OK = 0,
+ /**< The chain is in the normal OK state */
+
FLAC__METADATA_CHAIN_STATUS_ILLEGAL_INPUT,
+ /**< The data passed into a function violated the function's usage criteria */
+
FLAC__METADATA_CHAIN_STATUS_ERROR_OPENING_FILE,
+ /**< The chain could not open the target file */
+
FLAC__METADATA_CHAIN_STATUS_NOT_A_FLAC_FILE,
+ /**< The chain could not find the FLAC signature at the start of the file */
+
FLAC__METADATA_CHAIN_STATUS_NOT_WRITABLE,
+ /**< The chain tried to write to a file that was not writable */
+
FLAC__METADATA_CHAIN_STATUS_BAD_METADATA,
+ /**< The chain encountered input that does not conform to the FLAC metadata specification */
+
FLAC__METADATA_CHAIN_STATUS_READ_ERROR,
+ /**< The chain encountered an error while reading the FLAC file */
+
FLAC__METADATA_CHAIN_STATUS_SEEK_ERROR,
+ /**< The chain encountered an error while seeking in the FLAC file */
+
FLAC__METADATA_CHAIN_STATUS_WRITE_ERROR,
+ /**< The chain encountered an error while writing the FLAC file */
+
FLAC__METADATA_CHAIN_STATUS_RENAME_ERROR,
+ /**< The chain encountered an error renaming the FLAC file */
+
FLAC__METADATA_CHAIN_STATUS_UNLINK_ERROR,
+ /**< The chain encountered an error removing the temporary file */
+
FLAC__METADATA_CHAIN_STATUS_MEMORY_ALLOCATION_ERROR,
+ /**< Memory allocation failed */
+
FLAC__METADATA_CHAIN_STATUS_INTERNAL_ERROR
+ /**< The caller violated an assertion or an unexpected error occurred */
+
} FLAC__Metadata_ChainStatus;
+
+/** Maps a FLAC__Metadata_ChainStatus to a C string.
+ *
+ * The contents should not be modified.
+ */
extern const char * const FLAC__Metadata_ChainStatusString[];
/*********** FLAC__Metadata_Chain ***********/
-/*
- * Constructor/destructor
+/** Create a new chain instance.
+ *
+ * \retval FLAC__Metadata_Chain*
+ * NULL if there was an error allocating memory, else the new instance.
*/
FLAC__Metadata_Chain *FLAC__metadata_chain_new();
+
+/** Free a chain instance. Deletes the object pointed to by \a chain.
+ *
+ * \param chain A pointer to an existing chain.
+ * \pre \a chain != NULL
+ */
void FLAC__metadata_chain_delete(FLAC__Metadata_Chain *chain);
-/*
- * Get the current status of the chain. Call this after a function
- * returns false to get the reason for the error. Also resets the status
- * to FLAC__METADATA_CHAIN_STATUS_OK
+/** Get the current status of the chain. Call this after a function
+ * returns \a false to get the reason for the error. Also resets the
+ * status to FLAC__METADATA_CHAIN_STATUS_OK.
+ *
+ * \param chain A pointer to an existing chain.
+ * \pre \a chain != NULL
+ * \retval FLAC__Metadata_ChainStatus
+ * The current status of the chain.
*/
FLAC__Metadata_ChainStatus FLAC__metadata_chain_status(FLAC__Metadata_Chain *chain);
-/*
- * Read all metadata into the chain
+/** Read all metadata from a FLAC file into the chain.
+ *
+ * \param chain A pointer to an existing chain.
+ * \param filename The path to the FLAC file to read.
+ * \pre \a chain != NULL
+ * \pre \a filename != NULL
+ * \retval FLAC__bool
+ * \a true if a valid list of metadata blocks was read from
+ * \a filename, else \a false. On failure, check the status with
+ * FLAC__metadata_chain_status().
*/
FLAC__bool FLAC__metadata_chain_read(FLAC__Metadata_Chain *chain, const char *filename);
-/*
- * 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
- * 'use_padding' is 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
- * use_padding is 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
- * use_padding is 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
- * use_padding is false, the entire FLAC file is rewritten.
- *
- * If 'preserve_file_stats' is true, the owner and modification time will
- * be preserved even if the FLAC file is written.
+/** 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 \a 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 \a 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 \a 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 \a false, the entire FLAC file is rewritten.
+ *
+ * If \a preserve_file_stats is \a true, the owner and modification time will
+ * be preserved even if the FLAC file is written.
+ *
+ * \param chain A pointer to an existing chain.
+ * \param use_padding See above.
+ * \param preserve_file_stats See above.
+ * \pre \a chain != NULL
+ * \retval FLAC__bool
+ * \a true if the write succeeded, else \a false. On failure,
+ * check the status with FLAC__metadata_chain_status().
*/
FLAC__bool FLAC__metadata_chain_write(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__bool preserve_file_stats);
-/*
- * This function will merge adjacent PADDING blocks into a single block.
+/** Merge adjacent PADDING blocks into a single block.
*
- * NOTE: this function does not write to the FLAC file, it only
+ * \note This function does not write to the FLAC file, it only
* modifies the chain.
*
- * NOTE: Any iterator on the current chain will become invalid after this
+ * \warning Any iterator on the current chain will become invalid after this
* call. You should delete the iterator and get a new one.
+ *
+ * \param chain A pointer to an existing chain.
+ * \pre \a chain != NULL
*/
void FLAC__metadata_chain_merge_padding(FLAC__Metadata_Chain *chain);
-/*
- * This function will move all PADDING blocks to the end on the metadata,
- * then merge them into a single block.
+/** This function will move all PADDING blocks to the end on the metadata,
+ * then merge them into a single block.
*
- * NOTE: this function does not write to the FLAC file, it only
+ * \note This function does not write to the FLAC file, it only
* modifies the chain.
*
- * NOTE: Any iterator on the current chain will become invalid after this
+ * \warning Any iterator on the current chain will become invalid after this
* call. You should delete the iterator and get a new one.
+ *
+ * \param chain A pointer to an existing chain.
+ * \pre \a chain != NULL
*/
void FLAC__metadata_chain_sort_padding(FLAC__Metadata_Chain *chain);
/*********** FLAC__Metadata_Iterator ***********/
-/*
- * Constructor/destructor
+/** Create a new iterator instance.
+ *
+ * \retval FLAC__Metadata_Iterator*
+ * NULL if there was an error allocating memory, else the new instance.
*/
FLAC__Metadata_Iterator *FLAC__metadata_iterator_new();
+
+/** Free an iterator instance. Deletes the object pointed to by \a iterator.
+ *
+ * \param iterator A pointer to an existing iterator.
+ * \pre \a iterator != NULL
+ */
void FLAC__metadata_iterator_delete(FLAC__Metadata_Iterator *iterator);
-/*
- * Initialize the iterator to point to the first metadata block in the
- * given chain.
+/** Initialize the iterator to point to the first metadata block in the
+ * given chain.
+ *
+ * \param iterator A pointer to an existing iterator.
+ * \param chain A pointer to an existing and initialized (read) chain.
+ * \pre \a iterator != NULL
+ * \pre \a chain != NULL
*/
void FLAC__metadata_iterator_init(FLAC__Metadata_Iterator *iterator, FLAC__Metadata_Chain *chain);
-/*
- * These move the iterator forwards or backwards, returning false if
- * already at the end.
+/** Moves the iterator forward one metadata block, returning \a false if
+ * already at the end.
+ *
+ * \param iterator A pointer to an existing initialized iterator.
+ * \pre \a iterator != NULL
+ * \pre \a iterator has been successfully initialized with
+ * FLAC__metadata_iterator_init()
+ * \retval FLAC__bool
+ * \a false if already at the last metadata block of the chain, else
+ * \a true.
*/
FLAC__bool FLAC__metadata_iterator_next(FLAC__Metadata_Iterator *iterator);
+
+/** Moves the iterator backward one metadata block, returning \a false if
+ * already at the beginning.
+ *
+ * \param iterator A pointer to an existing initialized iterator.
+ * \pre \a iterator != NULL
+ * \pre \a iterator has been successfully initialized with
+ * FLAC__metadata_iterator_init()
+ * \retval FLAC__bool
+ * \a false if already at the first metadata block of the chain, else
+ * \a true.
+ */
FLAC__bool FLAC__metadata_iterator_prev(FLAC__Metadata_Iterator *iterator);
-/*
- * Get the type of the metadata block at the current position.
+/** Get the type of the metadata block at the current position.
+ *
+ * \param iterator A pointer to an existing initialized iterator.
+ * \pre \a iterator != NULL
+ * \pre \a iterator has been successfully initialized with
+ * FLAC__metadata_iterator_init()
+ * \retval FLAC__MetadataType
+ * The type of the metadata block at the current iterator position.
*/
FLAC__MetadataType FLAC__metadata_iterator_get_block_type(const FLAC__Metadata_Iterator *iterator);
-/*
- * Get the metadata block at the current position. You can modify
- * the block in place but must write the chain before the changes
- * are reflected to the FLAC file. You do not need to call
- * FLAC__metadata_iterator_set_block() to reflect the changes;
- * the pointer returned by FLAC__metadata_iterator_get_block()
- * points directly into the chain.
+/** Get the metadata block at the current position. You can modify
+ * the block in place but must write the chain before the changes
+ * are reflected to the FLAC file. You do not need to call
+ * FLAC__metadata_iterator_set_block() to reflect the changes;
+ * the pointer returned by FLAC__metadata_iterator_get_block()
+ * points directly into the chain.
*
- * Do not call FLAC__metadata_object_delete() on the returned object;
- * to delete a block use FLAC__metadata_iterator_delete_block().
+ * \warning
+ * Do not call FLAC__metadata_object_delete() on the returned object;
+ * to delete a block use FLAC__metadata_iterator_delete_block().
+ *
+ * \param iterator A pointer to an existing initialized iterator.
+ * \pre \a iterator != NULL
+ * \pre \a iterator has been successfully initialized with
+ * FLAC__metadata_iterator_init()
+ * \retval FLAC__StreamMetadata*
+ * The current metadata block.
*/
FLAC__StreamMetadata *FLAC__metadata_iterator_get_block(FLAC__Metadata_Iterator *iterator);
-/*
- * Set the metadata block at the current position, replacing the existing
- * block. The new block passed in becomes owned by the chain and will be
- * deleted when the chain is deleted.
+/** Set the metadata block at the current position, replacing the existing
+ * block. The new block passed in becomes owned by the chain and will be
+ * deleted when the chain is deleted.
+ *
+ * \param iterator A pointer to an existing initialized iterator.
+ * \param block A pointer to a metadata block.
+ * \pre \a iterator != NULL
+ * \pre \a iterator has been successfully initialized with
+ * FLAC__metadata_iterator_init()
+ * \pre \a block != NULL
+ * \retval FLAC__bool
+ * \a false if the conditions in the above description are not met, or
+ * a memory allocation error occurs, otherwise \a true.
*/
FLAC__bool FLAC__metadata_iterator_set_block(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
-/*
- * Removes the current block from the chain. If replace_with_padding is
- * true, the block will instead be replaced with a padding block of equal
- * size. You can not delete the STREAMINFO block. The iterator will be
- * left pointing to the block before the one just 'deleted', even if
- * 'replace_with_padding' is true.
+/** Removes the current block from the chain. If \a replace_with_padding is
+ * \a true, the block will instead be replaced with a padding block of equal
+ * size. You can not delete the STREAMINFO block. The iterator will be
+ * left pointing to the block before the one just "deleted", even if
+ * \a replace_with_padding is \a true.
+ *
+ * \param iterator A pointer to an existing initialized iterator.
+ * \param replace_with_padding See above.
+ * \pre \a iterator != NULL
+ * \pre \a iterator has been successfully initialized with
+ * FLAC__metadata_iterator_init()
+ * \retval FLAC__bool
+ * \a false if the conditions in the above description are not met,
+ * otherwise \a true.
*/
FLAC__bool FLAC__metadata_iterator_delete_block(FLAC__Metadata_Iterator *iterator, FLAC__bool replace_with_padding);
-/*
- * Insert a new block before or after the current block. You cannot
- * insert a block before the first STREAMINFO block. You cannot
- * insert a STREAMINFO block as there can be only one, the one that
- * already exists at the head when you read in a chain. The iterator
- * will be left pointing to the new block.
+/** Insert a new block before the current block. You cannot insert a block
+ * before the first STREAMINFO block. You cannot insert a STREAMINFO block
+ * as there can be only one, the one that already exists at the head when you
+ * read in a chain. The chain takes ownership of the new block and will be
+ * deleted when the chain is deleted. The iterator will be left pointing to
+ * the new block.
+ *
+ * \param iterator A pointer to an existing initialized iterator.
+ * \param block A pointer to a metadata block to insert.
+ * \pre \a iterator != NULL
+ * \pre \a iterator has been successfully initialized with
+ * FLAC__metadata_iterator_init()
+ * \retval FLAC__bool
+ * \a false if the conditions in the above description are not met, or
+ * a memory allocation error occurs, otherwise \a true.
*/
FLAC__bool FLAC__metadata_iterator_insert_block_before(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
+
+/** Insert a new block after the current block. You cannot insert a STREAMINFO
+ * block as there can be only one, the one that already exists at the head when
+ * you read in a chain. The chain takes ownership of the new block and will be
+ * deleted when the chain is deleted. The iterator will be left pointing to
+ * the new block.
+ *
+ * \param iterator A pointer to an existing initialized iterator.
+ * \param block A pointer to a metadata block to insert.
+ * \pre \a iterator != NULL
+ * \pre \a iterator has been successfully initialized with
+ * FLAC__metadata_iterator_init()
+ * \retval FLAC__bool
+ * \a false if the conditions in the above description are not met, or
+ * a memory allocation error occurs, otherwise \a true.
+ */
FLAC__bool FLAC__metadata_iterator_insert_block_after(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
+/* \} */
+
/******************************************************************************
- The following are methods for manipulating the defined block types.
- Since many are variable length we have to be careful about the memory
- management. We decree that all pointers to data in the object are
- owned by the object and memory-managed by the object.
-
- Use the _new and _delete functions to create all instances. When
- using the _set_ functions to set pointers to data, set 'copy' to true
- to have the function make it's own copy of the data, or to false to
- give the object ownership of your data. In the latter case your pointer
- must be freeable by free() and will be free()d when the object is
- FLAC__metadata_object_delete()d. It is legal to pass a null pointer
- as the data pointer to a _set_ function as long as then length argument
- is 0 and the copy argument is 'false'.
-
- The _new and _clone function will return NULL in the case of a memory
- allocation error, otherwise a new object. The _set_ functions return
- false in the case of a memory allocation error.
-
- We don't have the convenience of C++ here, so note that the library
- relies on you to keep the types straight. In other words, if you pass,
- for example, a FLAC__StreamMetadata* that represents a STREAMINFO block
- to FLAC__metadata_object_application_set_data(), you will get an
- assertion failure.
-
- There is no need to recalculate the length field on metadata blocks
- you have modified. They will be calculated automatically before they
- are written back to a file.
-******************************************************************************/
+
+/** \defgroup flac_metadata_object Metadata Object Methods
+ * \ingroup flac_metadata
+ *
+ * The following are methods for manipulating the defined block types.
+ * Since many are variable length we have to be careful about the memory
+ * management. We decree that all pointers to data in the object are
+ * owned by the object and memory-managed by the object.
+ *
+ * Use the FLAC__metadata_object_new() and FLAC__metadata_object_delete()
+ * functions to create all instances. When using the
+ * FLAC__metadata_object_set_*() functions to set pointers to data, set
+ * \a copy to \a true to have the function make it's own copy of the data, or
+ * to \a false to give the object ownership of your data. In the latter case
+ * your pointer must be freeable by free() and will be free()d when the object
+ * is FLAC__metadata_object_delete()d. It is legal to pass a null pointer as
+ * the data pointer to a FLAC__metadata_object_set_*() function as long as
+ * then length argument is 0 and the \a copy argument is \a false.
+ *
+ * The FLAC__metadata_object_new() and FLAC__metadata_object_clone() function
+ * will return NULL in the case of a memory allocation error, otherwise a new
+ * object. The FLAC__metadata_object_set_*() functions return \a false in the
+ * case of a memory allocation error.
+ *
+ * We don't have the convenience of C++ here, so note that the library relies
+ * on you to keep the types straight. In other words, if you pass, for
+ * example, a FLAC__StreamMetadata* that represents a STREAMINFO block to
+ * FLAC__metadata_object_application_set_data(), you will get an assertion
+ * failure.
+ *
+ * There is no need to recalculate the length field on metadata blocks you
+ * have modified. They will be calculated automatically before they are
+ * written back to a file.
+ *
+ * \{
+ */
-/******************************************************************
- * Common to all the types derived from FLAC__StreamMetadata:
+/** \defgroup flac_metadata_object_base Metadata Object Methods - Common
+ * \ingroup flac_metadata_object
+ *
+ * These are common to all the types derived from FLAC__StreamMetadata.
+ *
+ * \{
*/
+
FLAC__StreamMetadata *FLAC__metadata_object_new(FLAC__MetadataType type);
FLAC__StreamMetadata *FLAC__metadata_object_clone(const FLAC__StreamMetadata *object);
void FLAC__metadata_object_delete(FLAC__StreamMetadata *object);
/* Does a deep comparison of the block data */
FLAC__bool FLAC__metadata_object_is_equal(const FLAC__StreamMetadata *block1, const FLAC__StreamMetadata *block2);
-/******************************************************************
- * FLAC__StreamMetadata_Application
- * ----------------------------------------------------------------
- * Note: 'length' is in bytes.
+/* \} */
+
+/** \defgroup flac_metadata_object_application Metadata Object Methods - APPLICATION
+ * \ingroup flac_metadata_object
+ *
+ * These are for manipulating APPLICATION blocks.
+ *
+ * \{
*/
+
+/* Note: \a length is in bytes. */
FLAC__bool FLAC__metadata_object_application_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, unsigned length, FLAC__bool copy);
-/******************************************************************
- * FLAC__StreamMetadata_SeekTable
+/* \} */
+
+/** \defgroup flac_metadata_object_seektable Metadata Object Methods - SEEKTABLE
+ * \ingroup flac_metadata_object
+ *
+ * These are for manipulating SEEKTABLE blocks.
+ *
+ * If the size shrinks, elements will truncated; if it grows, new placeholder
+ * points will be added to the end.
+ *
+ * \{
*/
-/* If the size shrinks, elements will truncated; if it grows, new placeholder points will be added to the end. */
+
FLAC__bool FLAC__metadata_object_seektable_resize_points(FLAC__StreamMetadata *object, unsigned new_num_points);
void FLAC__metadata_object_seektable_set_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point);
FLAC__bool FLAC__metadata_object_seektable_insert_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point);
FLAC__bool FLAC__metadata_object_seektable_delete_point(FLAC__StreamMetadata *object, unsigned point_num);
-/******************************************************************
- * FLAC__StreamMetadata_VorbisComment
+/* \} */
+
+/** \defgroup flac_metadata_object_vorbiscomment Metadata Object Methods - VORBIS_COMMENT
+ * \ingroup flac_metadata_object
+ *
+ * These are for manipulating VORBIS_COMMENT blocks.
+ *
+ * If the size shrinks, elements will truncated; if it grows, new empty
+ * fields will be added to the end.
+ *
+ * \{
*/
+
FLAC__bool FLAC__metadata_object_vorbiscomment_set_vendor_string(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
FLAC__bool FLAC__metadata_object_vorbiscomment_resize_comments(FLAC__StreamMetadata *object, unsigned new_num_comments);
FLAC__bool FLAC__metadata_object_vorbiscomment_set_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
FLAC__bool FLAC__metadata_object_vorbiscomment_delete_comment(FLAC__StreamMetadata *object, unsigned comment_num);
FLAC__bool FLAC__metadata_object_seektable_is_legal(const FLAC__StreamMetadata *object);
+/* \} */
+
+/* \} */
+
#ifdef __cplusplus
}
#endif
projects / platform / upstream / flac.git / commitdiff