claunia/flac
1
0
Fork 0
mirror of https://github.com/claunia/flac.git synced 2025-12-16 18:54:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

more doxygen docs

Browse Source
This commit is contained in:
Josh Coalson
2002-07-12 05:42:04 +00:00
parent 55edea693d
commit 0e252ba45b
3 changed files with 1507 additions and 333 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
include/FLAC/all.h
View File

@@ -29,7 +29,51 @@
#include "stream_decoder.h" #include "stream_decoder.h"
#include "stream_encoder.h" #include "stream_encoder.h"
/** \mainpage
*
* \section intro Introduction.
*
* This is the documentation for the FLAC C and C++ APIs. It is
* highly interconnected; this introduction should give you a top
* level idea of the structure and how to find the information you
* need. As a prerequisite you should have at least a basic
* knowledge of the FLAC format, documented XXXhereXXX.
*
* The FLAC C API is the interface to libFLAC, a set of structures
* describing the components of FLAC streams, and functions for
* encoding and decoding streams, as well as manipulating FLAC
* metadata in files. The public include files will be installed
* in your include area as <include>/FLAC/*.
*
* The FLAC C++ API is a set of classes that encapsulate the
* structures and functions in libFLAC. They provide slightly more
* functionality with respect to metadata but are otherwise
* equivalent. For the most part, they share the same usage as
* their counterparts in libFLAC, and the FLAC C API documentation
* can be used as a supplement. The public include files
* for the C++ API will be installed in your include area as
* <include>/FLAC++/*.
*
* A good starting point for learning the API is to browse through
* the XXX modules XXX. Modules are logical groupings of related
* functions or classes, which correspond roughly to header files
* or sections of header files. Each module includes a detailed
* description of the general usage of its functions or classes.
*
* From there you can go on to look at the documentation of
* individual functions. You can see different views of the individual
* functions through the links in top bar across this page.
*/
/** \defgroup flac FLAC C API /** \defgroup flac FLAC C API
*
* The FLAC C API is the interface to libFLAC, a set of structures
* describing the components of FLAC streams, and functions for
* encoding and decoding streams, as well as manipulating FLAC
* metadata in files.
*
* You should start with the XXX Format XXX module as all other modules
* are dependent on it.
*/ */
#endif #endif

1465
include/FLAC/format.h
View File

File diff suppressed because it is too large Load Diff

331
include/FLAC/metadata.h
View File

