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