Subversion Repositories Games.Prince of Persia

/* libFLAC - Free Lossless Audio Codec library

 * Copyright (C) 2001-2009  Josh Coalson

 * Copyright (C) 2011-2016  Xiph.Org Foundation

 *

 * Redistribution and use in source and binary forms, with or without

 * modification, are permitted provided that the following conditions

 * are met:

 *

 * - Redistributions of source code must retain the above copyright

 * notice, this list of conditions and the following disclaimer.

 *

 * - Redistributions in binary form must reproduce the above copyright

 * notice, this list of conditions and the following disclaimer in the

 * documentation and/or other materials provided with the distribution.

 *

 * - Neither the name of the Xiph.org Foundation nor the names of its

 * contributors may be used to endorse or promote products derived from

 * this software without specific prior written permission.

 *

 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

 * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR

 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,

 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,

 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR

 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF

 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING

 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 */

#ifndef FLAC__METADATA_H

#define FLAC__METADATA_H

#include <sys/types.h> /* for off_t */

#include "export.h"

#include "callback.h"

#include "format.h"

/* --------------------------------------------------------------------

   (For an example of how all these routines are used, see the source

   code for the unit tests in src/test_libFLAC/metadata_*.c, or

   metaflac in src/metaflac/)

   ------------------------------------------------------------------*/

/** \file include/FLAC/metadata.h

 *

 *  \brief

 *  This module provides functions for creating and manipulating FLAC

 *  metadata blocks in memory, and three progressively more powerful

 *  interfaces for traversing and editing metadata in FLAC files.

 *

 *  See the detailed documentation for each interface in the

 *  \link flac_metadata metadata \endlink module.

 */

/** \defgroup flac_metadata FLAC/metadata.h: metadata interfaces

 *  \ingroup flac

 *

 *  \brief

 *  This module provides functions for creating and manipulating FLAC

 *  metadata blocks in memory, and three progressively more powerful

 *  interfaces for traversing and editing metadata in native FLAC files.

 *  Note that currently only the Chain interface (level 2) supports Ogg

 *  FLAC files, and it is read-only i.e. no writing back changed

 *  metadata to file.

 *

 *  There are three metadata interfaces of increasing complexity:

 *

 *  Level 0:

 *  Read-only access to the STREAMINFO, VORBIS_COMMENT, CUESHEET, and

 *  PICTURE blocks.

 *

 *  Level 1:

 *  Read-write access to all metadata blocks.  This level is write-

 *  efficient in most cases (more on this below), and uses less memory

 *  than level 2.

 *

 *  Level 2:

 *  Read-write access to all metadata blocks.  This level is write-

 *  efficient in all cases, but uses more memory since all metadata for

 *  the whole file is read into memory and manipulated before writing

 *  out again.

 *

 *  What do we mean by efficient?  Since FLAC metadata appears at the

 *  beginning of the file, when writing metadata back to a FLAC file

 *  it is possible to grow or shrink the metadata such that the entire

 *  file must be rewritten.  However, if the size remains the same during

 *  changes or PADDING blocks are utilized, only the metadata needs to be

 *  overwritten, which is much faster.

 *

 *  Efficient means the whole file is rewritten at most one time, and only

 *  when necessary.  Level 1 is not efficient only in the case that you

 *  cause more than one metadata block to grow or shrink beyond what can

 *  be accomodated by padding.  In this case you should probably use level

 *  2, which allows you to edit all the metadata for a file in memory and

 *  write it out all at once.

 *

 *  All levels know how to skip over and not disturb an ID3v2 tag at the

 *  front of the file.

 *

 *  All levels access files via their filenames.  In addition, level 2

 *  has additional alternative read and write functions that take an I/O

 *  handle and callbacks, for situations where access by filename is not

 *  possible.

 *

 *  In addition to the three interfaces, this module defines functions for

 *  creating and manipulating various metadata objects in memory.  As we see

 *  from the Format module, FLAC metadata blocks in memory are very primitive

 *  structures for storing information in an efficient way.  Reading

 *  information from the structures is easy but creating or modifying them

 *  directly is more complex.  The metadata object routines here facilitate

 *  this by taking care of the consistency and memory management drudgery.

 *

 *  Unless you will be using the level 1 or 2 interfaces to modify existing

 *  metadata however, you will not probably not need these.

 *

 *  From a dependency standpoint, none of the encoders or decoders require

 *  the metadata module.  This is so that embedded users can strip out the

 *  metadata module from libFLAC to reduce the size and complexity.

 */

#ifdef __cplusplus

