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