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