extern "C" {

#endif

/** \defgroup flac_metadata_level0 FLAC/metadata.h: metadata level 0 interface

 *  \ingroup flac_metadata

 *

 *  \brief

 *  The level 0 interface consists of individual routines to read the

 *  STREAMINFO, VORBIS_COMMENT, CUESHEET, and PICTURE blocks, requiring

 *  only a filename.

 *

 *  They try to skip any ID3v2 tag at the head of the file.

 *

 * \{

 */

/** Read the STREAMINFO metadata block of the given FLAC file.  This function

 *  will try to skip any ID3v2 tag at the head of the file.

 *

 * \param filename    The path to the FLAC file to read.

 * \param streaminfo  A pointer to space for the STREAMINFO block.  Since

 *                    FLAC__StreamMetadata is a simple structure with no

 *                    memory allocation involved, you pass the address of

 *                    an existing structure.  It need not be initialized.

 * \assert

 *    \code filename != NULL \endcode

 *    \code streaminfo != NULL \endcode

 * \retval FLAC__bool

 *    \c true if a valid STREAMINFO block was read from \a filename.  Returns

 *    \c false if there was a memory allocation error, a file decoder error,

 *    or the file contained no STREAMINFO block.  (A memory allocation error

 *    is possible because this function must set up a file decoder.)

 */

FLAC_API FLAC__bool FLAC__metadata_get_streaminfo(const char *filename, FLAC__StreamMetadata *streaminfo);

/** Read the VORBIS_COMMENT metadata block of the given FLAC file.  This

 *  function will try to skip any ID3v2 tag at the head of the file.

 *

 * \param filename    The path to the FLAC file to read.

 * \param tags        The address where the returned pointer will be

 *                    stored.  The \a tags object must be deleted by

 *                    the caller using FLAC__metadata_object_delete().

 * \assert

 *    \code filename != NULL \endcode

 *    \code tags != NULL \endcode

 * \retval FLAC__bool

 *    \c true if a valid VORBIS_COMMENT block was read from \a filename,

 *    and \a *tags will be set to the address of the metadata structure.

 *    Returns \c false if there was a memory allocation error, a file

 *    decoder error, or the file contained no VORBIS_COMMENT block, and

 *    \a *tags will be set to \c NULL.

 */

FLAC_API FLAC__bool FLAC__metadata_get_tags(const char *filename, FLAC__StreamMetadata **tags);

/** Read the CUESHEET metadata block of the given FLAC file.  This

 *  function will try to skip any ID3v2 tag at the head of the file.

 *

 * \param filename    The path to the FLAC file to read.

 * \param cuesheet    The address where the returned pointer will be

 *                    stored.  The \a cuesheet object must be deleted by

 *                    the caller using FLAC__metadata_object_delete().

 * \assert

 *    \code filename != NULL \endcode

 *    \code cuesheet != NULL \endcode

 * \retval FLAC__bool

 *    \c true if a valid CUESHEET block was read from \a filename,

 *    and \a *cuesheet will be set to the address of the metadata

 *    structure.  Returns \c false if there was a memory allocation

 *    error, a file decoder error, or the file contained no CUESHEET

 *    block, and \a *cuesheet will be set to \c NULL.

 */

FLAC_API FLAC__bool FLAC__metadata_get_cuesheet(const char *filename, FLAC__StreamMetadata **cuesheet);

/** Read a PICTURE metadata block of the given FLAC file.  This

 *  function will try to skip any ID3v2 tag at the head of the file.

 *  Since there can be more than one PICTURE block in a file, this

 *  function takes a number of parameters that act as constraints to

 *  the search.  The PICTURE block with the largest area matching all

 *  the constraints will be returned, or \a *picture will be set to

 *  \c NULL if there was no such block.

 *

 * \param filename    The path to the FLAC file to read.

 * \param picture     The address where the returned pointer will be

 *                    stored.  The \a picture object must be deleted by

 *                    the caller using FLAC__metadata_object_delete().

 * \param type        The desired picture type.  Use \c -1 to mean

 *                    "any type".

 * \param mime_type   The desired MIME type, e.g. "image/jpeg".  The

 *                    string will be matched exactly.  Use \c NULL to

 *                    mean "any MIME type".

 * \param description The desired description.  The string will be

 *                    matched exactly.  Use \c NULL to mean "any

 *                    description".

 * \param max_width   The maximum width in pixels desired.  Use

 *                    \c (unsigned)(-1) to mean "any width".

 * \param max_height  The maximum height in pixels desired.  Use

 *                    \c (unsigned)(-1) to mean "any height".

 * \param max_depth   The maximum color depth in bits-per-pixel desired.

 *                    Use \c (unsigned)(-1) to mean "any depth".

 * \param max_colors  The maximum number of colors desired.  Use

 *                    \c (unsigned)(-1) to mean "any number of colors".

 * \assert

 *    \code filename != NULL \endcode

 *    \code picture != NULL \endcode

 * \retval FLAC__bool

 *    \c true if a valid PICTURE block was read from \a filename,

 *    and \a *picture will be set to the address of the metadata

 *    structure.  Returns \c false if there was a memory allocation

 *    error, a file decoder error, or the file contained no PICTURE

 *    block, and \a *picture will be set to \c NULL.

 */

FLAC_API FLAC__bool FLAC__metadata_get_picture(const char *filename, FLAC__StreamMetadata **picture, FLAC__StreamMetadata_Picture_Type type, const char *mime_type, const FLAC__byte *description, unsigned max_width, unsigned max_height, unsigned max_depth, unsigned max_colors);

/* \} */

/** \defgroup flac_metadata_level1 FLAC/metadata.h: metadata level 1 interface

 *  \ingroup flac_metadata

 *

 * \brief

 * The level 1 interface provides read-write access to FLAC file metadata and

 * operates directly on the FLAC file.

 *

 * The general usage of this interface is:

 *

 * - Create an iterator using FLAC__metadata_simple_iterator_new()

 * - Attach it to a file using FLAC__metadata_simple_iterator_init() and check

 *   the exit code.  Call FLAC__metadata_simple_iterator_is_writable() to

 *   see if the file is writable, or only read access is allowed.

 * - Use FLAC__metadata_simple_iterator_next() and

 *   FLAC__metadata_simple_iterator_prev() to traverse the blocks.

 *   This is does not read the actual blocks themselves.

 *   FLAC__metadata_simple_iterator_next() is relatively fast.

 *   FLAC__metadata_simple_iterator_prev() is slower since it needs to search

 *   forward from the front of the file.

 * - Use FLAC__metadata_simple_iterator_get_block_type() or

 *   FLAC__metadata_simple_iterator_get_block() to access the actual data at

 *   the current iterator position.  The returned object is yours to modify

 *   and free.

 * - Use FLAC__metadata_simple_iterator_set_block() to write a modified block

 *   back.  You must have write permission to the original file.  Make sure to

 *   read the whole comment to FLAC__metadata_simple_iterator_set_block()

 *   below.

 * - Use FLAC__metadata_simple_iterator_insert_block_after() to add new blocks.

 *   Use the object creation functions from

 *   \link flac_metadata_object here \endlink to generate new objects.

 * - Use FLAC__metadata_simple_iterator_delete_block() to remove the block

 *   currently referred to by the iterator, or replace it with padding.

 * - Destroy the iterator with FLAC__metadata_simple_iterator_delete() when

 *   finished.

 *

 * \note

 * The FLAC file remains open the whole time between

 * FLAC__metadata_simple_iterator_init() and

 * FLAC__metadata_simple_iterator_delete(), so make sure you are not altering

 * the file during this time.

 *

 * \note

 * Do not modify the \a is_last, \a length, or \a type fields of returned

 * FLAC__StreamMetadata objects.  These are managed automatically.

 *

 * \note

 * If any of the modification functions

 * (FLAC__metadata_simple_iterator_set_block(),

 * FLAC__metadata_simple_iterator_delete_block(),

 * FLAC__metadata_simple_iterator_insert_block_after(), etc.) return \c false,

 * you should delete the iterator as it may no longer be valid.

 *

 * \{

 */

struct FLAC__Metadata_SimpleIterator;

/** The opaque structure definition for the level 1 iterator type.

 *  See the

 *  \link flac_metadata_level1 metadata level 1 module \endlink

 *  for a detailed description.

 */

typedef struct FLAC__Metadata_SimpleIterator FLAC__Metadata_SimpleIterator;

/** Status type for FLAC__Metadata_SimpleIterator.

 *

 *  The iterator's current status can be obtained by calling FLAC__metadata_simple_iterator_status().

 */

typedef enum {

        FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK = 0,

        /**< The iterator is in the normal OK state */

        FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT,

        /**< The data passed into a function violated the function's usage criteria */

        FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ERROR_OPENING_FILE,

        /**< The iterator could not open the target file */

        FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_A_FLAC_FILE,

        /**< The iterator could not find the FLAC signature at the start of the file */

        FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_WRITABLE,

        /**< The iterator tried to write to a file that was not writable */

        FLAC__METADATA_SIMPLE_ITERATOR_STATUS_BAD_METADATA,

        /**< The iterator encountered input that does not conform to the FLAC metadata specification */

        FLAC__METADATA_SIMPLE_ITERATOR_STATUS_READ_ERROR,

        /**< The iterator encountered an error while reading the FLAC file */

        FLAC__METADATA_SIMPLE_ITERATOR_STATUS_SEEK_ERROR,

        /**< The iterator encountered an error while seeking in the FLAC file */

        FLAC__METADATA_SIMPLE_ITERATOR_STATUS_WRITE_ERROR,

        /**< The iterator encountered an error while writing the FLAC file */

        FLAC__METADATA_SIMPLE_ITERATOR_STATUS_RENAME_ERROR,

        /**< The iterator encountered an error renaming the FLAC file */

        FLAC__METADATA_SIMPLE_ITERATOR_STATUS_UNLINK_ERROR,

        /**< The iterator encountered an error removing the temporary file */

        FLAC__METADATA_SIMPLE_ITERATOR_STATUS_MEMORY_ALLOCATION_ERROR,

        /**< Memory allocation failed */

        FLAC__METADATA_SIMPLE_ITERATOR_STATUS_INTERNAL_ERROR

        /**< The caller violated an assertion or an unexpected error occurred */

} FLAC__Metadata_SimpleIteratorStatus;

/** Maps a FLAC__Metadata_SimpleIteratorStatus to a C string.

 *

 *  Using a FLAC__Metadata_SimpleIteratorStatus as the index to this array

 *  will give the string equivalent.  The contents should not be modified.

 */

extern FLAC_API const char * const FLAC__Metadata_SimpleIteratorStatusString[];

/** Create a new iterator instance.

 *

 * \retval FLAC__Metadata_SimpleIterator*

 *    \c NULL if there was an error allocating memory, else the new instance.

 */

FLAC_API FLAC__Metadata_SimpleIterator *FLAC__metadata_simple_iterator_new(void);

/** Free an iterator instance.  Deletes the object pointed to by \a iterator.

 *

 * \param iterator  A pointer to an existing iterator.

 * \assert

 *    \code iterator != NULL \endcode

 */

FLAC_API void FLAC__metadata_simple_iterator_delete(FLAC__Metadata_SimpleIterator *iterator);

/** Get the current status of the iterator.  Call this after a function

 *  returns \c false to get the reason for the error.  Also resets the status

 *  to FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK.

 *

 * \param iterator  A pointer to an existing iterator.

 * \assert

 *    \code iterator != NULL \endcode

 * \retval FLAC__Metadata_SimpleIteratorStatus

 *    The current status of the iterator.

 */

FLAC_API FLAC__Metadata_SimpleIteratorStatus FLAC__metadata_simple_iterator_status(FLAC__Metadata_SimpleIterator *iterator);

/** Initialize the iterator to point to the first metadata block in the

 *  given FLAC file.

 *

 * \param iterator             A pointer to an existing iterator.

 * \param filename             The path to the FLAC file.

 * \param read_only            If \c true, the FLAC file will be opened

 *                             in read-only mode; if \c false, the FLAC

 *                             file will be opened for edit even if no

 *                             edits are performed.

 * \param preserve_file_stats  If \c true, the owner and modification

 *                             time will be preserved even if the FLAC

 *                             file is written to.

 * \assert

 *    \code iterator != NULL \endcode

 *    \code filename != NULL \endcode

 * \retval FLAC__bool

 *    \c false if a memory allocation error occurs, the file can't be

 *    opened, or another error occurs, else \c true.

 */

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);

