Chris@2: /* libFLAC - Free Lossless Audio Codec library Chris@2: * Copyright (C) 2001,2002,2003,2004,2005,2006,2007 Josh Coalson Chris@2: * Chris@2: * Redistribution and use in source and binary forms, with or without Chris@2: * modification, are permitted provided that the following conditions Chris@2: * are met: Chris@2: * Chris@2: * - Redistributions of source code must retain the above copyright Chris@2: * notice, this list of conditions and the following disclaimer. Chris@2: * Chris@2: * - Redistributions in binary form must reproduce the above copyright Chris@2: * notice, this list of conditions and the following disclaimer in the Chris@2: * documentation and/or other materials provided with the distribution. Chris@2: * Chris@2: * - Neither the name of the Xiph.org Foundation nor the names of its Chris@2: * contributors may be used to endorse or promote products derived from Chris@2: * this software without specific prior written permission. Chris@2: * Chris@2: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS Chris@2: * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT Chris@2: * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR Chris@2: * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR Chris@2: * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, Chris@2: * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, Chris@2: * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR Chris@2: * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF Chris@2: * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING Chris@2: * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS Chris@2: * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Chris@2: */ Chris@2: Chris@2: #ifndef FLAC__METADATA_H Chris@2: #define FLAC__METADATA_H Chris@2: Chris@2: #include /* for off_t */ Chris@2: #include "export.h" Chris@2: #include "callback.h" Chris@2: #include "format.h" Chris@2: Chris@2: /* -------------------------------------------------------------------- Chris@2: (For an example of how all these routines are used, see the source Chris@2: code for the unit tests in src/test_libFLAC/metadata_*.c, or Chris@2: metaflac in src/metaflac/) Chris@2: ------------------------------------------------------------------*/ Chris@2: Chris@2: /** \file include/FLAC/metadata.h Chris@2: * Chris@2: * \brief Chris@2: * This module provides functions for creating and manipulating FLAC Chris@2: * metadata blocks in memory, and three progressively more powerful Chris@2: * interfaces for traversing and editing metadata in FLAC files. Chris@2: * Chris@2: * See the detailed documentation for each interface in the Chris@2: * \link flac_metadata metadata \endlink module. Chris@2: */ Chris@2: Chris@2: /** \defgroup flac_metadata FLAC/metadata.h: metadata interfaces Chris@2: * \ingroup flac Chris@2: * Chris@2: * \brief Chris@2: * This module provides functions for creating and manipulating FLAC Chris@2: * metadata blocks in memory, and three progressively more powerful Chris@2: * interfaces for traversing and editing metadata in native FLAC files. Chris@2: * Note that currently only the Chain interface (level 2) supports Ogg Chris@2: * FLAC files, and it is read-only i.e. no writing back changed Chris@2: * metadata to file. Chris@2: * Chris@2: * There are three metadata interfaces of increasing complexity: Chris@2: * Chris@2: * Level 0: Chris@2: * Read-only access to the STREAMINFO, VORBIS_COMMENT, CUESHEET, and Chris@2: * PICTURE blocks. Chris@2: * Chris@2: * Level 1: Chris@2: * Read-write access to all metadata blocks. This level is write- Chris@2: * efficient in most cases (more on this below), and uses less memory Chris@2: * than level 2. Chris@2: * Chris@2: * Level 2: Chris@2: * Read-write access to all metadata blocks. This level is write- Chris@2: * efficient in all cases, but uses more memory since all metadata for Chris@2: * the whole file is read into memory and manipulated before writing Chris@2: * out again. Chris@2: * Chris@2: * What do we mean by efficient? Since FLAC metadata appears at the Chris@2: * beginning of the file, when writing metadata back to a FLAC file Chris@2: * it is possible to grow or shrink the metadata such that the entire Chris@2: * file must be rewritten. However, if the size remains the same during Chris@2: * changes or PADDING blocks are utilized, only the metadata needs to be Chris@2: * overwritten, which is much faster. Chris@2: * Chris@2: * Efficient means the whole file is rewritten at most one time, and only Chris@2: * when necessary. Level 1 is not efficient only in the case that you Chris@2: * cause more than one metadata block to grow or shrink beyond what can Chris@2: * be accomodated by padding. In this case you should probably use level Chris@2: * 2, which allows you to edit all the metadata for a file in memory and Chris@2: * write it out all at once. Chris@2: * Chris@2: * All levels know how to skip over and not disturb an ID3v2 tag at the Chris@2: * front of the file. Chris@2: * Chris@2: * All levels access files via their filenames. In addition, level 2 Chris@2: * has additional alternative read and write functions that take an I/O Chris@2: * handle and callbacks, for situations where access by filename is not Chris@2: * possible. Chris@2: * Chris@2: * In addition to the three interfaces, this module defines functions for Chris@2: * creating and manipulating various metadata objects in memory. As we see Chris@2: * from the Format module, FLAC metadata blocks in memory are very primitive Chris@2: * structures for storing information in an efficient way. Reading Chris@2: * information from the structures is easy but creating or modifying them Chris@2: * directly is more complex. The metadata object routines here facilitate Chris@2: * this by taking care of the consistency and memory management drudgery. Chris@2: * Chris@2: * Unless you will be using the level 1 or 2 interfaces to modify existing Chris@2: * metadata however, you will not probably not need these. Chris@2: * Chris@2: * From a dependency standpoint, none of the encoders or decoders require Chris@2: * the metadata module. This is so that embedded users can strip out the Chris@2: * metadata module from libFLAC to reduce the size and complexity. Chris@2: */ Chris@2: Chris@2: #ifdef __cplusplus Chris@2: extern "C" { Chris@2: #endif Chris@2: Chris@2: Chris@2: /** \defgroup flac_metadata_level0 FLAC/metadata.h: metadata level 0 interface Chris@2: * \ingroup flac_metadata Chris@2: * Chris@2: * \brief Chris@2: * The level 0 interface consists of individual routines to read the Chris@2: * STREAMINFO, VORBIS_COMMENT, CUESHEET, and PICTURE blocks, requiring Chris@2: * only a filename. Chris@2: * Chris@2: * They try to skip any ID3v2 tag at the head of the file. Chris@2: * Chris@2: * \{ Chris@2: */ Chris@2: Chris@2: /** Read the STREAMINFO metadata block of the given FLAC file. This function Chris@2: * will try to skip any ID3v2 tag at the head of the file. Chris@2: * Chris@2: * \param filename The path to the FLAC file to read. Chris@2: * \param streaminfo A pointer to space for the STREAMINFO block. Since Chris@2: * FLAC__StreamMetadata is a simple structure with no Chris@2: * memory allocation involved, you pass the address of Chris@2: * an existing structure. It need not be initialized. Chris@2: * \assert Chris@2: * \code filename != NULL \endcode Chris@2: * \code streaminfo != NULL \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c true if a valid STREAMINFO block was read from \a filename. Returns Chris@2: * \c false if there was a memory allocation error, a file decoder error, Chris@2: * or the file contained no STREAMINFO block. (A memory allocation error Chris@2: * is possible because this function must set up a file decoder.) Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_get_streaminfo(const char *filename, FLAC__StreamMetadata *streaminfo); Chris@2: Chris@2: /** Read the VORBIS_COMMENT metadata block of the given FLAC file. This Chris@2: * function will try to skip any ID3v2 tag at the head of the file. Chris@2: * Chris@2: * \param filename The path to the FLAC file to read. Chris@2: * \param tags The address where the returned pointer will be Chris@2: * stored. The \a tags object must be deleted by Chris@2: * the caller using FLAC__metadata_object_delete(). Chris@2: * \assert Chris@2: * \code filename != NULL \endcode Chris@2: * \code tags != NULL \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c true if a valid VORBIS_COMMENT block was read from \a filename, Chris@2: * and \a *tags will be set to the address of the metadata structure. Chris@2: * Returns \c false if there was a memory allocation error, a file Chris@2: * decoder error, or the file contained no VORBIS_COMMENT block, and Chris@2: * \a *tags will be set to \c NULL. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_get_tags(const char *filename, FLAC__StreamMetadata **tags); Chris@2: Chris@2: /** Read the CUESHEET metadata block of the given FLAC file. This Chris@2: * function will try to skip any ID3v2 tag at the head of the file. Chris@2: * Chris@2: * \param filename The path to the FLAC file to read. Chris@2: * \param cuesheet The address where the returned pointer will be Chris@2: * stored. The \a cuesheet object must be deleted by Chris@2: * the caller using FLAC__metadata_object_delete(). Chris@2: * \assert Chris@2: * \code filename != NULL \endcode Chris@2: * \code cuesheet != NULL \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c true if a valid CUESHEET block was read from \a filename, Chris@2: * and \a *cuesheet will be set to the address of the metadata Chris@2: * structure. Returns \c false if there was a memory allocation Chris@2: * error, a file decoder error, or the file contained no CUESHEET Chris@2: * block, and \a *cuesheet will be set to \c NULL. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_get_cuesheet(const char *filename, FLAC__StreamMetadata **cuesheet); Chris@2: Chris@2: /** Read a PICTURE metadata block of the given FLAC file. This Chris@2: * function will try to skip any ID3v2 tag at the head of the file. Chris@2: * Since there can be more than one PICTURE block in a file, this Chris@2: * function takes a number of parameters that act as constraints to Chris@2: * the search. The PICTURE block with the largest area matching all Chris@2: * the constraints will be returned, or \a *picture will be set to Chris@2: * \c NULL if there was no such block. Chris@2: * Chris@2: * \param filename The path to the FLAC file to read. Chris@2: * \param picture The address where the returned pointer will be Chris@2: * stored. The \a picture object must be deleted by Chris@2: * the caller using FLAC__metadata_object_delete(). Chris@2: * \param type The desired picture type. Use \c -1 to mean Chris@2: * "any type". Chris@2: * \param mime_type The desired MIME type, e.g. "image/jpeg". The Chris@2: * string will be matched exactly. Use \c NULL to Chris@2: * mean "any MIME type". Chris@2: * \param description The desired description. The string will be Chris@2: * matched exactly. Use \c NULL to mean "any Chris@2: * description". Chris@2: * \param max_width The maximum width in pixels desired. Use Chris@2: * \c (unsigned)(-1) to mean "any width". Chris@2: * \param max_height The maximum height in pixels desired. Use Chris@2: * \c (unsigned)(-1) to mean "any height". Chris@2: * \param max_depth The maximum color depth in bits-per-pixel desired. Chris@2: * Use \c (unsigned)(-1) to mean "any depth". Chris@2: * \param max_colors The maximum number of colors desired. Use Chris@2: * \c (unsigned)(-1) to mean "any number of colors". Chris@2: * \assert Chris@2: * \code filename != NULL \endcode Chris@2: * \code picture != NULL \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c true if a valid PICTURE block was read from \a filename, Chris@2: * and \a *picture will be set to the address of the metadata Chris@2: * structure. Returns \c false if there was a memory allocation Chris@2: * error, a file decoder error, or the file contained no PICTURE Chris@2: * block, and \a *picture will be set to \c NULL. Chris@2: */ Chris@2: 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); Chris@2: Chris@2: /* \} */ Chris@2: Chris@2: Chris@2: /** \defgroup flac_metadata_level1 FLAC/metadata.h: metadata level 1 interface Chris@2: * \ingroup flac_metadata Chris@2: * Chris@2: * \brief Chris@2: * The level 1 interface provides read-write access to FLAC file metadata and Chris@2: * operates directly on the FLAC file. Chris@2: * Chris@2: * The general usage of this interface is: Chris@2: * Chris@2: * - Create an iterator using FLAC__metadata_simple_iterator_new() Chris@2: * - Attach it to a file using FLAC__metadata_simple_iterator_init() and check Chris@2: * the exit code. Call FLAC__metadata_simple_iterator_is_writable() to Chris@2: * see if the file is writable, or only read access is allowed. Chris@2: * - Use FLAC__metadata_simple_iterator_next() and Chris@2: * FLAC__metadata_simple_iterator_prev() to traverse the blocks. Chris@2: * This is does not read the actual blocks themselves. Chris@2: * FLAC__metadata_simple_iterator_next() is relatively fast. Chris@2: * FLAC__metadata_simple_iterator_prev() is slower since it needs to search Chris@2: * forward from the front of the file. Chris@2: * - Use FLAC__metadata_simple_iterator_get_block_type() or Chris@2: * FLAC__metadata_simple_iterator_get_block() to access the actual data at Chris@2: * the current iterator position. The returned object is yours to modify Chris@2: * and free. Chris@2: * - Use FLAC__metadata_simple_iterator_set_block() to write a modified block Chris@2: * back. You must have write permission to the original file. Make sure to Chris@2: * read the whole comment to FLAC__metadata_simple_iterator_set_block() Chris@2: * below. Chris@2: * - Use FLAC__metadata_simple_iterator_insert_block_after() to add new blocks. Chris@2: * Use the object creation functions from Chris@2: * \link flac_metadata_object here \endlink to generate new objects. Chris@2: * - Use FLAC__metadata_simple_iterator_delete_block() to remove the block Chris@2: * currently referred to by the iterator, or replace it with padding. Chris@2: * - Destroy the iterator with FLAC__metadata_simple_iterator_delete() when Chris@2: * finished. Chris@2: * Chris@2: * \note Chris@2: * The FLAC file remains open the whole time between Chris@2: * FLAC__metadata_simple_iterator_init() and Chris@2: * FLAC__metadata_simple_iterator_delete(), so make sure you are not altering Chris@2: * the file during this time. Chris@2: * Chris@2: * \note Chris@2: * Do not modify the \a is_last, \a length, or \a type fields of returned Chris@2: * FLAC__StreamMetadata objects. These are managed automatically. Chris@2: * Chris@2: * \note Chris@2: * If any of the modification functions Chris@2: * (FLAC__metadata_simple_iterator_set_block(), Chris@2: * FLAC__metadata_simple_iterator_delete_block(), Chris@2: * FLAC__metadata_simple_iterator_insert_block_after(), etc.) return \c false, Chris@2: * you should delete the iterator as it may no longer be valid. Chris@2: * Chris@2: * \{ Chris@2: */ Chris@2: Chris@2: struct FLAC__Metadata_SimpleIterator; Chris@2: /** The opaque structure definition for the level 1 iterator type. Chris@2: * See the Chris@2: * \link flac_metadata_level1 metadata level 1 module \endlink Chris@2: * for a detailed description. Chris@2: */ Chris@2: typedef struct FLAC__Metadata_SimpleIterator FLAC__Metadata_SimpleIterator; Chris@2: Chris@2: /** Status type for FLAC__Metadata_SimpleIterator. Chris@2: * Chris@2: * The iterator's current status can be obtained by calling FLAC__metadata_simple_iterator_status(). Chris@2: */ Chris@2: typedef enum { Chris@2: Chris@2: FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK = 0, Chris@2: /**< The iterator is in the normal OK state */ Chris@2: Chris@2: FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT, Chris@2: /**< The data passed into a function violated the function's usage criteria */ Chris@2: Chris@2: FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ERROR_OPENING_FILE, Chris@2: /**< The iterator could not open the target file */ Chris@2: Chris@2: FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_A_FLAC_FILE, Chris@2: /**< The iterator could not find the FLAC signature at the start of the file */ Chris@2: Chris@2: FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_WRITABLE, Chris@2: /**< The iterator tried to write to a file that was not writable */ Chris@2: Chris@2: FLAC__METADATA_SIMPLE_ITERATOR_STATUS_BAD_METADATA, Chris@2: /**< The iterator encountered input that does not conform to the FLAC metadata specification */ Chris@2: Chris@2: FLAC__METADATA_SIMPLE_ITERATOR_STATUS_READ_ERROR, Chris@2: /**< The iterator encountered an error while reading the FLAC file */ Chris@2: Chris@2: FLAC__METADATA_SIMPLE_ITERATOR_STATUS_SEEK_ERROR, Chris@2: /**< The iterator encountered an error while seeking in the FLAC file */ Chris@2: Chris@2: FLAC__METADATA_SIMPLE_ITERATOR_STATUS_WRITE_ERROR, Chris@2: /**< The iterator encountered an error while writing the FLAC file */ Chris@2: Chris@2: FLAC__METADATA_SIMPLE_ITERATOR_STATUS_RENAME_ERROR, Chris@2: /**< The iterator encountered an error renaming the FLAC file */ Chris@2: Chris@2: FLAC__METADATA_SIMPLE_ITERATOR_STATUS_UNLINK_ERROR, Chris@2: /**< The iterator encountered an error removing the temporary file */ Chris@2: Chris@2: FLAC__METADATA_SIMPLE_ITERATOR_STATUS_MEMORY_ALLOCATION_ERROR, Chris@2: /**< Memory allocation failed */ Chris@2: Chris@2: FLAC__METADATA_SIMPLE_ITERATOR_STATUS_INTERNAL_ERROR Chris@2: /**< The caller violated an assertion or an unexpected error occurred */ Chris@2: Chris@2: } FLAC__Metadata_SimpleIteratorStatus; Chris@2: Chris@2: /** Maps a FLAC__Metadata_SimpleIteratorStatus to a C string. Chris@2: * Chris@2: * Using a FLAC__Metadata_SimpleIteratorStatus as the index to this array Chris@2: * will give the string equivalent. The contents should not be modified. Chris@2: */ Chris@2: extern FLAC_API const char * const FLAC__Metadata_SimpleIteratorStatusString[]; Chris@2: Chris@2: Chris@2: /** Create a new iterator instance. Chris@2: * Chris@2: * \retval FLAC__Metadata_SimpleIterator* Chris@2: * \c NULL if there was an error allocating memory, else the new instance. Chris@2: */ Chris@2: FLAC_API FLAC__Metadata_SimpleIterator *FLAC__metadata_simple_iterator_new(void); Chris@2: Chris@2: /** Free an iterator instance. Deletes the object pointed to by \a iterator. Chris@2: * Chris@2: * \param iterator A pointer to an existing iterator. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: */ Chris@2: FLAC_API void FLAC__metadata_simple_iterator_delete(FLAC__Metadata_SimpleIterator *iterator); Chris@2: Chris@2: /** Get the current status of the iterator. Call this after a function Chris@2: * returns \c false to get the reason for the error. Also resets the status Chris@2: * to FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK. Chris@2: * Chris@2: * \param iterator A pointer to an existing iterator. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: * \retval FLAC__Metadata_SimpleIteratorStatus Chris@2: * The current status of the iterator. Chris@2: */ Chris@2: FLAC_API FLAC__Metadata_SimpleIteratorStatus FLAC__metadata_simple_iterator_status(FLAC__Metadata_SimpleIterator *iterator); Chris@2: Chris@2: /** Initialize the iterator to point to the first metadata block in the Chris@2: * given FLAC file. Chris@2: * Chris@2: * \param iterator A pointer to an existing iterator. Chris@2: * \param filename The path to the FLAC file. Chris@2: * \param read_only If \c true, the FLAC file will be opened Chris@2: * in read-only mode; if \c false, the FLAC Chris@2: * file will be opened for edit even if no Chris@2: * edits are performed. Chris@2: * \param preserve_file_stats If \c true, the owner and modification Chris@2: * time will be preserved even if the FLAC Chris@2: * file is written to. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: * \code filename != NULL \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if a memory allocation error occurs, the file can't be Chris@2: * opened, or another error occurs, else \c true. Chris@2: */ Chris@2: 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); Chris@2: Chris@2: /** Returns \c true if the FLAC file is writable. If \c false, calls to Chris@2: * FLAC__metadata_simple_iterator_set_block() and Chris@2: * FLAC__metadata_simple_iterator_insert_block_after() will fail. Chris@2: * Chris@2: * \param iterator A pointer to an existing iterator. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: * \retval FLAC__bool Chris@2: * See above. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_writable(const FLAC__Metadata_SimpleIterator *iterator); Chris@2: Chris@2: /** Moves the iterator forward one metadata block, returning \c false if Chris@2: * already at the end. Chris@2: * Chris@2: * \param iterator A pointer to an existing initialized iterator. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: * \a iterator has been successfully initialized with Chris@2: * FLAC__metadata_simple_iterator_init() Chris@2: * \retval FLAC__bool Chris@2: * \c false if already at the last metadata block of the chain, else Chris@2: * \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_simple_iterator_next(FLAC__Metadata_SimpleIterator *iterator); Chris@2: Chris@2: /** Moves the iterator backward one metadata block, returning \c false if Chris@2: * already at the beginning. Chris@2: * Chris@2: * \param iterator A pointer to an existing initialized iterator. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: * \a iterator has been successfully initialized with Chris@2: * FLAC__metadata_simple_iterator_init() Chris@2: * \retval FLAC__bool Chris@2: * \c false if already at the first metadata block of the chain, else Chris@2: * \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_simple_iterator_prev(FLAC__Metadata_SimpleIterator *iterator); Chris@2: Chris@2: /** Returns a flag telling if the current metadata block is the last. Chris@2: * Chris@2: * \param iterator A pointer to an existing initialized iterator. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: * \a iterator has been successfully initialized with Chris@2: * FLAC__metadata_simple_iterator_init() Chris@2: * \retval FLAC__bool Chris@2: * \c true if the current metadata block is the last in the file, Chris@2: * else \c false. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_last(const FLAC__Metadata_SimpleIterator *iterator); Chris@2: Chris@2: /** Get the offset of the metadata block at the current position. This Chris@2: * avoids reading the actual block data which can save time for large Chris@2: * blocks. Chris@2: * Chris@2: * \param iterator A pointer to an existing initialized iterator. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: * \a iterator has been successfully initialized with Chris@2: * FLAC__metadata_simple_iterator_init() Chris@2: * \retval off_t Chris@2: * The offset of the metadata block at the current iterator position. Chris@2: * This is the byte offset relative to the beginning of the file of Chris@2: * the current metadata block's header. Chris@2: */ Chris@2: FLAC_API off_t FLAC__metadata_simple_iterator_get_block_offset(const FLAC__Metadata_SimpleIterator *iterator); Chris@2: Chris@2: /** Get the type of the metadata block at the current position. This Chris@2: * avoids reading the actual block data which can save time for large Chris@2: * blocks. Chris@2: * Chris@2: * \param iterator A pointer to an existing initialized iterator. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: * \a iterator has been successfully initialized with Chris@2: * FLAC__metadata_simple_iterator_init() Chris@2: * \retval FLAC__MetadataType Chris@2: * The type of the metadata block at the current iterator position. Chris@2: */ Chris@2: FLAC_API FLAC__MetadataType FLAC__metadata_simple_iterator_get_block_type(const FLAC__Metadata_SimpleIterator *iterator); Chris@2: Chris@2: /** Get the length of the metadata block at the current position. This Chris@2: * avoids reading the actual block data which can save time for large Chris@2: * blocks. Chris@2: * Chris@2: * \param iterator A pointer to an existing initialized iterator. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: * \a iterator has been successfully initialized with Chris@2: * FLAC__metadata_simple_iterator_init() Chris@2: * \retval unsigned Chris@2: * The length of the metadata block at the current iterator position. Chris@2: * The is same length as that in the Chris@2: * metadata block header, Chris@2: * i.e. the length of the metadata body that follows the header. Chris@2: */ Chris@2: FLAC_API unsigned FLAC__metadata_simple_iterator_get_block_length(const FLAC__Metadata_SimpleIterator *iterator); Chris@2: Chris@2: /** Get the application ID of the \c APPLICATION block at the current Chris@2: * position. This avoids reading the actual block data which can save Chris@2: * time for large blocks. Chris@2: * Chris@2: * \param iterator A pointer to an existing initialized iterator. Chris@2: * \param id A pointer to a buffer of at least \c 4 bytes where Chris@2: * the ID will be stored. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: * \code id != NULL \endcode Chris@2: * \a iterator has been successfully initialized with Chris@2: * FLAC__metadata_simple_iterator_init() Chris@2: * \retval FLAC__bool Chris@2: * \c true if the ID was successfully read, else \c false, in which Chris@2: * case you should check FLAC__metadata_simple_iterator_status() to Chris@2: * find out why. If the status is Chris@2: * \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT, then the Chris@2: * current metadata block is not an \c APPLICATION block. Otherwise Chris@2: * if the status is Chris@2: * \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_READ_ERROR or Chris@2: * \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_SEEK_ERROR, an I/O error Chris@2: * occurred and the iterator can no longer be used. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_simple_iterator_get_application_id(FLAC__Metadata_SimpleIterator *iterator, FLAC__byte *id); Chris@2: Chris@2: /** Get the metadata block at the current position. You can modify the Chris@2: * block but must use FLAC__metadata_simple_iterator_set_block() to Chris@2: * write it back to the FLAC file. Chris@2: * Chris@2: * You must call FLAC__metadata_object_delete() on the returned object Chris@2: * when you are finished with it. Chris@2: * Chris@2: * \param iterator A pointer to an existing initialized iterator. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: * \a iterator has been successfully initialized with Chris@2: * FLAC__metadata_simple_iterator_init() Chris@2: * \retval FLAC__StreamMetadata* Chris@2: * The current metadata block, or \c NULL if there was a memory Chris@2: * allocation error. Chris@2: */ Chris@2: FLAC_API FLAC__StreamMetadata *FLAC__metadata_simple_iterator_get_block(FLAC__Metadata_SimpleIterator *iterator); Chris@2: Chris@2: /** Write a block back to the FLAC file. This function tries to be Chris@2: * as efficient as possible; how the block is actually written is Chris@2: * shown by the following: Chris@2: * Chris@2: * Existing block is a STREAMINFO block and the new block is a Chris@2: * STREAMINFO block: the new block is written in place. Make sure Chris@2: * you know what you're doing when changing the values of a Chris@2: * STREAMINFO block. Chris@2: * Chris@2: * Existing block is a STREAMINFO block and the new block is a Chris@2: * not a STREAMINFO block: this is an error since the first block Chris@2: * must be a STREAMINFO block. Returns \c false without altering the Chris@2: * file. Chris@2: * Chris@2: * Existing block is not a STREAMINFO block and the new block is a Chris@2: * STREAMINFO block: this is an error since there may be only one Chris@2: * STREAMINFO block. Returns \c false without altering the file. Chris@2: * Chris@2: * Existing block and new block are the same length: the existing Chris@2: * block will be replaced by the new block, written in place. Chris@2: * Chris@2: * Existing block is longer than new block: if use_padding is \c true, Chris@2: * the existing block will be overwritten in place with the new Chris@2: * block followed by a PADDING block, if possible, to make the total Chris@2: * size the same as the existing block. Remember that a padding Chris@2: * block requires at least four bytes so if the difference in size Chris@2: * between the new block and existing block is less than that, the Chris@2: * entire file will have to be rewritten, using the new block's Chris@2: * exact size. If use_padding is \c false, the entire file will be Chris@2: * rewritten, replacing the existing block by the new block. Chris@2: * Chris@2: * Existing block is shorter than new block: if use_padding is \c true, Chris@2: * the function will try and expand the new block into the following Chris@2: * PADDING block, if it exists and doing so won't shrink the PADDING Chris@2: * block to less than 4 bytes. If there is no following PADDING Chris@2: * block, or it will shrink to less than 4 bytes, or use_padding is Chris@2: * \c false, the entire file is rewritten, replacing the existing block Chris@2: * with the new block. Note that in this case any following PADDING Chris@2: * block is preserved as is. Chris@2: * Chris@2: * After writing the block, the iterator will remain in the same Chris@2: * place, i.e. pointing to the new block. Chris@2: * Chris@2: * \param iterator A pointer to an existing initialized iterator. Chris@2: * \param block The block to set. Chris@2: * \param use_padding See above. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: * \a iterator has been successfully initialized with Chris@2: * FLAC__metadata_simple_iterator_init() Chris@2: * \code block != NULL \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c true if successful, else \c false. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_simple_iterator_set_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding); Chris@2: Chris@2: /** This is similar to FLAC__metadata_simple_iterator_set_block() Chris@2: * except that instead of writing over an existing block, it appends Chris@2: * a block after the existing block. \a use_padding is again used to Chris@2: * tell the function to try an expand into following padding in an Chris@2: * attempt to avoid rewriting the entire file. Chris@2: * Chris@2: * This function will fail and return \c false if given a STREAMINFO Chris@2: * block. Chris@2: * Chris@2: * After writing the block, the iterator will be pointing to the Chris@2: * new block. Chris@2: * Chris@2: * \param iterator A pointer to an existing initialized iterator. Chris@2: * \param block The block to set. Chris@2: * \param use_padding See above. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: * \a iterator has been successfully initialized with Chris@2: * FLAC__metadata_simple_iterator_init() Chris@2: * \code block != NULL \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c true if successful, else \c false. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_simple_iterator_insert_block_after(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding); Chris@2: Chris@2: /** Deletes the block at the current position. This will cause the Chris@2: * entire FLAC file to be rewritten, unless \a use_padding is \c true, Chris@2: * in which case the block will be replaced by an equal-sized PADDING Chris@2: * block. The iterator will be left pointing to the block before the Chris@2: * one just deleted. Chris@2: * Chris@2: * You may not delete the STREAMINFO block. Chris@2: * Chris@2: * \param iterator A pointer to an existing initialized iterator. Chris@2: * \param use_padding See above. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: * \a iterator has been successfully initialized with Chris@2: * FLAC__metadata_simple_iterator_init() Chris@2: * \retval FLAC__bool Chris@2: * \c true if successful, else \c false. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_simple_iterator_delete_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__bool use_padding); Chris@2: Chris@2: /* \} */ Chris@2: Chris@2: Chris@2: /** \defgroup flac_metadata_level2 FLAC/metadata.h: metadata level 2 interface Chris@2: * \ingroup flac_metadata Chris@2: * Chris@2: * \brief Chris@2: * The level 2 interface provides read-write access to FLAC file metadata; Chris@2: * all metadata is read into memory, operated on in memory, and then written Chris@2: * to file, which is more efficient than level 1 when editing multiple blocks. Chris@2: * Chris@2: * Currently Ogg FLAC is supported for read only, via Chris@2: * FLAC__metadata_chain_read_ogg() but a subsequent Chris@2: * FLAC__metadata_chain_write() will fail. Chris@2: * Chris@2: * The general usage of this interface is: Chris@2: * Chris@2: * - Create a new chain using FLAC__metadata_chain_new(). A chain is a Chris@2: * linked list of FLAC metadata blocks. Chris@2: * - Read all metadata into the the chain from a FLAC file using Chris@2: * FLAC__metadata_chain_read() or FLAC__metadata_chain_read_ogg() and Chris@2: * check the status. Chris@2: * - Optionally, consolidate the padding using Chris@2: * FLAC__metadata_chain_merge_padding() or Chris@2: * FLAC__metadata_chain_sort_padding(). Chris@2: * - Create a new iterator using FLAC__metadata_iterator_new() Chris@2: * - Initialize the iterator to point to the first element in the chain Chris@2: * using FLAC__metadata_iterator_init() Chris@2: * - Traverse the chain using FLAC__metadata_iterator_next and Chris@2: * FLAC__metadata_iterator_prev(). Chris@2: * - Get a block for reading or modification using Chris@2: * FLAC__metadata_iterator_get_block(). The pointer to the object Chris@2: * inside the chain is returned, so the block is yours to modify. Chris@2: * Changes will be reflected in the FLAC file when you write the Chris@2: * chain. You can also add and delete blocks (see functions below). Chris@2: * - When done, write out the chain using FLAC__metadata_chain_write(). Chris@2: * Make sure to read the whole comment to the function below. Chris@2: * - Delete the chain using FLAC__metadata_chain_delete(). Chris@2: * Chris@2: * \note Chris@2: * Even though the FLAC file is not open while the chain is being Chris@2: * manipulated, you must not alter the file externally during Chris@2: * this time. The chain assumes the FLAC file will not change Chris@2: * between the time of FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg() Chris@2: * and FLAC__metadata_chain_write(). Chris@2: * Chris@2: * \note Chris@2: * Do not modify the is_last, length, or type fields of returned Chris@2: * FLAC__StreamMetadata objects. These are managed automatically. Chris@2: * Chris@2: * \note Chris@2: * The metadata objects returned by FLAC__metadata_iterator_get_block() Chris@2: * are owned by the chain; do not FLAC__metadata_object_delete() them. Chris@2: * In the same way, blocks passed to FLAC__metadata_iterator_set_block() Chris@2: * become owned by the chain and they will be deleted when the chain is Chris@2: * deleted. Chris@2: * Chris@2: * \{ Chris@2: */ Chris@2: Chris@2: struct FLAC__Metadata_Chain; Chris@2: /** The opaque structure definition for the level 2 chain type. Chris@2: */ Chris@2: typedef struct FLAC__Metadata_Chain FLAC__Metadata_Chain; Chris@2: Chris@2: struct FLAC__Metadata_Iterator; Chris@2: /** The opaque structure definition for the level 2 iterator type. Chris@2: */ Chris@2: typedef struct FLAC__Metadata_Iterator FLAC__Metadata_Iterator; Chris@2: Chris@2: typedef enum { Chris@2: FLAC__METADATA_CHAIN_STATUS_OK = 0, Chris@2: /**< The chain is in the normal OK state */ Chris@2: Chris@2: FLAC__METADATA_CHAIN_STATUS_ILLEGAL_INPUT, Chris@2: /**< The data passed into a function violated the function's usage criteria */ Chris@2: Chris@2: FLAC__METADATA_CHAIN_STATUS_ERROR_OPENING_FILE, Chris@2: /**< The chain could not open the target file */ Chris@2: Chris@2: FLAC__METADATA_CHAIN_STATUS_NOT_A_FLAC_FILE, Chris@2: /**< The chain could not find the FLAC signature at the start of the file */ Chris@2: Chris@2: FLAC__METADATA_CHAIN_STATUS_NOT_WRITABLE, Chris@2: /**< The chain tried to write to a file that was not writable */ Chris@2: Chris@2: FLAC__METADATA_CHAIN_STATUS_BAD_METADATA, Chris@2: /**< The chain encountered input that does not conform to the FLAC metadata specification */ Chris@2: Chris@2: FLAC__METADATA_CHAIN_STATUS_READ_ERROR, Chris@2: /**< The chain encountered an error while reading the FLAC file */ Chris@2: Chris@2: FLAC__METADATA_CHAIN_STATUS_SEEK_ERROR, Chris@2: /**< The chain encountered an error while seeking in the FLAC file */ Chris@2: Chris@2: FLAC__METADATA_CHAIN_STATUS_WRITE_ERROR, Chris@2: /**< The chain encountered an error while writing the FLAC file */ Chris@2: Chris@2: FLAC__METADATA_CHAIN_STATUS_RENAME_ERROR, Chris@2: /**< The chain encountered an error renaming the FLAC file */ Chris@2: Chris@2: FLAC__METADATA_CHAIN_STATUS_UNLINK_ERROR, Chris@2: /**< The chain encountered an error removing the temporary file */ Chris@2: Chris@2: FLAC__METADATA_CHAIN_STATUS_MEMORY_ALLOCATION_ERROR, Chris@2: /**< Memory allocation failed */ Chris@2: Chris@2: FLAC__METADATA_CHAIN_STATUS_INTERNAL_ERROR, Chris@2: /**< The caller violated an assertion or an unexpected error occurred */ Chris@2: Chris@2: FLAC__METADATA_CHAIN_STATUS_INVALID_CALLBACKS, Chris@2: /**< One or more of the required callbacks was NULL */ Chris@2: Chris@2: FLAC__METADATA_CHAIN_STATUS_READ_WRITE_MISMATCH, Chris@2: /**< FLAC__metadata_chain_write() was called on a chain read by Chris@2: * FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(), Chris@2: * or Chris@2: * FLAC__metadata_chain_write_with_callbacks()/FLAC__metadata_chain_write_with_callbacks_and_tempfile() Chris@2: * was called on a chain read by Chris@2: * FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg(). Chris@2: * Matching read/write methods must always be used. */ Chris@2: Chris@2: FLAC__METADATA_CHAIN_STATUS_WRONG_WRITE_CALL Chris@2: /**< FLAC__metadata_chain_write_with_callbacks() was called when the Chris@2: * chain write requires a tempfile; use Chris@2: * FLAC__metadata_chain_write_with_callbacks_and_tempfile() instead. Chris@2: * Or, FLAC__metadata_chain_write_with_callbacks_and_tempfile() was Chris@2: * called when the chain write does not require a tempfile; use Chris@2: * FLAC__metadata_chain_write_with_callbacks() instead. Chris@2: * Always check FLAC__metadata_chain_check_if_tempfile_needed() Chris@2: * before writing via callbacks. */ Chris@2: Chris@2: } FLAC__Metadata_ChainStatus; Chris@2: Chris@2: /** Maps a FLAC__Metadata_ChainStatus to a C string. Chris@2: * Chris@2: * Using a FLAC__Metadata_ChainStatus as the index to this array Chris@2: * will give the string equivalent. The contents should not be modified. Chris@2: */ Chris@2: extern FLAC_API const char * const FLAC__Metadata_ChainStatusString[]; Chris@2: Chris@2: /*********** FLAC__Metadata_Chain ***********/ Chris@2: Chris@2: /** Create a new chain instance. Chris@2: * Chris@2: * \retval FLAC__Metadata_Chain* Chris@2: * \c NULL if there was an error allocating memory, else the new instance. Chris@2: */ Chris@2: FLAC_API FLAC__Metadata_Chain *FLAC__metadata_chain_new(void); Chris@2: Chris@2: /** Free a chain instance. Deletes the object pointed to by \a chain. Chris@2: * Chris@2: * \param chain A pointer to an existing chain. Chris@2: * \assert Chris@2: * \code chain != NULL \endcode Chris@2: */ Chris@2: FLAC_API void FLAC__metadata_chain_delete(FLAC__Metadata_Chain *chain); Chris@2: Chris@2: /** Get the current status of the chain. Call this after a function Chris@2: * returns \c false to get the reason for the error. Also resets the Chris@2: * status to FLAC__METADATA_CHAIN_STATUS_OK. Chris@2: * Chris@2: * \param chain A pointer to an existing chain. Chris@2: * \assert Chris@2: * \code chain != NULL \endcode Chris@2: * \retval FLAC__Metadata_ChainStatus Chris@2: * The current status of the chain. Chris@2: */ Chris@2: FLAC_API FLAC__Metadata_ChainStatus FLAC__metadata_chain_status(FLAC__Metadata_Chain *chain); Chris@2: Chris@2: /** Read all metadata from a FLAC file into the chain. Chris@2: * Chris@2: * \param chain A pointer to an existing chain. Chris@2: * \param filename The path to the FLAC file to read. Chris@2: * \assert Chris@2: * \code chain != NULL \endcode Chris@2: * \code filename != NULL \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c true if a valid list of metadata blocks was read from Chris@2: * \a filename, else \c false. On failure, check the status with Chris@2: * FLAC__metadata_chain_status(). Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_chain_read(FLAC__Metadata_Chain *chain, const char *filename); Chris@2: Chris@2: /** Read all metadata from an Ogg FLAC file into the chain. Chris@2: * Chris@2: * \note Ogg FLAC metadata data writing is not supported yet and Chris@2: * FLAC__metadata_chain_write() will fail. Chris@2: * Chris@2: * \param chain A pointer to an existing chain. Chris@2: * \param filename The path to the Ogg FLAC file to read. Chris@2: * \assert Chris@2: * \code chain != NULL \endcode Chris@2: * \code filename != NULL \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c true if a valid list of metadata blocks was read from Chris@2: * \a filename, else \c false. On failure, check the status with Chris@2: * FLAC__metadata_chain_status(). Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_chain_read_ogg(FLAC__Metadata_Chain *chain, const char *filename); Chris@2: Chris@2: /** Read all metadata from a FLAC stream into the chain via I/O callbacks. Chris@2: * Chris@2: * The \a handle need only be open for reading, but must be seekable. Chris@2: * The equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb" Chris@2: * for Windows). Chris@2: * Chris@2: * \param chain A pointer to an existing chain. Chris@2: * \param handle The I/O handle of the FLAC stream to read. The Chris@2: * handle will NOT be closed after the metadata is read; Chris@2: * that is the duty of the caller. Chris@2: * \param callbacks Chris@2: * A set of callbacks to use for I/O. The mandatory Chris@2: * callbacks are \a read, \a seek, and \a tell. Chris@2: * \assert Chris@2: * \code chain != NULL \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c true if a valid list of metadata blocks was read from Chris@2: * \a handle, else \c false. On failure, check the status with Chris@2: * FLAC__metadata_chain_status(). Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_chain_read_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks); Chris@2: Chris@2: /** Read all metadata from an Ogg FLAC stream into the chain via I/O callbacks. Chris@2: * Chris@2: * The \a handle need only be open for reading, but must be seekable. Chris@2: * The equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb" Chris@2: * for Windows). Chris@2: * Chris@2: * \note Ogg FLAC metadata data writing is not supported yet and Chris@2: * FLAC__metadata_chain_write() will fail. Chris@2: * Chris@2: * \param chain A pointer to an existing chain. Chris@2: * \param handle The I/O handle of the Ogg FLAC stream to read. The Chris@2: * handle will NOT be closed after the metadata is read; Chris@2: * that is the duty of the caller. Chris@2: * \param callbacks Chris@2: * A set of callbacks to use for I/O. The mandatory Chris@2: * callbacks are \a read, \a seek, and \a tell. Chris@2: * \assert Chris@2: * \code chain != NULL \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c true if a valid list of metadata blocks was read from Chris@2: * \a handle, else \c false. On failure, check the status with Chris@2: * FLAC__metadata_chain_status(). Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_chain_read_ogg_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks); Chris@2: Chris@2: /** Checks if writing the given chain would require the use of a Chris@2: * temporary file, or if it could be written in place. Chris@2: * Chris@2: * Under certain conditions, padding can be utilized so that writing Chris@2: * edited metadata back to the FLAC file does not require rewriting the Chris@2: * entire file. If rewriting is required, then a temporary workfile is Chris@2: * required. When writing metadata using callbacks, you must check Chris@2: * this function to know whether to call Chris@2: * FLAC__metadata_chain_write_with_callbacks() or Chris@2: * FLAC__metadata_chain_write_with_callbacks_and_tempfile(). When Chris@2: * writing with FLAC__metadata_chain_write(), the temporary file is Chris@2: * handled internally. Chris@2: * Chris@2: * \param chain A pointer to an existing chain. Chris@2: * \param use_padding Chris@2: * Whether or not padding will be allowed to be used Chris@2: * during the write. The value of \a use_padding given Chris@2: * here must match the value later passed to Chris@2: * FLAC__metadata_chain_write_with_callbacks() or Chris@2: * FLAC__metadata_chain_write_with_callbacks_with_tempfile(). Chris@2: * \assert Chris@2: * \code chain != NULL \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c true if writing the current chain would require a tempfile, or Chris@2: * \c false if metadata can be written in place. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_chain_check_if_tempfile_needed(FLAC__Metadata_Chain *chain, FLAC__bool use_padding); Chris@2: Chris@2: /** Write all metadata out to the FLAC file. This function tries to be as Chris@2: * efficient as possible; how the metadata is actually written is shown by Chris@2: * the following: Chris@2: * Chris@2: * If the current chain is the same size as the existing metadata, the new Chris@2: * data is written in place. Chris@2: * Chris@2: * If the current chain is longer than the existing metadata, and Chris@2: * \a use_padding is \c true, and the last block is a PADDING block of Chris@2: * sufficient length, the function will truncate the final padding block Chris@2: * so that the overall size of the metadata is the same as the existing Chris@2: * metadata, and then just rewrite the metadata. Otherwise, if not all of Chris@2: * the above conditions are met, the entire FLAC file must be rewritten. Chris@2: * If you want to use padding this way it is a good idea to call Chris@2: * FLAC__metadata_chain_sort_padding() first so that you have the maximum Chris@2: * amount of padding to work with, unless you need to preserve ordering Chris@2: * of the PADDING blocks for some reason. Chris@2: * Chris@2: * If the current chain is shorter than the existing metadata, and Chris@2: * \a use_padding is \c true, and the final block is a PADDING block, the padding Chris@2: * is extended to make the overall size the same as the existing data. If Chris@2: * \a use_padding is \c true and the last block is not a PADDING block, a new Chris@2: * PADDING block is added to the end of the new data to make it the same Chris@2: * size as the existing data (if possible, see the note to Chris@2: * FLAC__metadata_simple_iterator_set_block() about the four byte limit) Chris@2: * and the new data is written in place. If none of the above apply or Chris@2: * \a use_padding is \c false, the entire FLAC file is rewritten. Chris@2: * Chris@2: * If \a preserve_file_stats is \c true, the owner and modification time will Chris@2: * be preserved even if the FLAC file is written. Chris@2: * Chris@2: * For this write function to be used, the chain must have been read with Chris@2: * FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg(), not Chris@2: * FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(). Chris@2: * Chris@2: * \param chain A pointer to an existing chain. Chris@2: * \param use_padding See above. Chris@2: * \param preserve_file_stats See above. Chris@2: * \assert Chris@2: * \code chain != NULL \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c true if the write succeeded, else \c false. On failure, Chris@2: * check the status with FLAC__metadata_chain_status(). Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_chain_write(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__bool preserve_file_stats); Chris@2: Chris@2: /** Write all metadata out to a FLAC stream via callbacks. Chris@2: * Chris@2: * (See FLAC__metadata_chain_write() for the details on how padding is Chris@2: * used to write metadata in place if possible.) Chris@2: * Chris@2: * The \a handle must be open for updating and be seekable. The Chris@2: * equivalent minimum stdio fopen() file mode is \c "r+" (or \c "r+b" Chris@2: * for Windows). Chris@2: * Chris@2: * For this write function to be used, the chain must have been read with Chris@2: * FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(), Chris@2: * not FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg(). Chris@2: * Also, FLAC__metadata_chain_check_if_tempfile_needed() must have returned Chris@2: * \c false. Chris@2: * Chris@2: * \param chain A pointer to an existing chain. Chris@2: * \param use_padding See FLAC__metadata_chain_write() Chris@2: * \param handle The I/O handle of the FLAC stream to write. The Chris@2: * handle will NOT be closed after the metadata is Chris@2: * written; that is the duty of the caller. Chris@2: * \param callbacks A set of callbacks to use for I/O. The mandatory Chris@2: * callbacks are \a write and \a seek. Chris@2: * \assert Chris@2: * \code chain != NULL \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c true if the write succeeded, else \c false. On failure, Chris@2: * check the status with FLAC__metadata_chain_status(). Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_chain_write_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks); Chris@2: Chris@2: /** Write all metadata out to a FLAC stream via callbacks. Chris@2: * Chris@2: * (See FLAC__metadata_chain_write() for the details on how padding is Chris@2: * used to write metadata in place if possible.) Chris@2: * Chris@2: * This version of the write-with-callbacks function must be used when Chris@2: * FLAC__metadata_chain_check_if_tempfile_needed() returns true. In Chris@2: * this function, you must supply an I/O handle corresponding to the Chris@2: * FLAC file to edit, and a temporary handle to which the new FLAC Chris@2: * file will be written. It is the caller's job to move this temporary Chris@2: * FLAC file on top of the original FLAC file to complete the metadata Chris@2: * edit. Chris@2: * Chris@2: * The \a handle must be open for reading and be seekable. The Chris@2: * equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb" Chris@2: * for Windows). Chris@2: * Chris@2: * The \a temp_handle must be open for writing. The Chris@2: * equivalent minimum stdio fopen() file mode is \c "w" (or \c "wb" Chris@2: * for Windows). It should be an empty stream, or at least positioned Chris@2: * at the start-of-file (in which case it is the caller's duty to Chris@2: * truncate it on return). Chris@2: * Chris@2: * For this write function to be used, the chain must have been read with Chris@2: * FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(), Chris@2: * not FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg(). Chris@2: * Also, FLAC__metadata_chain_check_if_tempfile_needed() must have returned Chris@2: * \c true. Chris@2: * Chris@2: * \param chain A pointer to an existing chain. Chris@2: * \param use_padding See FLAC__metadata_chain_write() Chris@2: * \param handle The I/O handle of the original FLAC stream to read. Chris@2: * The handle will NOT be closed after the metadata is Chris@2: * written; that is the duty of the caller. Chris@2: * \param callbacks A set of callbacks to use for I/O on \a handle. Chris@2: * The mandatory callbacks are \a read, \a seek, and Chris@2: * \a eof. Chris@2: * \param temp_handle The I/O handle of the FLAC stream to write. The Chris@2: * handle will NOT be closed after the metadata is Chris@2: * written; that is the duty of the caller. Chris@2: * \param temp_callbacks Chris@2: * A set of callbacks to use for I/O on temp_handle. Chris@2: * The only mandatory callback is \a write. Chris@2: * \assert Chris@2: * \code chain != NULL \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c true if the write succeeded, else \c false. On failure, Chris@2: * check the status with FLAC__metadata_chain_status(). Chris@2: */ Chris@2: 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); Chris@2: Chris@2: /** Merge adjacent PADDING blocks into a single block. Chris@2: * Chris@2: * \note This function does not write to the FLAC file, it only Chris@2: * modifies the chain. Chris@2: * Chris@2: * \warning Any iterator on the current chain will become invalid after this Chris@2: * call. You should delete the iterator and get a new one. Chris@2: * Chris@2: * \param chain A pointer to an existing chain. Chris@2: * \assert Chris@2: * \code chain != NULL \endcode Chris@2: */ Chris@2: FLAC_API void FLAC__metadata_chain_merge_padding(FLAC__Metadata_Chain *chain); Chris@2: Chris@2: /** This function will move all PADDING blocks to the end on the metadata, Chris@2: * then merge them into a single block. Chris@2: * Chris@2: * \note This function does not write to the FLAC file, it only Chris@2: * modifies the chain. Chris@2: * Chris@2: * \warning Any iterator on the current chain will become invalid after this Chris@2: * call. You should delete the iterator and get a new one. Chris@2: * Chris@2: * \param chain A pointer to an existing chain. Chris@2: * \assert Chris@2: * \code chain != NULL \endcode Chris@2: */ Chris@2: FLAC_API void FLAC__metadata_chain_sort_padding(FLAC__Metadata_Chain *chain); Chris@2: Chris@2: Chris@2: /*********** FLAC__Metadata_Iterator ***********/ Chris@2: Chris@2: /** Create a new iterator instance. Chris@2: * Chris@2: * \retval FLAC__Metadata_Iterator* Chris@2: * \c NULL if there was an error allocating memory, else the new instance. Chris@2: */ Chris@2: FLAC_API FLAC__Metadata_Iterator *FLAC__metadata_iterator_new(void); Chris@2: Chris@2: /** Free an iterator instance. Deletes the object pointed to by \a iterator. Chris@2: * Chris@2: * \param iterator A pointer to an existing iterator. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: */ Chris@2: FLAC_API void FLAC__metadata_iterator_delete(FLAC__Metadata_Iterator *iterator); Chris@2: Chris@2: /** Initialize the iterator to point to the first metadata block in the Chris@2: * given chain. Chris@2: * Chris@2: * \param iterator A pointer to an existing iterator. Chris@2: * \param chain A pointer to an existing and initialized (read) chain. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: * \code chain != NULL \endcode Chris@2: */ Chris@2: FLAC_API void FLAC__metadata_iterator_init(FLAC__Metadata_Iterator *iterator, FLAC__Metadata_Chain *chain); Chris@2: Chris@2: /** Moves the iterator forward one metadata block, returning \c false if Chris@2: * already at the end. Chris@2: * Chris@2: * \param iterator A pointer to an existing initialized iterator. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: * \a iterator has been successfully initialized with Chris@2: * FLAC__metadata_iterator_init() Chris@2: * \retval FLAC__bool Chris@2: * \c false if already at the last metadata block of the chain, else Chris@2: * \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_iterator_next(FLAC__Metadata_Iterator *iterator); Chris@2: Chris@2: /** Moves the iterator backward one metadata block, returning \c false if Chris@2: * already at the beginning. Chris@2: * Chris@2: * \param iterator A pointer to an existing initialized iterator. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: * \a iterator has been successfully initialized with Chris@2: * FLAC__metadata_iterator_init() Chris@2: * \retval FLAC__bool Chris@2: * \c false if already at the first metadata block of the chain, else Chris@2: * \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_iterator_prev(FLAC__Metadata_Iterator *iterator); Chris@2: Chris@2: /** Get the type of the metadata block at the current position. Chris@2: * Chris@2: * \param iterator A pointer to an existing initialized iterator. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: * \a iterator has been successfully initialized with Chris@2: * FLAC__metadata_iterator_init() Chris@2: * \retval FLAC__MetadataType Chris@2: * The type of the metadata block at the current iterator position. Chris@2: */ Chris@2: FLAC_API FLAC__MetadataType FLAC__metadata_iterator_get_block_type(const FLAC__Metadata_Iterator *iterator); Chris@2: Chris@2: /** Get the metadata block at the current position. You can modify Chris@2: * the block in place but must write the chain before the changes Chris@2: * are reflected to the FLAC file. You do not need to call Chris@2: * FLAC__metadata_iterator_set_block() to reflect the changes; Chris@2: * the pointer returned by FLAC__metadata_iterator_get_block() Chris@2: * points directly into the chain. Chris@2: * Chris@2: * \warning Chris@2: * Do not call FLAC__metadata_object_delete() on the returned object; Chris@2: * to delete a block use FLAC__metadata_iterator_delete_block(). Chris@2: * Chris@2: * \param iterator A pointer to an existing initialized iterator. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: * \a iterator has been successfully initialized with Chris@2: * FLAC__metadata_iterator_init() Chris@2: * \retval FLAC__StreamMetadata* Chris@2: * The current metadata block. Chris@2: */ Chris@2: FLAC_API FLAC__StreamMetadata *FLAC__metadata_iterator_get_block(FLAC__Metadata_Iterator *iterator); Chris@2: Chris@2: /** Set the metadata block at the current position, replacing the existing Chris@2: * block. The new block passed in becomes owned by the chain and it will be Chris@2: * deleted when the chain is deleted. Chris@2: * Chris@2: * \param iterator A pointer to an existing initialized iterator. Chris@2: * \param block A pointer to a metadata block. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: * \a iterator has been successfully initialized with Chris@2: * FLAC__metadata_iterator_init() Chris@2: * \code block != NULL \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if the conditions in the above description are not met, or Chris@2: * a memory allocation error occurs, otherwise \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_iterator_set_block(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block); Chris@2: Chris@2: /** Removes the current block from the chain. If \a replace_with_padding is Chris@2: * \c true, the block will instead be replaced with a padding block of equal Chris@2: * size. You can not delete the STREAMINFO block. The iterator will be Chris@2: * left pointing to the block before the one just "deleted", even if Chris@2: * \a replace_with_padding is \c true. Chris@2: * Chris@2: * \param iterator A pointer to an existing initialized iterator. Chris@2: * \param replace_with_padding See above. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: * \a iterator has been successfully initialized with Chris@2: * FLAC__metadata_iterator_init() Chris@2: * \retval FLAC__bool Chris@2: * \c false if the conditions in the above description are not met, Chris@2: * otherwise \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_iterator_delete_block(FLAC__Metadata_Iterator *iterator, FLAC__bool replace_with_padding); Chris@2: Chris@2: /** Insert a new block before the current block. You cannot insert a block Chris@2: * before the first STREAMINFO block. You cannot insert a STREAMINFO block Chris@2: * as there can be only one, the one that already exists at the head when you Chris@2: * read in a chain. The chain takes ownership of the new block and it will be Chris@2: * deleted when the chain is deleted. The iterator will be left pointing to Chris@2: * the new block. Chris@2: * Chris@2: * \param iterator A pointer to an existing initialized iterator. Chris@2: * \param block A pointer to a metadata block to insert. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: * \a iterator has been successfully initialized with Chris@2: * FLAC__metadata_iterator_init() Chris@2: * \retval FLAC__bool Chris@2: * \c false if the conditions in the above description are not met, or Chris@2: * a memory allocation error occurs, otherwise \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_before(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block); Chris@2: Chris@2: /** Insert a new block after the current block. You cannot insert a STREAMINFO Chris@2: * block as there can be only one, the one that already exists at the head when Chris@2: * you read in a chain. The chain takes ownership of the new block and it will Chris@2: * be deleted when the chain is deleted. The iterator will be left pointing to Chris@2: * the new block. Chris@2: * Chris@2: * \param iterator A pointer to an existing initialized iterator. Chris@2: * \param block A pointer to a metadata block to insert. Chris@2: * \assert Chris@2: * \code iterator != NULL \endcode Chris@2: * \a iterator has been successfully initialized with Chris@2: * FLAC__metadata_iterator_init() Chris@2: * \retval FLAC__bool Chris@2: * \c false if the conditions in the above description are not met, or Chris@2: * a memory allocation error occurs, otherwise \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_after(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block); Chris@2: Chris@2: /* \} */ Chris@2: Chris@2: Chris@2: /** \defgroup flac_metadata_object FLAC/metadata.h: metadata object methods Chris@2: * \ingroup flac_metadata Chris@2: * Chris@2: * \brief Chris@2: * This module contains methods for manipulating FLAC metadata objects. Chris@2: * Chris@2: * Since many are variable length we have to be careful about the memory Chris@2: * management. We decree that all pointers to data in the object are Chris@2: * owned by the object and memory-managed by the object. Chris@2: * Chris@2: * Use the FLAC__metadata_object_new() and FLAC__metadata_object_delete() Chris@2: * functions to create all instances. When using the Chris@2: * FLAC__metadata_object_set_*() functions to set pointers to data, set Chris@2: * \a copy to \c true to have the function make it's own copy of the data, or Chris@2: * to \c false to give the object ownership of your data. In the latter case Chris@2: * your pointer must be freeable by free() and will be free()d when the object Chris@2: * is FLAC__metadata_object_delete()d. It is legal to pass a null pointer as Chris@2: * the data pointer to a FLAC__metadata_object_set_*() function as long as Chris@2: * the length argument is 0 and the \a copy argument is \c false. Chris@2: * Chris@2: * The FLAC__metadata_object_new() and FLAC__metadata_object_clone() function Chris@2: * will return \c NULL in the case of a memory allocation error, otherwise a new Chris@2: * object. The FLAC__metadata_object_set_*() functions return \c false in the Chris@2: * case of a memory allocation error. Chris@2: * Chris@2: * We don't have the convenience of C++ here, so note that the library relies Chris@2: * on you to keep the types straight. In other words, if you pass, for Chris@2: * example, a FLAC__StreamMetadata* that represents a STREAMINFO block to Chris@2: * FLAC__metadata_object_application_set_data(), you will get an assertion Chris@2: * failure. Chris@2: * Chris@2: * For convenience the FLAC__metadata_object_vorbiscomment_*() functions Chris@2: * maintain a trailing NUL on each Vorbis comment entry. This is not counted Chris@2: * toward the length or stored in the stream, but it can make working with plain Chris@2: * comments (those that don't contain embedded-NULs in the value) easier. Chris@2: * Entries passed into these functions have trailing NULs added if missing, and Chris@2: * returned entries are guaranteed to have a trailing NUL. Chris@2: * Chris@2: * The FLAC__metadata_object_vorbiscomment_*() functions that take a Vorbis Chris@2: * comment entry/name/value will first validate that it complies with the Vorbis Chris@2: * comment specification and return false if it does not. Chris@2: * Chris@2: * There is no need to recalculate the length field on metadata blocks you Chris@2: * have modified. They will be calculated automatically before they are Chris@2: * written back to a file. Chris@2: * Chris@2: * \{ Chris@2: */ Chris@2: Chris@2: Chris@2: /** Create a new metadata object instance of the given type. Chris@2: * Chris@2: * The object will be "empty"; i.e. values and data pointers will be \c 0, Chris@2: * with the exception of FLAC__METADATA_TYPE_VORBIS_COMMENT, which will have Chris@2: * the vendor string set (but zero comments). Chris@2: * Chris@2: * Do not pass in a value greater than or equal to Chris@2: * \a FLAC__METADATA_TYPE_UNDEFINED unless you really know what you're Chris@2: * doing. Chris@2: * Chris@2: * \param type Type of object to create Chris@2: * \retval FLAC__StreamMetadata* Chris@2: * \c NULL if there was an error allocating memory or the type code is Chris@2: * greater than FLAC__MAX_METADATA_TYPE_CODE, else the new instance. Chris@2: */ Chris@2: FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_new(FLAC__MetadataType type); Chris@2: Chris@2: /** Create a copy of an existing metadata object. Chris@2: * Chris@2: * The copy is a "deep" copy, i.e. dynamically allocated data within the Chris@2: * object is also copied. The caller takes ownership of the new block and Chris@2: * is responsible for freeing it with FLAC__metadata_object_delete(). Chris@2: * Chris@2: * \param object Pointer to object to copy. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \retval FLAC__StreamMetadata* Chris@2: * \c NULL if there was an error allocating memory, else the new instance. Chris@2: */ Chris@2: FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_clone(const FLAC__StreamMetadata *object); Chris@2: Chris@2: /** Free a metadata object. Deletes the object pointed to by \a object. Chris@2: * Chris@2: * The delete is a "deep" delete, i.e. dynamically allocated data within the Chris@2: * object is also deleted. Chris@2: * Chris@2: * \param object A pointer to an existing object. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: */ Chris@2: FLAC_API void FLAC__metadata_object_delete(FLAC__StreamMetadata *object); Chris@2: Chris@2: /** Compares two metadata objects. Chris@2: * Chris@2: * The compare is "deep", i.e. dynamically allocated data within the Chris@2: * object is also compared. Chris@2: * Chris@2: * \param block1 A pointer to an existing object. Chris@2: * \param block2 A pointer to an existing object. Chris@2: * \assert Chris@2: * \code block1 != NULL \endcode Chris@2: * \code block2 != NULL \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c true if objects are identical, else \c false. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_is_equal(const FLAC__StreamMetadata *block1, const FLAC__StreamMetadata *block2); Chris@2: Chris@2: /** Sets the application data of an APPLICATION block. Chris@2: * Chris@2: * If \a copy is \c true, a copy of the data is stored; otherwise, the object Chris@2: * takes ownership of the pointer. The existing data will be freed if this Chris@2: * function is successful, otherwise the original data will remain if \a copy Chris@2: * is \c true and malloc() fails. Chris@2: * Chris@2: * \note It is safe to pass a const pointer to \a data if \a copy is \c true. Chris@2: * Chris@2: * \param object A pointer to an existing APPLICATION object. Chris@2: * \param data A pointer to the data to set. Chris@2: * \param length The length of \a data in bytes. Chris@2: * \param copy See above. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_APPLICATION \endcode Chris@2: * \code (data != NULL && length > 0) || Chris@2: * (data == NULL && length == 0 && copy == false) \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if \a copy is \c true and malloc() fails, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_application_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, unsigned length, FLAC__bool copy); Chris@2: Chris@2: /** Resize the seekpoint array. Chris@2: * Chris@2: * If the size shrinks, elements will truncated; if it grows, new placeholder Chris@2: * points will be added to the end. Chris@2: * Chris@2: * \param object A pointer to an existing SEEKTABLE object. Chris@2: * \param new_num_points The desired length of the array; may be \c 0. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode Chris@2: * \code (object->data.seek_table.points == NULL && object->data.seek_table.num_points == 0) || Chris@2: * (object->data.seek_table.points != NULL && object->data.seek_table.num_points > 0) \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if memory allocation error, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_seektable_resize_points(FLAC__StreamMetadata *object, unsigned new_num_points); Chris@2: Chris@2: /** Set a seekpoint in a seektable. Chris@2: * Chris@2: * \param object A pointer to an existing SEEKTABLE object. Chris@2: * \param point_num Index into seekpoint array to set. Chris@2: * \param point The point to set. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode Chris@2: * \code object->data.seek_table.num_points > point_num \endcode Chris@2: */ Chris@2: FLAC_API void FLAC__metadata_object_seektable_set_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point); Chris@2: Chris@2: /** Insert a seekpoint into a seektable. Chris@2: * Chris@2: * \param object A pointer to an existing SEEKTABLE object. Chris@2: * \param point_num Index into seekpoint array to set. Chris@2: * \param point The point to set. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode Chris@2: * \code object->data.seek_table.num_points >= point_num \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if memory allocation error, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_seektable_insert_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point); Chris@2: Chris@2: /** Delete a seekpoint from a seektable. Chris@2: * Chris@2: * \param object A pointer to an existing SEEKTABLE object. Chris@2: * \param point_num Index into seekpoint array to set. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode Chris@2: * \code object->data.seek_table.num_points > point_num \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if memory allocation error, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_seektable_delete_point(FLAC__StreamMetadata *object, unsigned point_num); Chris@2: Chris@2: /** Check a seektable to see if it conforms to the FLAC specification. Chris@2: * See the format specification for limits on the contents of the Chris@2: * seektable. Chris@2: * Chris@2: * \param object A pointer to an existing SEEKTABLE object. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if seek table is illegal, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_seektable_is_legal(const FLAC__StreamMetadata *object); Chris@2: Chris@2: /** Append a number of placeholder points to the end of a seek table. Chris@2: * Chris@2: * \note Chris@2: * As with the other ..._seektable_template_... functions, you should Chris@2: * call FLAC__metadata_object_seektable_template_sort() when finished Chris@2: * to make the seek table legal. Chris@2: * Chris@2: * \param object A pointer to an existing SEEKTABLE object. Chris@2: * \param num The number of placeholder points to append. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if memory allocation fails, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_placeholders(FLAC__StreamMetadata *object, unsigned num); Chris@2: Chris@2: /** Append a specific seek point template to the end of a seek table. Chris@2: * Chris@2: * \note Chris@2: * As with the other ..._seektable_template_... functions, you should Chris@2: * call FLAC__metadata_object_seektable_template_sort() when finished Chris@2: * to make the seek table legal. Chris@2: * Chris@2: * \param object A pointer to an existing SEEKTABLE object. Chris@2: * \param sample_number The sample number of the seek point template. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if memory allocation fails, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_point(FLAC__StreamMetadata *object, FLAC__uint64 sample_number); Chris@2: Chris@2: /** Append specific seek point templates to the end of a seek table. Chris@2: * Chris@2: * \note Chris@2: * As with the other ..._seektable_template_... functions, you should Chris@2: * call FLAC__metadata_object_seektable_template_sort() when finished Chris@2: * to make the seek table legal. Chris@2: * Chris@2: * \param object A pointer to an existing SEEKTABLE object. Chris@2: * \param sample_numbers An array of sample numbers for the seek points. Chris@2: * \param num The number of seek point templates to append. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if memory allocation fails, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_points(FLAC__StreamMetadata *object, FLAC__uint64 sample_numbers[], unsigned num); Chris@2: Chris@2: /** Append a set of evenly-spaced seek point templates to the end of a Chris@2: * seek table. Chris@2: * Chris@2: * \note Chris@2: * As with the other ..._seektable_template_... functions, you should Chris@2: * call FLAC__metadata_object_seektable_template_sort() when finished Chris@2: * to make the seek table legal. Chris@2: * Chris@2: * \param object A pointer to an existing SEEKTABLE object. Chris@2: * \param num The number of placeholder points to append. Chris@2: * \param total_samples The total number of samples to be encoded; Chris@2: * the seekpoints will be spaced approximately Chris@2: * \a total_samples / \a num samples apart. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode Chris@2: * \code total_samples > 0 \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if memory allocation fails, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points(FLAC__StreamMetadata *object, unsigned num, FLAC__uint64 total_samples); Chris@2: Chris@2: /** Append a set of evenly-spaced seek point templates to the end of a Chris@2: * seek table. Chris@2: * Chris@2: * \note Chris@2: * As with the other ..._seektable_template_... functions, you should Chris@2: * call FLAC__metadata_object_seektable_template_sort() when finished Chris@2: * to make the seek table legal. Chris@2: * Chris@2: * \param object A pointer to an existing SEEKTABLE object. Chris@2: * \param samples The number of samples apart to space the placeholder Chris@2: * points. The first point will be at sample \c 0, the Chris@2: * second at sample \a samples, then 2*\a samples, and Chris@2: * so on. As long as \a samples and \a total_samples Chris@2: * are greater than \c 0, there will always be at least Chris@2: * one seekpoint at sample \c 0. Chris@2: * \param total_samples The total number of samples to be encoded; Chris@2: * the seekpoints will be spaced Chris@2: * \a samples samples apart. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode Chris@2: * \code samples > 0 \endcode Chris@2: * \code total_samples > 0 \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if memory allocation fails, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points_by_samples(FLAC__StreamMetadata *object, unsigned samples, FLAC__uint64 total_samples); Chris@2: Chris@2: /** Sort a seek table's seek points according to the format specification, Chris@2: * removing duplicates. Chris@2: * Chris@2: * \param object A pointer to a seek table to be sorted. Chris@2: * \param compact If \c false, behaves like FLAC__format_seektable_sort(). Chris@2: * If \c true, duplicates are deleted and the seek table is Chris@2: * shrunk appropriately; the number of placeholder points Chris@2: * present in the seek table will be the same after the call Chris@2: * as before. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if realloc() fails, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_sort(FLAC__StreamMetadata *object, FLAC__bool compact); Chris@2: Chris@2: /** Sets the vendor string in a VORBIS_COMMENT block. Chris@2: * Chris@2: * For convenience, a trailing NUL is added to the entry if it doesn't have Chris@2: * one already. Chris@2: * Chris@2: * If \a copy is \c true, a copy of the entry is stored; otherwise, the object Chris@2: * takes ownership of the \c entry.entry pointer. Chris@2: * Chris@2: * \note If this function returns \c false, the caller still owns the Chris@2: * pointer. Chris@2: * Chris@2: * \param object A pointer to an existing VORBIS_COMMENT object. Chris@2: * \param entry The entry to set the vendor string to. Chris@2: * \param copy See above. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode Chris@2: * \code (entry.entry != NULL && entry.length > 0) || Chris@2: * (entry.entry == NULL && entry.length == 0) \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if memory allocation fails or \a entry does not comply with the Chris@2: * Vorbis comment specification, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_vendor_string(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy); Chris@2: Chris@2: /** Resize the comment array. Chris@2: * Chris@2: * If the size shrinks, elements will truncated; if it grows, new empty Chris@2: * fields will be added to the end. Chris@2: * Chris@2: * \param object A pointer to an existing VORBIS_COMMENT object. Chris@2: * \param new_num_comments The desired length of the array; may be \c 0. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode Chris@2: * \code (object->data.vorbis_comment.comments == NULL && object->data.vorbis_comment.num_comments == 0) || Chris@2: * (object->data.vorbis_comment.comments != NULL && object->data.vorbis_comment.num_comments > 0) \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if memory allocation fails, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_resize_comments(FLAC__StreamMetadata *object, unsigned new_num_comments); Chris@2: Chris@2: /** Sets a comment in a VORBIS_COMMENT block. Chris@2: * Chris@2: * For convenience, a trailing NUL is added to the entry if it doesn't have Chris@2: * one already. Chris@2: * Chris@2: * If \a copy is \c true, a copy of the entry is stored; otherwise, the object Chris@2: * takes ownership of the \c entry.entry pointer. Chris@2: * Chris@2: * \note If this function returns \c false, the caller still owns the Chris@2: * pointer. Chris@2: * Chris@2: * \param object A pointer to an existing VORBIS_COMMENT object. Chris@2: * \param comment_num Index into comment array to set. Chris@2: * \param entry The entry to set the comment to. Chris@2: * \param copy See above. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode Chris@2: * \code comment_num < object->data.vorbis_comment.num_comments \endcode Chris@2: * \code (entry.entry != NULL && entry.length > 0) || Chris@2: * (entry.entry == NULL && entry.length == 0) \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if memory allocation fails or \a entry does not comply with the Chris@2: * Vorbis comment specification, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy); Chris@2: Chris@2: /** Insert a comment in a VORBIS_COMMENT block at the given index. Chris@2: * Chris@2: * For convenience, a trailing NUL is added to the entry if it doesn't have Chris@2: * one already. Chris@2: * Chris@2: * If \a copy is \c true, a copy of the entry is stored; otherwise, the object Chris@2: * takes ownership of the \c entry.entry pointer. Chris@2: * Chris@2: * \note If this function returns \c false, the caller still owns the Chris@2: * pointer. Chris@2: * Chris@2: * \param object A pointer to an existing VORBIS_COMMENT object. Chris@2: * \param comment_num The index at which to insert the comment. The comments Chris@2: * at and after \a comment_num move right one position. Chris@2: * To append a comment to the end, set \a comment_num to Chris@2: * \c object->data.vorbis_comment.num_comments . Chris@2: * \param entry The comment to insert. Chris@2: * \param copy See above. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode Chris@2: * \code object->data.vorbis_comment.num_comments >= comment_num \endcode Chris@2: * \code (entry.entry != NULL && entry.length > 0) || Chris@2: * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if memory allocation fails or \a entry does not comply with the Chris@2: * Vorbis comment specification, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_insert_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy); Chris@2: Chris@2: /** Appends a comment to a VORBIS_COMMENT block. Chris@2: * Chris@2: * For convenience, a trailing NUL is added to the entry if it doesn't have Chris@2: * one already. Chris@2: * Chris@2: * If \a copy is \c true, a copy of the entry is stored; otherwise, the object Chris@2: * takes ownership of the \c entry.entry pointer. Chris@2: * Chris@2: * \note If this function returns \c false, the caller still owns the Chris@2: * pointer. Chris@2: * Chris@2: * \param object A pointer to an existing VORBIS_COMMENT object. Chris@2: * \param entry The comment to insert. Chris@2: * \param copy See above. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode Chris@2: * \code (entry.entry != NULL && entry.length > 0) || Chris@2: * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if memory allocation fails or \a entry does not comply with the Chris@2: * Vorbis comment specification, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_append_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy); Chris@2: Chris@2: /** Replaces comments in a VORBIS_COMMENT block with a new one. Chris@2: * Chris@2: * For convenience, a trailing NUL is added to the entry if it doesn't have Chris@2: * one already. Chris@2: * Chris@2: * Depending on the the value of \a all, either all or just the first comment Chris@2: * whose field name(s) match the given entry's name will be replaced by the Chris@2: * given entry. If no comments match, \a entry will simply be appended. Chris@2: * Chris@2: * If \a copy is \c true, a copy of the entry is stored; otherwise, the object Chris@2: * takes ownership of the \c entry.entry pointer. Chris@2: * Chris@2: * \note If this function returns \c false, the caller still owns the Chris@2: * pointer. Chris@2: * Chris@2: * \param object A pointer to an existing VORBIS_COMMENT object. Chris@2: * \param entry The comment to insert. Chris@2: * \param all If \c true, all comments whose field name matches Chris@2: * \a entry's field name will be removed, and \a entry will Chris@2: * be inserted at the position of the first matching Chris@2: * comment. If \c false, only the first comment whose Chris@2: * field name matches \a entry's field name will be Chris@2: * replaced with \a entry. Chris@2: * \param copy See above. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode Chris@2: * \code (entry.entry != NULL && entry.length > 0) || Chris@2: * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if memory allocation fails or \a entry does not comply with the Chris@2: * Vorbis comment specification, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_replace_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool all, FLAC__bool copy); Chris@2: Chris@2: /** Delete a comment in a VORBIS_COMMENT block at the given index. Chris@2: * Chris@2: * \param object A pointer to an existing VORBIS_COMMENT object. Chris@2: * \param comment_num The index of the comment to delete. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode Chris@2: * \code object->data.vorbis_comment.num_comments > comment_num \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if realloc() fails, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_delete_comment(FLAC__StreamMetadata *object, unsigned comment_num); Chris@2: Chris@2: /** Creates a Vorbis comment entry from NUL-terminated name and value strings. Chris@2: * Chris@2: * On return, the filled-in \a entry->entry pointer will point to malloc()ed Chris@2: * memory and shall be owned by the caller. For convenience the entry will Chris@2: * have a terminating NUL. Chris@2: * Chris@2: * \param entry A pointer to a Vorbis comment entry. The entry's Chris@2: * \c entry pointer should not point to allocated Chris@2: * memory as it will be overwritten. Chris@2: * \param field_name The field name in ASCII, \c NUL terminated. Chris@2: * \param field_value The field value in UTF-8, \c NUL terminated. Chris@2: * \assert Chris@2: * \code entry != NULL \endcode Chris@2: * \code field_name != NULL \endcode Chris@2: * \code field_value != NULL \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if malloc() fails, or if \a field_name or \a field_value does Chris@2: * not comply with the Vorbis comment specification, else \c true. Chris@2: */ Chris@2: 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); Chris@2: Chris@2: /** Splits a Vorbis comment entry into NUL-terminated name and value strings. Chris@2: * Chris@2: * The returned pointers to name and value will be allocated by malloc() Chris@2: * and shall be owned by the caller. Chris@2: * Chris@2: * \param entry An existing Vorbis comment entry. Chris@2: * \param field_name The address of where the returned pointer to the Chris@2: * field name will be stored. Chris@2: * \param field_value The address of where the returned pointer to the Chris@2: * field value will be stored. Chris@2: * \assert Chris@2: * \code (entry.entry != NULL && entry.length > 0) \endcode Chris@2: * \code memchr(entry.entry, '=', entry.length) != NULL \endcode Chris@2: * \code field_name != NULL \endcode Chris@2: * \code field_value != NULL \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if memory allocation fails or \a entry does not comply with the Chris@2: * Vorbis comment specification, else \c true. Chris@2: */ Chris@2: 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); Chris@2: Chris@2: /** Check if the given Vorbis comment entry's field name matches the given Chris@2: * field name. Chris@2: * Chris@2: * \param entry An existing Vorbis comment entry. Chris@2: * \param field_name The field name to check. Chris@2: * \param field_name_length The length of \a field_name, not including the Chris@2: * terminating \c NUL. Chris@2: * \assert Chris@2: * \code (entry.entry != NULL && entry.length > 0) \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c true if the field names match, else \c false Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_matches(const FLAC__StreamMetadata_VorbisComment_Entry entry, const char *field_name, unsigned field_name_length); Chris@2: Chris@2: /** Find a Vorbis comment with the given field name. Chris@2: * Chris@2: * The search begins at entry number \a offset; use an offset of 0 to Chris@2: * search from the beginning of the comment array. Chris@2: * Chris@2: * \param object A pointer to an existing VORBIS_COMMENT object. Chris@2: * \param offset The offset into the comment array from where to start Chris@2: * the search. Chris@2: * \param field_name The field name of the comment to find. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode Chris@2: * \code field_name != NULL \endcode Chris@2: * \retval int Chris@2: * The offset in the comment array of the first comment whose field Chris@2: * name matches \a field_name, or \c -1 if no match was found. Chris@2: */ Chris@2: FLAC_API int FLAC__metadata_object_vorbiscomment_find_entry_from(const FLAC__StreamMetadata *object, unsigned offset, const char *field_name); Chris@2: Chris@2: /** Remove first Vorbis comment matching the given field name. Chris@2: * Chris@2: * \param object A pointer to an existing VORBIS_COMMENT object. Chris@2: * \param field_name The field name of comment to delete. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode Chris@2: * \retval int Chris@2: * \c -1 for memory allocation error, \c 0 for no matching entries, Chris@2: * \c 1 for one matching entry deleted. Chris@2: */ Chris@2: FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entry_matching(FLAC__StreamMetadata *object, const char *field_name); Chris@2: Chris@2: /** Remove all Vorbis comments matching the given field name. Chris@2: * Chris@2: * \param object A pointer to an existing VORBIS_COMMENT object. Chris@2: * \param field_name The field name of comments to delete. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode Chris@2: * \retval int Chris@2: * \c -1 for memory allocation error, \c 0 for no matching entries, Chris@2: * else the number of matching entries deleted. Chris@2: */ Chris@2: FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entries_matching(FLAC__StreamMetadata *object, const char *field_name); Chris@2: Chris@2: /** Create a new CUESHEET track instance. Chris@2: * Chris@2: * The object will be "empty"; i.e. values and data pointers will be \c 0. Chris@2: * Chris@2: * \retval FLAC__StreamMetadata_CueSheet_Track* Chris@2: * \c NULL if there was an error allocating memory, else the new instance. Chris@2: */ Chris@2: FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_new(void); Chris@2: Chris@2: /** Create a copy of an existing CUESHEET track object. Chris@2: * Chris@2: * The copy is a "deep" copy, i.e. dynamically allocated data within the Chris@2: * object is also copied. The caller takes ownership of the new object and Chris@2: * is responsible for freeing it with Chris@2: * FLAC__metadata_object_cuesheet_track_delete(). Chris@2: * Chris@2: * \param object Pointer to object to copy. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \retval FLAC__StreamMetadata_CueSheet_Track* Chris@2: * \c NULL if there was an error allocating memory, else the new instance. Chris@2: */ Chris@2: FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_clone(const FLAC__StreamMetadata_CueSheet_Track *object); Chris@2: Chris@2: /** Delete a CUESHEET track object Chris@2: * Chris@2: * \param object A pointer to an existing CUESHEET track object. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: */ Chris@2: FLAC_API void FLAC__metadata_object_cuesheet_track_delete(FLAC__StreamMetadata_CueSheet_Track *object); Chris@2: Chris@2: /** Resize a track's index point array. Chris@2: * Chris@2: * If the size shrinks, elements will truncated; if it grows, new blank Chris@2: * indices will be added to the end. Chris@2: * Chris@2: * \param object A pointer to an existing CUESHEET object. Chris@2: * \param track_num The index of the track to modify. NOTE: this is not Chris@2: * necessarily the same as the track's \a number field. Chris@2: * \param new_num_indices The desired length of the array; may be \c 0. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode Chris@2: * \code object->data.cue_sheet.num_tracks > track_num \endcode Chris@2: * \code (object->data.cue_sheet.tracks[track_num].indices == NULL && object->data.cue_sheet.tracks[track_num].num_indices == 0) || Chris@2: * (object->data.cue_sheet.tracks[track_num].indices != NULL && object->data.cue_sheet.tracks[track_num].num_indices > 0) \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if memory allocation error, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_resize_indices(FLAC__StreamMetadata *object, unsigned track_num, unsigned new_num_indices); Chris@2: Chris@2: /** Insert an index point in a CUESHEET track at the given index. Chris@2: * Chris@2: * \param object A pointer to an existing CUESHEET object. Chris@2: * \param track_num The index of the track to modify. NOTE: this is not Chris@2: * necessarily the same as the track's \a number field. Chris@2: * \param index_num The index into the track's index array at which to Chris@2: * insert the index point. NOTE: this is not necessarily Chris@2: * the same as the index point's \a number field. The Chris@2: * indices at and after \a index_num move right one Chris@2: * position. To append an index point to the end, set Chris@2: * \a index_num to Chris@2: * \c object->data.cue_sheet.tracks[track_num].num_indices . Chris@2: * \param index The index point to insert. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode Chris@2: * \code object->data.cue_sheet.num_tracks > track_num \endcode Chris@2: * \code object->data.cue_sheet.tracks[track_num].num_indices >= index_num \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if realloc() fails, else \c true. Chris@2: */ Chris@2: 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); Chris@2: Chris@2: /** Insert a blank index point in a CUESHEET track at the given index. Chris@2: * Chris@2: * A blank index point is one in which all field values are zero. Chris@2: * Chris@2: * \param object A pointer to an existing CUESHEET object. Chris@2: * \param track_num The index of the track to modify. NOTE: this is not Chris@2: * necessarily the same as the track's \a number field. Chris@2: * \param index_num The index into the track's index array at which to Chris@2: * insert the index point. NOTE: this is not necessarily Chris@2: * the same as the index point's \a number field. The Chris@2: * indices at and after \a index_num move right one Chris@2: * position. To append an index point to the end, set Chris@2: * \a index_num to Chris@2: * \c object->data.cue_sheet.tracks[track_num].num_indices . Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode Chris@2: * \code object->data.cue_sheet.num_tracks > track_num \endcode Chris@2: * \code object->data.cue_sheet.tracks[track_num].num_indices >= index_num \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if realloc() fails, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_blank_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num); Chris@2: Chris@2: /** Delete an index point in a CUESHEET track at the given index. Chris@2: * Chris@2: * \param object A pointer to an existing CUESHEET object. Chris@2: * \param track_num The index into the track array of the track to Chris@2: * modify. NOTE: this is not necessarily the same Chris@2: * as the track's \a number field. Chris@2: * \param index_num The index into the track's index array of the index Chris@2: * to delete. NOTE: this is not necessarily the same Chris@2: * as the index's \a number field. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode Chris@2: * \code object->data.cue_sheet.num_tracks > track_num \endcode Chris@2: * \code object->data.cue_sheet.tracks[track_num].num_indices > index_num \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if realloc() fails, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_delete_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num); Chris@2: Chris@2: /** Resize the track array. Chris@2: * Chris@2: * If the size shrinks, elements will truncated; if it grows, new blank Chris@2: * tracks will be added to the end. Chris@2: * Chris@2: * \param object A pointer to an existing CUESHEET object. Chris@2: * \param new_num_tracks The desired length of the array; may be \c 0. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode Chris@2: * \code (object->data.cue_sheet.tracks == NULL && object->data.cue_sheet.num_tracks == 0) || Chris@2: * (object->data.cue_sheet.tracks != NULL && object->data.cue_sheet.num_tracks > 0) \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if memory allocation error, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_resize_tracks(FLAC__StreamMetadata *object, unsigned new_num_tracks); Chris@2: Chris@2: /** Sets a track in a CUESHEET block. Chris@2: * Chris@2: * If \a copy is \c true, a copy of the track is stored; otherwise, the object Chris@2: * takes ownership of the \a track pointer. Chris@2: * Chris@2: * \param object A pointer to an existing CUESHEET object. Chris@2: * \param track_num Index into track array to set. NOTE: this is not Chris@2: * necessarily the same as the track's \a number field. Chris@2: * \param track The track to set the track to. You may safely pass in Chris@2: * a const pointer if \a copy is \c true. Chris@2: * \param copy See above. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode Chris@2: * \code track_num < object->data.cue_sheet.num_tracks \endcode Chris@2: * \code (track->indices != NULL && track->num_indices > 0) || Chris@2: * (track->indices == NULL && track->num_indices == 0) Chris@2: * \retval FLAC__bool Chris@2: * \c false if \a copy is \c true and malloc() fails, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_set_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy); Chris@2: Chris@2: /** Insert a track in a CUESHEET block at the given index. Chris@2: * Chris@2: * If \a copy is \c true, a copy of the track is stored; otherwise, the object Chris@2: * takes ownership of the \a track pointer. Chris@2: * Chris@2: * \param object A pointer to an existing CUESHEET object. Chris@2: * \param track_num The index at which to insert the track. NOTE: this Chris@2: * is not necessarily the same as the track's \a number Chris@2: * field. The tracks at and after \a track_num move right Chris@2: * one position. To append a track to the end, set Chris@2: * \a track_num to \c object->data.cue_sheet.num_tracks . Chris@2: * \param track The track to insert. You may safely pass in a const Chris@2: * pointer if \a copy is \c true. Chris@2: * \param copy See above. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode Chris@2: * \code object->data.cue_sheet.num_tracks >= track_num \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if \a copy is \c true and malloc() fails, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy); Chris@2: Chris@2: /** Insert a blank track in a CUESHEET block at the given index. Chris@2: * Chris@2: * A blank track is one in which all field values are zero. Chris@2: * Chris@2: * \param object A pointer to an existing CUESHEET object. Chris@2: * \param track_num The index at which to insert the track. NOTE: this Chris@2: * is not necessarily the same as the track's \a number Chris@2: * field. The tracks at and after \a track_num move right Chris@2: * one position. To append a track to the end, set Chris@2: * \a track_num to \c object->data.cue_sheet.num_tracks . Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode Chris@2: * \code object->data.cue_sheet.num_tracks >= track_num \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if \a copy is \c true and malloc() fails, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_blank_track(FLAC__StreamMetadata *object, unsigned track_num); Chris@2: Chris@2: /** Delete a track in a CUESHEET block at the given index. Chris@2: * Chris@2: * \param object A pointer to an existing CUESHEET object. Chris@2: * \param track_num The index into the track array of the track to Chris@2: * delete. NOTE: this is not necessarily the same Chris@2: * as the track's \a number field. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode Chris@2: * \code object->data.cue_sheet.num_tracks > track_num \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if realloc() fails, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_delete_track(FLAC__StreamMetadata *object, unsigned track_num); Chris@2: Chris@2: /** Check a cue sheet to see if it conforms to the FLAC specification. Chris@2: * See the format specification for limits on the contents of the Chris@2: * cue sheet. Chris@2: * Chris@2: * \param object A pointer to an existing CUESHEET object. Chris@2: * \param check_cd_da_subset If \c true, check CUESHEET against more Chris@2: * stringent requirements for a CD-DA (audio) disc. Chris@2: * \param violation Address of a pointer to a string. If there is a Chris@2: * violation, a pointer to a string explanation of the Chris@2: * violation will be returned here. \a violation may be Chris@2: * \c NULL if you don't need the returned string. Do not Chris@2: * free the returned string; it will always point to static Chris@2: * data. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if cue sheet is illegal, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_is_legal(const FLAC__StreamMetadata *object, FLAC__bool check_cd_da_subset, const char **violation); Chris@2: Chris@2: /** Calculate and return the CDDB/freedb ID for a cue sheet. The function Chris@2: * assumes the cue sheet corresponds to a CD; the result is undefined Chris@2: * if the cuesheet's is_cd bit is not set. Chris@2: * Chris@2: * \param object A pointer to an existing CUESHEET object. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode Chris@2: * \retval FLAC__uint32 Chris@2: * The unsigned integer representation of the CDDB/freedb ID Chris@2: */ Chris@2: FLAC_API FLAC__uint32 FLAC__metadata_object_cuesheet_calculate_cddb_id(const FLAC__StreamMetadata *object); Chris@2: Chris@2: /** Sets the MIME type of a PICTURE block. Chris@2: * Chris@2: * If \a copy is \c true, a copy of the string is stored; otherwise, the object Chris@2: * takes ownership of the pointer. The existing string will be freed if this Chris@2: * function is successful, otherwise the original string will remain if \a copy Chris@2: * is \c true and malloc() fails. Chris@2: * Chris@2: * \note It is safe to pass a const pointer to \a mime_type if \a copy is \c true. Chris@2: * Chris@2: * \param object A pointer to an existing PICTURE object. Chris@2: * \param mime_type A pointer to the MIME type string. The string must be Chris@2: * ASCII characters 0x20-0x7e, NUL-terminated. No validation Chris@2: * is done. Chris@2: * \param copy See above. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode Chris@2: * \code (mime_type != NULL) \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if \a copy is \c true and malloc() fails, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_picture_set_mime_type(FLAC__StreamMetadata *object, char *mime_type, FLAC__bool copy); Chris@2: Chris@2: /** Sets the description of a PICTURE block. Chris@2: * Chris@2: * If \a copy is \c true, a copy of the string is stored; otherwise, the object Chris@2: * takes ownership of the pointer. The existing string will be freed if this Chris@2: * function is successful, otherwise the original string will remain if \a copy Chris@2: * is \c true and malloc() fails. Chris@2: * Chris@2: * \note It is safe to pass a const pointer to \a description if \a copy is \c true. Chris@2: * Chris@2: * \param object A pointer to an existing PICTURE object. Chris@2: * \param description A pointer to the description string. The string must be Chris@2: * valid UTF-8, NUL-terminated. No validation is done. Chris@2: * \param copy See above. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode Chris@2: * \code (description != NULL) \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if \a copy is \c true and malloc() fails, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_picture_set_description(FLAC__StreamMetadata *object, FLAC__byte *description, FLAC__bool copy); Chris@2: Chris@2: /** Sets the picture data of a PICTURE block. Chris@2: * Chris@2: * If \a copy is \c true, a copy of the data is stored; otherwise, the object Chris@2: * takes ownership of the pointer. Also sets the \a data_length field of the Chris@2: * metadata object to what is passed in as the \a length parameter. The Chris@2: * existing data will be freed if this function is successful, otherwise the Chris@2: * original data and data_length will remain if \a copy is \c true and Chris@2: * malloc() fails. Chris@2: * Chris@2: * \note It is safe to pass a const pointer to \a data if \a copy is \c true. Chris@2: * Chris@2: * \param object A pointer to an existing PICTURE object. Chris@2: * \param data A pointer to the data to set. Chris@2: * \param length The length of \a data in bytes. Chris@2: * \param copy See above. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode Chris@2: * \code (data != NULL && length > 0) || Chris@2: * (data == NULL && length == 0 && copy == false) \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if \a copy is \c true and malloc() fails, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_picture_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, FLAC__uint32 length, FLAC__bool copy); Chris@2: Chris@2: /** Check a PICTURE block to see if it conforms to the FLAC specification. Chris@2: * See the format specification for limits on the contents of the Chris@2: * PICTURE block. Chris@2: * Chris@2: * \param object A pointer to existing PICTURE block to be checked. Chris@2: * \param violation Address of a pointer to a string. If there is a Chris@2: * violation, a pointer to a string explanation of the Chris@2: * violation will be returned here. \a violation may be Chris@2: * \c NULL if you don't need the returned string. Do not Chris@2: * free the returned string; it will always point to static Chris@2: * data. Chris@2: * \assert Chris@2: * \code object != NULL \endcode Chris@2: * \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode Chris@2: * \retval FLAC__bool Chris@2: * \c false if PICTURE block is illegal, else \c true. Chris@2: */ Chris@2: FLAC_API FLAC__bool FLAC__metadata_object_picture_is_legal(const FLAC__StreamMetadata *object, const char **violation); Chris@2: Chris@2: /* \} */ Chris@2: Chris@2: #ifdef __cplusplus Chris@2: } Chris@2: #endif Chris@2: Chris@2: #endif