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