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