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