vx32

Local 9vx git repository for patches.
git clone git://r-36.net/vx32
Log | Files | Refs

metadata.h (83577B)


      1 /* libFLAC - Free Lossless Audio Codec library
      2  * Copyright (C) 2001,2002,2003,2004,2005  Josh Coalson
      3  *
      4  * Redistribution and use in source and binary forms, with or without
      5  * modification, are permitted provided that the following conditions
      6  * are met:
      7  *
      8  * - Redistributions of source code must retain the above copyright
      9  * notice, this list of conditions and the following disclaimer.
     10  *
     11  * - Redistributions in binary form must reproduce the above copyright
     12  * notice, this list of conditions and the following disclaimer in the
     13  * documentation and/or other materials provided with the distribution.
     14  *
     15  * - Neither the name of the Xiph.org Foundation nor the names of its
     16  * contributors may be used to endorse or promote products derived from
     17  * this software without specific prior written permission.
     18  *
     19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
     20  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
     21  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
     22  * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
     23  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
     24  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
     25  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
     26  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
     27  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
     28  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
     29  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     30  */
     31 
     32 #ifndef FLAC__METADATA_H
     33 #define FLAC__METADATA_H
     34 
     35 #include "export.h"
     36 #include "callback.h"
     37 #include "format.h"
     38 
     39 /******************************************************************************
     40 	(For an example of how all these routines are used, see the source
     41 	code for the unit tests in src/test_libFLAC/metadata_*.c, or metaflac
     42 	in src/metaflac/)
     43 ******************************************************************************/
     44 
     45 /** \file include/FLAC/metadata.h
     46  *
     47  *  \brief
     48  *  This module provides functions for creating and manipulating FLAC
     49  *  metadata blocks in memory, and three progressively more powerful
     50  *  interfaces for traversing and editing metadata in FLAC files.
     51  *
     52  *  See the detailed documentation for each interface in the
     53  *  \link flac_metadata metadata \endlink module.
     54  */
     55 
     56 /** \defgroup flac_metadata FLAC/metadata.h: metadata interfaces
     57  *  \ingroup flac
     58  *
     59  *  \brief
     60  *  This module provides functions for creating and manipulating FLAC
     61  *  metadata blocks in memory, and three progressively more powerful
     62  *  interfaces for traversing and editing metadata in FLAC files.
     63  *
     64  *  There are three metadata interfaces of increasing complexity:
     65  *
     66  *  Level 0:
     67  *  Read-only access to the STREAMINFO and VORBIS_COMMENT blocks.
     68  *
     69  *  Level 1:
     70  *  Read-write access to all metadata blocks.  This level is write-
     71  *  efficient in most cases (more on this below), and uses less memory
     72  *  than level 2.
     73  *
     74  *  Level 2:
     75  *  Read-write access to all metadata blocks.  This level is write-
     76  *  efficient in all cases, but uses more memory since all metadata for
     77  *  the whole file is read into memory and manipulated before writing
     78  *  out again.
     79  *
     80  *  What do we mean by efficient?  Since FLAC metadata appears at the
     81  *  beginning of the file, when writing metadata back to a FLAC file
     82  *  it is possible to grow or shrink the metadata such that the entire
     83  *  file must be rewritten.  However, if the size remains the same during
     84  *  changes or PADDING blocks are utilized, only the metadata needs to be
     85  *  overwritten, which is much faster.
     86  *
     87  *  Efficient means the whole file is rewritten at most one time, and only
     88  *  when necessary.  Level 1 is not efficient only in the case that you
     89  *  cause more than one metadata block to grow or shrink beyond what can
     90  *  be accomodated by padding.  In this case you should probably use level
     91  *  2, which allows you to edit all the metadata for a file in memory and
     92  *  write it out all at once.
     93  *
     94  *  All levels know how to skip over and not disturb an ID3v2 tag at the
     95  *  front of the file.
     96  *
     97  *  All levels access files via their filenames.  In addition, level 2
     98  *  has additional alternative read and write functions that take an I/O
     99  *  handle and callbacks, for times when access by filename is not possible.
    100  *
    101  *  In addition to the three interfaces, this module defines functions for
    102  *  creating and manipulating various metadata objects in memory.  As we see
    103  *  from the Format module, FLAC metadata blocks in memory are very primitive
    104  *  structures for storing information in an efficient way.  Reading
    105  *  information from the structures is easy but creating or modifying them
    106  *  directly is more complex.  The metadata object routines here facilitate
    107  *  this by taking care of the consistency and memory management drudgery.
    108  *
    109  *  Unless you will be using the level 1 or 2 interfaces to modify existing
    110  *  metadata however, you will not probably not need these.
    111  *
    112  *  From a dependency standpoint, none of the encoders or decoders require
    113  *  the metadata module.  This is so that embedded users can strip out the
    114  *  metadata module from libFLAC to reduce the size and complexity.
    115  */
    116 
    117 #ifdef __cplusplus
    118 extern "C" {
    119 #endif
    120 
    121 
    122 /** \defgroup flac_metadata_level0 FLAC/metadata.h: metadata level 0 interface
    123  *  \ingroup flac_metadata
    124  *
    125  *  \brief
    126  *  The level 0 interface consists of individual routines to read the
    127  *  STREAMINFO and VORBIS_COMMENT blocks, requiring only a filename.
    128  *
    129  *  It skips any ID3v2 tag at the head of the file.
    130  *
    131  * \{
    132  */
    133 
    134 /** Read the STREAMINFO metadata block of the given FLAC file.  This function
    135  *  will skip any ID3v2 tag at the head of the file.
    136  *
    137  * \param filename    The path to the FLAC file to read.
    138  * \param streaminfo  A pointer to space for the STREAMINFO block.  Since
    139  *                    FLAC__StreamMetadata is a simple structure with no
    140  *                    memory allocation involved, you pass the address of
    141  *                    an existing structure.  It need not be initialized.
    142  * \assert
    143  *    \code filename != NULL \endcode
    144  *    \code streaminfo != NULL \endcode
    145  * \retval FLAC__bool
    146  *    \c true if a valid STREAMINFO block was read from \a filename.  Returns
    147  *    \c false if there was a memory allocation error, a file decoder error,
    148  *    or the file contained no STREAMINFO block.  (A memory allocation error
    149  *    is possible because this function must set up a file decoder.)
    150  */
    151 FLAC_API FLAC__bool FLAC__metadata_get_streaminfo(const char *filename, FLAC__StreamMetadata *streaminfo);
    152 
    153 /** Read the VORBIS_COMMENT metadata block of the given FLAC file.  This
    154  *  function will skip any ID3v2 tag at the head of the file.
    155  *
    156  * \param filename    The path to the FLAC file to read.
    157  * \param tags        The address where the returned pointer will be
    158  *                    stored.  The \a tags object must be deleted by
    159  *                    the caller using FLAC__metadata_object_delete().
    160  * \assert
    161  *    \code filename != NULL \endcode
    162  *    \code streaminfo != NULL \endcode
    163  * \retval FLAC__bool
    164  *    \c true if a valid VORBIS_COMMENT block was read from \a filename,
    165  *    and \a *tags will be set to the address of the tag structure.
    166  *    Returns \c false if there was a memory allocation error, a file
    167  *    decoder error, or the file contained no VORBIS_COMMENT block, and
    168  *    \a *tags will be set to \c NULL.
    169  */
    170 FLAC_API FLAC__bool FLAC__metadata_get_tags(const char *filename, FLAC__StreamMetadata **tags);
    171 
    172 /* \} */
    173 
    174 
    175 /** \defgroup flac_metadata_level1 FLAC/metadata.h: metadata level 1 interface
    176  *  \ingroup flac_metadata
    177  *
    178  * \brief
    179  * The level 1 interface provides read-write access to FLAC file metadata and
    180  * operates directly on the FLAC file.
    181  *
    182  * The general usage of this interface is:
    183  *
    184  * - Create an iterator using FLAC__metadata_simple_iterator_new()
    185  * - Attach it to a file using FLAC__metadata_simple_iterator_init() and check
    186  *   the exit code.  Call FLAC__metadata_simple_iterator_is_writable() to
    187  *   see if the file is writable, or read-only access is allowed.
    188  * - Use FLAC__metadata_simple_iterator_next() and
    189  *   FLAC__metadata_simple_iterator_prev() to move around the blocks.
    190  *   This is does not read the actual blocks themselves.
    191  *   FLAC__metadata_simple_iterator_next() is relatively fast.
    192  *   FLAC__metadata_simple_iterator_prev() is slower since it needs to search
    193  *   forward from the front of the file.
    194  * - Use FLAC__metadata_simple_iterator_get_block_type() or
    195  *   FLAC__metadata_simple_iterator_get_block() to access the actual data at
    196  *   the current iterator position.  The returned object is yours to modify
    197  *   and free.
    198  * - Use FLAC__metadata_simple_iterator_set_block() to write a modified block
    199  *   back.  You must have write permission to the original file.  Make sure to
    200  *   read the whole comment to FLAC__metadata_simple_iterator_set_block()
    201  *   below.
    202  * - Use FLAC__metadata_simple_iterator_insert_block_after() to add new blocks.
    203  *   Use the object creation functions from
    204  *   \link flac_metadata_object here \endlink to generate new objects.
    205  * - Use FLAC__metadata_simple_iterator_delete_block() to remove the block
    206  *   currently referred to by the iterator, or replace it with padding.
    207  * - Destroy the iterator with FLAC__metadata_simple_iterator_delete() when
    208  *   finished.
    209  *
    210  * \note
    211  * The FLAC file remains open the whole time between
    212  * FLAC__metadata_simple_iterator_init() and
    213  * FLAC__metadata_simple_iterator_delete(), so make sure you are not altering
    214  * the file during this time.
    215  *
    216  * \note
    217  * Do not modify the \a is_last, \a length, or \a type fields of returned
    218  * FLAC__StreamMetadata objects.  These are managed automatically.
    219  *
    220  * \note
    221  * If any of the modification functions
    222  * (FLAC__metadata_simple_iterator_set_block(),
    223  * FLAC__metadata_simple_iterator_delete_block(),
    224  * FLAC__metadata_simple_iterator_insert_block_after(), etc.) return \c false,
    225  * you should delete the iterator as it may no longer be valid.
    226  *
    227  * \{
    228  */
    229 
    230 struct FLAC__Metadata_SimpleIterator;
    231 /** The opaque structure definition for the level 1 iterator type.
    232  *  See the
    233  *  \link flac_metadata_level1 metadata level 1 module \endlink
    234  *  for a detailed description.
    235  */
    236 typedef struct FLAC__Metadata_SimpleIterator FLAC__Metadata_SimpleIterator;
    237 
    238 /** Status type for FLAC__Metadata_SimpleIterator.
    239  *
    240  *  The iterator's current status can be obtained by calling FLAC__metadata_simple_iterator_status().
    241  */
    242 typedef enum {
    243 
    244 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK = 0,
    245 	/**< The iterator is in the normal OK state */
    246 
    247 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT,
    248 	/**< The data passed into a function violated the function's usage criteria */
    249 
    250 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ERROR_OPENING_FILE,
    251 	/**< The iterator could not open the target file */
    252 
    253 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_A_FLAC_FILE,
    254 	/**< The iterator could not find the FLAC signature at the start of the file */
    255 
    256 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_WRITABLE,
    257 	/**< The iterator tried to write to a file that was not writable */
    258 
    259 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_BAD_METADATA,
    260 	/**< The iterator encountered input that does not conform to the FLAC metadata specification */
    261 
    262 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_READ_ERROR,
    263 	/**< The iterator encountered an error while reading the FLAC file */
    264 
    265 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_SEEK_ERROR,
    266 	/**< The iterator encountered an error while seeking in the FLAC file */
    267 
    268 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_WRITE_ERROR,
    269 	/**< The iterator encountered an error while writing the FLAC file */
    270 
    271 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_RENAME_ERROR,
    272 	/**< The iterator encountered an error renaming the FLAC file */
    273 
    274 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_UNLINK_ERROR,
    275 	/**< The iterator encountered an error removing the temporary file */
    276 
    277 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_MEMORY_ALLOCATION_ERROR,
    278 	/**< Memory allocation failed */
    279 
    280 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_INTERNAL_ERROR
    281 	/**< The caller violated an assertion or an unexpected error occurred */
    282 
    283 } FLAC__Metadata_SimpleIteratorStatus;
    284 
    285 /** Maps a FLAC__Metadata_SimpleIteratorStatus to a C string.
    286  *
    287  *  Using a FLAC__Metadata_SimpleIteratorStatus as the index to this array
    288  *  will give the string equivalent.  The contents should not be modified.
    289  */
    290 extern FLAC_API const char * const FLAC__Metadata_SimpleIteratorStatusString[];
    291 
    292 
    293 /** Create a new iterator instance.
    294  *
    295  * \retval FLAC__Metadata_SimpleIterator*
    296  *    \c NULL if there was an error allocating memory, else the new instance.
    297  */
    298 FLAC_API FLAC__Metadata_SimpleIterator *FLAC__metadata_simple_iterator_new();
    299 
    300 /** Free an iterator instance.  Deletes the object pointed to by \a iterator.
    301  *
    302  * \param iterator  A pointer to an existing iterator.
    303  * \assert
    304  *    \code iterator != NULL \endcode
    305  */
    306 FLAC_API void FLAC__metadata_simple_iterator_delete(FLAC__Metadata_SimpleIterator *iterator);
    307 
    308 /** Get the current status of the iterator.  Call this after a function
    309  *  returns \c false to get the reason for the error.  Also resets the status
    310  *  to FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK.
    311  *
    312  * \param iterator  A pointer to an existing iterator.
    313  * \assert
    314  *    \code iterator != NULL \endcode
    315  * \retval FLAC__Metadata_SimpleIteratorStatus
    316  *    The current status of the iterator.
    317  */
    318 FLAC_API FLAC__Metadata_SimpleIteratorStatus FLAC__metadata_simple_iterator_status(FLAC__Metadata_SimpleIterator *iterator);
    319 
    320 /** Initialize the iterator to point to the first metadata block in the
    321  *  given FLAC file.
    322  *
    323  * \param iterator             A pointer to an existing iterator.
    324  * \param filename             The path to the FLAC file.
    325  * \param read_only            If \c true, the FLAC file will be opened
    326  *                             in read-only mode; if \c false, the FLAC
    327  *                             file will be opened for edit even if no
    328  *                             edits are performed.
    329  * \param preserve_file_stats  If \c true, the owner and modification
    330  *                             time will be preserved even if the FLAC
    331  *                             file is written to.
    332  * \assert
    333  *    \code iterator != NULL \endcode
    334  *    \code filename != NULL \endcode
    335  * \retval FLAC__bool
    336  *    \c false if a memory allocation error occurs, the file can't be
    337  *    opened, or another error occurs, else \c true.
    338  */
    339 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_init(FLAC__Metadata_SimpleIterator *iterator, const char *filename, FLAC__bool read_only, FLAC__bool preserve_file_stats);
    340 
    341 /** Returns \c true if the FLAC file is writable.  If \c false, calls to
    342  *  FLAC__metadata_simple_iterator_set_block() and
    343  *  FLAC__metadata_simple_iterator_insert_block_after() will fail.
    344  *
    345  * \param iterator             A pointer to an existing iterator.
    346  * \assert
    347  *    \code iterator != NULL \endcode
    348  * \retval FLAC__bool
    349  *    See above.
    350  */
    351 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_writable(const FLAC__Metadata_SimpleIterator *iterator);
    352 
    353 /** Moves the iterator forward one metadata block, returning \c false if
    354  *  already at the end.
    355  *
    356  * \param iterator  A pointer to an existing initialized iterator.
    357  * \assert
    358  *    \code iterator != NULL \endcode
    359  *    \a iterator has been successfully initialized with
    360  *    FLAC__metadata_simple_iterator_init()
    361  * \retval FLAC__bool
    362  *    \c false if already at the last metadata block of the chain, else
    363  *    \c true.
    364  */
    365 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_next(FLAC__Metadata_SimpleIterator *iterator);
    366 
    367 /** Moves the iterator backward one metadata block, returning \c false if
    368  *  already at the beginning.
    369  *
    370  * \param iterator  A pointer to an existing initialized iterator.
    371  * \assert
    372  *    \code iterator != NULL \endcode
    373  *    \a iterator has been successfully initialized with
    374  *    FLAC__metadata_simple_iterator_init()
    375  * \retval FLAC__bool
    376  *    \c false if already at the first metadata block of the chain, else
    377  *    \c true.
    378  */
    379 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_prev(FLAC__Metadata_SimpleIterator *iterator);
    380 
    381 /** Get the type of the metadata block at the current position.  This
    382  *  avoids reading the actual block data which can save time for large
    383  *  blocks.
    384  *
    385  * \param iterator  A pointer to an existing initialized iterator.
    386  * \assert
    387  *    \code iterator != NULL \endcode
    388  *    \a iterator has been successfully initialized with
    389  *    FLAC__metadata_simple_iterator_init()
    390  * \retval FLAC__MetadataType
    391  *    The type of the metadata block at the current iterator position.
    392  */
    393 
    394 FLAC_API FLAC__MetadataType FLAC__metadata_simple_iterator_get_block_type(const FLAC__Metadata_SimpleIterator *iterator);
    395 
    396 /** Get the metadata block at the current position.  You can modify the
    397  *  block but must use FLAC__metadata_simple_iterator_set_block() to
    398  *  write it back to the FLAC file.
    399  *
    400  *  You must call FLAC__metadata_object_delete() on the returned object
    401  *  when you are finished with it.
    402  *
    403  * \param iterator  A pointer to an existing initialized iterator.
    404  * \assert
    405  *    \code iterator != NULL \endcode
    406  *    \a iterator has been successfully initialized with
    407  *    FLAC__metadata_simple_iterator_init()
    408  * \retval FLAC__StreamMetadata*
    409  *    The current metadata block.
    410  */
    411 FLAC_API FLAC__StreamMetadata *FLAC__metadata_simple_iterator_get_block(FLAC__Metadata_SimpleIterator *iterator);
    412 
    413 /** Write a block back to the FLAC file.  This function tries to be
    414  *  as efficient as possible; how the block is actually written is
    415  *  shown by the following:
    416  *
    417  *  Existing block is a STREAMINFO block and the new block is a
    418  *  STREAMINFO block: the new block is written in place.  Make sure
    419  *  you know what you're doing when changing the values of a
    420  *  STREAMINFO block.
    421  *
    422  *  Existing block is a STREAMINFO block and the new block is a
    423  *  not a STREAMINFO block: this is an error since the first block
    424  *  must be a STREAMINFO block.  Returns \c false without altering the
    425  *  file.
    426  *
    427  *  Existing block is not a STREAMINFO block and the new block is a
    428  *  STREAMINFO block: this is an error since there may be only one
    429  *  STREAMINFO block.  Returns \c false without altering the file.
    430  *
    431  *  Existing block and new block are the same length: the existing
    432  *  block will be replaced by the new block, written in place.
    433  *
    434  *  Existing block is longer than new block: if use_padding is \c true,
    435  *  the existing block will be overwritten in place with the new
    436  *  block followed by a PADDING block, if possible, to make the total
    437  *  size the same as the existing block.  Remember that a padding
    438  *  block requires at least four bytes so if the difference in size
    439  *  between the new block and existing block is less than that, the
    440  *  entire file will have to be rewritten, using the new block's
    441  *  exact size.  If use_padding is \c false, the entire file will be
    442  *  rewritten, replacing the existing block by the new block.
    443  *
    444  *  Existing block is shorter than new block: if use_padding is \c true,
    445  *  the function will try and expand the new block into the following
    446  *  PADDING block, if it exists and doing so won't shrink the PADDING
    447  *  block to less than 4 bytes.  If there is no following PADDING
    448  *  block, or it will shrink to less than 4 bytes, or use_padding is
    449  *  \c false, the entire file is rewritten, replacing the existing block
    450  *  with the new block.  Note that in this case any following PADDING
    451  *  block is preserved as is.
    452  *
    453  *  After writing the block, the iterator will remain in the same
    454  *  place, i.e. pointing to the new block.
    455  *
    456  * \param iterator     A pointer to an existing initialized iterator.
    457  * \param block        The block to set.
    458  * \param use_padding  See above.
    459  * \assert
    460  *    \code iterator != NULL \endcode
    461  *    \a iterator has been successfully initialized with
    462  *    FLAC__metadata_simple_iterator_init()
    463  *    \code block != NULL \endcode
    464  * \retval FLAC__bool
    465  *    \c true if successful, else \c false.
    466  */
    467 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_set_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding);
    468 
    469 /** This is similar to FLAC__metadata_simple_iterator_set_block()
    470  *  except that instead of writing over an existing block, it appends
    471  *  a block after the existing block.  \a use_padding is again used to
    472  *  tell the function to try an expand into following padding in an
    473  *  attempt to avoid rewriting the entire file.
    474  *
    475  *  This function will fail and return \c false if given a STREAMINFO
    476  *  block.
    477  *
    478  *  After writing the block, the iterator will be pointing to the
    479  *  new block.
    480  *
    481  * \param iterator     A pointer to an existing initialized iterator.
    482  * \param block        The block to set.
    483  * \param use_padding  See above.
    484  * \assert
    485  *    \code iterator != NULL \endcode
    486  *    \a iterator has been successfully initialized with
    487  *    FLAC__metadata_simple_iterator_init()
    488  *    \code block != NULL \endcode
    489  * \retval FLAC__bool
    490  *    \c true if successful, else \c false.
    491  */
    492 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_insert_block_after(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding);
    493 
    494 /** Deletes the block at the current position.  This will cause the
    495  *  entire FLAC file to be rewritten, unless \a use_padding is \c true,
    496  *  in which case the block will be replaced by an equal-sized PADDING
    497  *  block.  The iterator will be left pointing to the block before the
    498  *  one just deleted.
    499  *
    500  *  You may not delete the STREAMINFO block.
    501  *
    502  * \param iterator     A pointer to an existing initialized iterator.
    503  * \param use_padding  See above.
    504  * \assert
    505  *    \code iterator != NULL \endcode
    506  *    \a iterator has been successfully initialized with
    507  *    FLAC__metadata_simple_iterator_init()
    508  * \retval FLAC__bool
    509  *    \c true if successful, else \c false.
    510  */
    511 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_delete_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__bool use_padding);
    512 
    513 /* \} */
    514 
    515 
    516 /** \defgroup flac_metadata_level2 FLAC/metadata.h: metadata level 2 interface
    517  *  \ingroup flac_metadata
    518  *
    519  * \brief
    520  * The level 2 interface provides read-write access to FLAC file metadata;
    521  * all metadata is read into memory, operated on in memory, and then written
    522  * to file, which is more efficient than level 1 when editing multiple blocks.
    523  *
    524  * The general usage of this interface is:
    525  *
    526  * - Create a new chain using FLAC__metadata_chain_new().  A chain is a
    527  *   linked list of FLAC metadata blocks.
    528  * - Read all metadata into the the chain from a FLAC file using
    529  *   FLAC__metadata_chain_read() and check the status.
    530  * - Optionally, consolidate the padding using
    531  *   FLAC__metadata_chain_merge_padding() or
    532  *   FLAC__metadata_chain_sort_padding().
    533  * - Create a new iterator using FLAC__metadata_iterator_new()
    534  * - Initialize the iterator to point to the first element in the chain
    535  *   using FLAC__metadata_iterator_init()
    536  * - Traverse the chain using FLAC__metadata_iterator_next and
    537  *   FLAC__metadata_iterator_prev().
    538  * - Get a block for reading or modification using
    539  *   FLAC__metadata_iterator_get_block().  The pointer to the object
    540  *   inside the chain is returned, so the block is yours to modify.
    541  *   Changes will be reflected in the FLAC file when you write the
    542  *   chain.  You can also add and delete blocks (see functions below).
    543  * - When done, write out the chain using FLAC__metadata_chain_write().
    544  *   Make sure to read the whole comment to the function below.
    545  * - Delete the chain using FLAC__metadata_chain_delete().
    546  *
    547  * \note
    548  * Even though the FLAC file is not open while the chain is being
    549  * manipulated, you must not alter the file externally during
    550  * this time.  The chain assumes the FLAC file will not change
    551  * between the time of FLAC__metadata_chain_read() and
    552  * FLAC__metadata_chain_write().
    553  *
    554  * \note
    555  * Do not modify the is_last, length, or type fields of returned
    556  * FLAC__StreamMetadata objects.  These are managed automatically.
    557  *
    558  * \note
    559  * The metadata objects returned by FLAC__metadata_iterator_get_block()
    560  * are owned by the chain; do not FLAC__metadata_object_delete() them.
    561  * In the same way, blocks passed to FLAC__metadata_iterator_set_block()
    562  * become owned by the chain and they will be deleted when the chain is
    563  * deleted.
    564  *
    565  * \{
    566  */
    567 
    568 struct FLAC__Metadata_Chain;
    569 /** The opaque structure definition for the level 2 chain type.
    570  */
    571 typedef struct FLAC__Metadata_Chain FLAC__Metadata_Chain;
    572 
    573 struct FLAC__Metadata_Iterator;
    574 /** The opaque structure definition for the level 2 iterator type.
    575  */
    576 typedef struct FLAC__Metadata_Iterator FLAC__Metadata_Iterator;
    577 
    578 typedef enum {
    579 	FLAC__METADATA_CHAIN_STATUS_OK = 0,
    580 	/**< The chain is in the normal OK state */
    581 
    582 	FLAC__METADATA_CHAIN_STATUS_ILLEGAL_INPUT,
    583 	/**< The data passed into a function violated the function's usage criteria */
    584 
    585 	FLAC__METADATA_CHAIN_STATUS_ERROR_OPENING_FILE,
    586 	/**< The chain could not open the target file */
    587 
    588 	FLAC__METADATA_CHAIN_STATUS_NOT_A_FLAC_FILE,
    589 	/**< The chain could not find the FLAC signature at the start of the file */
    590 
    591 	FLAC__METADATA_CHAIN_STATUS_NOT_WRITABLE,
    592 	/**< The chain tried to write to a file that was not writable */
    593 
    594 	FLAC__METADATA_CHAIN_STATUS_BAD_METADATA,
    595 	/**< The chain encountered input that does not conform to the FLAC metadata specification */
    596 
    597 	FLAC__METADATA_CHAIN_STATUS_READ_ERROR,
    598 	/**< The chain encountered an error while reading the FLAC file */
    599 
    600 	FLAC__METADATA_CHAIN_STATUS_SEEK_ERROR,
    601 	/**< The chain encountered an error while seeking in the FLAC file */
    602 
    603 	FLAC__METADATA_CHAIN_STATUS_WRITE_ERROR,
    604 	/**< The chain encountered an error while writing the FLAC file */
    605 
    606 	FLAC__METADATA_CHAIN_STATUS_RENAME_ERROR,
    607 	/**< The chain encountered an error renaming the FLAC file */
    608 
    609 	FLAC__METADATA_CHAIN_STATUS_UNLINK_ERROR,
    610 	/**< The chain encountered an error removing the temporary file */
    611 
    612 	FLAC__METADATA_CHAIN_STATUS_MEMORY_ALLOCATION_ERROR,
    613 	/**< Memory allocation failed */
    614 
    615 	FLAC__METADATA_CHAIN_STATUS_INTERNAL_ERROR,
    616 	/**< The caller violated an assertion or an unexpected error occurred */
    617 
    618 	FLAC__METADATA_CHAIN_STATUS_INVALID_CALLBACKS,
    619 	/**< One or more of the required callbacks was NULL */
    620 
    621 	FLAC__METADATA_CHAIN_STATUS_READ_WRITE_MISMATCH,
    622 	/**< FLAC__metadata_chain_write() was called on a chain read by
    623 	 *   FLAC__metadata_chain_read_with_callbacks(), or
    624 	 *   FLAC__metadata_chain_write_with_callbacks() or
    625 	 *   FLAC__metadata_chain_write_with_callbacks_and_tempfile() was
    626 	 *   called on a chain read by FLAC__metadata_chain_read().  Matching
    627 	 *   read/write methods must always be used. */
    628 
    629 	FLAC__METADATA_CHAIN_STATUS_WRONG_WRITE_CALL
    630 	/**< FLAC__metadata_chain_write_with_callbacks() was called when the
    631 	 *   chain write requires a tempfile; use
    632 	 *   FLAC__metadata_chain_write_with_callbacks_and_tempfile() instead.
    633 	 *   Or, FLAC__metadata_chain_write_with_callbacks_and_tempfile() was
    634 	 *   called when the chain write does not require a tempfile; use
    635 	 *   FLAC__metadata_chain_write_with_callbacks() instead.
    636 	 *   Always check FLAC__metadata_chain_check_if_tempfile_needed()
    637 	 *   before writing via callbacks. */
    638 
    639 } FLAC__Metadata_ChainStatus;
    640 
    641 /** Maps a FLAC__Metadata_ChainStatus to a C string.
    642  *
    643  *  Using a FLAC__Metadata_ChainStatus as the index to this array
    644  *  will give the string equivalent.  The contents should not be modified.
    645  */
    646 extern FLAC_API const char * const FLAC__Metadata_ChainStatusString[];
    647 
    648 /*********** FLAC__Metadata_Chain ***********/
    649 
    650 /** Create a new chain instance.
    651  *
    652  * \retval FLAC__Metadata_Chain*
    653  *    \c NULL if there was an error allocating memory, else the new instance.
    654  */
    655 FLAC_API FLAC__Metadata_Chain *FLAC__metadata_chain_new();
    656 
    657 /** Free a chain instance.  Deletes the object pointed to by \a chain.
    658  *
    659  * \param chain  A pointer to an existing chain.
    660  * \assert
    661  *    \code chain != NULL \endcode
    662  */
    663 FLAC_API void FLAC__metadata_chain_delete(FLAC__Metadata_Chain *chain);
    664 
    665 /** Get the current status of the chain.  Call this after a function
    666  *  returns \c false to get the reason for the error.  Also resets the
    667  *  status to FLAC__METADATA_CHAIN_STATUS_OK.
    668  *
    669  * \param chain    A pointer to an existing chain.
    670  * \assert
    671  *    \code chain != NULL \endcode
    672  * \retval FLAC__Metadata_ChainStatus
    673  *    The current status of the chain.
    674  */
    675 FLAC_API FLAC__Metadata_ChainStatus FLAC__metadata_chain_status(FLAC__Metadata_Chain *chain);
    676 
    677 /** Read all metadata from a FLAC file into the chain.
    678  *
    679  * \param chain    A pointer to an existing chain.
    680  * \param filename The path to the FLAC file to read.
    681  * \assert
    682  *    \code chain != NULL \endcode
    683  *    \code filename != NULL \endcode
    684  * \retval FLAC__bool
    685  *    \c true if a valid list of metadata blocks was read from
    686  *    \a filename, else \c false.  On failure, check the status with
    687  *    FLAC__metadata_chain_status().
    688  */
    689 FLAC_API FLAC__bool FLAC__metadata_chain_read(FLAC__Metadata_Chain *chain, const char *filename);
    690 
    691 /** Read all metadata from a FLAC stream into the chain via I/O callbacks.
    692  *
    693  *  The \a handle need only be open for reading, but must be seekable.
    694  *  The equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb"
    695  *  for Windows).
    696  *
    697  * \param chain    A pointer to an existing chain.
    698  * \param handle   The I/O handle of the FLAC stream to read.  The
    699  *                 handle will NOT be closed after the metadata is read;
    700  *                 that is the duty of the caller.
    701  * \param callbacks
    702  *                 A set of callbacks to use for I/O.  The mandatory
    703  *                 callbacks are \a read, \a seek, and \a tell.
    704  * \assert
    705  *    \code chain != NULL \endcode
    706  * \retval FLAC__bool
    707  *    \c true if a valid list of metadata blocks was read from
    708  *    \a handle, else \c false.  On failure, check the status with
    709  *    FLAC__metadata_chain_status().
    710  */
    711 FLAC_API FLAC__bool FLAC__metadata_chain_read_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
    712 
    713 /** Checks if writing the given chain would require the use of a
    714  *  temporary file, or if it could be written in place.
    715  *
    716  *  Under certain conditions, padding can be utilized so that writing
    717  *  edited metadata back to the FLAC file does not require rewriting the
    718  *  entire file.  If rewriting is required, then a temporary workfile is
    719  *  required.  When writing metadata using callbacks, you must check
    720  *  this function to know whether to call
    721  *  FLAC__metadata_chain_write_with_callbacks() or
    722  *  FLAC__metadata_chain_write_with_callbacks_and_tempfile().  When
    723  *  writing with FLAC__metadata_chain_write(), the temporary file is
    724  *  handled internally.
    725  *
    726  * \param chain    A pointer to an existing chain.
    727  * \param use_padding
    728  *                 Whether or not padding will be allowed to be used
    729  *                 during the write.  The value of \a use_padding given
    730  *                 here must match the value later passed to
    731  *                 FLAC__metadata_chain_write_with_callbacks() or
    732  *                 FLAC__metadata_chain_write_with_callbacks_with_tempfile().
    733  * \assert
    734  *    \code chain != NULL \endcode
    735  * \retval FLAC__bool
    736  *    \c true if writing the current chain would require a tempfile, or
    737  *    \c false if metadata can be written in place.
    738  */
    739 FLAC_API FLAC__bool FLAC__metadata_chain_check_if_tempfile_needed(FLAC__Metadata_Chain *chain, FLAC__bool use_padding);
    740 
    741 /** Write all metadata out to the FLAC file.  This function tries to be as
    742  *  efficient as possible; how the metadata is actually written is shown by
    743  *  the following:
    744  *
    745  *  If the current chain is the same size as the existing metadata, the new
    746  *  data is written in place.
    747  *
    748  *  If the current chain is longer than the existing metadata, and
    749  *  \a use_padding is \c true, and the last block is a PADDING block of
    750  *  sufficient length, the function will truncate the final padding block
    751  *  so that the overall size of the metadata is the same as the existing
    752  *  metadata, and then just rewrite the metadata.  Otherwise, if not all of
    753  *  the above conditions are met, the entire FLAC file must be rewritten.
    754  *  If you want to use padding this way it is a good idea to call
    755  *  FLAC__metadata_chain_sort_padding() first so that you have the maximum
    756  *  amount of padding to work with, unless you need to preserve ordering
    757  *  of the PADDING blocks for some reason.
    758  *
    759  *  If the current chain is shorter than the existing metadata, and
    760  *  \a use_padding is \c true, and the final block is a PADDING block, the padding
    761  *  is extended to make the overall size the same as the existing data.  If
    762  *  \a use_padding is \c true and the last block is not a PADDING block, a new
    763  *  PADDING block is added to the end of the new data to make it the same
    764  *  size as the existing data (if possible, see the note to
    765  *  FLAC__metadata_simple_iterator_set_block() about the four byte limit)
    766  *  and the new data is written in place.  If none of the above apply or
    767  *  \a use_padding is \c false, the entire FLAC file is rewritten.
    768  *
    769  *  If \a preserve_file_stats is \c true, the owner and modification time will
    770  *  be preserved even if the FLAC file is written.
    771  *
    772  *  For this write function to be used, the chain must have been read with
    773  *  FLAC__metadata_chain_read(), not FLAC__metadata_chain_read_with_callbacks().
    774  *
    775  * \param chain               A pointer to an existing chain.
    776  * \param use_padding         See above.
    777  * \param preserve_file_stats See above.
    778  * \assert
    779  *    \code chain != NULL \endcode
    780  * \retval FLAC__bool
    781  *    \c true if the write succeeded, else \c false.  On failure,
    782  *    check the status with FLAC__metadata_chain_status().
    783  */
    784 FLAC_API FLAC__bool FLAC__metadata_chain_write(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__bool preserve_file_stats);
    785 
    786 /** Write all metadata out to a FLAC stream via callbacks.
    787  *
    788  *  (See FLAC__metadata_chain_write() for the details on how padding is
    789  *  used to write metadata in place if possible.)
    790  *
    791  *  The \a handle must be open for updating and be seekable.  The
    792  *  equivalent minimum stdio fopen() file mode is \c "r+" (or \c "r+b"
    793  *  for Windows).
    794  *
    795  *  For this write function to be used, the chain must have been read with
    796  *  FLAC__metadata_chain_read_with_callbacks(), not FLAC__metadata_chain_read().
    797  *  Also, FLAC__metadata_chain_check_if_tempfile_needed() must have returned
    798  *  \c false.
    799  *
    800  * \param chain        A pointer to an existing chain.
    801  * \param use_padding  See FLAC__metadata_chain_write()
    802  * \param handle       The I/O handle of the FLAC stream to write.  The
    803  *                     handle will NOT be closed after the metadata is
    804  *                     written; that is the duty of the caller.
    805  * \param callbacks    A set of callbacks to use for I/O.  The mandatory
    806  *                     callbacks are \a write and \a seek.
    807  * \assert
    808  *    \code chain != NULL \endcode
    809  * \retval FLAC__bool
    810  *    \c true if the write succeeded, else \c false.  On failure,
    811  *    check the status with FLAC__metadata_chain_status().
    812  */
    813 FLAC_API FLAC__bool FLAC__metadata_chain_write_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
    814 
    815 /** Write all metadata out to a FLAC stream via callbacks.
    816  *
    817  *  (See FLAC__metadata_chain_write() for the details on how padding is
    818  *  used to write metadata in place if possible.)
    819  *
    820  *  This version of the write-with-callbacks function must be used when
    821  *  FLAC__metadata_chain_check_if_tempfile_needed() returns true.  In
    822  *  this function, you must supply an I/O handle corresponding to the
    823  *  FLAC file to edit, and a temporary handle to which the new FLAC
    824  *  file will be written.  It is the caller's job to move this temporary
    825  *  FLAC file on top of the original FLAC file to complete the metadata
    826  *  edit.
    827  *
    828  *  The \a handle must be open for reading and be seekable.  The
    829  *  equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb"
    830  *  for Windows).
    831  *
    832  *  The \a temp_handle must be open for writing.  The
    833  *  equivalent minimum stdio fopen() file mode is \c "w" (or \c "wb"
    834  *  for Windows).  It should be an empty stream, or at least positioned
    835  *  at the start-of-file (in which case it is the caller's duty to
    836  *  truncate it on return).
    837  *
    838  *  For this write function to be used, the chain must have been read with
    839  *  FLAC__metadata_chain_read_with_callbacks(), not FLAC__metadata_chain_read().
    840  *  Also, FLAC__metadata_chain_check_if_tempfile_needed() must have returned
    841  *  \c true.
    842  *
    843  * \param chain        A pointer to an existing chain.
    844  * \param use_padding  See FLAC__metadata_chain_write()
    845  * \param handle       The I/O handle of the original FLAC stream to read.
    846  *                     The handle will NOT be closed after the metadata is
    847  *                     written; that is the duty of the caller.
    848  * \param callbacks    A set of callbacks to use for I/O on \a handle.
    849  *                     The mandatory callbacks are \a read, \a seek, and
    850  *                     \a eof.
    851  * \param temp_handle  The I/O handle of the FLAC stream to write.  The
    852  *                     handle will NOT be closed after the metadata is
    853  *                     written; that is the duty of the caller.
    854  * \param temp_callbacks
    855  *                     A set of callbacks to use for I/O on temp_handle.
    856  *                     The only mandatory callback is \a write.
    857  * \assert
    858  *    \code chain != NULL \endcode
    859  * \retval FLAC__bool
    860  *    \c true if the write succeeded, else \c false.  On failure,
    861  *    check the status with FLAC__metadata_chain_status().
    862  */
    863 FLAC_API FLAC__bool FLAC__metadata_chain_write_with_callbacks_and_tempfile(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks, FLAC__IOHandle temp_handle, FLAC__IOCallbacks temp_callbacks);
    864 
    865 /** Merge adjacent PADDING blocks into a single block.
    866  *
    867  * \note This function does not write to the FLAC file, it only
    868  * modifies the chain.
    869  *
    870  * \warning Any iterator on the current chain will become invalid after this
    871  * call.  You should delete the iterator and get a new one.
    872  *
    873  * \param chain               A pointer to an existing chain.
    874  * \assert
    875  *    \code chain != NULL \endcode
    876  */
    877 FLAC_API void FLAC__metadata_chain_merge_padding(FLAC__Metadata_Chain *chain);
    878 
    879 /** This function will move all PADDING blocks to the end on the metadata,
    880  *  then merge them into a single block.
    881  *
    882  * \note This function does not write to the FLAC file, it only
    883  * modifies the chain.
    884  *
    885  * \warning Any iterator on the current chain will become invalid after this
    886  * call.  You should delete the iterator and get a new one.
    887  *
    888  * \param chain  A pointer to an existing chain.
    889  * \assert
    890  *    \code chain != NULL \endcode
    891  */
    892 FLAC_API void FLAC__metadata_chain_sort_padding(FLAC__Metadata_Chain *chain);
    893 
    894 
    895 /*********** FLAC__Metadata_Iterator ***********/
    896 
    897 /** Create a new iterator instance.
    898  *
    899  * \retval FLAC__Metadata_Iterator*
    900  *    \c NULL if there was an error allocating memory, else the new instance.
    901  */
    902 FLAC_API FLAC__Metadata_Iterator *FLAC__metadata_iterator_new();
    903 
    904 /** Free an iterator instance.  Deletes the object pointed to by \a iterator.
    905  *
    906  * \param iterator  A pointer to an existing iterator.
    907  * \assert
    908  *    \code iterator != NULL \endcode
    909  */
    910 FLAC_API void FLAC__metadata_iterator_delete(FLAC__Metadata_Iterator *iterator);
    911 
    912 /** Initialize the iterator to point to the first metadata block in the
    913  *  given chain.
    914  *
    915  * \param iterator  A pointer to an existing iterator.
    916  * \param chain     A pointer to an existing and initialized (read) chain.
    917  * \assert
    918  *    \code iterator != NULL \endcode
    919  *    \code chain != NULL \endcode
    920  */
    921 FLAC_API void FLAC__metadata_iterator_init(FLAC__Metadata_Iterator *iterator, FLAC__Metadata_Chain *chain);
    922 
    923 /** Moves the iterator forward one metadata block, returning \c false if
    924  *  already at the end.
    925  *
    926  * \param iterator  A pointer to an existing initialized iterator.
    927  * \assert
    928  *    \code iterator != NULL \endcode
    929  *    \a iterator has been successfully initialized with
    930  *    FLAC__metadata_iterator_init()
    931  * \retval FLAC__bool
    932  *    \c false if already at the last metadata block of the chain, else
    933  *    \c true.
    934  */
    935 FLAC_API FLAC__bool FLAC__metadata_iterator_next(FLAC__Metadata_Iterator *iterator);
    936 
    937 /** Moves the iterator backward one metadata block, returning \c false if
    938  *  already at the beginning.
    939  *
    940  * \param iterator  A pointer to an existing initialized iterator.
    941  * \assert
    942  *    \code iterator != NULL \endcode
    943  *    \a iterator has been successfully initialized with
    944  *    FLAC__metadata_iterator_init()
    945  * \retval FLAC__bool
    946  *    \c false if already at the first metadata block of the chain, else
    947  *    \c true.
    948  */
    949 FLAC_API FLAC__bool FLAC__metadata_iterator_prev(FLAC__Metadata_Iterator *iterator);
    950 
    951 /** Get the type of the metadata block at the current position.
    952  *
    953  * \param iterator  A pointer to an existing initialized iterator.
    954  * \assert
    955  *    \code iterator != NULL \endcode
    956  *    \a iterator has been successfully initialized with
    957  *    FLAC__metadata_iterator_init()
    958  * \retval FLAC__MetadataType
    959  *    The type of the metadata block at the current iterator position.
    960  */
    961 FLAC_API FLAC__MetadataType FLAC__metadata_iterator_get_block_type(const FLAC__Metadata_Iterator *iterator);
    962 
    963 /** Get the metadata block at the current position.  You can modify
    964  *  the block in place but must write the chain before the changes
    965  *  are reflected to the FLAC file.  You do not need to call
    966  *  FLAC__metadata_iterator_set_block() to reflect the changes;
    967  *  the pointer returned by FLAC__metadata_iterator_get_block()
    968  *  points directly into the chain.
    969  *
    970  * \warning
    971  * Do not call FLAC__metadata_object_delete() on the returned object;
    972  * to delete a block use FLAC__metadata_iterator_delete_block().
    973  *
    974  * \param iterator  A pointer to an existing initialized iterator.
    975  * \assert
    976  *    \code iterator != NULL \endcode
    977  *    \a iterator has been successfully initialized with
    978  *    FLAC__metadata_iterator_init()
    979  * \retval FLAC__StreamMetadata*
    980  *    The current metadata block.
    981  */
    982 FLAC_API FLAC__StreamMetadata *FLAC__metadata_iterator_get_block(FLAC__Metadata_Iterator *iterator);
    983 
    984 /** Set the metadata block at the current position, replacing the existing
    985  *  block.  The new block passed in becomes owned by the chain and it will be
    986  *  deleted when the chain is deleted.
    987  *
    988  * \param iterator  A pointer to an existing initialized iterator.
    989  * \param block     A pointer to a metadata block.
    990  * \assert
    991  *    \code iterator != NULL \endcode
    992  *    \a iterator has been successfully initialized with
    993  *    FLAC__metadata_iterator_init()
    994  *    \code block != NULL \endcode
    995  * \retval FLAC__bool
    996  *    \c false if the conditions in the above description are not met, or
    997  *    a memory allocation error occurs, otherwise \c true.
    998  */
    999 FLAC_API FLAC__bool FLAC__metadata_iterator_set_block(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
   1000 
   1001 /** Removes the current block from the chain.  If \a replace_with_padding is
   1002  *  \c true, the block will instead be replaced with a padding block of equal
   1003  *  size.  You can not delete the STREAMINFO block.  The iterator will be
   1004  *  left pointing to the block before the one just "deleted", even if
   1005  *  \a replace_with_padding is \c true.
   1006  *
   1007  * \param iterator              A pointer to an existing initialized iterator.
   1008  * \param replace_with_padding  See above.
   1009  * \assert
   1010  *    \code iterator != NULL \endcode
   1011  *    \a iterator has been successfully initialized with
   1012  *    FLAC__metadata_iterator_init()
   1013  * \retval FLAC__bool
   1014  *    \c false if the conditions in the above description are not met,
   1015  *    otherwise \c true.
   1016  */
   1017 FLAC_API FLAC__bool FLAC__metadata_iterator_delete_block(FLAC__Metadata_Iterator *iterator, FLAC__bool replace_with_padding);
   1018 
   1019 /** Insert a new block before the current block.  You cannot insert a block
   1020  *  before the first STREAMINFO block.  You cannot insert a STREAMINFO block
   1021  *  as there can be only one, the one that already exists at the head when you
   1022  *  read in a chain.  The chain takes ownership of the new block and it will be
   1023  *  deleted when the chain is deleted.  The iterator will be left pointing to
   1024  *  the new block.
   1025  *
   1026  * \param iterator  A pointer to an existing initialized iterator.
   1027  * \param block     A pointer to a metadata block to insert.
   1028  * \assert
   1029  *    \code iterator != NULL \endcode
   1030  *    \a iterator has been successfully initialized with
   1031  *    FLAC__metadata_iterator_init()
   1032  * \retval FLAC__bool
   1033  *    \c false if the conditions in the above description are not met, or
   1034  *    a memory allocation error occurs, otherwise \c true.
   1035  */
   1036 FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_before(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
   1037 
   1038 /** Insert a new block after the current block.  You cannot insert a STREAMINFO
   1039  *  block as there can be only one, the one that already exists at the head when
   1040  *  you read in a chain.  The chain takes ownership of the new block and it will
   1041  *  be deleted when the chain is deleted.  The iterator will be left pointing to
   1042  *  the new block.
   1043  *
   1044  * \param iterator  A pointer to an existing initialized iterator.
   1045  * \param block     A pointer to a metadata block to insert.
   1046  * \assert
   1047  *    \code iterator != NULL \endcode
   1048  *    \a iterator has been successfully initialized with
   1049  *    FLAC__metadata_iterator_init()
   1050  * \retval FLAC__bool
   1051  *    \c false if the conditions in the above description are not met, or
   1052  *    a memory allocation error occurs, otherwise \c true.
   1053  */
   1054 FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_after(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
   1055 
   1056 /* \} */
   1057 
   1058 
   1059 /** \defgroup flac_metadata_object FLAC/metadata.h: metadata object methods
   1060  *  \ingroup flac_metadata
   1061  *
   1062  * \brief
   1063  * This module contains methods for manipulating FLAC metadata objects.
   1064  *
   1065  * Since many are variable length we have to be careful about the memory
   1066  * management.  We decree that all pointers to data in the object are
   1067  * owned by the object and memory-managed by the object.
   1068  *
   1069  * Use the FLAC__metadata_object_new() and FLAC__metadata_object_delete()
   1070  * functions to create all instances.  When using the
   1071  * FLAC__metadata_object_set_*() functions to set pointers to data, set
   1072  * \a copy to \c true to have the function make it's own copy of the data, or
   1073  * to \c false to give the object ownership of your data.  In the latter case
   1074  * your pointer must be freeable by free() and will be free()d when the object
   1075  * is FLAC__metadata_object_delete()d.  It is legal to pass a null pointer as
   1076  * the data pointer to a FLAC__metadata_object_set_*() function as long as
   1077  * the length argument is 0 and the \a copy argument is \c false.
   1078  *
   1079  * The FLAC__metadata_object_new() and FLAC__metadata_object_clone() function
   1080  * will return \c NULL in the case of a memory allocation error, otherwise a new
   1081  * object.  The FLAC__metadata_object_set_*() functions return \c false in the
   1082  * case of a memory allocation error.
   1083  *
   1084  * We don't have the convenience of C++ here, so note that the library relies
   1085  * on you to keep the types straight.  In other words, if you pass, for
   1086  * example, a FLAC__StreamMetadata* that represents a STREAMINFO block to
   1087  * FLAC__metadata_object_application_set_data(), you will get an assertion
   1088  * failure.
   1089  *
   1090  * For convenience the FLAC__metadata_object_vorbiscomment_*() functions
   1091  * maintain a trailing NUL on each Vorbis comment entry.  This is not counted
   1092  * toward the length or stored in the stream, but it can make working with plain
   1093  * comments (those that don't contain embedded-NULs in the value) easier.
   1094  * Entries passed into these functions have trailing NULs added if missing, and
   1095  * returned entries are guaranteed to have a trailing NUL.
   1096  *
   1097  * The FLAC__metadata_object_vorbiscomment_*() functions that take a Vorbis
   1098  * comment entry/name/value will first validate that it complies with the Vorbis
   1099  * comment specification and return false if it does not.
   1100  *
   1101  * There is no need to recalculate the length field on metadata blocks you
   1102  * have modified.  They will be calculated automatically before they  are
   1103  * written back to a file.
   1104  *
   1105  * \{
   1106  */
   1107 
   1108 
   1109 /** Create a new metadata object instance of the given type.
   1110  *
   1111  *  The object will be "empty"; i.e. values and data pointers will be \c 0,
   1112  *  with the exception of FLAC__METADATA_TYPE_VORBIS_COMMENT, which will have
   1113  *  the vendor string set (but zero comments).
   1114  *
   1115  *  Do not pass in a value greater than or equal to
   1116  *  \a FLAC__METADATA_TYPE_UNDEFINED unless you really know what you're
   1117  *  doing.
   1118  *
   1119  * \param type  Type of object to create
   1120  * \retval FLAC__StreamMetadata*
   1121  *    \c NULL if there was an error allocating memory or the type code is
   1122  *    greater than FLAC__MAX_METADATA_TYPE_CODE, else the new instance.
   1123  */
   1124 FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_new(FLAC__MetadataType type);
   1125 
   1126 /** Create a copy of an existing metadata object.
   1127  *
   1128  *  The copy is a "deep" copy, i.e. dynamically allocated data within the
   1129  *  object is also copied.  The caller takes ownership of the new block and
   1130  *  is responsible for freeing it with FLAC__metadata_object_delete().
   1131  *
   1132  * \param object  Pointer to object to copy.
   1133  * \assert
   1134  *    \code object != NULL \endcode
   1135  * \retval FLAC__StreamMetadata*
   1136  *    \c NULL if there was an error allocating memory, else the new instance.
   1137  */
   1138 FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_clone(const FLAC__StreamMetadata *object);
   1139 
   1140 /** Free a metadata object.  Deletes the object pointed to by \a object.
   1141  *
   1142  *  The delete is a "deep" delete, i.e. dynamically allocated data within the
   1143  *  object is also deleted.
   1144  *
   1145  * \param object  A pointer to an existing object.
   1146  * \assert
   1147  *    \code object != NULL \endcode
   1148  */
   1149 FLAC_API void FLAC__metadata_object_delete(FLAC__StreamMetadata *object);
   1150 
   1151 /** Compares two metadata objects.
   1152  *
   1153  *  The compare is "deep", i.e. dynamically allocated data within the
   1154  *  object is also compared.
   1155  *
   1156  * \param block1  A pointer to an existing object.
   1157  * \param block2  A pointer to an existing object.
   1158  * \assert
   1159  *    \code block1 != NULL \endcode
   1160  *    \code block2 != NULL \endcode
   1161  * \retval FLAC__bool
   1162  *    \c true if objects are identical, else \c false.
   1163  */
   1164 FLAC_API FLAC__bool FLAC__metadata_object_is_equal(const FLAC__StreamMetadata *block1, const FLAC__StreamMetadata *block2);
   1165 
   1166 /** Sets the application data of an APPLICATION block.
   1167  *
   1168  *  If \a copy is \c true, a copy of the data is stored; otherwise, the object
   1169  *  takes ownership of the pointer.
   1170  *
   1171  * \param object  A pointer to an existing APPLICATION object.
   1172  * \param data    A pointer to the data to set.
   1173  * \param length  The length of \a data in bytes.
   1174  * \param copy    See above.
   1175  * \assert
   1176  *    \code object != NULL \endcode
   1177  *    \code object->type == FLAC__METADATA_TYPE_APPLICATION \endcode
   1178  *    \code (data != NULL && length > 0) ||
   1179  * (data == NULL && length == 0 && copy == false) \endcode
   1180  * \retval FLAC__bool
   1181  *    \c false if \a copy is \c true and malloc() fails, else \c true.
   1182  */
   1183 FLAC_API FLAC__bool FLAC__metadata_object_application_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, unsigned length, FLAC__bool copy);
   1184 
   1185 /** Resize the seekpoint array.
   1186  *
   1187  *  If the size shrinks, elements will truncated; if it grows, new placeholder
   1188  *  points will be added to the end.
   1189  *
   1190  * \param object          A pointer to an existing SEEKTABLE object.
   1191  * \param new_num_points  The desired length of the array; may be \c 0.
   1192  * \assert
   1193  *    \code object != NULL \endcode
   1194  *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
   1195  *    \code (object->data.seek_table.points == NULL && object->data.seek_table.num_points == 0) ||
   1196  * (object->data.seek_table.points != NULL && object->data.seek_table.num_points > 0) \endcode
   1197  * \retval FLAC__bool
   1198  *    \c false if memory allocation error, else \c true.
   1199  */
   1200 FLAC_API FLAC__bool FLAC__metadata_object_seektable_resize_points(FLAC__StreamMetadata *object, unsigned new_num_points);
   1201 
   1202 /** Set a seekpoint in a seektable.
   1203  *
   1204  * \param object     A pointer to an existing SEEKTABLE object.
   1205  * \param point_num  Index into seekpoint array to set.
   1206  * \param point      The point to set.
   1207  * \assert
   1208  *    \code object != NULL \endcode
   1209  *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
   1210  *    \code object->data.seek_table.num_points > point_num \endcode
   1211  */
   1212 FLAC_API void FLAC__metadata_object_seektable_set_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point);
   1213 
   1214 /** Insert a seekpoint into a seektable.
   1215  *
   1216  * \param object     A pointer to an existing SEEKTABLE object.
   1217  * \param point_num  Index into seekpoint array to set.
   1218  * \param point      The point to set.
   1219  * \assert
   1220  *    \code object != NULL \endcode
   1221  *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
   1222  *    \code object->data.seek_table.num_points >= point_num \endcode
   1223  * \retval FLAC__bool
   1224  *    \c false if memory allocation error, else \c true.
   1225  */
   1226 FLAC_API FLAC__bool FLAC__metadata_object_seektable_insert_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point);
   1227 
   1228 /** Delete a seekpoint from a seektable.
   1229  *
   1230  * \param object     A pointer to an existing SEEKTABLE object.
   1231  * \param point_num  Index into seekpoint array to set.
   1232  * \assert
   1233  *    \code object != NULL \endcode
   1234  *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
   1235  *    \code object->data.seek_table.num_points > point_num \endcode
   1236  * \retval FLAC__bool
   1237  *    \c false if memory allocation error, else \c true.
   1238  */
   1239 FLAC_API FLAC__bool FLAC__metadata_object_seektable_delete_point(FLAC__StreamMetadata *object, unsigned point_num);
   1240 
   1241 /** Check a seektable to see if it conforms to the FLAC specification.
   1242  *  See the format specification for limits on the contents of the
   1243  *  seektable.
   1244  *
   1245  * \param object  A pointer to an existing SEEKTABLE object.
   1246  * \assert
   1247  *    \code object != NULL \endcode
   1248  *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
   1249  * \retval FLAC__bool
   1250  *    \c false if seek table is illegal, else \c true.
   1251  */
   1252 FLAC_API FLAC__bool FLAC__metadata_object_seektable_is_legal(const FLAC__StreamMetadata *object);
   1253 
   1254 /** Append a number of placeholder points to the end of a seek table.
   1255  *
   1256  * \note
   1257  * As with the other ..._seektable_template_... functions, you should
   1258  * call FLAC__metadata_object_seektable_template_sort() when finished
   1259  * to make the seek table legal.
   1260  *
   1261  * \param object  A pointer to an existing SEEKTABLE object.
   1262  * \param num     The number of placeholder points to append.
   1263  * \assert
   1264  *    \code object != NULL \endcode
   1265  *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
   1266  * \retval FLAC__bool
   1267  *    \c false if memory allocation fails, else \c true.
   1268  */
   1269 FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_placeholders(FLAC__StreamMetadata *object, unsigned num);
   1270 
   1271 /** Append a specific seek point template to the end of a seek table.
   1272  *
   1273  * \note
   1274  * As with the other ..._seektable_template_... functions, you should
   1275  * call FLAC__metadata_object_seektable_template_sort() when finished
   1276  * to make the seek table legal.
   1277  *
   1278  * \param object  A pointer to an existing SEEKTABLE object.
   1279  * \param sample_number  The sample number of the seek point template.
   1280  * \assert
   1281  *    \code object != NULL \endcode
   1282  *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
   1283  * \retval FLAC__bool
   1284  *    \c false if memory allocation fails, else \c true.
   1285  */
   1286 FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_point(FLAC__StreamMetadata *object, FLAC__uint64 sample_number);
   1287 
   1288 /** Append specific seek point templates to the end of a seek table.
   1289  *
   1290  * \note
   1291  * As with the other ..._seektable_template_... functions, you should
   1292  * call FLAC__metadata_object_seektable_template_sort() when finished
   1293  * to make the seek table legal.
   1294  *
   1295  * \param object  A pointer to an existing SEEKTABLE object.
   1296  * \param sample_numbers  An array of sample numbers for the seek points.
   1297  * \param num     The number of seek point templates to append.
   1298  * \assert
   1299  *    \code object != NULL \endcode
   1300  *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
   1301  * \retval FLAC__bool
   1302  *    \c false if memory allocation fails, else \c true.
   1303  */
   1304 FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_points(FLAC__StreamMetadata *object, FLAC__uint64 sample_numbers[], unsigned num);
   1305 
   1306 /** Append a set of evenly-spaced seek point templates to the end of a
   1307  *  seek table.
   1308  *
   1309  * \note
   1310  * As with the other ..._seektable_template_... functions, you should
   1311  * call FLAC__metadata_object_seektable_template_sort() when finished
   1312  * to make the seek table legal.
   1313  *
   1314  * \param object  A pointer to an existing SEEKTABLE object.
   1315  * \param num     The number of placeholder points to append.
   1316  * \param total_samples  The total number of samples to be encoded;
   1317  *                       the seekpoints will be spaced approximately
   1318  *                       \a total_samples / \a num samples apart.
   1319  * \assert
   1320  *    \code object != NULL \endcode
   1321  *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
   1322  * \retval FLAC__bool
   1323  *    \c false if memory allocation fails, else \c true.
   1324  */
   1325 FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points(FLAC__StreamMetadata *object, unsigned num, FLAC__uint64 total_samples);
   1326 
   1327 /** Sort a seek table's seek points according to the format specification,
   1328  *  removing duplicates.
   1329  *
   1330  * \param object   A pointer to a seek table to be sorted.
   1331  * \param compact  If \c false, behaves like FLAC__format_seektable_sort().
   1332  *                 If \c true, duplicates are deleted and the seek table is
   1333  *                 shrunk appropriately; the number of placeholder points
   1334  *                 present in the seek table will be the same after the call
   1335  *                 as before.
   1336  * \assert
   1337  *    \code object != NULL \endcode
   1338  *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
   1339  * \retval FLAC__bool
   1340  *    \c false if realloc() fails, else \c true.
   1341  */
   1342 FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_sort(FLAC__StreamMetadata *object, FLAC__bool compact);
   1343 
   1344 /** Sets the vendor string in a VORBIS_COMMENT block.
   1345  *
   1346  *  For convenience, a trailing NUL is added to the entry if it doesn't have
   1347  *  one already.
   1348  *
   1349  *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
   1350  *  takes ownership of the \c entry.entry pointer.
   1351  *
   1352  *  \note If this function returns \c false, the caller still owns the
   1353  *  pointer.
   1354  *
   1355  * \param object  A pointer to an existing VORBIS_COMMENT object.
   1356  * \param entry   The entry to set the vendor string to.
   1357  * \param copy    See above.
   1358  * \assert
   1359  *    \code object != NULL \endcode
   1360  *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
   1361  *    \code (entry.entry != NULL && entry.length > 0) ||
   1362  * (entry.entry == NULL && entry.length == 0) \endcode
   1363  * \retval FLAC__bool
   1364  *    \c false if memory allocation fails or \a entry does not comply with the
   1365  *    Vorbis comment specification, else \c true.
   1366  */
   1367 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_vendor_string(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
   1368 
   1369 /** Resize the comment array.
   1370  *
   1371  *  If the size shrinks, elements will truncated; if it grows, new empty
   1372  *  fields will be added to the end.
   1373  *
   1374  * \param object            A pointer to an existing VORBIS_COMMENT object.
   1375  * \param new_num_comments  The desired length of the array; may be \c 0.
   1376  * \assert
   1377  *    \code object != NULL \endcode
   1378  *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
   1379  *    \code (object->data.vorbis_comment.comments == NULL && object->data.vorbis_comment.num_comments == 0) ||
   1380  * (object->data.vorbis_comment.comments != NULL && object->data.vorbis_comment.num_comments > 0) \endcode
   1381  * \retval FLAC__bool
   1382  *    \c false if memory allocation fails, else \c true.
   1383  */
   1384 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_resize_comments(FLAC__StreamMetadata *object, unsigned new_num_comments);
   1385 
   1386 /** Sets a comment in a VORBIS_COMMENT block.
   1387  *
   1388  *  For convenience, a trailing NUL is added to the entry if it doesn't have
   1389  *  one already.
   1390  *
   1391  *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
   1392  *  takes ownership of the \c entry.entry pointer.
   1393  *
   1394  *  \note If this function returns \c false, the caller still owns the
   1395  *  pointer.
   1396  *
   1397  * \param object       A pointer to an existing VORBIS_COMMENT object.
   1398  * \param comment_num  Index into comment array to set.
   1399  * \param entry        The entry to set the comment to.
   1400  * \param copy         See above.
   1401  * \assert
   1402  *    \code object != NULL \endcode
   1403  *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
   1404  *    \code comment_num < object->data.vorbis_comment.num_comments \endcode
   1405  *    \code (entry.entry != NULL && entry.length > 0) ||
   1406  * (entry.entry == NULL && entry.length == 0) \endcode
   1407  * \retval FLAC__bool
   1408  *    \c false if memory allocation fails or \a entry does not comply with the
   1409  *    Vorbis comment specification, else \c true.
   1410  */
   1411 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
   1412 
   1413 /** Insert a comment in a VORBIS_COMMENT block at the given index.
   1414  *
   1415  *  For convenience, a trailing NUL is added to the entry if it doesn't have
   1416  *  one already.
   1417  *
   1418  *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
   1419  *  takes ownership of the \c entry.entry pointer.
   1420  *
   1421  *  \note If this function returns \c false, the caller still owns the
   1422  *  pointer.
   1423  *
   1424  * \param object       A pointer to an existing VORBIS_COMMENT object.
   1425  * \param comment_num  The index at which to insert the comment.  The comments
   1426  *                     at and after \a comment_num move right one position.
   1427  *                     To append a comment to the end, set \a comment_num to
   1428  *                     \c object->data.vorbis_comment.num_comments .
   1429  * \param entry        The comment to insert.
   1430  * \param copy         See above.
   1431  * \assert
   1432  *    \code object != NULL \endcode
   1433  *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
   1434  *    \code object->data.vorbis_comment.num_comments >= comment_num \endcode
   1435  *    \code (entry.entry != NULL && entry.length > 0) ||
   1436  * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode
   1437  * \retval FLAC__bool
   1438  *    \c false if memory allocation fails or \a entry does not comply with the
   1439  *    Vorbis comment specification, else \c true.
   1440  */
   1441 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_insert_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
   1442 
   1443 /** Appends a comment to a VORBIS_COMMENT block.
   1444  *
   1445  *  For convenience, a trailing NUL is added to the entry if it doesn't have
   1446  *  one already.
   1447  *
   1448  *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
   1449  *  takes ownership of the \c entry.entry pointer.
   1450  *
   1451  *  \note If this function returns \c false, the caller still owns the
   1452  *  pointer.
   1453  *
   1454  * \param object       A pointer to an existing VORBIS_COMMENT object.
   1455  * \param entry        The comment to insert.
   1456  * \param copy         See above.
   1457  * \assert
   1458  *    \code object != NULL \endcode
   1459  *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
   1460  *    \code (entry.entry != NULL && entry.length > 0) ||
   1461  * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode
   1462  * \retval FLAC__bool
   1463  *    \c false if memory allocation fails or \a entry does not comply with the
   1464  *    Vorbis comment specification, else \c true.
   1465  */
   1466 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_append_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
   1467 
   1468 /** Replaces comments in a VORBIS_COMMENT block with a new one.
   1469  *
   1470  *  For convenience, a trailing NUL is added to the entry if it doesn't have
   1471  *  one already.
   1472  *
   1473  *  Depending on the the value of \a all, either all or just the first comment
   1474  *  whose field name(s) match the given entry's name will be replaced by the
   1475  *  given entry.  If no comments match, \a entry will simply be appended.
   1476  *
   1477  *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
   1478  *  takes ownership of the \c entry.entry pointer.
   1479  *
   1480  *  \note If this function returns \c false, the caller still owns the
   1481  *  pointer.
   1482  *
   1483  * \param object       A pointer to an existing VORBIS_COMMENT object.
   1484  * \param entry        The comment to insert.
   1485  * \param all          If \c true, all comments whose field name matches
   1486  *                     \a entry's field name will be removed, and \a entry will
   1487  *                     be inserted at the position of the first matching
   1488  *                     comment.  If \c false, only the first comment whose
   1489  *                     field name matches \a entry's field name will be
   1490  *                     replaced with \a entry.
   1491  * \param copy         See above.
   1492  * \assert
   1493  *    \code object != NULL \endcode
   1494  *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
   1495  *    \code (entry.entry != NULL && entry.length > 0) ||
   1496  * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode
   1497  * \retval FLAC__bool
   1498  *    \c false if memory allocation fails or \a entry does not comply with the
   1499  *    Vorbis comment specification, else \c true.
   1500  */
   1501 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_replace_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool all, FLAC__bool copy);
   1502 
   1503 /** Delete a comment in a VORBIS_COMMENT block at the given index.
   1504  *
   1505  * \param object       A pointer to an existing VORBIS_COMMENT object.
   1506  * \param comment_num  The index of the comment to delete.
   1507  * \assert
   1508  *    \code object != NULL \endcode
   1509  *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
   1510  *    \code object->data.vorbis_comment.num_comments > comment_num \endcode
   1511  * \retval FLAC__bool
   1512  *    \c false if realloc() fails, else \c true.
   1513  */
   1514 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_delete_comment(FLAC__StreamMetadata *object, unsigned comment_num);
   1515 
   1516 /** Creates a Vorbis comment entry from NUL-terminated name and value strings.
   1517  *
   1518  *  On return, the filled-in \a entry->entry pointer will point to malloc()ed
   1519  *  memory and shall be owned by the caller.  For convenience the entry will
   1520  *  have a terminating NUL.
   1521  *
   1522  * \param entry              A pointer to a Vorbis comment entry.  The entry's
   1523  *                           \c entry pointer should not point to allocated
   1524  *                           memory as it will be overwritten.
   1525  * \param field_name         The field name in ASCII, \c NUL terminated.
   1526  * \param field_value        The field value in UTF-8, \c NUL terminated.
   1527  * \assert
   1528  *    \code entry != NULL \endcode
   1529  *    \code field_name != NULL \endcode
   1530  *    \code field_value != NULL \endcode
   1531  * \retval FLAC__bool
   1532  *    \c false if malloc() fails, or if \a field_name or \a field_value does
   1533  *    not comply with the Vorbis comment specification, else \c true.
   1534  */
   1535 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_from_name_value_pair(FLAC__StreamMetadata_VorbisComment_Entry *entry, const char *field_name, const char *field_value);
   1536 
   1537 /** Splits a Vorbis comment entry into NUL-terminated name and value strings.
   1538  *
   1539  *  The returned pointers to name and value will be allocated by malloc()
   1540  *  and shall be owned by the caller.
   1541  *
   1542  * \param entry              An existing Vorbis comment entry.
   1543  * \param field_name         The address of where the returned pointer to the
   1544  *                           field name will be stored.
   1545  * \param field_value        The address of where the returned pointer to the
   1546  *                           field value will be stored.
   1547  * \assert
   1548  *    \code (entry.entry != NULL && entry.length > 0) \endcode
   1549  *    \code memchr(entry.entry, '=', entry.length) != NULL \endcode
   1550  *    \code field_name != NULL \endcode
   1551  *    \code field_value != NULL \endcode
   1552  * \retval FLAC__bool
   1553  *    \c false if memory allocation fails or \a entry does not comply with the
   1554  *    Vorbis comment specification, else \c true.
   1555  */
   1556 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_to_name_value_pair(const FLAC__StreamMetadata_VorbisComment_Entry entry, char **field_name, char **field_value);
   1557 
   1558 /** Check if the given Vorbis comment entry's field name matches the given
   1559  *  field name.
   1560  *
   1561  * \param entry              An existing Vorbis comment entry.
   1562  * \param field_name         The field name to check.
   1563  * \param field_name_length  The length of \a field_name, not including the
   1564  *                           terminating \c NUL.
   1565  * \assert
   1566  *    \code (entry.entry != NULL && entry.length > 0) \endcode
   1567  * \retval FLAC__bool
   1568  *    \c true if the field names match, else \c false
   1569  */
   1570 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_matches(const FLAC__StreamMetadata_VorbisComment_Entry entry, const char *field_name, unsigned field_name_length);
   1571 
   1572 /** Find a Vorbis comment with the given field name.
   1573  *
   1574  *  The search begins at entry number \a offset; use an offset of 0 to
   1575  *  search from the beginning of the comment array.
   1576  *
   1577  * \param object      A pointer to an existing VORBIS_COMMENT object.
   1578  * \param offset      The offset into the comment array from where to start
   1579  *                    the search.
   1580  * \param field_name  The field name of the comment to find.
   1581  * \assert
   1582  *    \code object != NULL \endcode
   1583  *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
   1584  *    \code field_name != NULL \endcode
   1585  * \retval int
   1586  *    The offset in the comment array of the first comment whose field
   1587  *    name matches \a field_name, or \c -1 if no match was found.
   1588  */
   1589 FLAC_API int FLAC__metadata_object_vorbiscomment_find_entry_from(const FLAC__StreamMetadata *object, unsigned offset, const char *field_name);
   1590 
   1591 /** Remove first Vorbis comment matching the given field name.
   1592  *
   1593  * \param object      A pointer to an existing VORBIS_COMMENT object.
   1594  * \param field_name  The field name of comment to delete.
   1595  * \assert
   1596  *    \code object != NULL \endcode
   1597  *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
   1598  * \retval int
   1599  *    \c -1 for memory allocation error, \c 0 for no matching entries,
   1600  *    \c 1 for one matching entry deleted.
   1601  */
   1602 FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entry_matching(FLAC__StreamMetadata *object, const char *field_name);
   1603 
   1604 /** Remove all Vorbis comments matching the given field name.
   1605  *
   1606  * \param object      A pointer to an existing VORBIS_COMMENT object.
   1607  * \param field_name  The field name of comments to delete.
   1608  * \assert
   1609  *    \code object != NULL \endcode
   1610  *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
   1611  * \retval int
   1612  *    \c -1 for memory allocation error, \c 0 for no matching entries,
   1613  *    else the number of matching entries deleted.
   1614  */
   1615 FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entries_matching(FLAC__StreamMetadata *object, const char *field_name);
   1616 
   1617 /** Create a new CUESHEET track instance.
   1618  *
   1619  *  The object will be "empty"; i.e. values and data pointers will be \c 0.
   1620  *
   1621  * \retval FLAC__StreamMetadata_CueSheet_Track*
   1622  *    \c NULL if there was an error allocating memory, else the new instance.
   1623  */
   1624 FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_new();
   1625 
   1626 /** Create a copy of an existing CUESHEET track object.
   1627  *
   1628  *  The copy is a "deep" copy, i.e. dynamically allocated data within the
   1629  *  object is also copied.  The caller takes ownership of the new object and
   1630  *  is responsible for freeing it with
   1631  *  FLAC__metadata_object_cuesheet_track_delete().
   1632  *
   1633  * \param object  Pointer to object to copy.
   1634  * \assert
   1635  *    \code object != NULL \endcode
   1636  * \retval FLAC__StreamMetadata_CueSheet_Track*
   1637  *    \c NULL if there was an error allocating memory, else the new instance.
   1638  */
   1639 FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_clone(const FLAC__StreamMetadata_CueSheet_Track *object);
   1640 
   1641 /** Delete a CUESHEET track object
   1642  *
   1643  * \param object       A pointer to an existing CUESHEET track object.
   1644  * \assert
   1645  *    \code object != NULL \endcode
   1646  */
   1647 FLAC_API void FLAC__metadata_object_cuesheet_track_delete(FLAC__StreamMetadata_CueSheet_Track *object);
   1648 
   1649 /** Resize a track's index point array.
   1650  *
   1651  *  If the size shrinks, elements will truncated; if it grows, new blank
   1652  *  indices will be added to the end.
   1653  *
   1654  * \param object           A pointer to an existing CUESHEET object.
   1655  * \param track_num        The index of the track to modify.  NOTE: this is not
   1656  *                         necessarily the same as the track's \a number field.
   1657  * \param new_num_indices  The desired length of the array; may be \c 0.
   1658  * \assert
   1659  *    \code object != NULL \endcode
   1660  *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
   1661  *    \code object->data.cue_sheet.num_tracks > track_num \endcode
   1662  *    \code (object->data.cue_sheet.tracks[track_num].indices == NULL && object->data.cue_sheet.tracks[track_num].num_indices == 0) ||
   1663  * (object->data.cue_sheet.tracks[track_num].indices != NULL && object->data.cue_sheet.tracks[track_num].num_indices > 0) \endcode
   1664  * \retval FLAC__bool
   1665  *    \c false if memory allocation error, else \c true.
   1666  */
   1667 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_resize_indices(FLAC__StreamMetadata *object, unsigned track_num, unsigned new_num_indices);
   1668 
   1669 /** Insert an index point in a CUESHEET track at the given index.
   1670  *
   1671  * \param object       A pointer to an existing CUESHEET object.
   1672  * \param track_num    The index of the track to modify.  NOTE: this is not
   1673  *                     necessarily the same as the track's \a number field.
   1674  * \param index_num    The index into the track's index array at which to
   1675  *                     insert the index point.  NOTE: this is not necessarily
   1676  *                     the same as the index point's \a number field.  The
   1677  *                     indices at and after \a index_num move right one
   1678  *                     position.  To append an index point to the end, set
   1679  *                     \a index_num to
   1680  *                     \c object->data.cue_sheet.tracks[track_num].num_indices .
   1681  * \param index        The index point to insert.
   1682  * \assert
   1683  *    \code object != NULL \endcode
   1684  *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
   1685  *    \code object->data.cue_sheet.num_tracks > track_num \endcode
   1686  *    \code object->data.cue_sheet.tracks[track_num].num_indices >= index_num \endcode
   1687  * \retval FLAC__bool
   1688  *    \c false if realloc() fails, else \c true.
   1689  */
   1690 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num, FLAC__StreamMetadata_CueSheet_Index index);
   1691 
   1692 /** Insert a blank index point in a CUESHEET track at the given index.
   1693  *
   1694  *  A blank index point is one in which all field values are zero.
   1695  *
   1696  * \param object       A pointer to an existing CUESHEET object.
   1697  * \param track_num    The index of the track to modify.  NOTE: this is not
   1698  *                     necessarily the same as the track's \a number field.
   1699  * \param index_num    The index into the track's index array at which to
   1700  *                     insert the index point.  NOTE: this is not necessarily
   1701  *                     the same as the index point's \a number field.  The
   1702  *                     indices at and after \a index_num move right one
   1703  *                     position.  To append an index point to the end, set
   1704  *                     \a index_num to
   1705  *                     \c object->data.cue_sheet.tracks[track_num].num_indices .
   1706  * \assert
   1707  *    \code object != NULL \endcode
   1708  *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
   1709  *    \code object->data.cue_sheet.num_tracks > track_num \endcode
   1710  *    \code object->data.cue_sheet.tracks[track_num].num_indices >= index_num \endcode
   1711  * \retval FLAC__bool
   1712  *    \c false if realloc() fails, else \c true.
   1713  */
   1714 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_blank_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num);
   1715 
   1716 /** Delete an index point in a CUESHEET track at the given index.
   1717  *
   1718  * \param object       A pointer to an existing CUESHEET object.
   1719  * \param track_num    The index into the track array of the track to
   1720  *                     modify.  NOTE: this is not necessarily the same
   1721  *                     as the track's \a number field.
   1722  * \param index_num    The index into the track's index array of the index
   1723  *                     to delete.  NOTE: this is not necessarily the same
   1724  *                     as the index's \a number field.
   1725  * \assert
   1726  *    \code object != NULL \endcode
   1727  *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
   1728  *    \code object->data.cue_sheet.num_tracks > track_num \endcode
   1729  *    \code object->data.cue_sheet.tracks[track_num].num_indices > index_num \endcode
   1730  * \retval FLAC__bool
   1731  *    \c false if realloc() fails, else \c true.
   1732  */
   1733 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_delete_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num);
   1734 
   1735 /** Resize the track array.
   1736  *
   1737  *  If the size shrinks, elements will truncated; if it grows, new blank
   1738  *  tracks will be added to the end.
   1739  *
   1740  * \param object            A pointer to an existing CUESHEET object.
   1741  * \param new_num_tracks    The desired length of the array; may be \c 0.
   1742  * \assert
   1743  *    \code object != NULL \endcode
   1744  *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
   1745  *    \code (object->data.cue_sheet.tracks == NULL && object->data.cue_sheet.num_tracks == 0) ||
   1746  * (object->data.cue_sheet.tracks != NULL && object->data.cue_sheet.num_tracks > 0) \endcode
   1747  * \retval FLAC__bool
   1748  *    \c false if memory allocation error, else \c true.
   1749  */
   1750 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_resize_tracks(FLAC__StreamMetadata *object, unsigned new_num_tracks);
   1751 
   1752 /** Sets a track in a CUESHEET block.
   1753  *
   1754  *  If \a copy is \c true, a copy of the track is stored; otherwise, the object
   1755  *  takes ownership of the \a track pointer.
   1756  *
   1757  * \param object       A pointer to an existing CUESHEET object.
   1758  * \param track_num    Index into track array to set.  NOTE: this is not
   1759  *                     necessarily the same as the track's \a number field.
   1760  * \param track        The track to set the track to.  You may safely pass in
   1761  *                     a const pointer if \a copy is \c true.
   1762  * \param copy         See above.
   1763  * \assert
   1764  *    \code object != NULL \endcode
   1765  *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
   1766  *    \code track_num < object->data.cue_sheet.num_tracks \endcode
   1767  *    \code (track->indices != NULL && track->num_indices > 0) ||
   1768  * (track->indices == NULL && track->num_indices == 0)
   1769  * \retval FLAC__bool
   1770  *    \c false if \a copy is \c true and malloc() fails, else \c true.
   1771  */
   1772 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_set_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy);
   1773 
   1774 /** Insert a track in a CUESHEET block at the given index.
   1775  *
   1776  *  If \a copy is \c true, a copy of the track is stored; otherwise, the object
   1777  *  takes ownership of the \a track pointer.
   1778  *
   1779  * \param object       A pointer to an existing CUESHEET object.
   1780  * \param track_num    The index at which to insert the track.  NOTE: this
   1781  *                     is not necessarily the same as the track's \a number
   1782  *                     field.  The tracks at and after \a track_num move right
   1783  *                     one position.  To append a track to the end, set
   1784  *                     \a track_num to \c object->data.cue_sheet.num_tracks .
   1785  * \param track        The track to insert.  You may safely pass in a const
   1786  *                     pointer if \a copy is \c true.
   1787  * \param copy         See above.
   1788  * \assert
   1789  *    \code object != NULL \endcode
   1790  *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
   1791  *    \code object->data.cue_sheet.num_tracks >= track_num \endcode
   1792  * \retval FLAC__bool
   1793  *    \c false if \a copy is \c true and malloc() fails, else \c true.
   1794  */
   1795 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy);
   1796 
   1797 /** Insert a blank track in a CUESHEET block at the given index.
   1798  *
   1799  *  A blank track is one in which all field values are zero.
   1800  *
   1801  * \param object       A pointer to an existing CUESHEET object.
   1802  * \param track_num    The index at which to insert the track.  NOTE: this
   1803  *                     is not necessarily the same as the track's \a number
   1804  *                     field.  The tracks at and after \a track_num move right
   1805  *                     one position.  To append a track to the end, set
   1806  *                     \a track_num to \c object->data.cue_sheet.num_tracks .
   1807  * \assert
   1808  *    \code object != NULL \endcode
   1809  *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
   1810  *    \code object->data.cue_sheet.num_tracks >= track_num \endcode
   1811  * \retval FLAC__bool
   1812  *    \c false if \a copy is \c true and malloc() fails, else \c true.
   1813  */
   1814 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_blank_track(FLAC__StreamMetadata *object, unsigned track_num);
   1815 
   1816 /** Delete a track in a CUESHEET block at the given index.
   1817  *
   1818  * \param object       A pointer to an existing CUESHEET object.
   1819  * \param track_num    The index into the track array of the track to
   1820  *                     delete.  NOTE: this is not necessarily the same
   1821  *                     as the track's \a number field.
   1822  * \assert
   1823  *    \code object != NULL \endcode
   1824  *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
   1825  *    \code object->data.cue_sheet.num_tracks > track_num \endcode
   1826  * \retval FLAC__bool
   1827  *    \c false if realloc() fails, else \c true.
   1828  */
   1829 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_delete_track(FLAC__StreamMetadata *object, unsigned track_num);
   1830 
   1831 /** Check a cue sheet to see if it conforms to the FLAC specification.
   1832  *  See the format specification for limits on the contents of the
   1833  *  cue sheet.
   1834  *
   1835  * \param object     A pointer to an existing CUESHEET object.
   1836  * \param check_cd_da_subset  If \c true, check CUESHEET against more
   1837  *                   stringent requirements for a CD-DA (audio) disc.
   1838  * \param violation  Address of a pointer to a string.  If there is a
   1839  *                   violation, a pointer to a string explanation of the
   1840  *                   violation will be returned here. \a violation may be
   1841  *                   \c NULL if you don't need the returned string.  Do not
   1842  *                   free the returned string; it will always point to static
   1843  *                   data.
   1844  * \assert
   1845  *    \code object != NULL \endcode
   1846  *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
   1847  * \retval FLAC__bool
   1848  *    \c false if cue sheet is illegal, else \c true.
   1849  */
   1850 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_is_legal(const FLAC__StreamMetadata *object, FLAC__bool check_cd_da_subset, const char **violation);
   1851 
   1852 /* \} */
   1853 
   1854 #ifdef __cplusplus
   1855 }
   1856 #endif
   1857 
   1858 #endif