/** Returns \c true if the FLAC file is writable.  If \c false, calls to

 *  FLAC__metadata_simple_iterator_set_block() and

 *  FLAC__metadata_simple_iterator_insert_block_after() will fail.

 *

 * \param iterator             A pointer to an existing iterator.

 * \assert

 *    \code iterator != NULL \endcode

 * \retval FLAC__bool

 *    See above.

 */

FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_writable(const FLAC__Metadata_SimpleIterator *iterator);

/** Moves the iterator forward one metadata block, returning \c false if

 *  already at the end.

 *

 * \param iterator  A pointer to an existing initialized iterator.

 * \assert

 *    \code iterator != NULL \endcode

 *    \a iterator has been successfully initialized with

 *    FLAC__metadata_simple_iterator_init()

 * \retval FLAC__bool

 *    \c false if already at the last metadata block of the chain, else

 *    \c true.

 */

FLAC_API FLAC__bool FLAC__metadata_simple_iterator_next(FLAC__Metadata_SimpleIterator *iterator);

/** Moves the iterator backward one metadata block, returning \c false if

 *  already at the beginning.

 *

 * \param iterator  A pointer to an existing initialized iterator.

 * \assert

 *    \code iterator != NULL \endcode

 *    \a iterator has been successfully initialized with

 *    FLAC__metadata_simple_iterator_init()

 * \retval FLAC__bool

 *    \c false if already at the first metadata block of the chain, else

 *    \c true.

 */