@@ -35,11 +35,11 @@
* metadata blocks in memory, and three progressively more powerful * metadata blocks in memory, and three progressively more powerful
* interfaces for traversing and editing metadata in FLAC files. * interfaces for traversing and editing metadata in FLAC files.
* *
* See the documentation for each interface * See the detailed documentation for each interface in the
* \link flac_metadata here \endlink. * \link flac_metadata metadata \endlink module.
*/ */
/** \defgroup flac_metadata FLAC/metadata.h: FLAC metadata C interfaces /** \defgroup flac_metadata FLAC/metadata.h: metadata interfaces
* \ingroup flac * \ingroup flac
* *
* \brief * \brief
@@ -80,9 +80,22 @@
* front of the file. * front of the file.
* *
* In addition to the three interfaces, this module defines functions for * In addition to the three interfaces, this module defines functions for
* creating and manipulating various metadata objects in memory. Unless * creating and manipulating various metadata objects in memory. As we see
* you will be using the level 1 or 2 interfaces to modify existing * from the XXX Format XXX module, FLAC metadata blocks in memory are very primitive
* metadata you will not need these. * structures for storing information in an efficient way. Reading
* information from the structures is easy but creating or modifying them
* directly is more complex. The metadata object routines here facilitate
* this by taking care of the consistency and memory management drudgery.
*
* Unless you will be using the level 1 or 2 interfaces to modify existing
* metadata however, you will not probably not need these.
*
* From a dependency standpoint, none of the encoders or decoders require
* the metadata module (the only exception is
* FLAC__metadata_object_seektable_is_legal() used by the stream encoder,
* and this will eventually be fixed). This is so that embedded users
* can strip out the metadata module from libFLAC to reduce the size and
* complexity.
*/ */
#ifdef __cplusplus #ifdef __cplusplus
@@ -90,7 +103,7 @@ extern "C" {
#endif #endif
/** \defgroup flac_metadata_level0 FLAC/metadata.h: FLAC metadata C level 0 interface /** \defgroup flac_metadata_level0 FLAC/metadata.h: metadata level 0 interface
* \ingroup flac_metadata * \ingroup flac_metadata
* *
* \brief * \brief
@@ -107,8 +120,9 @@ extern "C" {
* *
* \param filename The path to the FLAC file to read. * \param filename The path to the FLAC file to read.
* \param streaminfo A pointer to space for the STREAMINFO block. * \param streaminfo A pointer to space for the STREAMINFO block.
* \pre \code filename != NULL \endcode * \assert
* \pre \code streaminfo != NULL \endcode * \code filename != NULL \endcode
* \code streaminfo != NULL \endcode
* \retval FLAC__bool * \retval FLAC__bool
* \c true if a valid STREAMINFO block was read from \a filename. Returns * \c true if a valid STREAMINFO block was read from \a filename. Returns
* \c false if there was a memory allocation error, a file decoder error, * \c false if there was a memory allocation error, a file decoder error,
@@ -119,7 +133,7 @@ FLAC__bool FLAC__metadata_get_streaminfo(const char *filename, FLAC__StreamMetad
/* \} */ /* \} */
/** \defgroup flac_metadata_level1 FLAC/metadata.h: FLAC metadata C level 1 interface /** \defgroup flac_metadata_level1 FLAC/metadata.h: metadata level 1 interface
* \ingroup flac_metadata * \ingroup flac_metadata
* *
* \brief * \brief
@@ -245,7 +259,8 @@ FLAC__Metadata_SimpleIterator *FLAC__metadata_simple_iterator_new();
/** Free an iterator instance. Deletes the object pointed to by \a iterator. /** Free an iterator instance. Deletes the object pointed to by \a iterator.
* *
* \param iterator A pointer to an existing iterator. * \param iterator A pointer to an existing iterator.
* \pre \code iterator != NULL \endcode * \assert
* \code iterator != NULL \endcode
*/ */
void FLAC__metadata_simple_iterator_delete(FLAC__Metadata_SimpleIterator *iterator); void FLAC__metadata_simple_iterator_delete(FLAC__Metadata_SimpleIterator *iterator);
@@ -254,7 +269,8 @@ void FLAC__metadata_simple_iterator_delete(FLAC__Metadata_SimpleIterator *iterat
* to FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK. * to FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK.
* *
* \param iterator A pointer to an existing iterator. * \param iterator A pointer to an existing iterator.
* \pre \code iterator != NULL \endcode * \assert
* \code iterator != NULL \endcode
* \retval FLAC__Metadata_SimpleIteratorStatus * \retval FLAC__Metadata_SimpleIteratorStatus
* The current status of the iterator. * The current status of the iterator.
*/ */
@@ -267,11 +283,12 @@ FLAC__Metadata_SimpleIteratorStatus FLAC__metadata_simple_iterator_status(FLAC__
* \param iterator A pointer to an existing iterator. * \param iterator A pointer to an existing iterator.
* \param filename The path to the FLAC file. * \param filename The path to the FLAC file.
* \param preserve_file_stats See above. * \param preserve_file_stats See above.
* \pre \code iterator != NULL \endcode * \assert
* \pre \code filename != NULL \endcode * \code iterator != NULL \endcode
* \code filename != NULL \endcode
* \retval FLAC__bool * \retval FLAC__bool
* \c false if a memory allocation error occurs, the file can't be * \c false if a memory allocation error occurs, the file can't be
* opened, or another error occurs, else \c true. * opened, or another error occurs, else \c true.
*/ */
FLAC__bool FLAC__metadata_simple_iterator_init(FLAC__Metadata_SimpleIterator *iterator, const char *filename, FLAC__bool preserve_file_stats); FLAC__bool FLAC__metadata_simple_iterator_init(FLAC__Metadata_SimpleIterator *iterator, const char *filename, FLAC__bool preserve_file_stats);
@@ -280,9 +297,10 @@ FLAC__bool FLAC__metadata_simple_iterator_init(FLAC__Metadata_SimpleIterator *it
* FLAC__metadata_simple_iterator_insert_block_after() will fail. * FLAC__metadata_simple_iterator_insert_block_after() will fail.
* *
* \param iterator A pointer to an existing iterator. * \param iterator A pointer to an existing iterator.
* \pre \code iterator != NULL \endcode * \assert
* \code iterator != NULL \endcode
* \retval FLAC__bool * \retval FLAC__bool
* See above. * See above.
*/ */
FLAC__bool FLAC__metadata_simple_iterator_is_writable(const FLAC__Metadata_SimpleIterator *iterator); FLAC__bool FLAC__metadata_simple_iterator_is_writable(const FLAC__Metadata_SimpleIterator *iterator);
@@ -290,9 +308,10 @@ FLAC__bool FLAC__metadata_simple_iterator_is_writable(const FLAC__Metadata_Simpl
* already at the end. * already at the end.
* *
* \param iterator A pointer to an existing initialized iterator. * \param iterator A pointer to an existing initialized iterator.
* \pre \code iterator != NULL \endcode * \assert
* \pre \a iterator has been successfully initialized with * \code iterator != NULL \endcode
* FLAC__metadata_simple_iterator_init() * \a iterator has been successfully initialized with
* FLAC__metadata_simple_iterator_init()
* \retval FLAC__bool * \retval FLAC__bool
* \c false if already at the last metadata block of the chain, else * \c false if already at the last metadata block of the chain, else
* \c true. * \c true.
@@ -303,9 +322,10 @@ FLAC__bool FLAC__metadata_simple_iterator_next(FLAC__Metadata_SimpleIterator *it
* already at the beginning. * already at the beginning.
* *
* \param iterator A pointer to an existing initialized iterator. * \param iterator A pointer to an existing initialized iterator.
* \pre \code iterator != NULL \endcode * \assert
* \pre \a iterator has been successfully initialized with * \code iterator != NULL \endcode
* FLAC__metadata_simple_iterator_init() * \a iterator has been successfully initialized with
* FLAC__metadata_simple_iterator_init()
* \retval FLAC__bool * \retval FLAC__bool
* \c false if already at the first metadata block of the chain, else * \c false if already at the first metadata block of the chain, else
* \c true. * \c true.
@@ -317,9 +337,10 @@ FLAC__bool FLAC__metadata_simple_iterator_prev(FLAC__Metadata_SimpleIterator *it
* blocks. * blocks.
* *
* \param iterator A pointer to an existing initialized iterator. * \param iterator A pointer to an existing initialized iterator.
* \pre \code iterator != NULL \endcode * \assert
* \pre \a iterator has been successfully initialized with * \code iterator != NULL \endcode
* FLAC__metadata_simple_iterator_init() * \a iterator has been successfully initialized with
* FLAC__metadata_simple_iterator_init()
* \retval FLAC__MetadataType * \retval FLAC__MetadataType
* The type of the metadata block at the current iterator position. * The type of the metadata block at the current iterator position.
*/ */
@@ -334,9 +355,10 @@ FLAC__MetadataType FLAC__metadata_simple_iterator_get_block_type(const FLAC__Met
* when you are finished with it. * when you are finished with it.
* *
* \param iterator A pointer to an existing initialized iterator. * \param iterator A pointer to an existing initialized iterator.
* \pre \code iterator != NULL \endcode * \assert
* \pre \a iterator has been successfully initialized with * \code iterator != NULL \endcode
* FLAC__metadata_simple_iterator_init() * \a iterator has been successfully initialized with
* FLAC__metadata_simple_iterator_init()
* \retval FLAC__StreamMetadata* * \retval FLAC__StreamMetadata*
* The current metadata block. * The current metadata block.
*/ */
@@ -388,10 +410,11 @@ FLAC__StreamMetadata *FLAC__metadata_simple_iterator_get_block(FLAC__Metadata_Si
* \param iterator A pointer to an existing initialized iterator. * \param iterator A pointer to an existing initialized iterator.
* \param block The block to set. * \param block The block to set.
* \param use_padding See above. * \param use_padding See above.
* \pre \code iterator != NULL \endcode * \assert
* \pre \a iterator has been successfully initialized with * \code iterator != NULL \endcode
* FLAC__metadata_simple_iterator_init() * \a iterator has been successfully initialized with
* \pre \code block != NULL \endcode * FLAC__metadata_simple_iterator_init()
* \code block != NULL \endcode
* \retval FLAC__bool * \retval FLAC__bool
* \c true if successful, else \c false. * \c true if successful, else \c false.
*/ */
@@ -412,10 +435,11 @@ FLAC__bool FLAC__metadata_simple_iterator_set_block(FLAC__Metadata_SimpleIterato
* \param iterator A pointer to an existing initialized iterator. * \param iterator A pointer to an existing initialized iterator.
* \param block The block to set. * \param block The block to set.
* \param use_padding See above. * \param use_padding See above.
* \pre \code iterator != NULL \endcode * \assert
* \pre \a iterator has been successfully initialized with * \code iterator != NULL \endcode
* FLAC__metadata_simple_iterator_init() * \a iterator has been successfully initialized with
* \pre \code block != NULL \endcode * FLAC__metadata_simple_iterator_init()
* \code block != NULL \endcode
* \retval FLAC__bool * \retval FLAC__bool
* \c true if successful, else \c false. * \c true if successful, else \c false.
*/ */
@@ -431,9 +455,10 @@ FLAC__bool FLAC__metadata_simple_iterator_insert_block_after(FLAC__Metadata_Simp
* *
* \param iterator A pointer to an existing initialized iterator. * \param iterator A pointer to an existing initialized iterator.
* \param use_padding See above. * \param use_padding See above.
* \pre \code iterator != NULL \endcode * \assert
* \pre \a iterator has been successfully initialized with * \code iterator != NULL \endcode
* FLAC__metadata_simple_iterator_init() * \a iterator has been successfully initialized with
* FLAC__metadata_simple_iterator_init()
* \retval FLAC__bool * \retval FLAC__bool
* \c true if successful, else \c false. * \c true if successful, else \c false.
*/ */
@@ -442,7 +467,7 @@ FLAC__bool FLAC__metadata_simple_iterator_delete_block(FLAC__Metadata_SimpleIter
/* \} */ /* \} */
/** \defgroup flac_metadata_level2 FLAC/metadata.h: FLAC metadata C level 2 interface /** \defgroup flac_metadata_level2 FLAC/metadata.h: metadata level 2 interface
* \ingroup flac_metadata * \ingroup flac_metadata
* *
* \brief * \brief
@@ -567,7 +592,8 @@ FLAC__Metadata_Chain *FLAC__metadata_chain_new();
/** Free a chain instance. Deletes the object pointed to by \a chain. /** Free a chain instance. Deletes the object pointed to by \a chain.
* *
* \param chain A pointer to an existing chain. * \param chain A pointer to an existing chain.
* \pre \code chain != NULL \endcode * \assert
* \code chain != NULL \endcode
*/ */
void FLAC__metadata_chain_delete(FLAC__Metadata_Chain *chain); void FLAC__metadata_chain_delete(FLAC__Metadata_Chain *chain);
@@ -576,7 +602,8 @@ void FLAC__metadata_chain_delete(FLAC__Metadata_Chain *chain);
* status to FLAC__METADATA_CHAIN_STATUS_OK. * status to FLAC__METADATA_CHAIN_STATUS_OK.
* *
* \param chain A pointer to an existing chain. * \param chain A pointer to an existing chain.
* \pre \code chain != NULL \endcode * \assert
* \code chain != NULL \endcode
* \retval FLAC__Metadata_ChainStatus * \retval FLAC__Metadata_ChainStatus
* The current status of the chain. * The current status of the chain.
*/ */
@@ -586,8 +613,9 @@ FLAC__Metadata_ChainStatus FLAC__metadata_chain_status(FLAC__Metadata_Chain *cha
* *
* \param chain A pointer to an existing chain. * \param chain A pointer to an existing chain.
* \param filename The path to the FLAC file to read. * \param filename The path to the FLAC file to read.
* \pre \code chain != NULL \endcode * \assert
* \pre \code filename != NULL \endcode * \code chain != NULL \endcode
* \code filename != NULL \endcode
* \retval FLAC__bool * \retval FLAC__bool
* \c true if a valid list of metadata blocks was read from * \c true if a valid list of metadata blocks was read from
* \a filename, else \c false. On failure, check the status with * \a filename, else \c false. On failure, check the status with
@@ -629,7 +657,8 @@ FLAC__bool FLAC__metadata_chain_read(FLAC__Metadata_Chain *chain, const char *fi
* \param chain A pointer to an existing chain. * \param chain A pointer to an existing chain.
* \param use_padding See above. * \param use_padding See above.
* \param preserve_file_stats See above. * \param preserve_file_stats See above.
* \pre \code chain != NULL \endcode * \assert
* \code chain != NULL \endcode
* \retval FLAC__bool * \retval FLAC__bool
* \c true if the write succeeded, else \c false. On failure, * \c true if the write succeeded, else \c false. On failure,
* check the status with FLAC__metadata_chain_status(). * check the status with FLAC__metadata_chain_status().
@@ -645,7 +674,8 @@ FLAC__bool FLAC__metadata_chain_write(FLAC__Metadata_Chain *chain, FLAC__bool us
* call. You should delete the iterator and get a new one. * call. You should delete the iterator and get a new one.
* *
* \param chain A pointer to an existing chain. * \param chain A pointer to an existing chain.
* \pre \code chain != NULL \endcode * \assert
* \code chain != NULL \endcode
*/ */
void FLAC__metadata_chain_merge_padding(FLAC__Metadata_Chain *chain); void FLAC__metadata_chain_merge_padding(FLAC__Metadata_Chain *chain);
@@ -659,7 +689,8 @@ void FLAC__metadata_chain_merge_padding(FLAC__Metadata_Chain *chain);
* call. You should delete the iterator and get a new one. * call. You should delete the iterator and get a new one.
* *
* \param chain A pointer to an existing chain. * \param chain A pointer to an existing chain.
* \pre \code chain != NULL \endcode * \assert
* \code chain != NULL \endcode
*/ */
void FLAC__metadata_chain_sort_padding(FLAC__Metadata_Chain *chain); void FLAC__metadata_chain_sort_padding(FLAC__Metadata_Chain *chain);
@@ -676,7 +707,8 @@ FLAC__Metadata_Iterator *FLAC__metadata_iterator_new();
/** Free an iterator instance. Deletes the object pointed to by \a iterator. /** Free an iterator instance. Deletes the object pointed to by \a iterator.
* *
* \param iterator A pointer to an existing iterator. * \param iterator A pointer to an existing iterator.
* \pre \code iterator != NULL \endcode * \assert
* \code iterator != NULL \endcode
*/ */
void FLAC__metadata_iterator_delete(FLAC__Metadata_Iterator *iterator); void FLAC__metadata_iterator_delete(FLAC__Metadata_Iterator *iterator);
@@ -685,8 +717,9 @@ void FLAC__metadata_iterator_delete(FLAC__Metadata_Iterator *iterator);
* *
* \param iterator A pointer to an existing iterator. * \param iterator A pointer to an existing iterator.
* \param chain A pointer to an existing and initialized (read) chain. * \param chain A pointer to an existing and initialized (read) chain.
* \pre \code iterator != NULL \endcode * \assert
* \pre \code chain != NULL \endcode * \code iterator != NULL \endcode
* \code chain != NULL \endcode
*/ */
void FLAC__metadata_iterator_init(FLAC__Metadata_Iterator *iterator, FLAC__Metadata_Chain *chain); void FLAC__metadata_iterator_init(FLAC__Metadata_Iterator *iterator, FLAC__Metadata_Chain *chain);
@@ -694,9 +727,10 @@ void FLAC__metadata_iterator_init(FLAC__Metadata_Iterator *iterator, FLAC__Metad
* already at the end. * already at the end.
* *
* \param iterator A pointer to an existing initialized iterator. * \param iterator A pointer to an existing initialized iterator.
* \pre \code iterator != NULL \endcode * \assert
* \pre \a iterator has been successfully initialized with * \code iterator != NULL \endcode
* FLAC__metadata_iterator_init() * \a iterator has been successfully initialized with
* FLAC__metadata_iterator_init()
* \retval FLAC__bool * \retval FLAC__bool
* \c false if already at the last metadata block of the chain, else * \c false if already at the last metadata block of the chain, else
* \c true. * \c true.
@@ -707,9 +741,10 @@ FLAC__bool FLAC__metadata_iterator_next(FLAC__Metadata_Iterator *iterator);
* already at the beginning. * already at the beginning.
* *
* \param iterator A pointer to an existing initialized iterator. * \param iterator A pointer to an existing initialized iterator.
* \pre \code iterator != NULL \endcode * \assert
* \pre \a iterator has been successfully initialized with * \code iterator != NULL \endcode
* FLAC__metadata_iterator_init() * \a iterator has been successfully initialized with
* FLAC__metadata_iterator_init()
* \retval FLAC__bool * \retval FLAC__bool
* \c false if already at the first metadata block of the chain, else * \c false if already at the first metadata block of the chain, else
* \c true. * \c true.
@@ -719,9 +754,10 @@ 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. * \param iterator A pointer to an existing initialized iterator.
* \pre \code iterator != NULL \endcode * \assert
* \pre \a iterator has been successfully initialized with * \code iterator != NULL \endcode
* FLAC__metadata_iterator_init() * \a iterator has been successfully initialized with
* FLAC__metadata_iterator_init()
* \retval FLAC__MetadataType * \retval FLAC__MetadataType
* The type of the metadata block at the current iterator position. * The type of the metadata block at the current iterator position.
*/ */
@@ -739,9 +775,10 @@ FLAC__MetadataType FLAC__metadata_iterator_get_block_type(const FLAC__Metadata_I
* to delete a block use FLAC__metadata_iterator_delete_block(). * to delete a block use FLAC__metadata_iterator_delete_block().
* *
* \param iterator A pointer to an existing initialized iterator. * \param iterator A pointer to an existing initialized iterator.
* \pre \code iterator != NULL \endcode * \assert
* \pre \a iterator has been successfully initialized with * \code iterator != NULL \endcode
* FLAC__metadata_iterator_init() * \a iterator has been successfully initialized with
* FLAC__metadata_iterator_init()
* \retval FLAC__StreamMetadata* * \retval FLAC__StreamMetadata*
* The current metadata block. * The current metadata block.
*/ */
@@ -753,10 +790,11 @@ FLAC__StreamMetadata *FLAC__metadata_iterator_get_block(FLAC__Metadata_Iterator
* *
* \param iterator A pointer to an existing initialized iterator. * \param iterator A pointer to an existing initialized iterator.
* \param block A pointer to a metadata block. * \param block A pointer to a metadata block.
* \pre \code iterator != NULL \endcode * \assert
* \pre \a iterator has been successfully initialized with * \code iterator != NULL \endcode
* FLAC__metadata_iterator_init() * \a iterator has been successfully initialized with
* \pre \code block != NULL \endcode * FLAC__metadata_iterator_init()
* \code block != NULL \endcode
* \retval FLAC__bool * \retval FLAC__bool
* \c false if the conditions in the above description are not met, or * \c false if the conditions in the above description are not met, or
* a memory allocation error occurs, otherwise \c true. * a memory allocation error occurs, otherwise \c true.
@@ -771,9 +809,10 @@ FLAC__bool FLAC__metadata_iterator_set_block(FLAC__Metadata_Iterator *iterator,
* *
* \param iterator A pointer to an existing initialized iterator. * \param iterator A pointer to an existing initialized iterator.
* \param replace_with_padding See above. * \param replace_with_padding See above.
* \pre \code iterator != NULL \endcode * \assert
* \pre \a iterator has been successfully initialized with * \code iterator != NULL \endcode
* FLAC__metadata_iterator_init() * \a iterator has been successfully initialized with
* FLAC__metadata_iterator_init()
* \retval FLAC__bool * \retval FLAC__bool
* \c false if the conditions in the above description are not met, * \c false if the conditions in the above description are not met,
* otherwise \c true. * otherwise \c true.
@@ -789,9 +828,10 @@ FLAC__bool FLAC__metadata_iterator_delete_block(FLAC__Metadata_Iterator *iterato
* *
* \param iterator A pointer to an existing initialized iterator. * \param iterator A pointer to an existing initialized iterator.
* \param block A pointer to a metadata block to insert. * \param block A pointer to a metadata block to insert.
* \pre \code iterator != NULL \endcode * \assert
* \pre \a iterator has been successfully initialized with * \code iterator != NULL \endcode
* FLAC__metadata_iterator_init() * \a iterator has been successfully initialized with
* FLAC__metadata_iterator_init()
* \retval FLAC__bool * \retval FLAC__bool
* \c false if the conditions in the above description are not met, or * \c false if the conditions in the above description are not met, or
* a memory allocation error occurs, otherwise \c true. * a memory allocation error occurs, otherwise \c true.
@@ -806,9 +846,10 @@ FLAC__bool FLAC__metadata_iterator_insert_block_before(FLAC__Metadata_Iterator *
* *
* \param iterator A pointer to an existing initialized iterator. * \param iterator A pointer to an existing initialized iterator.
* \param block A pointer to a metadata block to insert. * \param block A pointer to a metadata block to insert.
* \pre \code iterator != NULL \endcode * \assert
* \pre \a iterator has been successfully initialized with * \code iterator != NULL \endcode
* FLAC__metadata_iterator_init() * \a iterator has been successfully initialized with
* FLAC__metadata_iterator_init()
* \retval FLAC__bool * \retval FLAC__bool
* \c false if the conditions in the above description are not met, or * \c false if the conditions in the above description are not met, or
* a memory allocation error occurs, otherwise \c true. * a memory allocation error occurs, otherwise \c true.
@@ -818,7 +859,7 @@ FLAC__bool FLAC__metadata_iterator_insert_block_after(FLAC__Metadata_Iterator *i
/* \} */ /* \} */
/** \defgroup flac_metadata_object FLAC/metadata.h: FLAC metadata C object methods /** \defgroup flac_metadata_object FLAC/metadata.h: metadata object methods
* \ingroup flac_metadata * \ingroup flac_metadata
* *
* \brief * \brief
@@ -857,15 +898,6 @@ FLAC__bool FLAC__metadata_iterator_insert_block_after(FLAC__Metadata_Iterator *i
*/ */
/** \defgroup flac_metadata_object_common FLAC/metadata.h: FLAC metadata C object methods - common
* \ingroup flac_metadata_object
*
* \brief
* These are common to all the types derived from FLAC__StreamMetadata.
*
* \{
*/
/** Create a new metadata object instance of the given type. /** Create a new metadata object instance of the given type.
* *
* The object will be "empty"; i.e. values and data pointers will be \c 0. * The object will be "empty"; i.e. values and data pointers will be \c 0.
@@ -883,7 +915,8 @@ FLAC__StreamMetadata *FLAC__metadata_object_new(FLAC__MetadataType type);
* is responsible for freeing it with FLAC__metadata_object_delete(). * is responsible for freeing it with FLAC__metadata_object_delete().
* *
* \param object Pointer to object to copy. * \param object Pointer to object to copy.
* \pre \code object != NULL \endcode * \assert
* \code object != NULL \endcode
* \retval FLAC__StreamMetadata* * \retval FLAC__StreamMetadata*
* \c NULL if there was an error allocating memory, else the new instance. * \c NULL if there was an error allocating memory, else the new instance.
*/ */
@@ -895,7 +928,8 @@ FLAC__StreamMetadata *FLAC__metadata_object_clone(const FLAC__StreamMetadata *ob
* object is also deleted. * object is also deleted.
* *
* \param object A pointer to an existing object. * \param object A pointer to an existing object.
* \pre \code object != NULL \endcode * \assert
* \code object != NULL \endcode
*/ */
void FLAC__metadata_object_delete(FLAC__StreamMetadata *object); void FLAC__metadata_object_delete(FLAC__StreamMetadata *object);
@@ -907,24 +941,14 @@ void FLAC__metadata_object_delete(FLAC__StreamMetadata *object);
* *
* \param block1 A pointer to an existing object. * \param block1 A pointer to an existing object.
* \param block2 A pointer to an existing object. * \param block2 A pointer to an existing object.
* \pre \code block1 != NULL \endcode * \assert
* \pre \code block2 != NULL \endcode * \code block1 != NULL \endcode
* \code block2 != NULL \endcode
* \retval FLAC__bool * \retval FLAC__bool
* \c true if objects are identical, else \c false. * \c true if objects are identical, else \c false.
*/ */
FLAC__bool FLAC__metadata_object_is_equal(const FLAC__StreamMetadata *block1, const FLAC__StreamMetadata *block2); FLAC__bool FLAC__metadata_object_is_equal(const FLAC__StreamMetadata *block1, const FLAC__StreamMetadata *block2);
/* \} */
/** \defgroup flac_metadata_object_application FLAC/metadata.h: FLAC metadata C object methods - APPLICATION
* \ingroup flac_metadata_object
*
* \brief
* These are for manipulating APPLICATION blocks.
*
* \{
*/
/** Sets the application data of an APPLICATION block. /** Sets the application data of an APPLICATION block.
* *
* If \a copy is \c true, a copy of the data is stored; otherwise, the object * If \a copy is \c true, a copy of the data is stored; otherwise, the object
@@ -935,26 +959,16 @@ FLAC__bool FLAC__metadata_object_is_equal(const FLAC__StreamMetadata *block1, co
* \param data A pointer to the data to set. * \param data A pointer to the data to set.
* \param length The length of \a data in bytes. * \param length The length of \a data in bytes.
* \param copy See above. * \param copy See above.
* \pre \code object != NULL \endcode * \assert
* \pre \code object->type == FLAC__METADATA_TYPE_APPLICATION \endcode * \code object != NULL \endcode
* \pre \code (data != NULL && length > 0) || * \code object->type == FLAC__METADATA_TYPE_APPLICATION \endcode
* \code (data != NULL && length > 0) ||
* (data == NULL && length == 0 && copy == false) \endcode * (data == NULL && length == 0 && copy == false) \endcode
* \retval FLAC__bool * \retval FLAC__bool
* \c false if \a copy is \c true and malloc fails, else \c true. * \c false if \a copy is \c true and malloc fails, else \c true.
*/ */
FLAC__bool FLAC__metadata_object_application_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, unsigned length, FLAC__bool copy); FLAC__bool FLAC__metadata_object_application_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, unsigned length, FLAC__bool copy);
/* \} */
/** \defgroup flac_metadata_object_seektable FLAC/metadata.h: FLAC metadata C object methods - SEEKTABLE
* \ingroup flac_metadata_object
*
* \brief
* These are for manipulating SEEKTABLE blocks.
*
* \{
*/
/** Resize the seekpoint array. /** Resize the seekpoint array.
* *
* If the size shrinks, elements will truncated; if it grows, new placeholder * If the size shrinks, elements will truncated; if it grows, new placeholder
@@ -962,9 +976,10 @@ FLAC__bool FLAC__metadata_object_application_set_data(FLAC__StreamMetadata *obje
* *
* \param object A pointer to an existing SEEKTABLE object. * \param object A pointer to an existing SEEKTABLE object.
* \param new_num_points The desired length of the array; may be \c 0. * \param new_num_points The desired length of the array; may be \c 0.
* \pre \code object != NULL \endcode * \assert
* \pre \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode * \code object != NULL \endcode
* \pre \code (object->data.seek_table.points == NULL && object->data.seek_table.num_points == 0) || * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
* \code (object->data.seek_table.points == NULL && object->data.seek_table.num_points == 0) ||
* (object->data.seek_table.points != NULL && object->data.seek_table.num_points > 0) \endcode * (object->data.seek_table.points != NULL && object->data.seek_table.num_points > 0) \endcode
* \retval FLAC__bool * \retval FLAC__bool
* \c false if memory allocation error, else \c true. * \c false if memory allocation error, else \c true.
@@ -976,9 +991,10 @@ FLAC__bool FLAC__metadata_object_seektable_resize_points(FLAC__StreamMetadata *o
* \param object A pointer to an existing SEEKTABLE object. * \param object A pointer to an existing SEEKTABLE object.
* \param point_num Index into seekpoint array to set. * \param point_num Index into seekpoint array to set.
* \param point The point to set. * \param point The point to set.
* \pre \code object != NULL \endcode * \assert
* \pre \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode * \code object != NULL \endcode
* \pre \code object->data.seek_table.num_points > point_num \endcode * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
* \code object->data.seek_table.num_points > point_num \endcode
*/ */
void FLAC__metadata_object_seektable_set_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point); void FLAC__metadata_object_seektable_set_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point);
@@ -987,9 +1003,10 @@ void FLAC__metadata_object_seektable_set_point(FLAC__StreamMetadata *object, uns
* \param object A pointer to an existing SEEKTABLE object. * \param object A pointer to an existing SEEKTABLE object.
* \param point_num Index into seekpoint array to set. * \param point_num Index into seekpoint array to set.
* \param point The point to set. * \param point The point to set.
* \pre \code object != NULL \endcode * \assert
* \pre \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode * \code object != NULL \endcode
* \pre \code object->data.seek_table.num_points >= point_num \endcode * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
* \code object->data.seek_table.num_points >= point_num \endcode
* \retval FLAC__bool * \retval FLAC__bool
* \c false if memory allocation error, else \c true. * \c false if memory allocation error, else \c true.
*/ */
@@ -999,9 +1016,10 @@ FLAC__bool FLAC__metadata_object_seektable_insert_point(FLAC__StreamMetadata *ob
* *
* \param object A pointer to an existing SEEKTABLE object. * \param object A pointer to an existing SEEKTABLE object.
* \param point_num Index into seekpoint array to set. * \param point_num Index into seekpoint array to set.
* \pre \code object != NULL \endcode * \assert
* \pre \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode * \code object != NULL \endcode
* \pre \code object->data.seek_table.num_points > point_num \endcode * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
* \code object->data.seek_table.num_points > point_num \endcode
* \retval FLAC__bool * \retval FLAC__bool
* \c false if memory allocation error, else \c true. * \c false if memory allocation error, else \c true.
*/ */
@@ -1012,24 +1030,14 @@ FLAC__bool FLAC__metadata_object_seektable_delete_point(FLAC__StreamMetadata *ob
* seektable. * seektable.
* *
* \param object A pointer to an existing SEEKTABLE object. * \param object A pointer to an existing SEEKTABLE object.
* \pre \code object != NULL \endcode * \assert
* \pre \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode * \code object != NULL \endcode
* \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
* \retval FLAC__bool * \retval FLAC__bool
* \c false if seektable is illegal, else \c true. * \c false if seektable is illegal, else \c true.
*/ */
FLAC__bool FLAC__metadata_object_seektable_is_legal(const FLAC__StreamMetadata *object); FLAC__bool FLAC__metadata_object_seektable_is_legal(const FLAC__StreamMetadata *object);
/* \} */
/** \defgroup flac_metadata_object_vorbiscomment FLAC/metadata.h: FLAC metadata C object methods - VORBIS_COMMENT
* \ingroup flac_metadata_object
*
* \brief
* These are for manipulating VORBIS_COMMENT blocks.
*
* \{
*/
/** Sets the vendor string in a VORBIS_COMMENT block. /** Sets the vendor string in a VORBIS_COMMENT block.
* *
* If \a copy is \c true, a copy of the entry is stored; otherwise, the object * If \a copy is \c true, a copy of the entry is stored; otherwise, the object
@@ -1039,9 +1047,10 @@ FLAC__bool FLAC__metadata_object_seektable_is_legal(const FLAC__StreamMetadata *
* \param object A pointer to an existing VORBIS_COMMENT object. * \param object A pointer to an existing VORBIS_COMMENT object.
* \param entry The entry to set the vendor string to. * \param entry The entry to set the vendor string to.
* \param copy See above. * \param copy See above.
* \pre \code object != NULL \endcode * \assert
* \pre \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode * \code object != NULL \endcode
* \pre \code (entry->entry != NULL && entry->length > 0) || * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
* \code (entry->entry != NULL && entry->length > 0) ||
* (entry->entry == NULL && entry->length == 0 && copy == false) \endcode * (entry->entry == NULL && entry->length == 0 && copy == false) \endcode
* \retval FLAC__bool * \retval FLAC__bool
* \c false if \a copy is \c true and malloc fails, else \c true. * \c false if \a copy is \c true and malloc fails, else \c true.
@@ -1055,9 +1064,10 @@ FLAC__bool FLAC__metadata_object_vorbiscomment_set_vendor_string(FLAC__StreamMet
* *
* \param object A pointer to an existing VORBIS_COMMENT object. * \param object A pointer to an existing VORBIS_COMMENT object.
* \param new_num_comments The desired length of the array; may be \c 0. * \param new_num_comments The desired length of the array; may be \c 0.
* \pre \code object != NULL \endcode * \assert
* \pre \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode * \code object != NULL \endcode
* \pre \code (object->data.vorbis_comment.comments == NULL && object->data.vorbis_comment.num_comments == 0) || * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
* \code (object->data.vorbis_comment.comments == NULL && object->data.vorbis_comment.num_comments == 0) ||
* (object->data.vorbis_comment.comments != NULL && object->data.vorbis_comment.num_comments > 0) \endcode * (object->data.vorbis_comment.comments != NULL && object->data.vorbis_comment.num_comments > 0) \endcode
* \retval FLAC__bool * \retval FLAC__bool
* \c false if memory allocation error, else \c true. * \c false if memory allocation error, else \c true.
@@ -1074,9 +1084,10 @@ FLAC__bool FLAC__metadata_object_vorbiscomment_resize_comments(FLAC__StreamMetad
* \param comment_num Index into comment array to set. * \param comment_num Index into comment array to set.
* \param entry The entry to set the comment to. * \param entry The entry to set the comment to.
* \param copy See above. * \param copy See above.
* \pre \code object != NULL \endcode * \assert
* \pre \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode * \code object != NULL \endcode
* \pre \code (entry->entry != NULL && entry->length > 0) || * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
* \code (entry->entry != NULL && entry->length > 0) ||
* (entry->entry == NULL && entry->length == 0 && copy == false) \endcode * (entry->entry == NULL && entry->length == 0 && copy == false) \endcode
* \retval FLAC__bool * \retval FLAC__bool
* \c false if \a copy is \c true and malloc fails, else \c true. * \c false if \a copy is \c true and malloc fails, else \c true.
@@ -1096,10 +1107,11 @@ FLAC__bool FLAC__metadata_object_vorbiscomment_set_comment(FLAC__StreamMetadata
* \c object->data.vorbis_comment.num_comments . * \c object->data.vorbis_comment.num_comments .
* \param entry The comment to insert. * \param entry The comment to insert.
* \param copy See above. * \param copy See above.
* \pre \code object != NULL \endcode * \assert
* \pre \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode * \code object != NULL \endcode
* \pre \code object->data.vorbis_comment.num_comments >= comment_num \endcode * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
* \pre \code (entry->entry != NULL && entry->length > 0) || * \code object->data.vorbis_comment.num_comments >= comment_num \endcode
* \code (entry->entry != NULL && entry->length > 0) ||
* (entry->entry == NULL && entry->length == 0 && copy == false) \endcode * (entry->entry == NULL && entry->length == 0 && copy == false) \endcode
* \retval FLAC__bool * \retval FLAC__bool
* \c false if \a copy is \c true and malloc fails, else \c true. * \c false if \a copy is \c true and malloc fails, else \c true.
@@ -1114,10 +1126,11 @@ FLAC__bool FLAC__metadata_object_vorbiscomment_insert_comment(FLAC__StreamMetada
* *
* \param object A pointer to an existing VORBIS_COMMENT object. * \param object A pointer to an existing VORBIS_COMMENT object.
* \param comment_num The index of the comment to delete. * \param comment_num The index of the comment to delete.
* \pre \code object != NULL \endcode * \assert
* \pre \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode * \code object != NULL \endcode
* \pre \code object->data.vorbis_comment.num_comments > comment_num \endcode * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
* \pre \code (entry->entry != NULL && entry->length > 0) || * \code object->data.vorbis_comment.num_comments > comment_num \endcode
* \code (entry->entry != NULL && entry->length > 0) ||
* (entry->entry == NULL && entry->length == 0 && copy == false) \endcode * (entry->entry == NULL && entry->length == 0 && copy == false) \endcode
* \retval FLAC__bool * \retval FLAC__bool
* \c false if realloc fails, else \c true. * \c false if realloc fails, else \c true.
@@ -1126,8 +1139,6 @@ FLAC__bool FLAC__metadata_object_vorbiscomment_delete_comment(FLAC__StreamMetada
/* \} */ /* \} */
/* \} */
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif