/* libFLAC - Free Lossless Audio Codec library * Copyright (C) 2001-2009  Josh Coalson * Copyright (C) 2011-2016  Xiph.Org Foundation * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * - Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * - Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * - Neither the name of the Xiph.org Foundation nor the names of its * contributors may be used to endorse or promote products derived from * this software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ #ifndef FLAC__METADATA_H#define FLAC__METADATA_H #include <sys/types.h> /* for off_t */#include "export.h"#include "callback.h"#include "format.h" /* --------------------------------------------------------------------   (For an example of how all these routines are used, see the source   code for the unit tests in src/test_libFLAC/metadata_*.c, or   metaflac in src/metaflac/)   ------------------------------------------------------------------*/ /** \file include/FLAC/metadata.h * *  \brief *  This module provides functions for creating and manipulating FLAC *  metadata blocks in memory, and three progressively more powerful *  interfaces for traversing and editing metadata in FLAC files. * *  See the detailed documentation for each interface in the *  \link flac_metadata metadata \endlink module. */ /** \defgroup flac_metadata FLAC/metadata.h: metadata interfaces *  \ingroup flac * *  \brief *  This module provides functions for creating and manipulating FLAC *  metadata blocks in memory, and three progressively more powerful *  interfaces for traversing and editing metadata in native FLAC files. *  Note that currently only the Chain interface (level 2) supports Ogg *  FLAC files, and it is read-only i.e. no writing back changed *  metadata to file. * *  There are three metadata interfaces of increasing complexity: * *  Level 0: *  Read-only access to the STREAMINFO, VORBIS_COMMENT, CUESHEET, and *  PICTURE blocks. * *  Level 1: *  Read-write access to all metadata blocks.  This level is write- *  efficient in most cases (more on this below), and uses less memory *  than level 2. * *  Level 2: *  Read-write access to all metadata blocks.  This level is write- *  efficient in all cases, but uses more memory since all metadata for *  the whole file is read into memory and manipulated before writing *  out again. * *  What do we mean by efficient?  Since FLAC metadata appears at the *  beginning of the file, when writing metadata back to a FLAC file *  it is possible to grow or shrink the metadata such that the entire *  file must be rewritten.  However, if the size remains the same during *  changes or PADDING blocks are utilized, only the metadata needs to be *  overwritten, which is much faster. * *  Efficient means the whole file is rewritten at most one time, and only *  when necessary.  Level 1 is not efficient only in the case that you *  cause more than one metadata block to grow or shrink beyond what can *  be accommodated by padding.  In this case you should probably use level *  2, which allows you to edit all the metadata for a file in memory and *  write it out all at once. * *  All levels know how to skip over and not disturb an ID3v2 tag at the *  front of the file. * *  All levels access files via their filenames.  In addition, level 2 *  has additional alternative read and write functions that take an I/O *  handle and callbacks, for situations where access by filename is not *  possible. * *  In addition to the three interfaces, this module defines functions for *  creating and manipulating various metadata objects in memory.  As we see *  from the Format module, FLAC metadata blocks in memory are very primitive *  structures for storing information in an efficient way.  Reading *  information from the structures is easy but creating or modifying them *  directly is more complex.  The metadata object routines here facilitate *  this by taking care of the consistency and memory management drudgery. * *  Unless you will be using the level 1 or 2 interfaces to modify existing *  metadata however, you will not probably not need these. * *  From a dependency standpoint, none of the encoders or decoders require *  the metadata module.  This is so that embedded users can strip out the *  metadata module from libFLAC to reduce the size and complexity. */ #ifdef __cplusplusextern "C" {#endif  /** \defgroup flac_metadata_level0 FLAC/metadata.h: metadata level 0 interface *  \ingroup flac_metadata * *  \brief *  The level 0 interface consists of individual routines to read the *  STREAMINFO, VORBIS_COMMENT, CUESHEET, and PICTURE blocks, requiring *  only a filename. * *  They try to skip any ID3v2 tag at the head of the file. * * \{ */ /** Read the STREAMINFO metadata block of the given FLAC file.  This function *  will try to skip any ID3v2 tag at the head of the file. * * \param filename    The path to the FLAC file to read. * \param streaminfo  A pointer to space for the STREAMINFO block.  Since *                    FLAC__StreamMetadata is a simple structure with no *                    memory allocation involved, you pass the address of *                    an existing structure.  It need not be initialized. * \assert *    \code filename != NULL \endcode *    \code streaminfo != NULL \endcode * \retval FLAC__bool *    \c true if a valid STREAMINFO block was read from \a filename.  Returns *    \c false if there was a memory allocation error, a file decoder error, *    or the file contained no STREAMINFO block.  (A memory allocation error *    is possible because this function must set up a file decoder.) */FLAC_API FLAC__bool FLAC__metadata_get_streaminfo(const char *filename, FLAC__StreamMetadata *streaminfo); /** Read the VORBIS_COMMENT metadata block of the given FLAC file.  This *  function will try to skip any ID3v2 tag at the head of the file. * * \param filename    The path to the FLAC file to read. * \param tags        The address where the returned pointer will be *                    stored.  The \a tags object must be deleted by *                    the caller using FLAC__metadata_object_delete(). * \assert *    \code filename != NULL \endcode *    \code tags != NULL \endcode * \retval FLAC__bool *    \c true if a valid VORBIS_COMMENT block was read from \a filename, *    and \a *tags will be set to the address of the metadata structure. *    Returns \c false if there was a memory allocation error, a file *    decoder error, or the file contained no VORBIS_COMMENT block, and *    \a *tags will be set to \c NULL. */FLAC_API FLAC__bool FLAC__metadata_get_tags(const char *filename, FLAC__StreamMetadata **tags); /** Read the CUESHEET metadata block of the given FLAC file.  This *  function will try to skip any ID3v2 tag at the head of the file. * * \param filename    The path to the FLAC file to read. * \param cuesheet    The address where the returned pointer will be *                    stored.  The \a cuesheet object must be deleted by *                    the caller using FLAC__metadata_object_delete(). * \assert *    \code filename != NULL \endcode *    \code cuesheet != NULL \endcode * \retval FLAC__bool *    \c true if a valid CUESHEET block was read from \a filename, *    and \a *cuesheet will be set to the address of the metadata *    structure.  Returns \c false if there was a memory allocation *    error, a file decoder error, or the file contained no CUESHEET *    block, and \a *cuesheet will be set to \c NULL. */FLAC_API FLAC__bool FLAC__metadata_get_cuesheet(const char *filename, FLAC__StreamMetadata **cuesheet); /** Read a PICTURE metadata block of the given FLAC file.  This *  function will try to skip any ID3v2 tag at the head of the file. *  Since there can be more than one PICTURE block in a file, this *  function takes a number of parameters that act as constraints to *  the search.  The PICTURE block with the largest area matching all *  the constraints will be returned, or \a *picture will be set to *  \c NULL if there was no such block. * * \param filename    The path to the FLAC file to read. * \param picture     The address where the returned pointer will be *                    stored.  The \a picture object must be deleted by *                    the caller using FLAC__metadata_object_delete(). * \param type        The desired picture type.  Use \c -1 to mean *                    "any type". * \param mime_type   The desired MIME type, e.g. "image/jpeg".  The *                    string will be matched exactly.  Use \c NULL to *                    mean "any MIME type". * \param description The desired description.  The string will be *                    matched exactly.  Use \c NULL to mean "any *                    description". * \param max_width   The maximum width in pixels desired.  Use *                    \c (uint32_t)(-1) to mean "any width". * \param max_height  The maximum height in pixels desired.  Use *                    \c (uint32_t)(-1) to mean "any height". * \param max_depth   The maximum color depth in bits-per-pixel desired. *                    Use \c (uint32_t)(-1) to mean "any depth". * \param max_colors  The maximum number of colors desired.  Use *                    \c (uint32_t)(-1) to mean "any number of colors". * \assert *    \code filename != NULL \endcode *    \code picture != NULL \endcode * \retval FLAC__bool *    \c true if a valid PICTURE block was read from \a filename, *    and \a *picture will be set to the address of the metadata *    structure.  Returns \c false if there was a memory allocation *    error, a file decoder error, or the file contained no PICTURE *    block, and \a *picture will be set to \c NULL. */FLAC_API FLAC__bool FLAC__metadata_get_picture(const char *filename, FLAC__StreamMetadata **picture, FLAC__StreamMetadata_Picture_Type type, const char *mime_type, const FLAC__byte *description, uint32_t max_width, uint32_t max_height, uint32_t max_depth, uint32_t max_colors); /* \} */  /** \defgroup flac_metadata_level1 FLAC/metadata.h: metadata level 1 interface *  \ingroup flac_metadata * * \brief * The level 1 interface provides read-write access to FLAC file metadata and * operates directly on the FLAC file. * * The general usage of this interface is: * * - Create an iterator using FLAC__metadata_simple_iterator_new() * - Attach it to a file using FLAC__metadata_simple_iterator_init() and check *   the exit code.  Call FLAC__metadata_simple_iterator_is_writable() to *   see if the file is writable, or only read access is allowed. * - Use FLAC__metadata_simple_iterator_next() and *   FLAC__metadata_simple_iterator_prev() to traverse the blocks. *   This is does not read the actual blocks themselves. *   FLAC__metadata_simple_iterator_next() is relatively fast. *   FLAC__metadata_simple_iterator_prev() is slower since it needs to search *   forward from the front of the file. * - Use FLAC__metadata_simple_iterator_get_block_type() or *   FLAC__metadata_simple_iterator_get_block() to access the actual data at *   the current iterator position.  The returned object is yours to modify *   and free. * - Use FLAC__metadata_simple_iterator_set_block() to write a modified block *   back.  You must have write permission to the original file.  Make sure to *   read the whole comment to FLAC__metadata_simple_iterator_set_block() *   below. * - Use FLAC__metadata_simple_iterator_insert_block_after() to add new blocks. *   Use the object creation functions from *   \link flac_metadata_object here \endlink to generate new objects. * - Use FLAC__metadata_simple_iterator_delete_block() to remove the block *   currently referred to by the iterator, or replace it with padding. * - Destroy the iterator with FLAC__metadata_simple_iterator_delete() when *   finished. * * \note * The FLAC file remains open the whole time between * FLAC__metadata_simple_iterator_init() and * FLAC__metadata_simple_iterator_delete(), so make sure you are not altering * the file during this time. * * \note * Do not modify the \a is_last, \a length, or \a type fields of returned * FLAC__StreamMetadata objects.  These are managed automatically. * * \note * If any of the modification functions * (FLAC__metadata_simple_iterator_set_block(), * FLAC__metadata_simple_iterator_delete_block(), * FLAC__metadata_simple_iterator_insert_block_after(), etc.) return \c false, * you should delete the iterator as it may no longer be valid. * * \{ */ struct FLAC__Metadata_SimpleIterator;/** The opaque structure definition for the level 1 iterator type. *  See the *  \link flac_metadata_level1 metadata level 1 module \endlink *  for a detailed description. */typedef struct FLAC__Metadata_SimpleIterator FLAC__Metadata_SimpleIterator; /** Status type for FLAC__Metadata_SimpleIterator. * *  The iterator's current status can be obtained by calling FLAC__metadata_simple_iterator_status(). */typedef enum { 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK = 0,	/**< The iterator is in the normal OK state */ 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT,	/**< The data passed into a function violated the function's usage criteria */ 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ERROR_OPENING_FILE,	/**< The iterator could not open the target file */ 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_A_FLAC_FILE,	/**< The iterator could not find the FLAC signature at the start of the file */ 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_WRITABLE,	/**< The iterator tried to write to a file that was not writable */ 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_BAD_METADATA,	/**< The iterator encountered input that does not conform to the FLAC metadata specification */ 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_READ_ERROR,	/**< The iterator encountered an error while reading the FLAC file */ 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_SEEK_ERROR,	/**< The iterator encountered an error while seeking in the FLAC file */ 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_WRITE_ERROR,	/**< The iterator encountered an error while writing the FLAC file */ 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_RENAME_ERROR,	/**< The iterator encountered an error renaming the FLAC file */ 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_UNLINK_ERROR,	/**< The iterator encountered an error removing the temporary file */ 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_MEMORY_ALLOCATION_ERROR,	/**< Memory allocation failed */ 	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_INTERNAL_ERROR	/**< The caller violated an assertion or an unexpected error occurred */ } FLAC__Metadata_SimpleIteratorStatus; /** Maps a FLAC__Metadata_SimpleIteratorStatus to a C string. * *  Using a FLAC__Metadata_SimpleIteratorStatus as the index to this array *  will give the string equivalent.  The contents should not be modified. */extern FLAC_API const char * const FLAC__Metadata_SimpleIteratorStatusString[];  /** Create a new iterator instance. * * \retval FLAC__Metadata_SimpleIterator* *    \c NULL if there was an error allocating memory, else the new instance. */FLAC_API FLAC__Metadata_SimpleIterator *FLAC__metadata_simple_iterator_new(void); /** Free an iterator instance.  Deletes the object pointed to by \a iterator. * * \param iterator  A pointer to an existing iterator. * \assert *    \code iterator != NULL \endcode */FLAC_API void FLAC__metadata_simple_iterator_delete(FLAC__Metadata_SimpleIterator *iterator); /** Get the current status of the iterator.  Call this after a function *  returns \c false to get the reason for the error.  Also resets the status *  to FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK. * * \param iterator  A pointer to an existing iterator. * \assert *    \code iterator != NULL \endcode * \retval FLAC__Metadata_SimpleIteratorStatus *    The current status of the iterator. */FLAC_API FLAC__Metadata_SimpleIteratorStatus FLAC__metadata_simple_iterator_status(FLAC__Metadata_SimpleIterator *iterator); /** Initialize the iterator to point to the first metadata block in the *  given FLAC file. * * \param iterator             A pointer to an existing iterator. * \param filename             The path to the FLAC file. * \param read_only            If \c true, the FLAC file will be opened *                             in read-only mode; if \c false, the FLAC *                             file will be opened for edit even if no *                             edits are performed. * \param preserve_file_stats  If \c true, the owner and modification *                             time will be preserved even if the FLAC *                             file is written to. * \assert *    \code iterator != NULL \endcode *    \code filename != NULL \endcode * \retval FLAC__bool *    \c false if a memory allocation error occurs, the file can't be *    opened, or another error occurs, else \c true. */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); /** Returns \c true if the FLAC file is writable.  If \c false, calls to *  FLAC__metadata_simple_iterator_set_block() and *  FLAC__metadata_simple_iterator_insert_block_after() will fail. * * \param iterator             A pointer to an existing iterator. * \assert *    \code iterator != NULL \endcode * \retval FLAC__bool *    See above. */FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_writable(const FLAC__Metadata_SimpleIterator *iterator); /** Moves the iterator forward one metadata block, returning \c false if *  already at the end. * * \param iterator  A pointer to an existing initialized iterator. * \assert *    \code iterator != NULL \endcode *    \a iterator has been successfully initialized with *    FLAC__metadata_simple_iterator_init() * \retval FLAC__bool *    \c false if already at the last metadata block of the chain, else *    \c true. */FLAC_API FLAC__bool FLAC__metadata_simple_iterator_next(FLAC__Metadata_SimpleIterator *iterator); /** Moves the iterator backward one metadata block, returning \c false if *  already at the beginning. * * \param iterator  A pointer to an existing initialized iterator. * \assert *    \code iterator != NULL \endcode *    \a iterator has been successfully initialized with *    FLAC__metadata_simple_iterator_init() * \retval FLAC__bool *    \c false if already at the first metadata block of the chain, else *    \c true. */FLAC_API FLAC__bool FLAC__metadata_simple_iterator_prev(FLAC__Metadata_SimpleIterator *iterator); /** Returns a flag telling if the current metadata block is the last. * * \param iterator  A pointer to an existing initialized iterator. * \assert *    \code iterator != NULL \endcode *    \a iterator has been successfully initialized with *    FLAC__metadata_simple_iterator_init() * \retval FLAC__bool *    \c true if the current metadata block is the last in the file, *    else \c false. */FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_last(const FLAC__Metadata_SimpleIterator *iterator); /** Get the offset of the metadata block at the current position.  This *  avoids reading the actual block data which can save time for large *  blocks. * * \param iterator  A pointer to an existing initialized iterator. * \assert *    \code iterator != NULL \endcode *    \a iterator has been successfully initialized with *    FLAC__metadata_simple_iterator_init() * \retval off_t *    The offset of the metadata block at the current iterator position. *    This is the byte offset relative to the beginning of the file of *    the current metadata block's header. */FLAC_API off_t FLAC__metadata_simple_iterator_get_block_offset(const FLAC__Metadata_SimpleIterator *iterator); /** Get the type of the metadata block at the current position.  This *  avoids reading the actual block data which can save time for large *  blocks. * * \param iterator  A pointer to an existing initialized iterator. * \assert *    \code iterator != NULL \endcode *    \a iterator has been successfully initialized with *    FLAC__metadata_simple_iterator_init() * \retval FLAC__MetadataType *    The type of the metadata block at the current iterator position. */FLAC_API FLAC__MetadataType FLAC__metadata_simple_iterator_get_block_type(const FLAC__Metadata_SimpleIterator *iterator); /** Get the length of the metadata block at the current position.  This *  avoids reading the actual block data which can save time for large *  blocks. * * \param iterator  A pointer to an existing initialized iterator. * \assert *    \code iterator != NULL \endcode *    \a iterator has been successfully initialized with *    FLAC__metadata_simple_iterator_init() * \retval uint32_t

Lines 1–500 of 2182. Load more