FLAC_API FLAC__bool FLAC__metadata_simple_iterator_prev(FLAC__Metadata_SimpleIterator *iterator);

/** Returns a flag telling if the current metadata block is the last.

 *

 * \param iterator  A pointer to an existing initialized iterator.

 * \assert

 *    \code iterator != NULL \endcode

 *    \a iterator has been successfully initialized with

 *    FLAC__metadata_simple_iterator_init()

 * \retval FLAC__bool

 *    \c true if the current metadata block is the last in the file,

 *    else \c false.

 */

FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_last(const FLAC__Metadata_SimpleIterator *iterator);

/** Get the offset of the metadata block at the current position.  This

 *  avoids reading the actual block data which can save time for large

 *  blocks.

 *

 * \param iterator  A pointer to an existing initialized iterator.

 * \assert

 *    \code iterator != NULL \endcode

 *    \a iterator has been successfully initialized with

 *    FLAC__metadata_simple_iterator_init()

 * \retval off_t

 *    The offset of the metadata block at the current iterator position.

 *    This is the byte offset relative to the beginning of the file of

 *    the current metadata block's header.

 */

FLAC_API off_t FLAC__metadata_simple_iterator_get_block_offset(const FLAC__Metadata_SimpleIterator *iterator);

/** Get the type of the metadata block at the current position.  This

 *  avoids reading the actual block data which can save time for large

 *  blocks.

 *

 * \param iterator  A pointer to an existing initialized iterator.

 * \assert

 *    \code iterator != NULL \endcode

 *    \a iterator has been successfully initialized with

 *    FLAC__metadata_simple_iterator_init()

 * \retval FLAC__MetadataType

 *    The type of the metadata block at the current iterator position.

 */

FLAC_API FLAC__MetadataType FLAC__metadata_simple_iterator_get_block_type(const FLAC__Metadata_SimpleIterator *iterator);

/** Get the length of the metadata block at the current position.  This

 *  avoids reading the actual block data which can save time for large

 *  blocks.

 *

 * \param iterator  A pointer to an existing initialized iterator.

 * \assert

 *    \code iterator != NULL \endcode

 *    \a iterator has been successfully initialized with

 *    FLAC__metadata_simple_iterator_init()

 * \retval unsigned

 *    The length of the metadata block at the current iterator position.

 *    The is same length as that in the

 *    <a href="http://xiph.org/flac/format.html#metadata_block_header">metadata block header</a>,

 *    i.e. the length of the metadata body that follows the header.

 */

