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