VisualC/flac/include/FLAC/metadata.h
changeset 556 2686e67b59fd
parent 555 b92bfb451700
child 557 a55168d8babe
     1.1 --- a/VisualC/flac/include/FLAC/metadata.h	Mon Jan 09 01:58:40 2012 -0500
     1.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.3 @@ -1,2181 +0,0 @@
     1.4 -/* libFLAC - Free Lossless Audio Codec library
     1.5 - * Copyright (C) 2001,2002,2003,2004,2005,2006,2007  Josh Coalson
     1.6 - *
     1.7 - * Redistribution and use in source and binary forms, with or without
     1.8 - * modification, are permitted provided that the following conditions
     1.9 - * are met:
    1.10 - *
    1.11 - * - Redistributions of source code must retain the above copyright
    1.12 - * notice, this list of conditions and the following disclaimer.
    1.13 - *
    1.14 - * - Redistributions in binary form must reproduce the above copyright
    1.15 - * notice, this list of conditions and the following disclaimer in the
    1.16 - * documentation and/or other materials provided with the distribution.
    1.17 - *
    1.18 - * - Neither the name of the Xiph.org Foundation nor the names of its
    1.19 - * contributors may be used to endorse or promote products derived from
    1.20 - * this software without specific prior written permission.
    1.21 - *
    1.22 - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    1.23 - * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    1.24 - * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    1.25 - * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
    1.26 - * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    1.27 - * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    1.28 - * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    1.29 - * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    1.30 - * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    1.31 - * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    1.32 - * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    1.33 - */
    1.34 -
    1.35 -#ifndef FLAC__METADATA_H
    1.36 -#define FLAC__METADATA_H
    1.37 -
    1.38 -#include <sys/types.h> /* for off_t */
    1.39 -#include "export.h"
    1.40 -#include "callback.h"
    1.41 -#include "format.h"
    1.42 -
    1.43 -/* --------------------------------------------------------------------
    1.44 -   (For an example of how all these routines are used, see the source
    1.45 -   code for the unit tests in src/test_libFLAC/metadata_*.c, or
    1.46 -   metaflac in src/metaflac/)
    1.47 -   ------------------------------------------------------------------*/
    1.48 -
    1.49 -/** \file include/FLAC/metadata.h
    1.50 - *
    1.51 - *  \brief
    1.52 - *  This module provides functions for creating and manipulating FLAC
    1.53 - *  metadata blocks in memory, and three progressively more powerful
    1.54 - *  interfaces for traversing and editing metadata in FLAC files.
    1.55 - *
    1.56 - *  See the detailed documentation for each interface in the
    1.57 - *  \link flac_metadata metadata \endlink module.
    1.58 - */
    1.59 -
    1.60 -/** \defgroup flac_metadata FLAC/metadata.h: metadata interfaces
    1.61 - *  \ingroup flac
    1.62 - *
    1.63 - *  \brief
    1.64 - *  This module provides functions for creating and manipulating FLAC
    1.65 - *  metadata blocks in memory, and three progressively more powerful
    1.66 - *  interfaces for traversing and editing metadata in native FLAC files.
    1.67 - *  Note that currently only the Chain interface (level 2) supports Ogg
    1.68 - *  FLAC files, and it is read-only i.e. no writing back changed
    1.69 - *  metadata to file.
    1.70 - *
    1.71 - *  There are three metadata interfaces of increasing complexity:
    1.72 - *
    1.73 - *  Level 0:
    1.74 - *  Read-only access to the STREAMINFO, VORBIS_COMMENT, CUESHEET, and
    1.75 - *  PICTURE blocks.
    1.76 - *
    1.77 - *  Level 1:
    1.78 - *  Read-write access to all metadata blocks.  This level is write-
    1.79 - *  efficient in most cases (more on this below), and uses less memory
    1.80 - *  than level 2.
    1.81 - *
    1.82 - *  Level 2:
    1.83 - *  Read-write access to all metadata blocks.  This level is write-
    1.84 - *  efficient in all cases, but uses more memory since all metadata for
    1.85 - *  the whole file is read into memory and manipulated before writing
    1.86 - *  out again.
    1.87 - *
    1.88 - *  What do we mean by efficient?  Since FLAC metadata appears at the
    1.89 - *  beginning of the file, when writing metadata back to a FLAC file
    1.90 - *  it is possible to grow or shrink the metadata such that the entire
    1.91 - *  file must be rewritten.  However, if the size remains the same during
    1.92 - *  changes or PADDING blocks are utilized, only the metadata needs to be
    1.93 - *  overwritten, which is much faster.
    1.94 - *
    1.95 - *  Efficient means the whole file is rewritten at most one time, and only
    1.96 - *  when necessary.  Level 1 is not efficient only in the case that you
    1.97 - *  cause more than one metadata block to grow or shrink beyond what can
    1.98 - *  be accomodated by padding.  In this case you should probably use level
    1.99 - *  2, which allows you to edit all the metadata for a file in memory and
   1.100 - *  write it out all at once.
   1.101 - *
   1.102 - *  All levels know how to skip over and not disturb an ID3v2 tag at the
   1.103 - *  front of the file.
   1.104 - *
   1.105 - *  All levels access files via their filenames.  In addition, level 2
   1.106 - *  has additional alternative read and write functions that take an I/O
   1.107 - *  handle and callbacks, for situations where access by filename is not
   1.108 - *  possible.
   1.109 - *
   1.110 - *  In addition to the three interfaces, this module defines functions for
   1.111 - *  creating and manipulating various metadata objects in memory.  As we see
   1.112 - *  from the Format module, FLAC metadata blocks in memory are very primitive
   1.113 - *  structures for storing information in an efficient way.  Reading
   1.114 - *  information from the structures is easy but creating or modifying them
   1.115 - *  directly is more complex.  The metadata object routines here facilitate
   1.116 - *  this by taking care of the consistency and memory management drudgery.
   1.117 - *
   1.118 - *  Unless you will be using the level 1 or 2 interfaces to modify existing
   1.119 - *  metadata however, you will not probably not need these.
   1.120 - *
   1.121 - *  From a dependency standpoint, none of the encoders or decoders require
   1.122 - *  the metadata module.  This is so that embedded users can strip out the
   1.123 - *  metadata module from libFLAC to reduce the size and complexity.
   1.124 - */
   1.125 -
   1.126 -#ifdef __cplusplus
   1.127 -extern "C" {
   1.128 -#endif
   1.129 -
   1.130 -
   1.131 -/** \defgroup flac_metadata_level0 FLAC/metadata.h: metadata level 0 interface
   1.132 - *  \ingroup flac_metadata
   1.133 - *
   1.134 - *  \brief
   1.135 - *  The level 0 interface consists of individual routines to read the
   1.136 - *  STREAMINFO, VORBIS_COMMENT, CUESHEET, and PICTURE blocks, requiring
   1.137 - *  only a filename.
   1.138 - *
   1.139 - *  They try to skip any ID3v2 tag at the head of the file.
   1.140 - *
   1.141 - * \{
   1.142 - */
   1.143 -
   1.144 -/** Read the STREAMINFO metadata block of the given FLAC file.  This function
   1.145 - *  will try to skip any ID3v2 tag at the head of the file.
   1.146 - *
   1.147 - * \param filename    The path to the FLAC file to read.
   1.148 - * \param streaminfo  A pointer to space for the STREAMINFO block.  Since
   1.149 - *                    FLAC__StreamMetadata is a simple structure with no
   1.150 - *                    memory allocation involved, you pass the address of
   1.151 - *                    an existing structure.  It need not be initialized.
   1.152 - * \assert
   1.153 - *    \code filename != NULL \endcode
   1.154 - *    \code streaminfo != NULL \endcode
   1.155 - * \retval FLAC__bool
   1.156 - *    \c true if a valid STREAMINFO block was read from \a filename.  Returns
   1.157 - *    \c false if there was a memory allocation error, a file decoder error,
   1.158 - *    or the file contained no STREAMINFO block.  (A memory allocation error
   1.159 - *    is possible because this function must set up a file decoder.)
   1.160 - */
   1.161 -FLAC_API FLAC__bool FLAC__metadata_get_streaminfo(const char *filename, FLAC__StreamMetadata *streaminfo);
   1.162 -
   1.163 -/** Read the VORBIS_COMMENT metadata block of the given FLAC file.  This
   1.164 - *  function will try to skip any ID3v2 tag at the head of the file.
   1.165 - *
   1.166 - * \param filename    The path to the FLAC file to read.
   1.167 - * \param tags        The address where the returned pointer will be
   1.168 - *                    stored.  The \a tags object must be deleted by
   1.169 - *                    the caller using FLAC__metadata_object_delete().
   1.170 - * \assert
   1.171 - *    \code filename != NULL \endcode
   1.172 - *    \code tags != NULL \endcode
   1.173 - * \retval FLAC__bool
   1.174 - *    \c true if a valid VORBIS_COMMENT block was read from \a filename,
   1.175 - *    and \a *tags will be set to the address of the metadata structure.
   1.176 - *    Returns \c false if there was a memory allocation error, a file
   1.177 - *    decoder error, or the file contained no VORBIS_COMMENT block, and
   1.178 - *    \a *tags will be set to \c NULL.
   1.179 - */
   1.180 -FLAC_API FLAC__bool FLAC__metadata_get_tags(const char *filename, FLAC__StreamMetadata **tags);
   1.181 -
   1.182 -/** Read the CUESHEET metadata block of the given FLAC file.  This
   1.183 - *  function will try to skip any ID3v2 tag at the head of the file.
   1.184 - *
   1.185 - * \param filename    The path to the FLAC file to read.
   1.186 - * \param cuesheet    The address where the returned pointer will be
   1.187 - *                    stored.  The \a cuesheet object must be deleted by
   1.188 - *                    the caller using FLAC__metadata_object_delete().
   1.189 - * \assert
   1.190 - *    \code filename != NULL \endcode
   1.191 - *    \code cuesheet != NULL \endcode
   1.192 - * \retval FLAC__bool
   1.193 - *    \c true if a valid CUESHEET block was read from \a filename,
   1.194 - *    and \a *cuesheet will be set to the address of the metadata
   1.195 - *    structure.  Returns \c false if there was a memory allocation
   1.196 - *    error, a file decoder error, or the file contained no CUESHEET
   1.197 - *    block, and \a *cuesheet will be set to \c NULL.
   1.198 - */
   1.199 -FLAC_API FLAC__bool FLAC__metadata_get_cuesheet(const char *filename, FLAC__StreamMetadata **cuesheet);
   1.200 -
   1.201 -/** Read a PICTURE metadata block of the given FLAC file.  This
   1.202 - *  function will try to skip any ID3v2 tag at the head of the file.
   1.203 - *  Since there can be more than one PICTURE block in a file, this
   1.204 - *  function takes a number of parameters that act as constraints to
   1.205 - *  the search.  The PICTURE block with the largest area matching all
   1.206 - *  the constraints will be returned, or \a *picture will be set to
   1.207 - *  \c NULL if there was no such block.
   1.208 - *
   1.209 - * \param filename    The path to the FLAC file to read.
   1.210 - * \param picture     The address where the returned pointer will be
   1.211 - *                    stored.  The \a picture object must be deleted by
   1.212 - *                    the caller using FLAC__metadata_object_delete().
   1.213 - * \param type        The desired picture type.  Use \c -1 to mean
   1.214 - *                    "any type".
   1.215 - * \param mime_type   The desired MIME type, e.g. "image/jpeg".  The
   1.216 - *                    string will be matched exactly.  Use \c NULL to
   1.217 - *                    mean "any MIME type".
   1.218 - * \param description The desired description.  The string will be
   1.219 - *                    matched exactly.  Use \c NULL to mean "any
   1.220 - *                    description".
   1.221 - * \param max_width   The maximum width in pixels desired.  Use
   1.222 - *                    \c (unsigned)(-1) to mean "any width".
   1.223 - * \param max_height  The maximum height in pixels desired.  Use
   1.224 - *                    \c (unsigned)(-1) to mean "any height".
   1.225 - * \param max_depth   The maximum color depth in bits-per-pixel desired.
   1.226 - *                    Use \c (unsigned)(-1) to mean "any depth".
   1.227 - * \param max_colors  The maximum number of colors desired.  Use
   1.228 - *                    \c (unsigned)(-1) to mean "any number of colors".
   1.229 - * \assert
   1.230 - *    \code filename != NULL \endcode
   1.231 - *    \code picture != NULL \endcode
   1.232 - * \retval FLAC__bool
   1.233 - *    \c true if a valid PICTURE block was read from \a filename,
   1.234 - *    and \a *picture will be set to the address of the metadata
   1.235 - *    structure.  Returns \c false if there was a memory allocation
   1.236 - *    error, a file decoder error, or the file contained no PICTURE
   1.237 - *    block, and \a *picture will be set to \c NULL.
   1.238 - */
   1.239 -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);
   1.240 -
   1.241 -/* \} */
   1.242 -
   1.243 -
   1.244 -/** \defgroup flac_metadata_level1 FLAC/metadata.h: metadata level 1 interface
   1.245 - *  \ingroup flac_metadata
   1.246 - *
   1.247 - * \brief
   1.248 - * The level 1 interface provides read-write access to FLAC file metadata and
   1.249 - * operates directly on the FLAC file.
   1.250 - *
   1.251 - * The general usage of this interface is:
   1.252 - *
   1.253 - * - Create an iterator using FLAC__metadata_simple_iterator_new()
   1.254 - * - Attach it to a file using FLAC__metadata_simple_iterator_init() and check
   1.255 - *   the exit code.  Call FLAC__metadata_simple_iterator_is_writable() to
   1.256 - *   see if the file is writable, or only read access is allowed.
   1.257 - * - Use FLAC__metadata_simple_iterator_next() and
   1.258 - *   FLAC__metadata_simple_iterator_prev() to traverse the blocks.
   1.259 - *   This is does not read the actual blocks themselves.
   1.260 - *   FLAC__metadata_simple_iterator_next() is relatively fast.
   1.261 - *   FLAC__metadata_simple_iterator_prev() is slower since it needs to search
   1.262 - *   forward from the front of the file.
   1.263 - * - Use FLAC__metadata_simple_iterator_get_block_type() or
   1.264 - *   FLAC__metadata_simple_iterator_get_block() to access the actual data at
   1.265 - *   the current iterator position.  The returned object is yours to modify
   1.266 - *   and free.
   1.267 - * - Use FLAC__metadata_simple_iterator_set_block() to write a modified block
   1.268 - *   back.  You must have write permission to the original file.  Make sure to
   1.269 - *   read the whole comment to FLAC__metadata_simple_iterator_set_block()
   1.270 - *   below.
   1.271 - * - Use FLAC__metadata_simple_iterator_insert_block_after() to add new blocks.
   1.272 - *   Use the object creation functions from
   1.273 - *   \link flac_metadata_object here \endlink to generate new objects.
   1.274 - * - Use FLAC__metadata_simple_iterator_delete_block() to remove the block
   1.275 - *   currently referred to by the iterator, or replace it with padding.
   1.276 - * - Destroy the iterator with FLAC__metadata_simple_iterator_delete() when
   1.277 - *   finished.
   1.278 - *
   1.279 - * \note
   1.280 - * The FLAC file remains open the whole time between
   1.281 - * FLAC__metadata_simple_iterator_init() and
   1.282 - * FLAC__metadata_simple_iterator_delete(), so make sure you are not altering
   1.283 - * the file during this time.
   1.284 - *
   1.285 - * \note
   1.286 - * Do not modify the \a is_last, \a length, or \a type fields of returned
   1.287 - * FLAC__StreamMetadata objects.  These are managed automatically.
   1.288 - *
   1.289 - * \note
   1.290 - * If any of the modification functions
   1.291 - * (FLAC__metadata_simple_iterator_set_block(),
   1.292 - * FLAC__metadata_simple_iterator_delete_block(),
   1.293 - * FLAC__metadata_simple_iterator_insert_block_after(), etc.) return \c false,
   1.294 - * you should delete the iterator as it may no longer be valid.
   1.295 - *
   1.296 - * \{
   1.297 - */
   1.298 -
   1.299 -struct FLAC__Metadata_SimpleIterator;
   1.300 -/** The opaque structure definition for the level 1 iterator type.
   1.301 - *  See the
   1.302 - *  \link flac_metadata_level1 metadata level 1 module \endlink
   1.303 - *  for a detailed description.
   1.304 - */
   1.305 -typedef struct FLAC__Metadata_SimpleIterator FLAC__Metadata_SimpleIterator;
   1.306 -
   1.307 -/** Status type for FLAC__Metadata_SimpleIterator.
   1.308 - *
   1.309 - *  The iterator's current status can be obtained by calling FLAC__metadata_simple_iterator_status().
   1.310 - */
   1.311 -typedef enum {
   1.312 -
   1.313 -	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK = 0,
   1.314 -	/**< The iterator is in the normal OK state */
   1.315 -
   1.316 -	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT,
   1.317 -	/**< The data passed into a function violated the function's usage criteria */
   1.318 -
   1.319 -	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ERROR_OPENING_FILE,
   1.320 -	/**< The iterator could not open the target file */
   1.321 -
   1.322 -	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_A_FLAC_FILE,
   1.323 -	/**< The iterator could not find the FLAC signature at the start of the file */
   1.324 -
   1.325 -	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_WRITABLE,
   1.326 -	/**< The iterator tried to write to a file that was not writable */
   1.327 -
   1.328 -	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_BAD_METADATA,
   1.329 -	/**< The iterator encountered input that does not conform to the FLAC metadata specification */
   1.330 -
   1.331 -	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_READ_ERROR,
   1.332 -	/**< The iterator encountered an error while reading the FLAC file */
   1.333 -
   1.334 -	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_SEEK_ERROR,
   1.335 -	/**< The iterator encountered an error while seeking in the FLAC file */
   1.336 -
   1.337 -	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_WRITE_ERROR,
   1.338 -	/**< The iterator encountered an error while writing the FLAC file */
   1.339 -
   1.340 -	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_RENAME_ERROR,
   1.341 -	/**< The iterator encountered an error renaming the FLAC file */
   1.342 -
   1.343 -	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_UNLINK_ERROR,
   1.344 -	/**< The iterator encountered an error removing the temporary file */
   1.345 -
   1.346 -	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_MEMORY_ALLOCATION_ERROR,
   1.347 -	/**< Memory allocation failed */
   1.348 -
   1.349 -	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_INTERNAL_ERROR
   1.350 -	/**< The caller violated an assertion or an unexpected error occurred */
   1.351 -
   1.352 -} FLAC__Metadata_SimpleIteratorStatus;
   1.353 -
   1.354 -/** Maps a FLAC__Metadata_SimpleIteratorStatus to a C string.
   1.355 - *
   1.356 - *  Using a FLAC__Metadata_SimpleIteratorStatus as the index to this array
   1.357 - *  will give the string equivalent.  The contents should not be modified.
   1.358 - */
   1.359 -extern FLAC_API const char * const FLAC__Metadata_SimpleIteratorStatusString[];
   1.360 -
   1.361 -
   1.362 -/** Create a new iterator instance.
   1.363 - *
   1.364 - * \retval FLAC__Metadata_SimpleIterator*
   1.365 - *    \c NULL if there was an error allocating memory, else the new instance.
   1.366 - */
   1.367 -FLAC_API FLAC__Metadata_SimpleIterator *FLAC__metadata_simple_iterator_new(void);
   1.368 -
   1.369 -/** Free an iterator instance.  Deletes the object pointed to by \a iterator.
   1.370 - *
   1.371 - * \param iterator  A pointer to an existing iterator.
   1.372 - * \assert
   1.373 - *    \code iterator != NULL \endcode
   1.374 - */
   1.375 -FLAC_API void FLAC__metadata_simple_iterator_delete(FLAC__Metadata_SimpleIterator *iterator);
   1.376 -
   1.377 -/** Get the current status of the iterator.  Call this after a function
   1.378 - *  returns \c false to get the reason for the error.  Also resets the status
   1.379 - *  to FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK.
   1.380 - *
   1.381 - * \param iterator  A pointer to an existing iterator.
   1.382 - * \assert
   1.383 - *    \code iterator != NULL \endcode
   1.384 - * \retval FLAC__Metadata_SimpleIteratorStatus
   1.385 - *    The current status of the iterator.
   1.386 - */
   1.387 -FLAC_API FLAC__Metadata_SimpleIteratorStatus FLAC__metadata_simple_iterator_status(FLAC__Metadata_SimpleIterator *iterator);
   1.388 -
   1.389 -/** Initialize the iterator to point to the first metadata block in the
   1.390 - *  given FLAC file.
   1.391 - *
   1.392 - * \param iterator             A pointer to an existing iterator.
   1.393 - * \param filename             The path to the FLAC file.
   1.394 - * \param read_only            If \c true, the FLAC file will be opened
   1.395 - *                             in read-only mode; if \c false, the FLAC
   1.396 - *                             file will be opened for edit even if no
   1.397 - *                             edits are performed.
   1.398 - * \param preserve_file_stats  If \c true, the owner and modification
   1.399 - *                             time will be preserved even if the FLAC
   1.400 - *                             file is written to.
   1.401 - * \assert
   1.402 - *    \code iterator != NULL \endcode
   1.403 - *    \code filename != NULL \endcode
   1.404 - * \retval FLAC__bool
   1.405 - *    \c false if a memory allocation error occurs, the file can't be
   1.406 - *    opened, or another error occurs, else \c true.
   1.407 - */
   1.408 -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);
   1.409 -
   1.410 -/** Returns \c true if the FLAC file is writable.  If \c false, calls to
   1.411 - *  FLAC__metadata_simple_iterator_set_block() and
   1.412 - *  FLAC__metadata_simple_iterator_insert_block_after() will fail.
   1.413 - *
   1.414 - * \param iterator             A pointer to an existing iterator.
   1.415 - * \assert
   1.416 - *    \code iterator != NULL \endcode
   1.417 - * \retval FLAC__bool
   1.418 - *    See above.
   1.419 - */
   1.420 -FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_writable(const FLAC__Metadata_SimpleIterator *iterator);
   1.421 -
   1.422 -/** Moves the iterator forward one metadata block, returning \c false if
   1.423 - *  already at the end.
   1.424 - *
   1.425 - * \param iterator  A pointer to an existing initialized iterator.
   1.426 - * \assert
   1.427 - *    \code iterator != NULL \endcode
   1.428 - *    \a iterator has been successfully initialized with
   1.429 - *    FLAC__metadata_simple_iterator_init()
   1.430 - * \retval FLAC__bool
   1.431 - *    \c false if already at the last metadata block of the chain, else
   1.432 - *    \c true.
   1.433 - */
   1.434 -FLAC_API FLAC__bool FLAC__metadata_simple_iterator_next(FLAC__Metadata_SimpleIterator *iterator);
   1.435 -
   1.436 -/** Moves the iterator backward one metadata block, returning \c false if
   1.437 - *  already at the beginning.
   1.438 - *
   1.439 - * \param iterator  A pointer to an existing initialized iterator.
   1.440 - * \assert
   1.441 - *    \code iterator != NULL \endcode
   1.442 - *    \a iterator has been successfully initialized with
   1.443 - *    FLAC__metadata_simple_iterator_init()
   1.444 - * \retval FLAC__bool
   1.445 - *    \c false if already at the first metadata block of the chain, else
   1.446 - *    \c true.
   1.447 - */
   1.448 -FLAC_API FLAC__bool FLAC__metadata_simple_iterator_prev(FLAC__Metadata_SimpleIterator *iterator);
   1.449 -
   1.450 -/** Returns a flag telling if the current metadata block is the last.
   1.451 - *
   1.452 - * \param iterator  A pointer to an existing initialized iterator.
   1.453 - * \assert
   1.454 - *    \code iterator != NULL \endcode
   1.455 - *    \a iterator has been successfully initialized with
   1.456 - *    FLAC__metadata_simple_iterator_init()
   1.457 - * \retval FLAC__bool
   1.458 - *    \c true if the current metadata block is the last in the file,
   1.459 - *    else \c false.
   1.460 - */
   1.461 -FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_last(const FLAC__Metadata_SimpleIterator *iterator);
   1.462 -
   1.463 -/** Get the offset of the metadata block at the current position.  This
   1.464 - *  avoids reading the actual block data which can save time for large
   1.465 - *  blocks.
   1.466 - *
   1.467 - * \param iterator  A pointer to an existing initialized iterator.
   1.468 - * \assert
   1.469 - *    \code iterator != NULL \endcode
   1.470 - *    \a iterator has been successfully initialized with
   1.471 - *    FLAC__metadata_simple_iterator_init()
   1.472 - * \retval off_t
   1.473 - *    The offset of the metadata block at the current iterator position.
   1.474 - *    This is the byte offset relative to the beginning of the file of
   1.475 - *    the current metadata block's header.
   1.476 - */
   1.477 -FLAC_API off_t FLAC__metadata_simple_iterator_get_block_offset(const FLAC__Metadata_SimpleIterator *iterator);
   1.478 -
   1.479 -/** Get the type of the metadata block at the current position.  This
   1.480 - *  avoids reading the actual block data which can save time for large
   1.481 - *  blocks.
   1.482 - *
   1.483 - * \param iterator  A pointer to an existing initialized iterator.
   1.484 - * \assert
   1.485 - *    \code iterator != NULL \endcode
   1.486 - *    \a iterator has been successfully initialized with
   1.487 - *    FLAC__metadata_simple_iterator_init()
   1.488 - * \retval FLAC__MetadataType
   1.489 - *    The type of the metadata block at the current iterator position.
   1.490 - */
   1.491 -FLAC_API FLAC__MetadataType FLAC__metadata_simple_iterator_get_block_type(const FLAC__Metadata_SimpleIterator *iterator);
   1.492 -
   1.493 -/** Get the length of the metadata block at the current position.  This
   1.494 - *  avoids reading the actual block data which can save time for large
   1.495 - *  blocks.
   1.496 - *
   1.497 - * \param iterator  A pointer to an existing initialized iterator.
   1.498 - * \assert
   1.499 - *    \code iterator != NULL \endcode
   1.500 - *    \a iterator has been successfully initialized with
   1.501 - *    FLAC__metadata_simple_iterator_init()
   1.502 - * \retval unsigned
   1.503 - *    The length of the metadata block at the current iterator position.
   1.504 - *    The is same length as that in the
   1.505 - *    <a href="http://flac.sourceforge.net/format.html#metadata_block_header">metadata block header</a>,
   1.506 - *    i.e. the length of the metadata body that follows the header.
   1.507 - */
   1.508 -FLAC_API unsigned FLAC__metadata_simple_iterator_get_block_length(const FLAC__Metadata_SimpleIterator *iterator);
   1.509 -
   1.510 -/** Get the application ID of the \c APPLICATION block at the current
   1.511 - *  position.  This avoids reading the actual block data which can save
   1.512 - *  time for large blocks.
   1.513 - *
   1.514 - * \param iterator  A pointer to an existing initialized iterator.
   1.515 - * \param id        A pointer to a buffer of at least \c 4 bytes where
   1.516 - *                  the ID will be stored.
   1.517 - * \assert
   1.518 - *    \code iterator != NULL \endcode
   1.519 - *    \code id != NULL \endcode
   1.520 - *    \a iterator has been successfully initialized with
   1.521 - *    FLAC__metadata_simple_iterator_init()
   1.522 - * \retval FLAC__bool
   1.523 - *    \c true if the ID was successfully read, else \c false, in which
   1.524 - *    case you should check FLAC__metadata_simple_iterator_status() to
   1.525 - *    find out why.  If the status is
   1.526 - *    \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT, then the
   1.527 - *    current metadata block is not an \c APPLICATION block.  Otherwise
   1.528 - *    if the status is
   1.529 - *    \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_READ_ERROR or
   1.530 - *    \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_SEEK_ERROR, an I/O error
   1.531 - *    occurred and the iterator can no longer be used.
   1.532 - */
   1.533 -FLAC_API FLAC__bool FLAC__metadata_simple_iterator_get_application_id(FLAC__Metadata_SimpleIterator *iterator, FLAC__byte *id);
   1.534 -
   1.535 -/** Get the metadata block at the current position.  You can modify the
   1.536 - *  block but must use FLAC__metadata_simple_iterator_set_block() to
   1.537 - *  write it back to the FLAC file.
   1.538 - *
   1.539 - *  You must call FLAC__metadata_object_delete() on the returned object
   1.540 - *  when you are finished with it.
   1.541 - *
   1.542 - * \param iterator  A pointer to an existing initialized iterator.
   1.543 - * \assert
   1.544 - *    \code iterator != NULL \endcode
   1.545 - *    \a iterator has been successfully initialized with
   1.546 - *    FLAC__metadata_simple_iterator_init()
   1.547 - * \retval FLAC__StreamMetadata*
   1.548 - *    The current metadata block, or \c NULL if there was a memory
   1.549 - *    allocation error.
   1.550 - */
   1.551 -FLAC_API FLAC__StreamMetadata *FLAC__metadata_simple_iterator_get_block(FLAC__Metadata_SimpleIterator *iterator);
   1.552 -
   1.553 -/** Write a block back to the FLAC file.  This function tries to be
   1.554 - *  as efficient as possible; how the block is actually written is
   1.555 - *  shown by the following:
   1.556 - *
   1.557 - *  Existing block is a STREAMINFO block and the new block is a
   1.558 - *  STREAMINFO block: the new block is written in place.  Make sure
   1.559 - *  you know what you're doing when changing the values of a
   1.560 - *  STREAMINFO block.
   1.561 - *
   1.562 - *  Existing block is a STREAMINFO block and the new block is a
   1.563 - *  not a STREAMINFO block: this is an error since the first block
   1.564 - *  must be a STREAMINFO block.  Returns \c false without altering the
   1.565 - *  file.
   1.566 - *
   1.567 - *  Existing block is not a STREAMINFO block and the new block is a
   1.568 - *  STREAMINFO block: this is an error since there may be only one
   1.569 - *  STREAMINFO block.  Returns \c false without altering the file.
   1.570 - *
   1.571 - *  Existing block and new block are the same length: the existing
   1.572 - *  block will be replaced by the new block, written in place.
   1.573 - *
   1.574 - *  Existing block is longer than new block: if use_padding is \c true,
   1.575 - *  the existing block will be overwritten in place with the new
   1.576 - *  block followed by a PADDING block, if possible, to make the total
   1.577 - *  size the same as the existing block.  Remember that a padding
   1.578 - *  block requires at least four bytes so if the difference in size
   1.579 - *  between the new block and existing block is less than that, the
   1.580 - *  entire file will have to be rewritten, using the new block's
   1.581 - *  exact size.  If use_padding is \c false, the entire file will be
   1.582 - *  rewritten, replacing the existing block by the new block.
   1.583 - *
   1.584 - *  Existing block is shorter than new block: if use_padding is \c true,
   1.585 - *  the function will try and expand the new block into the following
   1.586 - *  PADDING block, if it exists and doing so won't shrink the PADDING
   1.587 - *  block to less than 4 bytes.  If there is no following PADDING
   1.588 - *  block, or it will shrink to less than 4 bytes, or use_padding is
   1.589 - *  \c false, the entire file is rewritten, replacing the existing block
   1.590 - *  with the new block.  Note that in this case any following PADDING
   1.591 - *  block is preserved as is.
   1.592 - *
   1.593 - *  After writing the block, the iterator will remain in the same
   1.594 - *  place, i.e. pointing to the new block.
   1.595 - *
   1.596 - * \param iterator     A pointer to an existing initialized iterator.
   1.597 - * \param block        The block to set.
   1.598 - * \param use_padding  See above.
   1.599 - * \assert
   1.600 - *    \code iterator != NULL \endcode
   1.601 - *    \a iterator has been successfully initialized with
   1.602 - *    FLAC__metadata_simple_iterator_init()
   1.603 - *    \code block != NULL \endcode
   1.604 - * \retval FLAC__bool
   1.605 - *    \c true if successful, else \c false.
   1.606 - */
   1.607 -FLAC_API FLAC__bool FLAC__metadata_simple_iterator_set_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding);
   1.608 -
   1.609 -/** This is similar to FLAC__metadata_simple_iterator_set_block()
   1.610 - *  except that instead of writing over an existing block, it appends
   1.611 - *  a block after the existing block.  \a use_padding is again used to
   1.612 - *  tell the function to try an expand into following padding in an
   1.613 - *  attempt to avoid rewriting the entire file.
   1.614 - *
   1.615 - *  This function will fail and return \c false if given a STREAMINFO
   1.616 - *  block.
   1.617 - *
   1.618 - *  After writing the block, the iterator will be pointing to the
   1.619 - *  new block.
   1.620 - *
   1.621 - * \param iterator     A pointer to an existing initialized iterator.
   1.622 - * \param block        The block to set.
   1.623 - * \param use_padding  See above.
   1.624 - * \assert
   1.625 - *    \code iterator != NULL \endcode
   1.626 - *    \a iterator has been successfully initialized with
   1.627 - *    FLAC__metadata_simple_iterator_init()
   1.628 - *    \code block != NULL \endcode
   1.629 - * \retval FLAC__bool
   1.630 - *    \c true if successful, else \c false.
   1.631 - */
   1.632 -FLAC_API FLAC__bool FLAC__metadata_simple_iterator_insert_block_after(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding);
   1.633 -
   1.634 -/** Deletes the block at the current position.  This will cause the
   1.635 - *  entire FLAC file to be rewritten, unless \a use_padding is \c true,
   1.636 - *  in which case the block will be replaced by an equal-sized PADDING
   1.637 - *  block.  The iterator will be left pointing to the block before the
   1.638 - *  one just deleted.
   1.639 - *
   1.640 - *  You may not delete the STREAMINFO block.
   1.641 - *
   1.642 - * \param iterator     A pointer to an existing initialized iterator.
   1.643 - * \param use_padding  See above.
   1.644 - * \assert
   1.645 - *    \code iterator != NULL \endcode
   1.646 - *    \a iterator has been successfully initialized with
   1.647 - *    FLAC__metadata_simple_iterator_init()
   1.648 - * \retval FLAC__bool
   1.649 - *    \c true if successful, else \c false.
   1.650 - */
   1.651 -FLAC_API FLAC__bool FLAC__metadata_simple_iterator_delete_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__bool use_padding);
   1.652 -
   1.653 -/* \} */
   1.654 -
   1.655 -
   1.656 -/** \defgroup flac_metadata_level2 FLAC/metadata.h: metadata level 2 interface
   1.657 - *  \ingroup flac_metadata
   1.658 - *
   1.659 - * \brief
   1.660 - * The level 2 interface provides read-write access to FLAC file metadata;
   1.661 - * all metadata is read into memory, operated on in memory, and then written
   1.662 - * to file, which is more efficient than level 1 when editing multiple blocks.
   1.663 - *
   1.664 - * Currently Ogg FLAC is supported for read only, via
   1.665 - * FLAC__metadata_chain_read_ogg() but a subsequent
   1.666 - * FLAC__metadata_chain_write() will fail.
   1.667 - *
   1.668 - * The general usage of this interface is:
   1.669 - *
   1.670 - * - Create a new chain using FLAC__metadata_chain_new().  A chain is a
   1.671 - *   linked list of FLAC metadata blocks.
   1.672 - * - Read all metadata into the the chain from a FLAC file using
   1.673 - *   FLAC__metadata_chain_read() or FLAC__metadata_chain_read_ogg() and
   1.674 - *   check the status.
   1.675 - * - Optionally, consolidate the padding using
   1.676 - *   FLAC__metadata_chain_merge_padding() or
   1.677 - *   FLAC__metadata_chain_sort_padding().
   1.678 - * - Create a new iterator using FLAC__metadata_iterator_new()
   1.679 - * - Initialize the iterator to point to the first element in the chain
   1.680 - *   using FLAC__metadata_iterator_init()
   1.681 - * - Traverse the chain using FLAC__metadata_iterator_next and
   1.682 - *   FLAC__metadata_iterator_prev().
   1.683 - * - Get a block for reading or modification using
   1.684 - *   FLAC__metadata_iterator_get_block().  The pointer to the object
   1.685 - *   inside the chain is returned, so the block is yours to modify.
   1.686 - *   Changes will be reflected in the FLAC file when you write the
   1.687 - *   chain.  You can also add and delete blocks (see functions below).
   1.688 - * - When done, write out the chain using FLAC__metadata_chain_write().
   1.689 - *   Make sure to read the whole comment to the function below.
   1.690 - * - Delete the chain using FLAC__metadata_chain_delete().
   1.691 - *
   1.692 - * \note
   1.693 - * Even though the FLAC file is not open while the chain is being
   1.694 - * manipulated, you must not alter the file externally during
   1.695 - * this time.  The chain assumes the FLAC file will not change
   1.696 - * between the time of FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg()
   1.697 - * and FLAC__metadata_chain_write().
   1.698 - *
   1.699 - * \note
   1.700 - * Do not modify the is_last, length, or type fields of returned
   1.701 - * FLAC__StreamMetadata objects.  These are managed automatically.
   1.702 - *
   1.703 - * \note
   1.704 - * The metadata objects returned by FLAC__metadata_iterator_get_block()
   1.705 - * are owned by the chain; do not FLAC__metadata_object_delete() them.
   1.706 - * In the same way, blocks passed to FLAC__metadata_iterator_set_block()
   1.707 - * become owned by the chain and they will be deleted when the chain is
   1.708 - * deleted.
   1.709 - *
   1.710 - * \{
   1.711 - */
   1.712 -
   1.713 -struct FLAC__Metadata_Chain;
   1.714 -/** The opaque structure definition for the level 2 chain type.
   1.715 - */
   1.716 -typedef struct FLAC__Metadata_Chain FLAC__Metadata_Chain;
   1.717 -
   1.718 -struct FLAC__Metadata_Iterator;
   1.719 -/** The opaque structure definition for the level 2 iterator type.
   1.720 - */
   1.721 -typedef struct FLAC__Metadata_Iterator FLAC__Metadata_Iterator;
   1.722 -
   1.723 -typedef enum {
   1.724 -	FLAC__METADATA_CHAIN_STATUS_OK = 0,
   1.725 -	/**< The chain is in the normal OK state */
   1.726 -
   1.727 -	FLAC__METADATA_CHAIN_STATUS_ILLEGAL_INPUT,
   1.728 -	/**< The data passed into a function violated the function's usage criteria */
   1.729 -
   1.730 -	FLAC__METADATA_CHAIN_STATUS_ERROR_OPENING_FILE,
   1.731 -	/**< The chain could not open the target file */
   1.732 -
   1.733 -	FLAC__METADATA_CHAIN_STATUS_NOT_A_FLAC_FILE,
   1.734 -	/**< The chain could not find the FLAC signature at the start of the file */
   1.735 -
   1.736 -	FLAC__METADATA_CHAIN_STATUS_NOT_WRITABLE,
   1.737 -	/**< The chain tried to write to a file that was not writable */
   1.738 -
   1.739 -	FLAC__METADATA_CHAIN_STATUS_BAD_METADATA,
   1.740 -	/**< The chain encountered input that does not conform to the FLAC metadata specification */
   1.741 -
   1.742 -	FLAC__METADATA_CHAIN_STATUS_READ_ERROR,
   1.743 -	/**< The chain encountered an error while reading the FLAC file */
   1.744 -
   1.745 -	FLAC__METADATA_CHAIN_STATUS_SEEK_ERROR,
   1.746 -	/**< The chain encountered an error while seeking in the FLAC file */
   1.747 -
   1.748 -	FLAC__METADATA_CHAIN_STATUS_WRITE_ERROR,
   1.749 -	/**< The chain encountered an error while writing the FLAC file */
   1.750 -
   1.751 -	FLAC__METADATA_CHAIN_STATUS_RENAME_ERROR,
   1.752 -	/**< The chain encountered an error renaming the FLAC file */
   1.753 -
   1.754 -	FLAC__METADATA_CHAIN_STATUS_UNLINK_ERROR,
   1.755 -	/**< The chain encountered an error removing the temporary file */
   1.756 -
   1.757 -	FLAC__METADATA_CHAIN_STATUS_MEMORY_ALLOCATION_ERROR,
   1.758 -	/**< Memory allocation failed */
   1.759 -
   1.760 -	FLAC__METADATA_CHAIN_STATUS_INTERNAL_ERROR,
   1.761 -	/**< The caller violated an assertion or an unexpected error occurred */
   1.762 -
   1.763 -	FLAC__METADATA_CHAIN_STATUS_INVALID_CALLBACKS,
   1.764 -	/**< One or more of the required callbacks was NULL */
   1.765 -
   1.766 -	FLAC__METADATA_CHAIN_STATUS_READ_WRITE_MISMATCH,
   1.767 -	/**< FLAC__metadata_chain_write() was called on a chain read by
   1.768 -	 *   FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(),
   1.769 -	 *   or 
   1.770 -	 *   FLAC__metadata_chain_write_with_callbacks()/FLAC__metadata_chain_write_with_callbacks_and_tempfile()
   1.771 -	 *   was called on a chain read by
   1.772 -	 *   FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg().
   1.773 -	 *   Matching read/write methods must always be used. */
   1.774 -
   1.775 -	FLAC__METADATA_CHAIN_STATUS_WRONG_WRITE_CALL
   1.776 -	/**< FLAC__metadata_chain_write_with_callbacks() was called when the
   1.777 -	 *   chain write requires a tempfile; use
   1.778 -	 *   FLAC__metadata_chain_write_with_callbacks_and_tempfile() instead.
   1.779 -	 *   Or, FLAC__metadata_chain_write_with_callbacks_and_tempfile() was
   1.780 -	 *   called when the chain write does not require a tempfile; use
   1.781 -	 *   FLAC__metadata_chain_write_with_callbacks() instead.
   1.782 -	 *   Always check FLAC__metadata_chain_check_if_tempfile_needed()
   1.783 -	 *   before writing via callbacks. */
   1.784 -
   1.785 -} FLAC__Metadata_ChainStatus;
   1.786 -
   1.787 -/** Maps a FLAC__Metadata_ChainStatus to a C string.
   1.788 - *
   1.789 - *  Using a FLAC__Metadata_ChainStatus as the index to this array
   1.790 - *  will give the string equivalent.  The contents should not be modified.
   1.791 - */
   1.792 -extern FLAC_API const char * const FLAC__Metadata_ChainStatusString[];
   1.793 -
   1.794 -/*********** FLAC__Metadata_Chain ***********/
   1.795 -
   1.796 -/** Create a new chain instance.
   1.797 - *
   1.798 - * \retval FLAC__Metadata_Chain*
   1.799 - *    \c NULL if there was an error allocating memory, else the new instance.
   1.800 - */
   1.801 -FLAC_API FLAC__Metadata_Chain *FLAC__metadata_chain_new(void);
   1.802 -
   1.803 -/** Free a chain instance.  Deletes the object pointed to by \a chain.
   1.804 - *
   1.805 - * \param chain  A pointer to an existing chain.
   1.806 - * \assert
   1.807 - *    \code chain != NULL \endcode
   1.808 - */
   1.809 -FLAC_API void FLAC__metadata_chain_delete(FLAC__Metadata_Chain *chain);
   1.810 -
   1.811 -/** Get the current status of the chain.  Call this after a function
   1.812 - *  returns \c false to get the reason for the error.  Also resets the
   1.813 - *  status to FLAC__METADATA_CHAIN_STATUS_OK.
   1.814 - *
   1.815 - * \param chain    A pointer to an existing chain.
   1.816 - * \assert
   1.817 - *    \code chain != NULL \endcode
   1.818 - * \retval FLAC__Metadata_ChainStatus
   1.819 - *    The current status of the chain.
   1.820 - */
   1.821 -FLAC_API FLAC__Metadata_ChainStatus FLAC__metadata_chain_status(FLAC__Metadata_Chain *chain);
   1.822 -
   1.823 -/** Read all metadata from a FLAC file into the chain.
   1.824 - *
   1.825 - * \param chain    A pointer to an existing chain.
   1.826 - * \param filename The path to the FLAC file to read.
   1.827 - * \assert
   1.828 - *    \code chain != NULL \endcode
   1.829 - *    \code filename != NULL \endcode
   1.830 - * \retval FLAC__bool
   1.831 - *    \c true if a valid list of metadata blocks was read from
   1.832 - *    \a filename, else \c false.  On failure, check the status with
   1.833 - *    FLAC__metadata_chain_status().
   1.834 - */
   1.835 -FLAC_API FLAC__bool FLAC__metadata_chain_read(FLAC__Metadata_Chain *chain, const char *filename);
   1.836 -
   1.837 -/** Read all metadata from an Ogg FLAC file into the chain.
   1.838 - *
   1.839 - * \note Ogg FLAC metadata data writing is not supported yet and
   1.840 - * FLAC__metadata_chain_write() will fail.
   1.841 - *
   1.842 - * \param chain    A pointer to an existing chain.
   1.843 - * \param filename The path to the Ogg FLAC file to read.
   1.844 - * \assert
   1.845 - *    \code chain != NULL \endcode
   1.846 - *    \code filename != NULL \endcode
   1.847 - * \retval FLAC__bool
   1.848 - *    \c true if a valid list of metadata blocks was read from
   1.849 - *    \a filename, else \c false.  On failure, check the status with
   1.850 - *    FLAC__metadata_chain_status().
   1.851 - */
   1.852 -FLAC_API FLAC__bool FLAC__metadata_chain_read_ogg(FLAC__Metadata_Chain *chain, const char *filename);
   1.853 -
   1.854 -/** Read all metadata from a FLAC stream into the chain via I/O callbacks.
   1.855 - *
   1.856 - *  The \a handle need only be open for reading, but must be seekable.
   1.857 - *  The equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb"
   1.858 - *  for Windows).
   1.859 - *
   1.860 - * \param chain    A pointer to an existing chain.
   1.861 - * \param handle   The I/O handle of the FLAC stream to read.  The
   1.862 - *                 handle will NOT be closed after the metadata is read;
   1.863 - *                 that is the duty of the caller.
   1.864 - * \param callbacks
   1.865 - *                 A set of callbacks to use for I/O.  The mandatory
   1.866 - *                 callbacks are \a read, \a seek, and \a tell.
   1.867 - * \assert
   1.868 - *    \code chain != NULL \endcode
   1.869 - * \retval FLAC__bool
   1.870 - *    \c true if a valid list of metadata blocks was read from
   1.871 - *    \a handle, else \c false.  On failure, check the status with
   1.872 - *    FLAC__metadata_chain_status().
   1.873 - */
   1.874 -FLAC_API FLAC__bool FLAC__metadata_chain_read_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
   1.875 -
   1.876 -/** Read all metadata from an Ogg FLAC stream into the chain via I/O callbacks.
   1.877 - *
   1.878 - *  The \a handle need only be open for reading, but must be seekable.
   1.879 - *  The equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb"
   1.880 - *  for Windows).
   1.881 - *
   1.882 - * \note Ogg FLAC metadata data writing is not supported yet and
   1.883 - * FLAC__metadata_chain_write() will fail.
   1.884 - *
   1.885 - * \param chain    A pointer to an existing chain.
   1.886 - * \param handle   The I/O handle of the Ogg FLAC stream to read.  The
   1.887 - *                 handle will NOT be closed after the metadata is read;
   1.888 - *                 that is the duty of the caller.
   1.889 - * \param callbacks
   1.890 - *                 A set of callbacks to use for I/O.  The mandatory
   1.891 - *                 callbacks are \a read, \a seek, and \a tell.
   1.892 - * \assert
   1.893 - *    \code chain != NULL \endcode
   1.894 - * \retval FLAC__bool
   1.895 - *    \c true if a valid list of metadata blocks was read from
   1.896 - *    \a handle, else \c false.  On failure, check the status with
   1.897 - *    FLAC__metadata_chain_status().
   1.898 - */
   1.899 -FLAC_API FLAC__bool FLAC__metadata_chain_read_ogg_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
   1.900 -
   1.901 -/** Checks if writing the given chain would require the use of a
   1.902 - *  temporary file, or if it could be written in place.
   1.903 - *
   1.904 - *  Under certain conditions, padding can be utilized so that writing
   1.905 - *  edited metadata back to the FLAC file does not require rewriting the
   1.906 - *  entire file.  If rewriting is required, then a temporary workfile is
   1.907 - *  required.  When writing metadata using callbacks, you must check
   1.908 - *  this function to know whether to call
   1.909 - *  FLAC__metadata_chain_write_with_callbacks() or
   1.910 - *  FLAC__metadata_chain_write_with_callbacks_and_tempfile().  When
   1.911 - *  writing with FLAC__metadata_chain_write(), the temporary file is
   1.912 - *  handled internally.
   1.913 - *
   1.914 - * \param chain    A pointer to an existing chain.
   1.915 - * \param use_padding
   1.916 - *                 Whether or not padding will be allowed to be used
   1.917 - *                 during the write.  The value of \a use_padding given
   1.918 - *                 here must match the value later passed to
   1.919 - *                 FLAC__metadata_chain_write_with_callbacks() or
   1.920 - *                 FLAC__metadata_chain_write_with_callbacks_with_tempfile().
   1.921 - * \assert
   1.922 - *    \code chain != NULL \endcode
   1.923 - * \retval FLAC__bool
   1.924 - *    \c true if writing the current chain would require a tempfile, or
   1.925 - *    \c false if metadata can be written in place.
   1.926 - */
   1.927 -FLAC_API FLAC__bool FLAC__metadata_chain_check_if_tempfile_needed(FLAC__Metadata_Chain *chain, FLAC__bool use_padding);
   1.928 -
   1.929 -/** Write all metadata out to the FLAC file.  This function tries to be as
   1.930 - *  efficient as possible; how the metadata is actually written is shown by
   1.931 - *  the following:
   1.932 - *
   1.933 - *  If the current chain is the same size as the existing metadata, the new
   1.934 - *  data is written in place.
   1.935 - *
   1.936 - *  If the current chain is longer than the existing metadata, and
   1.937 - *  \a use_padding is \c true, and the last block is a PADDING block of
   1.938 - *  sufficient length, the function will truncate the final padding block
   1.939 - *  so that the overall size of the metadata is the same as the existing
   1.940 - *  metadata, and then just rewrite the metadata.  Otherwise, if not all of
   1.941 - *  the above conditions are met, the entire FLAC file must be rewritten.
   1.942 - *  If you want to use padding this way it is a good idea to call
   1.943 - *  FLAC__metadata_chain_sort_padding() first so that you have the maximum
   1.944 - *  amount of padding to work with, unless you need to preserve ordering
   1.945 - *  of the PADDING blocks for some reason.
   1.946 - *
   1.947 - *  If the current chain is shorter than the existing metadata, and
   1.948 - *  \a use_padding is \c true, and the final block is a PADDING block, the padding
   1.949 - *  is extended to make the overall size the same as the existing data.  If
   1.950 - *  \a use_padding is \c true and the last block is not a PADDING block, a new
   1.951 - *  PADDING block is added to the end of the new data to make it the same
   1.952 - *  size as the existing data (if possible, see the note to
   1.953 - *  FLAC__metadata_simple_iterator_set_block() about the four byte limit)
   1.954 - *  and the new data is written in place.  If none of the above apply or
   1.955 - *  \a use_padding is \c false, the entire FLAC file is rewritten.
   1.956 - *
   1.957 - *  If \a preserve_file_stats is \c true, the owner and modification time will
   1.958 - *  be preserved even if the FLAC file is written.
   1.959 - *
   1.960 - *  For this write function to be used, the chain must have been read with
   1.961 - *  FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg(), not
   1.962 - *  FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks().
   1.963 - *
   1.964 - * \param chain               A pointer to an existing chain.
   1.965 - * \param use_padding         See above.
   1.966 - * \param preserve_file_stats See above.
   1.967 - * \assert
   1.968 - *    \code chain != NULL \endcode
   1.969 - * \retval FLAC__bool
   1.970 - *    \c true if the write succeeded, else \c false.  On failure,
   1.971 - *    check the status with FLAC__metadata_chain_status().
   1.972 - */
   1.973 -FLAC_API FLAC__bool FLAC__metadata_chain_write(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__bool preserve_file_stats);
   1.974 -
   1.975 -/** Write all metadata out to a FLAC stream via callbacks.
   1.976 - *
   1.977 - *  (See FLAC__metadata_chain_write() for the details on how padding is
   1.978 - *  used to write metadata in place if possible.)
   1.979 - *
   1.980 - *  The \a handle must be open for updating and be seekable.  The
   1.981 - *  equivalent minimum stdio fopen() file mode is \c "r+" (or \c "r+b"
   1.982 - *  for Windows).
   1.983 - *
   1.984 - *  For this write function to be used, the chain must have been read with
   1.985 - *  FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(),
   1.986 - *  not FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg().
   1.987 - *  Also, FLAC__metadata_chain_check_if_tempfile_needed() must have returned
   1.988 - *  \c false.
   1.989 - *
   1.990 - * \param chain        A pointer to an existing chain.
   1.991 - * \param use_padding  See FLAC__metadata_chain_write()
   1.992 - * \param handle       The I/O handle of the FLAC stream to write.  The
   1.993 - *                     handle will NOT be closed after the metadata is
   1.994 - *                     written; that is the duty of the caller.
   1.995 - * \param callbacks    A set of callbacks to use for I/O.  The mandatory
   1.996 - *                     callbacks are \a write and \a seek.
   1.997 - * \assert
   1.998 - *    \code chain != NULL \endcode
   1.999 - * \retval FLAC__bool
  1.1000 - *    \c true if the write succeeded, else \c false.  On failure,
  1.1001 - *    check the status with FLAC__metadata_chain_status().
  1.1002 - */
  1.1003 -FLAC_API FLAC__bool FLAC__metadata_chain_write_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
  1.1004 -
  1.1005 -/** Write all metadata out to a FLAC stream via callbacks.
  1.1006 - *
  1.1007 - *  (See FLAC__metadata_chain_write() for the details on how padding is
  1.1008 - *  used to write metadata in place if possible.)
  1.1009 - *
  1.1010 - *  This version of the write-with-callbacks function must be used when
  1.1011 - *  FLAC__metadata_chain_check_if_tempfile_needed() returns true.  In
  1.1012 - *  this function, you must supply an I/O handle corresponding to the
  1.1013 - *  FLAC file to edit, and a temporary handle to which the new FLAC
  1.1014 - *  file will be written.  It is the caller's job to move this temporary
  1.1015 - *  FLAC file on top of the original FLAC file to complete the metadata
  1.1016 - *  edit.
  1.1017 - *
  1.1018 - *  The \a handle must be open for reading and be seekable.  The
  1.1019 - *  equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb"
  1.1020 - *  for Windows).
  1.1021 - *
  1.1022 - *  The \a temp_handle must be open for writing.  The
  1.1023 - *  equivalent minimum stdio fopen() file mode is \c "w" (or \c "wb"
  1.1024 - *  for Windows).  It should be an empty stream, or at least positioned
  1.1025 - *  at the start-of-file (in which case it is the caller's duty to
  1.1026 - *  truncate it on return).
  1.1027 - *
  1.1028 - *  For this write function to be used, the chain must have been read with
  1.1029 - *  FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(),
  1.1030 - *  not FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg().
  1.1031 - *  Also, FLAC__metadata_chain_check_if_tempfile_needed() must have returned
  1.1032 - *  \c true.
  1.1033 - *
  1.1034 - * \param chain        A pointer to an existing chain.
  1.1035 - * \param use_padding  See FLAC__metadata_chain_write()
  1.1036 - * \param handle       The I/O handle of the original FLAC stream to read.
  1.1037 - *                     The handle will NOT be closed after the metadata is
  1.1038 - *                     written; that is the duty of the caller.
  1.1039 - * \param callbacks    A set of callbacks to use for I/O on \a handle.
  1.1040 - *                     The mandatory callbacks are \a read, \a seek, and
  1.1041 - *                     \a eof.
  1.1042 - * \param temp_handle  The I/O handle of the FLAC stream to write.  The
  1.1043 - *                     handle will NOT be closed after the metadata is
  1.1044 - *                     written; that is the duty of the caller.
  1.1045 - * \param temp_callbacks
  1.1046 - *                     A set of callbacks to use for I/O on temp_handle.
  1.1047 - *                     The only mandatory callback is \a write.
  1.1048 - * \assert
  1.1049 - *    \code chain != NULL \endcode
  1.1050 - * \retval FLAC__bool
  1.1051 - *    \c true if the write succeeded, else \c false.  On failure,
  1.1052 - *    check the status with FLAC__metadata_chain_status().
  1.1053 - */
  1.1054 -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);
  1.1055 -
  1.1056 -/** Merge adjacent PADDING blocks into a single block.
  1.1057 - *
  1.1058 - * \note This function does not write to the FLAC file, it only
  1.1059 - * modifies the chain.
  1.1060 - *
  1.1061 - * \warning Any iterator on the current chain will become invalid after this
  1.1062 - * call.  You should delete the iterator and get a new one.
  1.1063 - *
  1.1064 - * \param chain               A pointer to an existing chain.
  1.1065 - * \assert
  1.1066 - *    \code chain != NULL \endcode
  1.1067 - */
  1.1068 -FLAC_API void FLAC__metadata_chain_merge_padding(FLAC__Metadata_Chain *chain);
  1.1069 -
  1.1070 -/** This function will move all PADDING blocks to the end on the metadata,
  1.1071 - *  then merge them into a single block.
  1.1072 - *
  1.1073 - * \note This function does not write to the FLAC file, it only
  1.1074 - * modifies the chain.
  1.1075 - *
  1.1076 - * \warning Any iterator on the current chain will become invalid after this
  1.1077 - * call.  You should delete the iterator and get a new one.
  1.1078 - *
  1.1079 - * \param chain  A pointer to an existing chain.
  1.1080 - * \assert
  1.1081 - *    \code chain != NULL \endcode
  1.1082 - */
  1.1083 -FLAC_API void FLAC__metadata_chain_sort_padding(FLAC__Metadata_Chain *chain);
  1.1084 -
  1.1085 -
  1.1086 -/*********** FLAC__Metadata_Iterator ***********/
  1.1087 -
  1.1088 -/** Create a new iterator instance.
  1.1089 - *
  1.1090 - * \retval FLAC__Metadata_Iterator*
  1.1091 - *    \c NULL if there was an error allocating memory, else the new instance.
  1.1092 - */
  1.1093 -FLAC_API FLAC__Metadata_Iterator *FLAC__metadata_iterator_new(void);
  1.1094 -
  1.1095 -/** Free an iterator instance.  Deletes the object pointed to by \a iterator.
  1.1096 - *
  1.1097 - * \param iterator  A pointer to an existing iterator.
  1.1098 - * \assert
  1.1099 - *    \code iterator != NULL \endcode
  1.1100 - */
  1.1101 -FLAC_API void FLAC__metadata_iterator_delete(FLAC__Metadata_Iterator *iterator);
  1.1102 -
  1.1103 -/** Initialize the iterator to point to the first metadata block in the
  1.1104 - *  given chain.
  1.1105 - *
  1.1106 - * \param iterator  A pointer to an existing iterator.
  1.1107 - * \param chain     A pointer to an existing and initialized (read) chain.
  1.1108 - * \assert
  1.1109 - *    \code iterator != NULL \endcode
  1.1110 - *    \code chain != NULL \endcode
  1.1111 - */
  1.1112 -FLAC_API void FLAC__metadata_iterator_init(FLAC__Metadata_Iterator *iterator, FLAC__Metadata_Chain *chain);
  1.1113 -
  1.1114 -/** Moves the iterator forward one metadata block, returning \c false if
  1.1115 - *  already at the end.
  1.1116 - *
  1.1117 - * \param iterator  A pointer to an existing initialized iterator.
  1.1118 - * \assert
  1.1119 - *    \code iterator != NULL \endcode
  1.1120 - *    \a iterator has been successfully initialized with
  1.1121 - *    FLAC__metadata_iterator_init()
  1.1122 - * \retval FLAC__bool
  1.1123 - *    \c false if already at the last metadata block of the chain, else
  1.1124 - *    \c true.
  1.1125 - */
  1.1126 -FLAC_API FLAC__bool FLAC__metadata_iterator_next(FLAC__Metadata_Iterator *iterator);
  1.1127 -
  1.1128 -/** Moves the iterator backward one metadata block, returning \c false if
  1.1129 - *  already at the beginning.
  1.1130 - *
  1.1131 - * \param iterator  A pointer to an existing initialized iterator.
  1.1132 - * \assert
  1.1133 - *    \code iterator != NULL \endcode
  1.1134 - *    \a iterator has been successfully initialized with
  1.1135 - *    FLAC__metadata_iterator_init()
  1.1136 - * \retval FLAC__bool
  1.1137 - *    \c false if already at the first metadata block of the chain, else
  1.1138 - *    \c true.
  1.1139 - */
  1.1140 -FLAC_API FLAC__bool FLAC__metadata_iterator_prev(FLAC__Metadata_Iterator *iterator);
  1.1141 -
  1.1142 -/** Get the type of the metadata block at the current position.
  1.1143 - *
  1.1144 - * \param iterator  A pointer to an existing initialized iterator.
  1.1145 - * \assert
  1.1146 - *    \code iterator != NULL \endcode
  1.1147 - *    \a iterator has been successfully initialized with
  1.1148 - *    FLAC__metadata_iterator_init()
  1.1149 - * \retval FLAC__MetadataType
  1.1150 - *    The type of the metadata block at the current iterator position.
  1.1151 - */
  1.1152 -FLAC_API FLAC__MetadataType FLAC__metadata_iterator_get_block_type(const FLAC__Metadata_Iterator *iterator);
  1.1153 -
  1.1154 -/** Get the metadata block at the current position.  You can modify
  1.1155 - *  the block in place but must write the chain before the changes
  1.1156 - *  are reflected to the FLAC file.  You do not need to call
  1.1157 - *  FLAC__metadata_iterator_set_block() to reflect the changes;
  1.1158 - *  the pointer returned by FLAC__metadata_iterator_get_block()
  1.1159 - *  points directly into the chain.
  1.1160 - *
  1.1161 - * \warning
  1.1162 - * Do not call FLAC__metadata_object_delete() on the returned object;
  1.1163 - * to delete a block use FLAC__metadata_iterator_delete_block().
  1.1164 - *
  1.1165 - * \param iterator  A pointer to an existing initialized iterator.
  1.1166 - * \assert
  1.1167 - *    \code iterator != NULL \endcode
  1.1168 - *    \a iterator has been successfully initialized with
  1.1169 - *    FLAC__metadata_iterator_init()
  1.1170 - * \retval FLAC__StreamMetadata*
  1.1171 - *    The current metadata block.
  1.1172 - */
  1.1173 -FLAC_API FLAC__StreamMetadata *FLAC__metadata_iterator_get_block(FLAC__Metadata_Iterator *iterator);
  1.1174 -
  1.1175 -/** Set the metadata block at the current position, replacing the existing
  1.1176 - *  block.  The new block passed in becomes owned by the chain and it will be
  1.1177 - *  deleted when the chain is deleted.
  1.1178 - *
  1.1179 - * \param iterator  A pointer to an existing initialized iterator.
  1.1180 - * \param block     A pointer to a metadata block.
  1.1181 - * \assert
  1.1182 - *    \code iterator != NULL \endcode
  1.1183 - *    \a iterator has been successfully initialized with
  1.1184 - *    FLAC__metadata_iterator_init()
  1.1185 - *    \code block != NULL \endcode
  1.1186 - * \retval FLAC__bool
  1.1187 - *    \c false if the conditions in the above description are not met, or
  1.1188 - *    a memory allocation error occurs, otherwise \c true.
  1.1189 - */
  1.1190 -FLAC_API FLAC__bool FLAC__metadata_iterator_set_block(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
  1.1191 -
  1.1192 -/** Removes the current block from the chain.  If \a replace_with_padding is
  1.1193 - *  \c true, the block will instead be replaced with a padding block of equal
  1.1194 - *  size.  You can not delete the STREAMINFO block.  The iterator will be
  1.1195 - *  left pointing to the block before the one just "deleted", even if
  1.1196 - *  \a replace_with_padding is \c true.
  1.1197 - *
  1.1198 - * \param iterator              A pointer to an existing initialized iterator.
  1.1199 - * \param replace_with_padding  See above.
  1.1200 - * \assert
  1.1201 - *    \code iterator != NULL \endcode
  1.1202 - *    \a iterator has been successfully initialized with
  1.1203 - *    FLAC__metadata_iterator_init()
  1.1204 - * \retval FLAC__bool
  1.1205 - *    \c false if the conditions in the above description are not met,
  1.1206 - *    otherwise \c true.
  1.1207 - */
  1.1208 -FLAC_API FLAC__bool FLAC__metadata_iterator_delete_block(FLAC__Metadata_Iterator *iterator, FLAC__bool replace_with_padding);
  1.1209 -
  1.1210 -/** Insert a new block before the current block.  You cannot insert a block
  1.1211 - *  before the first STREAMINFO block.  You cannot insert a STREAMINFO block
  1.1212 - *  as there can be only one, the one that already exists at the head when you
  1.1213 - *  read in a chain.  The chain takes ownership of the new block and it will be
  1.1214 - *  deleted when the chain is deleted.  The iterator will be left pointing to
  1.1215 - *  the new block.
  1.1216 - *
  1.1217 - * \param iterator  A pointer to an existing initialized iterator.
  1.1218 - * \param block     A pointer to a metadata block to insert.
  1.1219 - * \assert
  1.1220 - *    \code iterator != NULL \endcode
  1.1221 - *    \a iterator has been successfully initialized with
  1.1222 - *    FLAC__metadata_iterator_init()
  1.1223 - * \retval FLAC__bool
  1.1224 - *    \c false if the conditions in the above description are not met, or
  1.1225 - *    a memory allocation error occurs, otherwise \c true.
  1.1226 - */
  1.1227 -FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_before(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
  1.1228 -
  1.1229 -/** Insert a new block after the current block.  You cannot insert a STREAMINFO
  1.1230 - *  block as there can be only one, the one that already exists at the head when
  1.1231 - *  you read in a chain.  The chain takes ownership of the new block and it will
  1.1232 - *  be deleted when the chain is deleted.  The iterator will be left pointing to
  1.1233 - *  the new block.
  1.1234 - *
  1.1235 - * \param iterator  A pointer to an existing initialized iterator.
  1.1236 - * \param block     A pointer to a metadata block to insert.
  1.1237 - * \assert
  1.1238 - *    \code iterator != NULL \endcode
  1.1239 - *    \a iterator has been successfully initialized with
  1.1240 - *    FLAC__metadata_iterator_init()
  1.1241 - * \retval FLAC__bool
  1.1242 - *    \c false if the conditions in the above description are not met, or
  1.1243 - *    a memory allocation error occurs, otherwise \c true.
  1.1244 - */
  1.1245 -FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_after(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
  1.1246 -
  1.1247 -/* \} */
  1.1248 -
  1.1249 -
  1.1250 -/** \defgroup flac_metadata_object FLAC/metadata.h: metadata object methods
  1.1251 - *  \ingroup flac_metadata
  1.1252 - *
  1.1253 - * \brief
  1.1254 - * This module contains methods for manipulating FLAC metadata objects.
  1.1255 - *
  1.1256 - * Since many are variable length we have to be careful about the memory
  1.1257 - * management.  We decree that all pointers to data in the object are
  1.1258 - * owned by the object and memory-managed by the object.
  1.1259 - *
  1.1260 - * Use the FLAC__metadata_object_new() and FLAC__metadata_object_delete()
  1.1261 - * functions to create all instances.  When using the
  1.1262 - * FLAC__metadata_object_set_*() functions to set pointers to data, set
  1.1263 - * \a copy to \c true to have the function make it's own copy of the data, or
  1.1264 - * to \c false to give the object ownership of your data.  In the latter case
  1.1265 - * your pointer must be freeable by free() and will be free()d when the object
  1.1266 - * is FLAC__metadata_object_delete()d.  It is legal to pass a null pointer as
  1.1267 - * the data pointer to a FLAC__metadata_object_set_*() function as long as
  1.1268 - * the length argument is 0 and the \a copy argument is \c false.
  1.1269 - *
  1.1270 - * The FLAC__metadata_object_new() and FLAC__metadata_object_clone() function
  1.1271 - * will return \c NULL in the case of a memory allocation error, otherwise a new
  1.1272 - * object.  The FLAC__metadata_object_set_*() functions return \c false in the
  1.1273 - * case of a memory allocation error.
  1.1274 - *
  1.1275 - * We don't have the convenience of C++ here, so note that the library relies
  1.1276 - * on you to keep the types straight.  In other words, if you pass, for
  1.1277 - * example, a FLAC__StreamMetadata* that represents a STREAMINFO block to
  1.1278 - * FLAC__metadata_object_application_set_data(), you will get an assertion
  1.1279 - * failure.
  1.1280 - *
  1.1281 - * For convenience the FLAC__metadata_object_vorbiscomment_*() functions
  1.1282 - * maintain a trailing NUL on each Vorbis comment entry.  This is not counted
  1.1283 - * toward the length or stored in the stream, but it can make working with plain
  1.1284 - * comments (those that don't contain embedded-NULs in the value) easier.
  1.1285 - * Entries passed into these functions have trailing NULs added if missing, and
  1.1286 - * returned entries are guaranteed to have a trailing NUL.
  1.1287 - *
  1.1288 - * The FLAC__metadata_object_vorbiscomment_*() functions that take a Vorbis
  1.1289 - * comment entry/name/value will first validate that it complies with the Vorbis
  1.1290 - * comment specification and return false if it does not.
  1.1291 - *
  1.1292 - * There is no need to recalculate the length field on metadata blocks you
  1.1293 - * have modified.  They will be calculated automatically before they  are
  1.1294 - * written back to a file.
  1.1295 - *
  1.1296 - * \{
  1.1297 - */
  1.1298 -
  1.1299 -
  1.1300 -/** Create a new metadata object instance of the given type.
  1.1301 - *
  1.1302 - *  The object will be "empty"; i.e. values and data pointers will be \c 0,
  1.1303 - *  with the exception of FLAC__METADATA_TYPE_VORBIS_COMMENT, which will have
  1.1304 - *  the vendor string set (but zero comments).
  1.1305 - *
  1.1306 - *  Do not pass in a value greater than or equal to
  1.1307 - *  \a FLAC__METADATA_TYPE_UNDEFINED unless you really know what you're
  1.1308 - *  doing.
  1.1309 - *
  1.1310 - * \param type  Type of object to create
  1.1311 - * \retval FLAC__StreamMetadata*
  1.1312 - *    \c NULL if there was an error allocating memory or the type code is
  1.1313 - *    greater than FLAC__MAX_METADATA_TYPE_CODE, else the new instance.
  1.1314 - */
  1.1315 -FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_new(FLAC__MetadataType type);
  1.1316 -
  1.1317 -/** Create a copy of an existing metadata object.
  1.1318 - *
  1.1319 - *  The copy is a "deep" copy, i.e. dynamically allocated data within the
  1.1320 - *  object is also copied.  The caller takes ownership of the new block and
  1.1321 - *  is responsible for freeing it with FLAC__metadata_object_delete().
  1.1322 - *
  1.1323 - * \param object  Pointer to object to copy.
  1.1324 - * \assert
  1.1325 - *    \code object != NULL \endcode
  1.1326 - * \retval FLAC__StreamMetadata*
  1.1327 - *    \c NULL if there was an error allocating memory, else the new instance.
  1.1328 - */
  1.1329 -FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_clone(const FLAC__StreamMetadata *object);
  1.1330 -
  1.1331 -/** Free a metadata object.  Deletes the object pointed to by \a object.
  1.1332 - *
  1.1333 - *  The delete is a "deep" delete, i.e. dynamically allocated data within the
  1.1334 - *  object is also deleted.
  1.1335 - *
  1.1336 - * \param object  A pointer to an existing object.
  1.1337 - * \assert
  1.1338 - *    \code object != NULL \endcode
  1.1339 - */
  1.1340 -FLAC_API void FLAC__metadata_object_delete(FLAC__StreamMetadata *object);
  1.1341 -
  1.1342 -/** Compares two metadata objects.
  1.1343 - *
  1.1344 - *  The compare is "deep", i.e. dynamically allocated data within the
  1.1345 - *  object is also compared.
  1.1346 - *
  1.1347 - * \param block1  A pointer to an existing object.
  1.1348 - * \param block2  A pointer to an existing object.
  1.1349 - * \assert
  1.1350 - *    \code block1 != NULL \endcode
  1.1351 - *    \code block2 != NULL \endcode
  1.1352 - * \retval FLAC__bool
  1.1353 - *    \c true if objects are identical, else \c false.
  1.1354 - */
  1.1355 -FLAC_API FLAC__bool FLAC__metadata_object_is_equal(const FLAC__StreamMetadata *block1, const FLAC__StreamMetadata *block2);
  1.1356 -
  1.1357 -/** Sets the application data of an APPLICATION block.
  1.1358 - *
  1.1359 - *  If \a copy is \c true, a copy of the data is stored; otherwise, the object
  1.1360 - *  takes ownership of the pointer.  The existing data will be freed if this
  1.1361 - *  function is successful, otherwise the original data will remain if \a copy
  1.1362 - *  is \c true and malloc() fails.
  1.1363 - *
  1.1364 - * \note It is safe to pass a const pointer to \a data if \a copy is \c true.
  1.1365 - *
  1.1366 - * \param object  A pointer to an existing APPLICATION object.
  1.1367 - * \param data    A pointer to the data to set.
  1.1368 - * \param length  The length of \a data in bytes.
  1.1369 - * \param copy    See above.
  1.1370 - * \assert
  1.1371 - *    \code object != NULL \endcode
  1.1372 - *    \code object->type == FLAC__METADATA_TYPE_APPLICATION \endcode
  1.1373 - *    \code (data != NULL && length > 0) ||
  1.1374 - * (data == NULL && length == 0 && copy == false) \endcode
  1.1375 - * \retval FLAC__bool
  1.1376 - *    \c false if \a copy is \c true and malloc() fails, else \c true.
  1.1377 - */
  1.1378 -FLAC_API FLAC__bool FLAC__metadata_object_application_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, unsigned length, FLAC__bool copy);
  1.1379 -
  1.1380 -/** Resize the seekpoint array.
  1.1381 - *
  1.1382 - *  If the size shrinks, elements will truncated; if it grows, new placeholder
  1.1383 - *  points will be added to the end.
  1.1384 - *
  1.1385 - * \param object          A pointer to an existing SEEKTABLE object.
  1.1386 - * \param new_num_points  The desired length of the array; may be \c 0.
  1.1387 - * \assert
  1.1388 - *    \code object != NULL \endcode
  1.1389 - *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  1.1390 - *    \code (object->data.seek_table.points == NULL && object->data.seek_table.num_points == 0) ||
  1.1391 - * (object->data.seek_table.points != NULL && object->data.seek_table.num_points > 0) \endcode
  1.1392 - * \retval FLAC__bool
  1.1393 - *    \c false if memory allocation error, else \c true.
  1.1394 - */
  1.1395 -FLAC_API FLAC__bool FLAC__metadata_object_seektable_resize_points(FLAC__StreamMetadata *object, unsigned new_num_points);
  1.1396 -
  1.1397 -/** Set a seekpoint in a seektable.
  1.1398 - *
  1.1399 - * \param object     A pointer to an existing SEEKTABLE object.
  1.1400 - * \param point_num  Index into seekpoint array to set.
  1.1401 - * \param point      The point to set.
  1.1402 - * \assert
  1.1403 - *    \code object != NULL \endcode
  1.1404 - *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  1.1405 - *    \code object->data.seek_table.num_points > point_num \endcode
  1.1406 - */
  1.1407 -FLAC_API void FLAC__metadata_object_seektable_set_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point);
  1.1408 -
  1.1409 -/** Insert a seekpoint into a seektable.
  1.1410 - *
  1.1411 - * \param object     A pointer to an existing SEEKTABLE object.
  1.1412 - * \param point_num  Index into seekpoint array to set.
  1.1413 - * \param point      The point to set.
  1.1414 - * \assert
  1.1415 - *    \code object != NULL \endcode
  1.1416 - *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  1.1417 - *    \code object->data.seek_table.num_points >= point_num \endcode
  1.1418 - * \retval FLAC__bool
  1.1419 - *    \c false if memory allocation error, else \c true.
  1.1420 - */
  1.1421 -FLAC_API FLAC__bool FLAC__metadata_object_seektable_insert_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point);
  1.1422 -
  1.1423 -/** Delete a seekpoint from a seektable.
  1.1424 - *
  1.1425 - * \param object     A pointer to an existing SEEKTABLE object.
  1.1426 - * \param point_num  Index into seekpoint array to set.
  1.1427 - * \assert
  1.1428 - *    \code object != NULL \endcode
  1.1429 - *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  1.1430 - *    \code object->data.seek_table.num_points > point_num \endcode
  1.1431 - * \retval FLAC__bool
  1.1432 - *    \c false if memory allocation error, else \c true.
  1.1433 - */
  1.1434 -FLAC_API FLAC__bool FLAC__metadata_object_seektable_delete_point(FLAC__StreamMetadata *object, unsigned point_num);
  1.1435 -
  1.1436 -/** Check a seektable to see if it conforms to the FLAC specification.
  1.1437 - *  See the format specification for limits on the contents of the
  1.1438 - *  seektable.
  1.1439 - *
  1.1440 - * \param object  A pointer to an existing SEEKTABLE object.
  1.1441 - * \assert
  1.1442 - *    \code object != NULL \endcode
  1.1443 - *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  1.1444 - * \retval FLAC__bool
  1.1445 - *    \c false if seek table is illegal, else \c true.
  1.1446 - */
  1.1447 -FLAC_API FLAC__bool FLAC__metadata_object_seektable_is_legal(const FLAC__StreamMetadata *object);
  1.1448 -
  1.1449 -/** Append a number of placeholder points to the end of a seek table.
  1.1450 - *
  1.1451 - * \note
  1.1452 - * As with the other ..._seektable_template_... functions, you should
  1.1453 - * call FLAC__metadata_object_seektable_template_sort() when finished
  1.1454 - * to make the seek table legal.
  1.1455 - *
  1.1456 - * \param object  A pointer to an existing SEEKTABLE object.
  1.1457 - * \param num     The number of placeholder points to append.
  1.1458 - * \assert
  1.1459 - *    \code object != NULL \endcode
  1.1460 - *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  1.1461 - * \retval FLAC__bool
  1.1462 - *    \c false if memory allocation fails, else \c true.
  1.1463 - */
  1.1464 -FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_placeholders(FLAC__StreamMetadata *object, unsigned num);
  1.1465 -
  1.1466 -/** Append a specific seek point template to the end of a seek table.
  1.1467 - *
  1.1468 - * \note
  1.1469 - * As with the other ..._seektable_template_... functions, you should
  1.1470 - * call FLAC__metadata_object_seektable_template_sort() when finished
  1.1471 - * to make the seek table legal.
  1.1472 - *
  1.1473 - * \param object  A pointer to an existing SEEKTABLE object.
  1.1474 - * \param sample_number  The sample number of the seek point template.
  1.1475 - * \assert
  1.1476 - *    \code object != NULL \endcode
  1.1477 - *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  1.1478 - * \retval FLAC__bool
  1.1479 - *    \c false if memory allocation fails, else \c true.
  1.1480 - */
  1.1481 -FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_point(FLAC__StreamMetadata *object, FLAC__uint64 sample_number);
  1.1482 -
  1.1483 -/** Append specific seek point templates to the end of a seek table.
  1.1484 - *
  1.1485 - * \note
  1.1486 - * As with the other ..._seektable_template_... functions, you should
  1.1487 - * call FLAC__metadata_object_seektable_template_sort() when finished
  1.1488 - * to make the seek table legal.
  1.1489 - *
  1.1490 - * \param object  A pointer to an existing SEEKTABLE object.
  1.1491 - * \param sample_numbers  An array of sample numbers for the seek points.
  1.1492 - * \param num     The number of seek point templates to append.
  1.1493 - * \assert
  1.1494 - *    \code object != NULL \endcode
  1.1495 - *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  1.1496 - * \retval FLAC__bool
  1.1497 - *    \c false if memory allocation fails, else \c true.
  1.1498 - */
  1.1499 -FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_points(FLAC__StreamMetadata *object, FLAC__uint64 sample_numbers[], unsigned num);
  1.1500 -
  1.1501 -/** Append a set of evenly-spaced seek point templates to the end of a
  1.1502 - *  seek table.
  1.1503 - *
  1.1504 - * \note
  1.1505 - * As with the other ..._seektable_template_... functions, you should
  1.1506 - * call FLAC__metadata_object_seektable_template_sort() when finished
  1.1507 - * to make the seek table legal.
  1.1508 - *
  1.1509 - * \param object  A pointer to an existing SEEKTABLE object.
  1.1510 - * \param num     The number of placeholder points to append.
  1.1511 - * \param total_samples  The total number of samples to be encoded;
  1.1512 - *                       the seekpoints will be spaced approximately
  1.1513 - *                       \a total_samples / \a num samples apart.
  1.1514 - * \assert
  1.1515 - *    \code object != NULL \endcode
  1.1516 - *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  1.1517 - *    \code total_samples > 0 \endcode
  1.1518 - * \retval FLAC__bool
  1.1519 - *    \c false if memory allocation fails, else \c true.
  1.1520 - */
  1.1521 -FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points(FLAC__StreamMetadata *object, unsigned num, FLAC__uint64 total_samples);
  1.1522 -
  1.1523 -/** Append a set of evenly-spaced seek point templates to the end of a
  1.1524 - *  seek table.
  1.1525 - *
  1.1526 - * \note
  1.1527 - * As with the other ..._seektable_template_... functions, you should
  1.1528 - * call FLAC__metadata_object_seektable_template_sort() when finished
  1.1529 - * to make the seek table legal.
  1.1530 - *
  1.1531 - * \param object  A pointer to an existing SEEKTABLE object.
  1.1532 - * \param samples The number of samples apart to space the placeholder
  1.1533 - *                points.  The first point will be at sample \c 0, the
  1.1534 - *                second at sample \a samples, then 2*\a samples, and
  1.1535 - *                so on.  As long as \a samples and \a total_samples
  1.1536 - *                are greater than \c 0, there will always be at least
  1.1537 - *                one seekpoint at sample \c 0.
  1.1538 - * \param total_samples  The total number of samples to be encoded;
  1.1539 - *                       the seekpoints will be spaced
  1.1540 - *                       \a samples samples apart.
  1.1541 - * \assert
  1.1542 - *    \code object != NULL \endcode
  1.1543 - *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  1.1544 - *    \code samples > 0 \endcode
  1.1545 - *    \code total_samples > 0 \endcode
  1.1546 - * \retval FLAC__bool
  1.1547 - *    \c false if memory allocation fails, else \c true.
  1.1548 - */
  1.1549 -FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points_by_samples(FLAC__StreamMetadata *object, unsigned samples, FLAC__uint64 total_samples);
  1.1550 -
  1.1551 -/** Sort a seek table's seek points according to the format specification,
  1.1552 - *  removing duplicates.
  1.1553 - *
  1.1554 - * \param object   A pointer to a seek table to be sorted.
  1.1555 - * \param compact  If \c false, behaves like FLAC__format_seektable_sort().
  1.1556 - *                 If \c true, duplicates are deleted and the seek table is
  1.1557 - *                 shrunk appropriately; the number of placeholder points
  1.1558 - *                 present in the seek table will be the same after the call
  1.1559 - *                 as before.
  1.1560 - * \assert
  1.1561 - *    \code object != NULL \endcode
  1.1562 - *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  1.1563 - * \retval FLAC__bool
  1.1564 - *    \c false if realloc() fails, else \c true.
  1.1565 - */
  1.1566 -FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_sort(FLAC__StreamMetadata *object, FLAC__bool compact);
  1.1567 -
  1.1568 -/** Sets the vendor string in a VORBIS_COMMENT block.
  1.1569 - *
  1.1570 - *  For convenience, a trailing NUL is added to the entry if it doesn't have
  1.1571 - *  one already.
  1.1572 - *
  1.1573 - *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
  1.1574 - *  takes ownership of the \c entry.entry pointer.
  1.1575 - *
  1.1576 - *  \note If this function returns \c false, the caller still owns the
  1.1577 - *  pointer.
  1.1578 - *
  1.1579 - * \param object  A pointer to an existing VORBIS_COMMENT object.
  1.1580 - * \param entry   The entry to set the vendor string to.
  1.1581 - * \param copy    See above.
  1.1582 - * \assert
  1.1583 - *    \code object != NULL \endcode
  1.1584 - *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  1.1585 - *    \code (entry.entry != NULL && entry.length > 0) ||
  1.1586 - * (entry.entry == NULL && entry.length == 0) \endcode
  1.1587 - * \retval FLAC__bool
  1.1588 - *    \c false if memory allocation fails or \a entry does not comply with the
  1.1589 - *    Vorbis comment specification, else \c true.
  1.1590 - */
  1.1591 -FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_vendor_string(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
  1.1592 -
  1.1593 -/** Resize the comment array.
  1.1594 - *
  1.1595 - *  If the size shrinks, elements will truncated; if it grows, new empty
  1.1596 - *  fields will be added to the end.
  1.1597 - *
  1.1598 - * \param object            A pointer to an existing VORBIS_COMMENT object.
  1.1599 - * \param new_num_comments  The desired length of the array; may be \c 0.
  1.1600 - * \assert
  1.1601 - *    \code object != NULL \endcode
  1.1602 - *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  1.1603 - *    \code (object->data.vorbis_comment.comments == NULL && object->data.vorbis_comment.num_comments == 0) ||
  1.1604 - * (object->data.vorbis_comment.comments != NULL && object->data.vorbis_comment.num_comments > 0) \endcode
  1.1605 - * \retval FLAC__bool
  1.1606 - *    \c false if memory allocation fails, else \c true.
  1.1607 - */
  1.1608 -FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_resize_comments(FLAC__StreamMetadata *object, unsigned new_num_comments);
  1.1609 -
  1.1610 -/** Sets a comment in a VORBIS_COMMENT block.
  1.1611 - *
  1.1612 - *  For convenience, a trailing NUL is added to the entry if it doesn't have
  1.1613 - *  one already.
  1.1614 - *
  1.1615 - *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
  1.1616 - *  takes ownership of the \c entry.entry pointer.
  1.1617 - *
  1.1618 - *  \note If this function returns \c false, the caller still owns the
  1.1619 - *  pointer.
  1.1620 - *
  1.1621 - * \param object       A pointer to an existing VORBIS_COMMENT object.
  1.1622 - * \param comment_num  Index into comment array to set.
  1.1623 - * \param entry        The entry to set the comment to.
  1.1624 - * \param copy         See above.
  1.1625 - * \assert
  1.1626 - *    \code object != NULL \endcode
  1.1627 - *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  1.1628 - *    \code comment_num < object->data.vorbis_comment.num_comments \endcode
  1.1629 - *    \code (entry.entry != NULL && entry.length > 0) ||
  1.1630 - * (entry.entry == NULL && entry.length == 0) \endcode
  1.1631 - * \retval FLAC__bool
  1.1632 - *    \c false if memory allocation fails or \a entry does not comply with the
  1.1633 - *    Vorbis comment specification, else \c true.
  1.1634 - */
  1.1635 -FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
  1.1636 -
  1.1637 -/** Insert a comment in a VORBIS_COMMENT block at the given index.
  1.1638 - *
  1.1639 - *  For convenience, a trailing NUL is added to the entry if it doesn't have
  1.1640 - *  one already.
  1.1641 - *
  1.1642 - *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
  1.1643 - *  takes ownership of the \c entry.entry pointer.
  1.1644 - *
  1.1645 - *  \note If this function returns \c false, the caller still owns the
  1.1646 - *  pointer.
  1.1647 - *
  1.1648 - * \param object       A pointer to an existing VORBIS_COMMENT object.
  1.1649 - * \param comment_num  The index at which to insert the comment.  The comments
  1.1650 - *                     at and after \a comment_num move right one position.
  1.1651 - *                     To append a comment to the end, set \a comment_num to
  1.1652 - *                     \c object->data.vorbis_comment.num_comments .
  1.1653 - * \param entry        The comment to insert.
  1.1654 - * \param copy         See above.
  1.1655 - * \assert
  1.1656 - *    \code object != NULL \endcode
  1.1657 - *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  1.1658 - *    \code object->data.vorbis_comment.num_comments >= comment_num \endcode
  1.1659 - *    \code (entry.entry != NULL && entry.length > 0) ||
  1.1660 - * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode
  1.1661 - * \retval FLAC__bool
  1.1662 - *    \c false if memory allocation fails or \a entry does not comply with the
  1.1663 - *    Vorbis comment specification, else \c true.
  1.1664 - */
  1.1665 -FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_insert_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
  1.1666 -
  1.1667 -/** Appends a comment to a VORBIS_COMMENT block.
  1.1668 - *
  1.1669 - *  For convenience, a trailing NUL is added to the entry if it doesn't have
  1.1670 - *  one already.
  1.1671 - *
  1.1672 - *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
  1.1673 - *  takes ownership of the \c entry.entry pointer.
  1.1674 - *
  1.1675 - *  \note If this function returns \c false, the caller still owns the
  1.1676 - *  pointer.
  1.1677 - *
  1.1678 - * \param object       A pointer to an existing VORBIS_COMMENT object.
  1.1679 - * \param entry        The comment to insert.
  1.1680 - * \param copy         See above.
  1.1681 - * \assert
  1.1682 - *    \code object != NULL \endcode
  1.1683 - *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  1.1684 - *    \code (entry.entry != NULL && entry.length > 0) ||
  1.1685 - * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode
  1.1686 - * \retval FLAC__bool
  1.1687 - *    \c false if memory allocation fails or \a entry does not comply with the
  1.1688 - *    Vorbis comment specification, else \c true.
  1.1689 - */
  1.1690 -FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_append_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
  1.1691 -
  1.1692 -/** Replaces comments in a VORBIS_COMMENT block with a new one.
  1.1693 - *
  1.1694 - *  For convenience, a trailing NUL is added to the entry if it doesn't have
  1.1695 - *  one already.
  1.1696 - *
  1.1697 - *  Depending on the the value of \a all, either all or just the first comment
  1.1698 - *  whose field name(s) match the given entry's name will be replaced by the
  1.1699 - *  given entry.  If no comments match, \a entry will simply be appended.
  1.1700 - *
  1.1701 - *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
  1.1702 - *  takes ownership of the \c entry.entry pointer.
  1.1703 - *
  1.1704 - *  \note If this function returns \c false, the caller still owns the
  1.1705 - *  pointer.
  1.1706 - *
  1.1707 - * \param object       A pointer to an existing VORBIS_COMMENT object.
  1.1708 - * \param entry        The comment to insert.
  1.1709 - * \param all          If \c true, all comments whose field name matches
  1.1710 - *                     \a entry's field name will be removed, and \a entry will
  1.1711 - *                     be inserted at the position of the first matching
  1.1712 - *                     comment.  If \c false, only the first comment whose
  1.1713 - *                     field name matches \a entry's field name will be
  1.1714 - *                     replaced with \a entry.
  1.1715 - * \param copy         See above.
  1.1716 - * \assert
  1.1717 - *    \code object != NULL \endcode
  1.1718 - *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  1.1719 - *    \code (entry.entry != NULL && entry.length > 0) ||
  1.1720 - * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode
  1.1721 - * \retval FLAC__bool
  1.1722 - *    \c false if memory allocation fails or \a entry does not comply with the
  1.1723 - *    Vorbis comment specification, else \c true.
  1.1724 - */
  1.1725 -FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_replace_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool all, FLAC__bool copy);
  1.1726 -
  1.1727 -/** Delete a comment in a VORBIS_COMMENT block at the given index.
  1.1728 - *
  1.1729 - * \param object       A pointer to an existing VORBIS_COMMENT object.
  1.1730 - * \param comment_num  The index of the comment to delete.
  1.1731 - * \assert
  1.1732 - *    \code object != NULL \endcode
  1.1733 - *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  1.1734 - *    \code object->data.vorbis_comment.num_comments > comment_num \endcode
  1.1735 - * \retval FLAC__bool
  1.1736 - *    \c false if realloc() fails, else \c true.
  1.1737 - */
  1.1738 -FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_delete_comment(FLAC__StreamMetadata *object, unsigned comment_num);
  1.1739 -
  1.1740 -/** Creates a Vorbis comment entry from NUL-terminated name and value strings.
  1.1741 - *
  1.1742 - *  On return, the filled-in \a entry->entry pointer will point to malloc()ed
  1.1743 - *  memory and shall be owned by the caller.  For convenience the entry will
  1.1744 - *  have a terminating NUL.
  1.1745 - *
  1.1746 - * \param entry              A pointer to a Vorbis comment entry.  The entry's
  1.1747 - *                           \c entry pointer should not point to allocated
  1.1748 - *                           memory as it will be overwritten.
  1.1749 - * \param field_name         The field name in ASCII, \c NUL terminated.
  1.1750 - * \param field_value        The field value in UTF-8, \c NUL terminated.
  1.1751 - * \assert
  1.1752 - *    \code entry != NULL \endcode
  1.1753 - *    \code field_name != NULL \endcode
  1.1754 - *    \code field_value != NULL \endcode
  1.1755 - * \retval FLAC__bool
  1.1756 - *    \c false if malloc() fails, or if \a field_name or \a field_value does
  1.1757 - *    not comply with the Vorbis comment specification, else \c true.
  1.1758 - */
  1.1759 -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);
  1.1760 -
  1.1761 -/** Splits a Vorbis comment entry into NUL-terminated name and value strings.
  1.1762 - *
  1.1763 - *  The returned pointers to name and value will be allocated by malloc()
  1.1764 - *  and shall be owned by the caller.
  1.1765 - *
  1.1766 - * \param entry              An existing Vorbis comment entry.
  1.1767 - * \param field_name         The address of where the returned pointer to the
  1.1768 - *                           field name will be stored.
  1.1769 - * \param field_value        The address of where the returned pointer to the
  1.1770 - *                           field value will be stored.
  1.1771 - * \assert
  1.1772 - *    \code (entry.entry != NULL && entry.length > 0) \endcode
  1.1773 - *    \code memchr(entry.entry, '=', entry.length) != NULL \endcode
  1.1774 - *    \code field_name != NULL \endcode
  1.1775 - *    \code field_value != NULL \endcode
  1.1776 - * \retval FLAC__bool
  1.1777 - *    \c false if memory allocation fails or \a entry does not comply with the
  1.1778 - *    Vorbis comment specification, else \c true.
  1.1779 - */
  1.1780 -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);
  1.1781 -
  1.1782 -/** Check if the given Vorbis comment entry's field name matches the given
  1.1783 - *  field name.
  1.1784 - *
  1.1785 - * \param entry              An existing Vorbis comment entry.
  1.1786 - * \param field_name         The field name to check.
  1.1787 - * \param field_name_length  The length of \a field_name, not including the
  1.1788 - *                           terminating \c NUL.
  1.1789 - * \assert
  1.1790 - *    \code (entry.entry != NULL && entry.length > 0) \endcode
  1.1791 - * \retval FLAC__bool
  1.1792 - *    \c true if the field names match, else \c false
  1.1793 - */
  1.1794 -FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_matches(const FLAC__StreamMetadata_VorbisComment_Entry entry, const char *field_name, unsigned field_name_length);
  1.1795 -
  1.1796 -/** Find a Vorbis comment with the given field name.
  1.1797 - *
  1.1798 - *  The search begins at entry number \a offset; use an offset of 0 to
  1.1799 - *  search from the beginning of the comment array.
  1.1800 - *
  1.1801 - * \param object      A pointer to an existing VORBIS_COMMENT object.
  1.1802 - * \param offset      The offset into the comment array from where to start
  1.1803 - *                    the search.
  1.1804 - * \param field_name  The field name of the comment to find.
  1.1805 - * \assert
  1.1806 - *    \code object != NULL \endcode
  1.1807 - *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  1.1808 - *    \code field_name != NULL \endcode
  1.1809 - * \retval int
  1.1810 - *    The offset in the comment array of the first comment whose field
  1.1811 - *    name matches \a field_name, or \c -1 if no match was found.
  1.1812 - */
  1.1813 -FLAC_API int FLAC__metadata_object_vorbiscomment_find_entry_from(const FLAC__StreamMetadata *object, unsigned offset, const char *field_name);
  1.1814 -
  1.1815 -/** Remove first Vorbis comment matching the given field name.
  1.1816 - *
  1.1817 - * \param object      A pointer to an existing VORBIS_COMMENT object.
  1.1818 - * \param field_name  The field name of comment to delete.
  1.1819 - * \assert
  1.1820 - *    \code object != NULL \endcode
  1.1821 - *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  1.1822 - * \retval int
  1.1823 - *    \c -1 for memory allocation error, \c 0 for no matching entries,
  1.1824 - *    \c 1 for one matching entry deleted.
  1.1825 - */
  1.1826 -FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entry_matching(FLAC__StreamMetadata *object, const char *field_name);
  1.1827 -
  1.1828 -/** Remove all Vorbis comments matching the given field name.
  1.1829 - *
  1.1830 - * \param object      A pointer to an existing VORBIS_COMMENT object.
  1.1831 - * \param field_name  The field name of comments to delete.
  1.1832 - * \assert
  1.1833 - *    \code object != NULL \endcode
  1.1834 - *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  1.1835 - * \retval int
  1.1836 - *    \c -1 for memory allocation error, \c 0 for no matching entries,
  1.1837 - *    else the number of matching entries deleted.
  1.1838 - */
  1.1839 -FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entries_matching(FLAC__StreamMetadata *object, const char *field_name);
  1.1840 -
  1.1841 -/** Create a new CUESHEET track instance.
  1.1842 - *
  1.1843 - *  The object will be "empty"; i.e. values and data pointers will be \c 0.
  1.1844 - *
  1.1845 - * \retval FLAC__StreamMetadata_CueSheet_Track*
  1.1846 - *    \c NULL if there was an error allocating memory, else the new instance.
  1.1847 - */
  1.1848 -FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_new(void);
  1.1849 -
  1.1850 -/** Create a copy of an existing CUESHEET track object.
  1.1851 - *
  1.1852 - *  The copy is a "deep" copy, i.e. dynamically allocated data within the
  1.1853 - *  object is also copied.  The caller takes ownership of the new object and
  1.1854 - *  is responsible for freeing it with
  1.1855 - *  FLAC__metadata_object_cuesheet_track_delete().
  1.1856 - *
  1.1857 - * \param object  Pointer to object to copy.
  1.1858 - * \assert
  1.1859 - *    \code object != NULL \endcode
  1.1860 - * \retval FLAC__StreamMetadata_CueSheet_Track*
  1.1861 - *    \c NULL if there was an error allocating memory, else the new instance.
  1.1862 - */
  1.1863 -FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_clone(const FLAC__StreamMetadata_CueSheet_Track *object);
  1.1864 -
  1.1865 -/** Delete a CUESHEET track object
  1.1866 - *
  1.1867 - * \param object       A pointer to an existing CUESHEET track object.
  1.1868 - * \assert
  1.1869 - *    \code object != NULL \endcode
  1.1870 - */
  1.1871 -FLAC_API void FLAC__metadata_object_cuesheet_track_delete(FLAC__StreamMetadata_CueSheet_Track *object);
  1.1872 -
  1.1873 -/** Resize a track's index point array.
  1.1874 - *
  1.1875 - *  If the size shrinks, elements will truncated; if it grows, new blank
  1.1876 - *  indices will be added to the end.
  1.1877 - *
  1.1878 - * \param object           A pointer to an existing CUESHEET object.
  1.1879 - * \param track_num        The index of the track to modify.  NOTE: this is not
  1.1880 - *                         necessarily the same as the track's \a number field.
  1.1881 - * \param new_num_indices  The desired length of the array; may be \c 0.
  1.1882 - * \assert
  1.1883 - *    \code object != NULL \endcode
  1.1884 - *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  1.1885 - *    \code object->data.cue_sheet.num_tracks > track_num \endcode
  1.1886 - *    \code (object->data.cue_sheet.tracks[track_num].indices == NULL && object->data.cue_sheet.tracks[track_num].num_indices == 0) ||
  1.1887 - * (object->data.cue_sheet.tracks[track_num].indices != NULL && object->data.cue_sheet.tracks[track_num].num_indices > 0) \endcode
  1.1888 - * \retval FLAC__bool
  1.1889 - *    \c false if memory allocation error, else \c true.
  1.1890 - */
  1.1891 -FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_resize_indices(FLAC__StreamMetadata *object, unsigned track_num, unsigned new_num_indices);
  1.1892 -
  1.1893 -/** Insert an index point in a CUESHEET track at the given index.
  1.1894 - *
  1.1895 - * \param object       A pointer to an existing CUESHEET object.
  1.1896 - * \param track_num    The index of the track to modify.  NOTE: this is not
  1.1897 - *                     necessarily the same as the track's \a number field.
  1.1898 - * \param index_num    The index into the track's index array at which to
  1.1899 - *                     insert the index point.  NOTE: this is not necessarily
  1.1900 - *                     the same as the index point's \a number field.  The
  1.1901 - *                     indices at and after \a index_num move right one
  1.1902 - *                     position.  To append an index point to the end, set
  1.1903 - *                     \a index_num to
  1.1904 - *                     \c object->data.cue_sheet.tracks[track_num].num_indices .
  1.1905 - * \param index        The index point to insert.
  1.1906 - * \assert
  1.1907 - *    \code object != NULL \endcode
  1.1908 - *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  1.1909 - *    \code object->data.cue_sheet.num_tracks > track_num \endcode
  1.1910 - *    \code object->data.cue_sheet.tracks[track_num].num_indices >= index_num \endcode
  1.1911 - * \retval FLAC__bool
  1.1912 - *    \c false if realloc() fails, else \c true.
  1.1913 - */
  1.1914 -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);
  1.1915 -
  1.1916 -/** Insert a blank index point in a CUESHEET track at the given index.
  1.1917 - *
  1.1918 - *  A blank index point is one in which all field values are zero.
  1.1919 - *
  1.1920 - * \param object       A pointer to an existing CUESHEET object.
  1.1921 - * \param track_num    The index of the track to modify.  NOTE: this is not
  1.1922 - *                     necessarily the same as the track's \a number field.
  1.1923 - * \param index_num    The index into the track's index array at which to
  1.1924 - *                     insert the index point.  NOTE: this is not necessarily
  1.1925 - *                     the same as the index point's \a number field.  The
  1.1926 - *                     indices at and after \a index_num move right one
  1.1927 - *                     position.  To append an index point to the end, set
  1.1928 - *                     \a index_num to
  1.1929 - *                     \c object->data.cue_sheet.tracks[track_num].num_indices .
  1.1930 - * \assert
  1.1931 - *    \code object != NULL \endcode
  1.1932 - *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  1.1933 - *    \code object->data.cue_sheet.num_tracks > track_num \endcode
  1.1934 - *    \code object->data.cue_sheet.tracks[track_num].num_indices >= index_num \endcode
  1.1935 - * \retval FLAC__bool
  1.1936 - *    \c false if realloc() fails, else \c true.
  1.1937 - */
  1.1938 -FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_blank_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num);
  1.1939 -
  1.1940 -/** Delete an index point in a CUESHEET track at the given index.
  1.1941 - *
  1.1942 - * \param object       A pointer to an existing CUESHEET object.
  1.1943 - * \param track_num    The index into the track array of the track to
  1.1944 - *                     modify.  NOTE: this is not necessarily the same
  1.1945 - *                     as the track's \a number field.
  1.1946 - * \param index_num    The index into the track's index array of the index
  1.1947 - *                     to delete.  NOTE: this is not necessarily the same
  1.1948 - *                     as the index's \a number field.
  1.1949 - * \assert
  1.1950 - *    \code object != NULL \endcode
  1.1951 - *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  1.1952 - *    \code object->data.cue_sheet.num_tracks > track_num \endcode
  1.1953 - *    \code object->data.cue_sheet.tracks[track_num].num_indices > index_num \endcode
  1.1954 - * \retval FLAC__bool
  1.1955 - *    \c false if realloc() fails, else \c true.
  1.1956 - */
  1.1957 -FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_delete_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num);
  1.1958 -
  1.1959 -/** Resize the track array.
  1.1960 - *
  1.1961 - *  If the size shrinks, elements will truncated; if it grows, new blank
  1.1962 - *  tracks will be added to the end.
  1.1963 - *
  1.1964 - * \param object            A pointer to an existing CUESHEET object.
  1.1965 - * \param new_num_tracks    The desired length of the array; may be \c 0.
  1.1966 - * \assert
  1.1967 - *    \code object != NULL \endcode
  1.1968 - *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  1.1969 - *    \code (object->data.cue_sheet.tracks == NULL && object->data.cue_sheet.num_tracks == 0) ||
  1.1970 - * (object->data.cue_sheet.tracks != NULL && object->data.cue_sheet.num_tracks > 0) \endcode
  1.1971 - * \retval FLAC__bool
  1.1972 - *    \c false if memory allocation error, else \c true.
  1.1973 - */
  1.1974 -FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_resize_tracks(FLAC__StreamMetadata *object, unsigned new_num_tracks);
  1.1975 -
  1.1976 -/** Sets a track in a CUESHEET block.
  1.1977 - *
  1.1978 - *  If \a copy is \c true, a copy of the track is stored; otherwise, the object
  1.1979 - *  takes ownership of the \a track pointer.
  1.1980 - *
  1.1981 - * \param object       A pointer to an existing CUESHEET object.
  1.1982 - * \param track_num    Index into track array to set.  NOTE: this is not
  1.1983 - *                     necessarily the same as the track's \a number field.
  1.1984 - * \param track        The track to set the track to.  You may safely pass in
  1.1985 - *                     a const pointer if \a copy is \c true.
  1.1986 - * \param copy         See above.
  1.1987 - * \assert
  1.1988 - *    \code object != NULL \endcode
  1.1989 - *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  1.1990 - *    \code track_num < object->data.cue_sheet.num_tracks \endcode
  1.1991 - *    \code (track->indices != NULL && track->num_indices > 0) ||
  1.1992 - * (track->indices == NULL && track->num_indices == 0)
  1.1993 - * \retval FLAC__bool
  1.1994 - *    \c false if \a copy is \c true and malloc() fails, else \c true.
  1.1995 - */
  1.1996 -FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_set_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy);
  1.1997 -
  1.1998 -/** Insert a track in a CUESHEET block at the given index.
  1.1999 - *
  1.2000 - *  If \a copy is \c true, a copy of the track is stored; otherwise, the object
  1.2001 - *  takes ownership of the \a track pointer.
  1.2002 - *
  1.2003 - * \param object       A pointer to an existing CUESHEET object.
  1.2004 - * \param track_num    The index at which to insert the track.  NOTE: this
  1.2005 - *                     is not necessarily the same as the track's \a number
  1.2006 - *                     field.  The tracks at and after \a track_num move right
  1.2007 - *                     one position.  To append a track to the end, set
  1.2008 - *                     \a track_num to \c object->data.cue_sheet.num_tracks .
  1.2009 - * \param track        The track to insert.  You may safely pass in a const
  1.2010 - *                     pointer if \a copy is \c true.
  1.2011 - * \param copy         See above.
  1.2012 - * \assert
  1.2013 - *    \code object != NULL \endcode
  1.2014 - *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  1.2015 - *    \code object->data.cue_sheet.num_tracks >= track_num \endcode
  1.2016 - * \retval FLAC__bool
  1.2017 - *    \c false if \a copy is \c true and malloc() fails, else \c true.
  1.2018 - */
  1.2019 -FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy);
  1.2020 -
  1.2021 -/** Insert a blank track in a CUESHEET block at the given index.
  1.2022 - *
  1.2023 - *  A blank track is one in which all field values are zero.
  1.2024 - *
  1.2025 - * \param object       A pointer to an existing CUESHEET object.
  1.2026 - * \param track_num    The index at which to insert the track.  NOTE: this
  1.2027 - *                     is not necessarily the same as the track's \a number
  1.2028 - *                     field.  The tracks at and after \a track_num move right
  1.2029 - *                     one position.  To append a track to the end, set
  1.2030 - *                     \a track_num to \c object->data.cue_sheet.num_tracks .
  1.2031 - * \assert
  1.2032 - *    \code object != NULL \endcode
  1.2033 - *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  1.2034 - *    \code object->data.cue_sheet.num_tracks >= track_num \endcode
  1.2035 - * \retval FLAC__bool
  1.2036 - *    \c false if \a copy is \c true and malloc() fails, else \c true.
  1.2037 - */
  1.2038 -FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_blank_track(FLAC__StreamMetadata *object, unsigned track_num);
  1.2039 -
  1.2040 -/** Delete a track in a CUESHEET block at the given index.
  1.2041 - *
  1.2042 - * \param object       A pointer to an existing CUESHEET object.
  1.2043 - * \param track_num    The index into the track array of the track to
  1.2044 - *                     delete.  NOTE: this is not necessarily the same
  1.2045 - *                     as the track's \a number field.
  1.2046 - * \assert
  1.2047 - *    \code object != NULL \endcode
  1.2048 - *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  1.2049 - *    \code object->data.cue_sheet.num_tracks > track_num \endcode
  1.2050 - * \retval FLAC__bool
  1.2051 - *    \c false if realloc() fails, else \c true.
  1.2052 - */
  1.2053 -FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_delete_track(FLAC__StreamMetadata *object, unsigned track_num);
  1.2054 -
  1.2055 -/** Check a cue sheet to see if it conforms to the FLAC specification.
  1.2056 - *  See the format specification for limits on the contents of the
  1.2057 - *  cue sheet.
  1.2058 - *
  1.2059 - * \param object     A pointer to an existing CUESHEET object.
  1.2060 - * \param check_cd_da_subset  If \c true, check CUESHEET against more
  1.2061 - *                   stringent requirements for a CD-DA (audio) disc.
  1.2062 - * \param violation  Address of a pointer to a string.  If there is a
  1.2063 - *                   violation, a pointer to a string explanation of the
  1.2064 - *                   violation will be returned here. \a violation may be
  1.2065 - *                   \c NULL if you don't need the returned string.  Do not
  1.2066 - *                   free the returned string; it will always point to static
  1.2067 - *                   data.
  1.2068 - * \assert
  1.2069 - *    \code object != NULL \endcode
  1.2070 - *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  1.2071 - * \retval FLAC__bool
  1.2072 - *    \c false if cue sheet is illegal, else \c true.
  1.2073 - */
  1.2074 -FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_is_legal(const FLAC__StreamMetadata *object, FLAC__bool check_cd_da_subset, const char **violation);
  1.2075 -
  1.2076 -/** Calculate and return the CDDB/freedb ID for a cue sheet.  The function
  1.2077 - *  assumes the cue sheet corresponds to a CD; the result is undefined
  1.2078 - *  if the cuesheet's is_cd bit is not set.
  1.2079 - *
  1.2080 - * \param object     A pointer to an existing CUESHEET object.
  1.2081 - * \assert
  1.2082 - *    \code object != NULL \endcode
  1.2083 - *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  1.2084 - * \retval FLAC__uint32
  1.2085 - *    The unsigned integer representation of the CDDB/freedb ID
  1.2086 - */
  1.2087 -FLAC_API FLAC__uint32 FLAC__metadata_object_cuesheet_calculate_cddb_id(const FLAC__StreamMetadata *object);
  1.2088 -
  1.2089 -/** Sets the MIME type of a PICTURE block.
  1.2090 - *
  1.2091 - *  If \a copy is \c true, a copy of the string is stored; otherwise, the object
  1.2092 - *  takes ownership of the pointer.  The existing string will be freed if this
  1.2093 - *  function is successful, otherwise the original string will remain if \a copy
  1.2094 - *  is \c true and malloc() fails.
  1.2095 - *
  1.2096 - * \note It is safe to pass a const pointer to \a mime_type if \a copy is \c true.
  1.2097 - *
  1.2098 - * \param object      A pointer to an existing PICTURE object.
  1.2099 - * \param mime_type   A pointer to the MIME type string.  The string must be
  1.2100 - *                    ASCII characters 0x20-0x7e, NUL-terminated.  No validation
  1.2101 - *                    is done.
  1.2102 - * \param copy        See above.
  1.2103 - * \assert
  1.2104 - *    \code object != NULL \endcode
  1.2105 - *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
  1.2106 - *    \code (mime_type != NULL) \endcode
  1.2107 - * \retval FLAC__bool
  1.2108 - *    \c false if \a copy is \c true and malloc() fails, else \c true.
  1.2109 - */
  1.2110 -FLAC_API FLAC__bool FLAC__metadata_object_picture_set_mime_type(FLAC__StreamMetadata *object, char *mime_type, FLAC__bool copy);
  1.2111 -
  1.2112 -/** Sets the description of a PICTURE block.
  1.2113 - *
  1.2114 - *  If \a copy is \c true, a copy of the string is stored; otherwise, the object
  1.2115 - *  takes ownership of the pointer.  The existing string will be freed if this
  1.2116 - *  function is successful, otherwise the original string will remain if \a copy
  1.2117 - *  is \c true and malloc() fails.
  1.2118 - *
  1.2119 - * \note It is safe to pass a const pointer to \a description if \a copy is \c true.
  1.2120 - *
  1.2121 - * \param object      A pointer to an existing PICTURE object.
  1.2122 - * \param description A pointer to the description string.  The string must be
  1.2123 - *                    valid UTF-8, NUL-terminated.  No validation is done.
  1.2124 - * \param copy        See above.
  1.2125 - * \assert
  1.2126 - *    \code object != NULL \endcode
  1.2127 - *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
  1.2128 - *    \code (description != NULL) \endcode
  1.2129 - * \retval FLAC__bool
  1.2130 - *    \c false if \a copy is \c true and malloc() fails, else \c true.
  1.2131 - */
  1.2132 -FLAC_API FLAC__bool FLAC__metadata_object_picture_set_description(FLAC__StreamMetadata *object, FLAC__byte *description, FLAC__bool copy);
  1.2133 -
  1.2134 -/** Sets the picture data of a PICTURE block.
  1.2135 - *
  1.2136 - *  If \a copy is \c true, a copy of the data is stored; otherwise, the object
  1.2137 - *  takes ownership of the pointer.  Also sets the \a data_length field of the
  1.2138 - *  metadata object to what is passed in as the \a length parameter.  The
  1.2139 - *  existing data will be freed if this function is successful, otherwise the
  1.2140 - *  original data and data_length will remain if \a copy is \c true and
  1.2141 - *  malloc() fails.
  1.2142 - *
  1.2143 - * \note It is safe to pass a const pointer to \a data if \a copy is \c true.
  1.2144 - *
  1.2145 - * \param object  A pointer to an existing PICTURE object.
  1.2146 - * \param data    A pointer to the data to set.
  1.2147 - * \param length  The length of \a data in bytes.
  1.2148 - * \param copy    See above.
  1.2149 - * \assert
  1.2150 - *    \code object != NULL \endcode
  1.2151 - *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
  1.2152 - *    \code (data != NULL && length > 0) ||
  1.2153 - * (data == NULL && length == 0 && copy == false) \endcode
  1.2154 - * \retval FLAC__bool
  1.2155 - *    \c false if \a copy is \c true and malloc() fails, else \c true.
  1.2156 - */
  1.2157 -FLAC_API FLAC__bool FLAC__metadata_object_picture_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, FLAC__uint32 length, FLAC__bool copy);
  1.2158 -
  1.2159 -/** Check a PICTURE block to see if it conforms to the FLAC specification.
  1.2160 - *  See the format specification for limits on the contents of the
  1.2161 - *  PICTURE block.
  1.2162 - *
  1.2163 - * \param object     A pointer to existing PICTURE block to be checked.
  1.2164 - * \param violation  Address of a pointer to a string.  If there is a
  1.2165 - *                   violation, a pointer to a string explanation of the
  1.2166 - *                   violation will be returned here. \a violation may be
  1.2167 - *                   \c NULL if you don't need the returned string.  Do not
  1.2168 - *                   free the returned string; it will always point to static
  1.2169 - *                   data.
  1.2170 - * \assert
  1.2171 - *    \code object != NULL \endcode
  1.2172 - *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
  1.2173 - * \retval FLAC__bool
  1.2174 - *    \c false if PICTURE block is illegal, else \c true.
  1.2175 - */
  1.2176 -FLAC_API FLAC__bool FLAC__metadata_object_picture_is_legal(const FLAC__StreamMetadata *object, const char **violation);
  1.2177 -
  1.2178 -/* \} */
  1.2179 -
  1.2180 -#ifdef __cplusplus
  1.2181 -}
  1.2182 -#endif
  1.2183 -
  1.2184 -#endif