FLAC_API unsigned FLAC__metadata_simple_iterator_get_block_length(const FLAC__Metadata_SimpleIterator *iterator);

/** Get the application ID of the \c APPLICATION block at the current

 *  position.  This avoids reading the actual block data which can save

 *  time for large blocks.

 *

 * \param iterator  A pointer to an existing initialized iterator.

 * \param id        A pointer to a buffer of at least \c 4 bytes where

 *                  the ID will be stored.

 * \assert

 *    \code iterator != NULL \endcode

 *    \code id != NULL \endcode

 *    \a iterator has been successfully initialized with

 *    FLAC__metadata_simple_iterator_init()

 * \retval FLAC__bool

 *    \c true if the ID was successfully read, else \c false, in which

 *    case you should check FLAC__metadata_simple_iterator_status() to

 *    find out why.  If the status is

 *    \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT, then the

 *    current metadata block is not an \c APPLICATION block.  Otherwise

 *    if the status is

 *    \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_READ_ERROR or

 *    \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_SEEK_ERROR, an I/O error

 *    occurred and the iterator can no longer be used.

 */

FLAC_API FLAC__bool FLAC__metadata_simple_iterator_get_application_id(FLAC__Metadata_SimpleIterator *iterator, FLAC__byte *id);

/** Get the metadata block at the current position.  You can modify the

 *  block but must use FLAC__metadata_simple_iterator_set_block() to

 *  write it back to the FLAC file.

 *

 *  You must call FLAC__metadata_object_delete() on the returned object

 *  when you are finished with it.

 *

 * \param iterator  A pointer to an existing initialized iterator.

 * \assert

 *    \code iterator != NULL \endcode

 *    \a iterator has been successfully initialized with

 *    FLAC__metadata_simple_iterator_init()

 * \retval FLAC__StreamMetadata*

 *    The current metadata block, or \c NULL if there was a memory

 *    allocation error.

 */

FLAC_API FLAC__StreamMetadata *FLAC__metadata_simple_iterator_get_block(FLAC__Metadata_SimpleIterator *iterator);

/** Write a block back to the FLAC file.  This function tries to be

 *  as efficient as possible; how the block is actually written is

 *  shown by the following:

 *

 *  Existing block is a STREAMINFO block and the new block is a

 *  STREAMINFO block: the new block is written in place.  Make sure

 *  you know what you're doing when changing the values of a

 *  STREAMINFO block.

 *

 *  Existing block is a STREAMINFO block and the new block is a

 *  not a STREAMINFO block: this is an error since the first block

 *  must be a STREAMINFO block.  Returns \c false without altering the

 *  file.

 *

 *  Existing block is not a STREAMINFO block and the new block is a

 *  STREAMINFO block: this is an error since there may be only one

 *  STREAMINFO block.  Returns \c false without altering the file.

 *

 *  Existing block and new block are the same length: the existing

 *  block will be replaced by the new block, written in place.

 *

 *  Existing block is longer than new block: if use_padding is \c true,

 *  the existing block will be overwritten in place with the new

 *  block followed by a PADDING block, if possible, to make the total

 *  size the same as the existing block.  Remember that a padding

 *  block requires at least four bytes so if the difference in size

 *  between the new block and existing block is less than that, the

 *  entire file will have to be rewritten, using the new block's

 *  exact size.  If use_padding is \c false, the entire file will be

 *  rewritten, replacing the existing block by the new block.

 *

 *  Existing block is shorter than new block: if use_padding is \c true,

 *  the function will try and expand the new block into the following

 *  PADDING block, if it exists and doing so won't shrink the PADDING

 *  block to less than 4 bytes.  If there is no following PADDING

 *  block, or it will shrink to less than 4 bytes, or use_padding is

 *  \c false, the entire file is rewritten, replacing the existing block

 *  with the new block.  Note that in this case any following PADDING

 *  block is preserved as is.

 *

 *  After writing the block, the iterator will remain in the same

 *  place, i.e. pointing to the new block.

 *

 * \param iterator     A pointer to an existing initialized iterator.

 * \param block        The block to set.

 * \param use_padding  See above.

 * \assert

 *    \code iterator != NULL \endcode

 *    \a iterator has been successfully initialized with

 *    FLAC__metadata_simple_iterator_init()

 *    \code block != NULL \endcode

 * \retval FLAC__bool

 *    \c true if successful, else \c false.

 */

FLAC_API FLAC__bool FLAC__metadata_simple_iterator_set_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding);

/** This is similar to FLAC__metadata_simple_iterator_set_block()

 *  except that instead of writing over an existing block, it appends

 *  a block after the existing block.  \a use_padding is again used to

 *  tell the function to try an expand into following padding in an

 *  attempt to avoid rewriting the entire file.

 *

 *  This function will fail and return \c false if given a STREAMINFO

 *  block.

 *

 *  After writing the block, the iterator will be pointing to the

 *  new block.

 *

 * \param iterator     A pointer to an existing initialized iterator.

 * \param block        The block to set.

 * \param use_padding  See above.

 * \assert

 *    \code iterator != NULL \endcode

 *    \a iterator has been successfully initialized with

 *    FLAC__metadata_simple_iterator_init()

 *    \code block != NULL \endcode

 * \retval FLAC__bool

 *    \c true if successful, else \c false.

 */

FLAC_API FLAC__bool FLAC__metadata_simple_iterator_insert_block_after(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding);

/** Deletes the block at the current position.  This will cause the

 *  entire FLAC file to be rewritten, unless \a use_padding is \c true,

 *  in which case the block will be replaced by an equal-sized PADDING

 *  block.  The iterator will be left pointing to the block before the

 *  one just deleted.

 *

 *  You may not delete the STREAMINFO block.

 *

 * \param iterator     A pointer to an existing initialized iterator.

 * \param use_padding  See above.

 * \assert

 *    \code iterator != NULL \endcode

 *    \a iterator has been successfully initialized with

 *    FLAC__metadata_simple_iterator_init()

 * \retval FLAC__bool

 *    \c true if successful, else \c false.

 */

FLAC_API FLAC__bool FLAC__metadata_simple_iterator_delete_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__bool use_padding);

/* \} */

/** \defgroup flac_metadata_level2 FLAC/metadata.h: metadata level 2 interface

 *  \ingroup flac_metadata

 *

 * \brief

 * The level 2 interface provides read-write access to FLAC file metadata;

 * all metadata is read into memory, operated on in memory, and then written

 * to file, which is more efficient than level 1 when editing multiple blocks.

 *

 * Currently Ogg FLAC is supported for read only, via

 * FLAC__metadata_chain_read_ogg() but a subsequent

 * FLAC__metadata_chain_write() will fail.

 *

 * The general usage of this interface is:

 *

 * - Create a new chain using FLAC__metadata_chain_new().  A chain is a

 *   linked list of FLAC metadata blocks.

 * - Read all metadata into the chain from a FLAC file using

 *   FLAC__metadata_chain_read() or FLAC__metadata_chain_read_ogg() and

 *   check the status.

 * - Optionally, consolidate the padding using

 *   FLAC__metadata_chain_merge_padding() or

 *   FLAC__metadata_chain_sort_padding().

 * - Create a new iterator using FLAC__metadata_iterator_new()

 * - Initialize the iterator to point to the first element in the chain

 *   using FLAC__metadata_iterator_init()

 * - Traverse the chain using FLAC__metadata_iterator_next and

 *   FLAC__metadata_iterator_prev().

 * - Get a block for reading or modification using

 *   FLAC__metadata_iterator_get_block().  The pointer to the object

 *   inside the chain is returned, so the block is yours to modify.

 *   Changes will be reflected in the FLAC file when you write the

 *   chain.  You can also add and delete blocks (see functions below).

 * - When done, write out the chain using FLAC__metadata_chain_write().

 *   Make sure to read the whole comment to the function below.

 * - Delete the chain using FLAC__metadata_chain_delete().

 *

 * \note

 * Even though the FLAC file is not open while the chain is being

 * manipulated, you must not alter the file externally during

 * this time.  The chain assumes the FLAC file will not change

 * between the time of FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg()

 * and FLAC__metadata_chain_write().

 *

 * \note

 * Do not modify the is_last, length, or type fields of returned

 * FLAC__StreamMetadata objects.  These are managed automatically.

 *

 * \note

 * The metadata objects returned by FLAC__metadata_iterator_get_block()

 * are owned by the chain; do not FLAC__metadata_object_delete() them.

 * In the same way, blocks passed to FLAC__metadata_iterator_set_block()

 * become owned by the chain and they will be deleted when the chain is

 * deleted.

 *

 * \{

 */

struct FLAC__Metadata_Chain;

/** The opaque structure definition for the level 2 chain type.

 */

typedef struct FLAC__Metadata_Chain FLAC__Metadata_Chain;

struct FLAC__Metadata_Iterator;

/** The opaque structure definition for the level 2 iterator type.

 */

typedef struct FLAC__Metadata_Iterator FLAC__Metadata_Iterator;

typedef enum {

        FLAC__METADATA_CHAIN_STATUS_OK = 0,

        /**< The chain is in the normal OK state */

        FLAC__METADATA_CHAIN_STATUS_ILLEGAL_INPUT,

        /**< The data passed into a function violated the function's usage criteria */

        FLAC__METADATA_CHAIN_STATUS_ERROR_OPENING_FILE,

        /**< The chain could not open the target file */

        FLAC__METADATA_CHAIN_STATUS_NOT_A_FLAC_FILE,

        /**< The chain could not find the FLAC signature at the start of the file */

        FLAC__METADATA_CHAIN_STATUS_NOT_WRITABLE,

        /**< The chain tried to write to a file that was not writable */

        FLAC__METADATA_CHAIN_STATUS_BAD_METADATA,

        /**< The chain encountered input that does not conform to the FLAC metadata specification */

        FLAC__METADATA_CHAIN_STATUS_READ_ERROR,

        /**< The chain encountered an error while reading the FLAC file */

        FLAC__METADATA_CHAIN_STATUS_SEEK_ERROR,

        /**< The chain encountered an error while seeking in the FLAC file */

        FLAC__METADATA_CHAIN_STATUS_WRITE_ERROR,

        /**< The chain encountered an error while writing the FLAC file */

        FLAC__METADATA_CHAIN_STATUS_RENAME_ERROR,

        /**< The chain encountered an error renaming the FLAC file */

        FLAC__METADATA_CHAIN_STATUS_UNLINK_ERROR,

        /**< The chain encountered an error removing the temporary file */

        FLAC__METADATA_CHAIN_STATUS_MEMORY_ALLOCATION_ERROR,

        /**< Memory allocation failed */

        FLAC__METADATA_CHAIN_STATUS_INTERNAL_ERROR,

        /**< The caller violated an assertion or an unexpected error occurred */

        FLAC__METADATA_CHAIN_STATUS_INVALID_CALLBACKS,

        /**< One or more of the required callbacks was NULL */

        FLAC__METADATA_CHAIN_STATUS_READ_WRITE_MISMATCH,

        /**< FLAC__metadata_chain_write() was called on a chain read by

         *   FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(),

         *   or

         *   FLAC__metadata_chain_write_with_callbacks()/FLAC__metadata_chain_write_with_callbacks_and_tempfile()

         *   was called on a chain read by

         *   FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg().

         *   Matching read/write methods must always be used. */

        FLAC__METADATA_CHAIN_STATUS_WRONG_WRITE_CALL

        /**< FLAC__metadata_chain_write_with_callbacks() was called when the

         *   chain write requires a tempfile; use

         *   FLAC__metadata_chain_write_with_callbacks_and_tempfile() instead.

         *   Or, FLAC__metadata_chain_write_with_callbacks_and_tempfile() was

         *   called when the chain write does not require a tempfile; use

         *   FLAC__metadata_chain_write_with_callbacks() instead.

         *   Always check FLAC__metadata_chain_check_if_tempfile_needed()

         *   before writing via callbacks. */

} FLAC__Metadata_ChainStatus;

/** Maps a FLAC__Metadata_ChainStatus to a C string.

 *

 *  Using a FLAC__Metadata_ChainStatus as the index to this array

 *  will give the string equivalent.  The contents should not be modified.

 */

extern FLAC_API const char * const FLAC__Metadata_ChainStatusString[];

/*********** FLAC__Metadata_Chain ***********/

/** Create a new chain instance.

 *

 * \retval FLAC__Metadata_Chain*

 *    \c NULL if there was an error allocating memory, else the new instance.

 */

FLAC_API FLAC__Metadata_Chain *FLAC__metadata_chain_new(void);

/** Free a chain instance.  Deletes the object pointed to by \a chain.

 *

 * \param chain  A pointer to an existing chain.

 * \assert

 *    \code chain != NULL \endcode

 */

FLAC_API void FLAC__metadata_chain_delete(FLAC__Metadata_Chain *chain);

/** Get the current status of the chain.  Call this after a function

 *  returns \c false to get the reason for the error.  Also resets the

 *  status to FLAC__METADATA_CHAIN_STATUS_OK.

 *

 * \param chain    A pointer to an existing chain.

 * \assert

 *    \code chain != NULL \endcode

 * \retval FLAC__Metadata_ChainStatus

 *    The current status of the chain.

 */

FLAC_API FLAC__Metadata_ChainStatus FLAC__metadata_chain_status(FLAC__Metadata_Chain *chain);

/** Read all metadata from a FLAC file into the chain.

 *

 * \param chain    A pointer to an existing chain.

 * \param filename The path to the FLAC file to read.

 * \assert

 *    \code chain != NULL \endcode

 *    \code filename != NULL \endcode

 * \retval FLAC__bool

 *    \c true if a valid list of metadata blocks was read from

 *    \a filename, else \c false.  On failure, check the status with

 *    FLAC__metadata_chain_status().

 */

FLAC_API FLAC__bool FLAC__metadata_chain_read(FLAC__Metadata_Chain *chain, const char *filename);

/** Read all metadata from an Ogg FLAC file into the chain.

 *

 * \note Ogg FLAC metadata data writing is not supported yet and

 * FLAC__metadata_chain_write() will fail.

 *

 * \param chain    A pointer to an existing chain.

 * \param filename The path to the Ogg FLAC file to read.

 * \assert

 *    \code chain != NULL \endcode

 *    \code filename != NULL \endcode

 * \retval FLAC__bool

 *    \c true if a valid list of metadata blocks was read from

 *    \a filename, else \c false.  On failure, check the status with

 *    FLAC__metadata_chain_status().

 */

FLAC_API FLAC__bool FLAC__metadata_chain_read_ogg(FLAC__Metadata_Chain *chain, const char *filename);

/** Read all metadata from a FLAC stream into the chain via I/O callbacks.

 *

 *  The \a handle need only be open for reading, but must be seekable.

 *  The equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb"

 *  for Windows).

 *

 * \param chain    A pointer to an existing chain.

 * \param handle   The I/O handle of the FLAC stream to read.  The

 *                 handle will NOT be closed after the metadata is read;

 *                 that is the duty of the caller.

 * \param callbacks

 *                 A set of callbacks to use for I/O.  The mandatory

 *                 callbacks are \a read, \a seek, and \a tell.

 * \assert

 *    \code chain != NULL \endcode

 * \retval FLAC__bool

 *    \c true if a valid list of metadata blocks was read from

 *    \a handle, else \c false.  On failure, check the status with

 *    FLAC__metadata_chain_status().

 */

FLAC_API FLAC__bool FLAC__metadata_chain_read_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);

/** Read all metadata from an Ogg FLAC stream into the chain via I/O callbacks.

 *

 *  The \a handle need only be open for reading, but must be seekable.

 *  The equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb"

 *  for Windows).

 *

 * \note Ogg FLAC metadata data writing is not supported yet and

 * FLAC__metadata_chain_write() will fail.

 *

 * \param chain    A pointer to an existing chain.

 * \param handle   The I/O handle of the Ogg FLAC stream to read.  The

 *                 handle will NOT be closed after the metadata is read;

 *                 that is the duty of the caller.

 * \param callbacks

 *                 A set of callbacks to use for I/O.  The mandatory

 *                 callbacks are \a read, \a seek, and \a tell.

 * \assert

 *    \code chain != NULL \endcode

 * \retval FLAC__bool

 *    \c true if a valid list of metadata blocks was read from

 *    \a handle, else \c false.  On failure, check the status with

 *    FLAC__metadata_chain_status().

 */

FLAC_API FLAC__bool FLAC__metadata_chain_read_ogg_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);

/** Checks if writing the given chain would require the use of a

 *  temporary file, or if it could be written in place.

 *

 *  Under certain conditions, padding can be utilized so that writing

 *  edited metadata back to the FLAC file does not require rewriting the

 *  entire file.  If rewriting is required, then a temporary workfile is

 *  required.  When writing metadata using callbacks, you must check

 *  this function to know whether to call

 *  FLAC__metadata_chain_write_with_callbacks() or

 *  FLAC__metadata_chain_write_with_callbacks_and_tempfile().  When

 *  writing with FLAC__metadata_chain_write(), the temporary file is

 *  handled internally.

 *

 * \param chain    A pointer to an existing chain.

 * \param use_padding

 *                 Whether or not padding will be allowed to be used

 *                 during the write.  The value of \a use_padding given

 *                 here must match the value later passed to

 *                 FLAC__metadata_chain_write_with_callbacks() or

 *                 FLAC__metadata_chain_write_with_callbacks_with_tempfile().

 * \assert

 *    \code chain != NULL \endcode

 * \retval FLAC__bool

 *    \c true if writing the current chain would require a tempfile, or

 *    \c false if metadata can be written in place.

 */

FLAC_API FLAC__bool FLAC__metadata_chain_check_if_tempfile_needed(FLAC__Metadata_Chain *chain, FLAC__bool use_padding);

/** Write all metadata out to the FLAC file.  This function tries to be as

 *  efficient as possible; how the metadata is actually written is shown by

 *  the following:

 *

 *  If the current chain is the same size as the existing metadata, the new

 *  data is written in place.

 *

 *  If the current chain is longer than the existing metadata, and

 *  \a use_padding is \c true, and the last block is a PADDING block of

 *  sufficient length, the function will truncate the final padding block

 *  so that the overall size of the metadata is the same as the existing

 *  metadata, and then just rewrite the metadata.  Otherwise, if not all of

 *  the above conditions are met, the entire FLAC file must be rewritten.

 *  If you want to use padding this way it is a good idea to call

 *  FLAC__metadata_chain_sort_padding() first so that you have the maximum

 *  amount of padding to work with, unless you need to preserve ordering

 *  of the PADDING blocks for some reason.

 *

 *  If the current chain is shorter than the existing metadata, and

 *  \a use_padding is \c true, and the final block is a PADDING block, the padding

 *  is extended to make the overall size the same as the existing data.  If

 *  \a use_padding is \c true and the last block is not a PADDING block, a new

 *  PADDING block is added to the end of the new data to make it the same

 *  size as the existing data (if possible, see the note to

 *  FLAC__metadata_simple_iterator_set_block() about the four byte limit)

 *  and the new data is written in place.  If none of the above apply or

 *  \a use_padding is \c false, the entire FLAC file is rewritten.

 *

 *  If \a preserve_file_stats is \c true, the owner and modification time will

 *  be preserved even if the FLAC file is written.

 *

 *  For this write function to be used, the chain must have been read with

 *  FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg(), not

 *  FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks().

 *

 * \param chain               A pointer to an existing chain.

 * \param use_padding         See above.

 * \param preserve_file_stats See above.

 * \assert

 *    \code chain != NULL \endcode

 * \retval FLAC__bool

 *    \c true if the write succeeded, else \c false.  On failure,

 *    check the status with FLAC__metadata_chain_status().

 */

FLAC_API FLAC__bool FLAC__metadata_chain_write(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__bool preserve_file_stats);

/** Write all metadata out to a FLAC stream via callbacks.

 *

 *  (See FLAC__metadata_chain_write() for the details on how padding is

 *  used to write metadata in place if possible.)

 *

 *  The \a handle must be open for updating and be seekable.  The

 *  equivalent minimum stdio fopen() file mode is \c "r+" (or \c "r+b"

 *  for Windows).

 *

 *  For this write function to be used, the chain must have been read with

 *  FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(),