Moved external frameworks to the "Frameworks" directory for consistency
authorSam Lantinga <slouken@libsdl.org>
Mon, 09 Jan 2012 01:58:40 -0500
changeset 555b92bfb451700
parent 554 d9f9a5f01dad
child 556 2686e67b59fd
Moved external frameworks to the "Frameworks" directory for consistency
Xcode/Frameworks/FLAC.framework/FLAC
Xcode/Frameworks/FLAC.framework/Headers
Xcode/Frameworks/FLAC.framework/LICENSE.FLAC.txt
Xcode/Frameworks/FLAC.framework/Resources
Xcode/Frameworks/FLAC.framework/Versions/A/FLAC
Xcode/Frameworks/FLAC.framework/Versions/A/Headers/FLAC/all.h
Xcode/Frameworks/FLAC.framework/Versions/A/Headers/FLAC/assert.h
Xcode/Frameworks/FLAC.framework/Versions/A/Headers/FLAC/callback.h
Xcode/Frameworks/FLAC.framework/Versions/A/Headers/FLAC/export.h
Xcode/Frameworks/FLAC.framework/Versions/A/Headers/FLAC/format.h
Xcode/Frameworks/FLAC.framework/Versions/A/Headers/FLAC/metadata.h
Xcode/Frameworks/FLAC.framework/Versions/A/Headers/FLAC/ordinals.h
Xcode/Frameworks/FLAC.framework/Versions/A/Headers/FLAC/stream_decoder.h
Xcode/Frameworks/FLAC.framework/Versions/A/Headers/FLAC/stream_encoder.h
Xcode/Frameworks/FLAC.framework/Versions/A/Resources/English.lproj/InfoPlist.strings
Xcode/Frameworks/FLAC.framework/Versions/A/Resources/Info.plist
Xcode/Frameworks/FLAC.framework/Versions/Current
Xcode/Frameworks/Ogg.framework/Headers
Xcode/Frameworks/Ogg.framework/LICENSE.ogg-vorbis.txt
Xcode/Frameworks/Ogg.framework/Ogg
Xcode/Frameworks/Ogg.framework/Resources
Xcode/Frameworks/Ogg.framework/Versions/A/Headers/ogg.h
Xcode/Frameworks/Ogg.framework/Versions/A/Headers/os_types.h
Xcode/Frameworks/Ogg.framework/Versions/A/Ogg
Xcode/Frameworks/Ogg.framework/Versions/A/Resources/English.lproj/InfoPlist.strings
Xcode/Frameworks/Ogg.framework/Versions/A/Resources/Info.plist
Xcode/Frameworks/Ogg.framework/Versions/Current
Xcode/Frameworks/Vorbis.framework/Headers
Xcode/Frameworks/Vorbis.framework/LICENSE.ogg-vorbis.txt
Xcode/Frameworks/Vorbis.framework/Resources
Xcode/Frameworks/Vorbis.framework/Versions/A/Headers/codec.h
Xcode/Frameworks/Vorbis.framework/Versions/A/Headers/vorbisenc.h
Xcode/Frameworks/Vorbis.framework/Versions/A/Headers/vorbisfile.h
Xcode/Frameworks/Vorbis.framework/Versions/A/Resources/English.lproj/InfoPlist.strings
Xcode/Frameworks/Vorbis.framework/Versions/A/Resources/Info.plist
Xcode/Frameworks/Vorbis.framework/Versions/A/Vorbis
Xcode/Frameworks/Vorbis.framework/Versions/Current
Xcode/Frameworks/Vorbis.framework/Vorbis
Xcode/Frameworks/mikmod.framework/Headers
Xcode/Frameworks/mikmod.framework/LICENSE.mikmod.txt
Xcode/Frameworks/mikmod.framework/Resources
Xcode/Frameworks/mikmod.framework/Versions/A/Headers/mikmod.h
Xcode/Frameworks/mikmod.framework/Versions/A/Resources/English.lproj/InfoPlist.strings
Xcode/Frameworks/mikmod.framework/Versions/A/Resources/Info.plist
Xcode/Frameworks/mikmod.framework/Versions/A/mikmod
Xcode/Frameworks/mikmod.framework/Versions/Current
Xcode/Frameworks/mikmod.framework/mikmod
Xcode/Frameworks/smpeg.framework/Headers
Xcode/Frameworks/smpeg.framework/LICENSE.smpeg.txt
Xcode/Frameworks/smpeg.framework/Resources
Xcode/Frameworks/smpeg.framework/Versions/A/Headers/MPEG.h
Xcode/Frameworks/smpeg.framework/Versions/A/Headers/MPEGaction.h
Xcode/Frameworks/smpeg.framework/Versions/A/Headers/MPEGaudio.h
Xcode/Frameworks/smpeg.framework/Versions/A/Headers/MPEGerror.h
Xcode/Frameworks/smpeg.framework/Versions/A/Headers/MPEGfilter.h
Xcode/Frameworks/smpeg.framework/Versions/A/Headers/MPEGlist.h
Xcode/Frameworks/smpeg.framework/Versions/A/Headers/MPEGring.h
Xcode/Frameworks/smpeg.framework/Versions/A/Headers/MPEGstream.h
Xcode/Frameworks/smpeg.framework/Versions/A/Headers/MPEGsystem.h
Xcode/Frameworks/smpeg.framework/Versions/A/Headers/MPEGvideo.h
Xcode/Frameworks/smpeg.framework/Versions/A/Headers/smpeg.h
Xcode/Frameworks/smpeg.framework/Versions/A/Resources/Info.plist
Xcode/Frameworks/smpeg.framework/Versions/A/smpeg
Xcode/Frameworks/smpeg.framework/Versions/Current
Xcode/Frameworks/smpeg.framework/smpeg
Xcode/SDL_mixer.xcodeproj/project.pbxproj
Xcode/flac/FLAC.framework/FLAC
Xcode/flac/FLAC.framework/Headers
Xcode/flac/FLAC.framework/LICENSE.FLAC.txt
Xcode/flac/FLAC.framework/Resources
Xcode/flac/FLAC.framework/Versions/A/FLAC
Xcode/flac/FLAC.framework/Versions/A/Headers/FLAC/all.h
Xcode/flac/FLAC.framework/Versions/A/Headers/FLAC/assert.h
Xcode/flac/FLAC.framework/Versions/A/Headers/FLAC/callback.h
Xcode/flac/FLAC.framework/Versions/A/Headers/FLAC/export.h
Xcode/flac/FLAC.framework/Versions/A/Headers/FLAC/format.h
Xcode/flac/FLAC.framework/Versions/A/Headers/FLAC/metadata.h
Xcode/flac/FLAC.framework/Versions/A/Headers/FLAC/ordinals.h
Xcode/flac/FLAC.framework/Versions/A/Headers/FLAC/stream_decoder.h
Xcode/flac/FLAC.framework/Versions/A/Headers/FLAC/stream_encoder.h
Xcode/flac/FLAC.framework/Versions/A/Resources/English.lproj/InfoPlist.strings
Xcode/flac/FLAC.framework/Versions/A/Resources/Info.plist
Xcode/flac/FLAC.framework/Versions/Current
Xcode/mikmod/mikmod.framework/Headers
Xcode/mikmod/mikmod.framework/LICENSE.mikmod.txt
Xcode/mikmod/mikmod.framework/Resources
Xcode/mikmod/mikmod.framework/Versions/A/Headers/mikmod.h
Xcode/mikmod/mikmod.framework/Versions/A/Resources/English.lproj/InfoPlist.strings
Xcode/mikmod/mikmod.framework/Versions/A/Resources/Info.plist
Xcode/mikmod/mikmod.framework/Versions/A/mikmod
Xcode/mikmod/mikmod.framework/Versions/Current
Xcode/mikmod/mikmod.framework/mikmod
Xcode/smpeg/smpeg.framework/Headers
Xcode/smpeg/smpeg.framework/LICENSE.smpeg.txt
Xcode/smpeg/smpeg.framework/Resources
Xcode/smpeg/smpeg.framework/Versions/A/Headers/MPEG.h
Xcode/smpeg/smpeg.framework/Versions/A/Headers/MPEGaction.h
Xcode/smpeg/smpeg.framework/Versions/A/Headers/MPEGaudio.h
Xcode/smpeg/smpeg.framework/Versions/A/Headers/MPEGerror.h
Xcode/smpeg/smpeg.framework/Versions/A/Headers/MPEGfilter.h
Xcode/smpeg/smpeg.framework/Versions/A/Headers/MPEGlist.h
Xcode/smpeg/smpeg.framework/Versions/A/Headers/MPEGring.h
Xcode/smpeg/smpeg.framework/Versions/A/Headers/MPEGstream.h
Xcode/smpeg/smpeg.framework/Versions/A/Headers/MPEGsystem.h
Xcode/smpeg/smpeg.framework/Versions/A/Headers/MPEGvideo.h
Xcode/smpeg/smpeg.framework/Versions/A/Headers/smpeg.h
Xcode/smpeg/smpeg.framework/Versions/A/Resources/Info.plist
Xcode/smpeg/smpeg.framework/Versions/A/smpeg
Xcode/smpeg/smpeg.framework/Versions/Current
Xcode/smpeg/smpeg.framework/smpeg
Xcode/vorbis/Ogg.framework/Headers
Xcode/vorbis/Ogg.framework/LICENSE.ogg-vorbis.txt
Xcode/vorbis/Ogg.framework/Ogg
Xcode/vorbis/Ogg.framework/Resources
Xcode/vorbis/Ogg.framework/Versions/A/Headers/ogg.h
Xcode/vorbis/Ogg.framework/Versions/A/Headers/os_types.h
Xcode/vorbis/Ogg.framework/Versions/A/Ogg
Xcode/vorbis/Ogg.framework/Versions/A/Resources/English.lproj/InfoPlist.strings
Xcode/vorbis/Ogg.framework/Versions/A/Resources/Info.plist
Xcode/vorbis/Ogg.framework/Versions/Current
Xcode/vorbis/Vorbis.framework/Headers
Xcode/vorbis/Vorbis.framework/LICENSE.ogg-vorbis.txt
Xcode/vorbis/Vorbis.framework/Resources
Xcode/vorbis/Vorbis.framework/Versions/A/Headers/codec.h
Xcode/vorbis/Vorbis.framework/Versions/A/Headers/vorbisenc.h
Xcode/vorbis/Vorbis.framework/Versions/A/Headers/vorbisfile.h
Xcode/vorbis/Vorbis.framework/Versions/A/Resources/English.lproj/InfoPlist.strings
Xcode/vorbis/Vorbis.framework/Versions/A/Resources/Info.plist
Xcode/vorbis/Vorbis.framework/Versions/A/Vorbis
Xcode/vorbis/Vorbis.framework/Versions/Current
Xcode/vorbis/Vorbis.framework/Vorbis
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/Xcode/Frameworks/FLAC.framework/FLAC	Mon Jan 09 01:58:40 2012 -0500
     1.3 @@ -0,0 +1,1 @@
     1.4 +Versions/Current/FLAC
     1.5 \ No newline at end of file
     2.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.2 +++ b/Xcode/Frameworks/FLAC.framework/Headers	Mon Jan 09 01:58:40 2012 -0500
     2.3 @@ -0,0 +1,1 @@
     2.4 +Versions/Current/Headers
     2.5 \ No newline at end of file
     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/Xcode/Frameworks/FLAC.framework/LICENSE.FLAC.txt	Mon Jan 09 01:58:40 2012 -0500
     3.3 @@ -0,0 +1,28 @@
     3.4 +Copyright (C) 2000,2001,2002,2003,2004,2005,2006,2007  Josh Coalson
     3.5 +
     3.6 +Redistribution and use in source and binary forms, with or without
     3.7 +modification, are permitted provided that the following conditions
     3.8 +are met:
     3.9 +
    3.10 +- Redistributions of source code must retain the above copyright
    3.11 +notice, this list of conditions and the following disclaimer.
    3.12 +
    3.13 +- Redistributions in binary form must reproduce the above copyright
    3.14 +notice, this list of conditions and the following disclaimer in the
    3.15 +documentation and/or other materials provided with the distribution.
    3.16 +
    3.17 +- Neither the name of the Xiph.org Foundation nor the names of its
    3.18 +contributors may be used to endorse or promote products derived from
    3.19 +this software without specific prior written permission.
    3.20 +
    3.21 +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    3.22 +``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    3.23 +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    3.24 +A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
    3.25 +CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    3.26 +EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    3.27 +PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    3.28 +PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    3.29 +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    3.30 +NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    3.31 +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/Xcode/Frameworks/FLAC.framework/Resources	Mon Jan 09 01:58:40 2012 -0500
     4.3 @@ -0,0 +1,1 @@
     4.4 +Versions/Current/Resources
     4.5 \ No newline at end of file
     5.1 Binary file Xcode/Frameworks/FLAC.framework/Versions/A/FLAC has changed
     6.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.2 +++ b/Xcode/Frameworks/FLAC.framework/Versions/A/Headers/FLAC/all.h	Mon Jan 09 01:58:40 2012 -0500
     6.3 @@ -0,0 +1,370 @@
     6.4 +/* libFLAC - Free Lossless Audio Codec library
     6.5 + * Copyright (C) 2000,2001,2002,2003,2004,2005,2006,2007  Josh Coalson
     6.6 + *
     6.7 + * Redistribution and use in source and binary forms, with or without
     6.8 + * modification, are permitted provided that the following conditions
     6.9 + * are met:
    6.10 + *
    6.11 + * - Redistributions of source code must retain the above copyright
    6.12 + * notice, this list of conditions and the following disclaimer.
    6.13 + *
    6.14 + * - Redistributions in binary form must reproduce the above copyright
    6.15 + * notice, this list of conditions and the following disclaimer in the
    6.16 + * documentation and/or other materials provided with the distribution.
    6.17 + *
    6.18 + * - Neither the name of the Xiph.org Foundation nor the names of its
    6.19 + * contributors may be used to endorse or promote products derived from
    6.20 + * this software without specific prior written permission.
    6.21 + *
    6.22 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    6.23 + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    6.24 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    6.25 + * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
    6.26 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    6.27 + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    6.28 + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    6.29 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    6.30 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    6.31 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    6.32 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    6.33 + */
    6.34 +
    6.35 +#ifndef FLAC__ALL_H
    6.36 +#define FLAC__ALL_H
    6.37 +
    6.38 +#include "export.h"
    6.39 +
    6.40 +#include "assert.h"
    6.41 +#include "callback.h"
    6.42 +#include "format.h"
    6.43 +#include "metadata.h"
    6.44 +#include "ordinals.h"
    6.45 +#include "stream_decoder.h"
    6.46 +#include "stream_encoder.h"
    6.47 +
    6.48 +/** \mainpage
    6.49 + *
    6.50 + * \section intro Introduction
    6.51 + *
    6.52 + * This is the documentation for the FLAC C and C++ APIs.  It is
    6.53 + * highly interconnected; this introduction should give you a top
    6.54 + * level idea of the structure and how to find the information you
    6.55 + * need.  As a prerequisite you should have at least a basic
    6.56 + * knowledge of the FLAC format, documented
    6.57 + * <A HREF="../format.html">here</A>.
    6.58 + *
    6.59 + * \section c_api FLAC C API
    6.60 + *
    6.61 + * The FLAC C API is the interface to libFLAC, a set of structures
    6.62 + * describing the components of FLAC streams, and functions for
    6.63 + * encoding and decoding streams, as well as manipulating FLAC
    6.64 + * metadata in files.  The public include files will be installed
    6.65 + * in your include area (for example /usr/include/FLAC/...).
    6.66 + *
    6.67 + * By writing a little code and linking against libFLAC, it is
    6.68 + * relatively easy to add FLAC support to another program.  The
    6.69 + * library is licensed under <A HREF="../license.html">Xiph's BSD license</A>.
    6.70 + * Complete source code of libFLAC as well as the command-line
    6.71 + * encoder and plugins is available and is a useful source of
    6.72 + * examples.
    6.73 + *
    6.74 + * Aside from encoders and decoders, libFLAC provides a powerful
    6.75 + * metadata interface for manipulating metadata in FLAC files.  It
    6.76 + * allows the user to add, delete, and modify FLAC metadata blocks
    6.77 + * and it can automatically take advantage of PADDING blocks to avoid
    6.78 + * rewriting the entire FLAC file when changing the size of the
    6.79 + * metadata.
    6.80 + *
    6.81 + * libFLAC usually only requires the standard C library and C math
    6.82 + * library. In particular, threading is not used so there is no
    6.83 + * dependency on a thread library. However, libFLAC does not use
    6.84 + * global variables and should be thread-safe.
    6.85 + *
    6.86 + * libFLAC also supports encoding to and decoding from Ogg FLAC.
    6.87 + * However the metadata editing interfaces currently have limited
    6.88 + * read-only support for Ogg FLAC files.
    6.89 + *
    6.90 + * \section cpp_api FLAC C++ API
    6.91 + *
    6.92 + * The FLAC C++ API is a set of classes that encapsulate the
    6.93 + * structures and functions in libFLAC.  They provide slightly more
    6.94 + * functionality with respect to metadata but are otherwise
    6.95 + * equivalent.  For the most part, they share the same usage as
    6.96 + * their counterparts in libFLAC, and the FLAC C API documentation
    6.97 + * can be used as a supplement.  The public include files
    6.98 + * for the C++ API will be installed in your include area (for
    6.99 + * example /usr/include/FLAC++/...).
   6.100 + *
   6.101 + * libFLAC++ is also licensed under
   6.102 + * <A HREF="../license.html">Xiph's BSD license</A>.
   6.103 + *
   6.104 + * \section getting_started Getting Started
   6.105 + *
   6.106 + * A good starting point for learning the API is to browse through
   6.107 + * the <A HREF="modules.html">modules</A>.  Modules are logical
   6.108 + * groupings of related functions or classes, which correspond roughly
   6.109 + * to header files or sections of header files.  Each module includes a
   6.110 + * detailed description of the general usage of its functions or
   6.111 + * classes.
   6.112 + *
   6.113 + * From there you can go on to look at the documentation of
   6.114 + * individual functions.  You can see different views of the individual
   6.115 + * functions through the links in top bar across this page.
   6.116 + *
   6.117 + * If you prefer a more hands-on approach, you can jump right to some
   6.118 + * <A HREF="../documentation_example_code.html">example code</A>.
   6.119 + *
   6.120 + * \section porting_guide Porting Guide
   6.121 + *
   6.122 + * Starting with FLAC 1.1.3 a \link porting Porting Guide \endlink
   6.123 + * has been introduced which gives detailed instructions on how to
   6.124 + * port your code to newer versions of FLAC.
   6.125 + *
   6.126 + * \section embedded_developers Embedded Developers
   6.127 + *
   6.128 + * libFLAC has grown larger over time as more functionality has been
   6.129 + * included, but much of it may be unnecessary for a particular embedded
   6.130 + * implementation.  Unused parts may be pruned by some simple editing of
   6.131 + * src/libFLAC/Makefile.am.  In general, the decoders, encoders, and
   6.132 + * metadata interface are all independent from each other.
   6.133 + *
   6.134 + * It is easiest to just describe the dependencies:
   6.135 + *
   6.136 + * - All modules depend on the \link flac_format Format \endlink module.
   6.137 + * - The decoders and encoders depend on the bitbuffer.
   6.138 + * - The decoder is independent of the encoder.  The encoder uses the
   6.139 + *   decoder because of the verify feature, but this can be removed if
   6.140 + *   not needed.
   6.141 + * - Parts of the metadata interface require the stream decoder (but not
   6.142 + *   the encoder).
   6.143 + * - Ogg support is selectable through the compile time macro
   6.144 + *   \c FLAC__HAS_OGG.
   6.145 + *
   6.146 + * For example, if your application only requires the stream decoder, no
   6.147 + * encoder, and no metadata interface, you can remove the stream encoder
   6.148 + * and the metadata interface, which will greatly reduce the size of the
   6.149 + * library.
   6.150 + *
   6.151 + * Also, there are several places in the libFLAC code with comments marked
   6.152 + * with "OPT:" where a #define can be changed to enable code that might be
   6.153 + * faster on a specific platform.  Experimenting with these can yield faster
   6.154 + * binaries.
   6.155 + */
   6.156 +
   6.157 +/** \defgroup porting Porting Guide for New Versions
   6.158 + *
   6.159 + * This module describes differences in the library interfaces from
   6.160 + * version to version.  It assists in the porting of code that uses
   6.161 + * the libraries to newer versions of FLAC.
   6.162 + *
   6.163 + * One simple facility for making porting easier that has been added
   6.164 + * in FLAC 1.1.3 is a set of \c #defines in \c export.h of each
   6.165 + * library's includes (e.g. \c include/FLAC/export.h).  The
   6.166 + * \c #defines mirror the libraries'
   6.167 + * <A HREF="http://www.gnu.org/software/libtool/manual.html#Libtool-versioning">libtool version numbers</A>,
   6.168 + * e.g. in libFLAC there are \c FLAC_API_VERSION_CURRENT,
   6.169 + * \c FLAC_API_VERSION_REVISION, and \c FLAC_API_VERSION_AGE.
   6.170 + * These can be used to support multiple versions of an API during the
   6.171 + * transition phase, e.g.
   6.172 + *
   6.173 + * \code
   6.174 + * #if !defined(FLAC_API_VERSION_CURRENT) || FLAC_API_VERSION_CURRENT <= 7
   6.175 + *   legacy code
   6.176 + * #else
   6.177 + *   new code
   6.178 + * #endif
   6.179 + * \endcode
   6.180 + *
   6.181 + * The the source will work for multiple versions and the legacy code can
   6.182 + * easily be removed when the transition is complete.
   6.183 + *
   6.184 + * Another available symbol is FLAC_API_SUPPORTS_OGG_FLAC (defined in
   6.185 + * include/FLAC/export.h), which can be used to determine whether or not
   6.186 + * the library has been compiled with support for Ogg FLAC.  This is
   6.187 + * simpler than trying to call an Ogg init function and catching the
   6.188 + * error.
   6.189 + */
   6.190 +
   6.191 +/** \defgroup porting_1_1_2_to_1_1_3 Porting from FLAC 1.1.2 to 1.1.3
   6.192 + *  \ingroup porting
   6.193 + *
   6.194 + *  \brief
   6.195 + *  This module describes porting from FLAC 1.1.2 to FLAC 1.1.3.
   6.196 + *
   6.197 + * The main change between the APIs in 1.1.2 and 1.1.3 is that they have
   6.198 + * been simplified.  First, libOggFLAC has been merged into libFLAC and
   6.199 + * libOggFLAC++ has been merged into libFLAC++.  Second, both the three
   6.200 + * decoding layers and three encoding layers have been merged into a
   6.201 + * single stream decoder and stream encoder.  That is, the functionality
   6.202 + * of FLAC__SeekableStreamDecoder and FLAC__FileDecoder has been merged
   6.203 + * into FLAC__StreamDecoder, and FLAC__SeekableStreamEncoder and
   6.204 + * FLAC__FileEncoder into FLAC__StreamEncoder.  Only the
   6.205 + * FLAC__StreamDecoder and FLAC__StreamEncoder remain.  What this means
   6.206 + * is there is now a single API that can be used to encode or decode
   6.207 + * streams to/from native FLAC or Ogg FLAC and the single API can work
   6.208 + * on both seekable and non-seekable streams.
   6.209 + *
   6.210 + * Instead of creating an encoder or decoder of a certain layer, now the
   6.211 + * client will always create a FLAC__StreamEncoder or
   6.212 + * FLAC__StreamDecoder.  The old layers are now differentiated by the
   6.213 + * initialization function.  For example, for the decoder,
   6.214 + * FLAC__stream_decoder_init() has been replaced by
   6.215 + * FLAC__stream_decoder_init_stream().  This init function takes
   6.216 + * callbacks for the I/O, and the seeking callbacks are optional.  This
   6.217 + * allows the client to use the same object for seekable and
   6.218 + * non-seekable streams.  For decoding a FLAC file directly, the client
   6.219 + * can use FLAC__stream_decoder_init_file() and pass just a filename
   6.220 + * and fewer callbacks; most of the other callbacks are supplied
   6.221 + * internally.  For situations where fopen()ing by filename is not
   6.222 + * possible (e.g. Unicode filenames on Windows) the client can instead
   6.223 + * open the file itself and supply the FILE* to
   6.224 + * FLAC__stream_decoder_init_FILE().  The init functions now returns a
   6.225 + * FLAC__StreamDecoderInitStatus instead of FLAC__StreamDecoderState.
   6.226 + * Since the callbacks and client data are now passed to the init
   6.227 + * function, the FLAC__stream_decoder_set_*_callback() functions and
   6.228 + * FLAC__stream_decoder_set_client_data() are no longer needed.  The
   6.229 + * rest of the calls to the decoder are the same as before.
   6.230 + *
   6.231 + * There are counterpart init functions for Ogg FLAC, e.g.
   6.232 + * FLAC__stream_decoder_init_ogg_stream().  All the rest of the calls
   6.233 + * and callbacks are the same as for native FLAC.
   6.234 + *
   6.235 + * As an example, in FLAC 1.1.2 a seekable stream decoder would have
   6.236 + * been set up like so:
   6.237 + *
   6.238 + * \code
   6.239 + * FLAC__SeekableStreamDecoder *decoder = FLAC__seekable_stream_decoder_new();
   6.240 + * if(decoder == NULL) do_something;
   6.241 + * FLAC__seekable_stream_decoder_set_md5_checking(decoder, true);
   6.242 + * [... other settings ...]
   6.243 + * FLAC__seekable_stream_decoder_set_read_callback(decoder, my_read_callback);
   6.244 + * FLAC__seekable_stream_decoder_set_seek_callback(decoder, my_seek_callback);
   6.245 + * FLAC__seekable_stream_decoder_set_tell_callback(decoder, my_tell_callback);
   6.246 + * FLAC__seekable_stream_decoder_set_length_callback(decoder, my_length_callback);
   6.247 + * FLAC__seekable_stream_decoder_set_eof_callback(decoder, my_eof_callback);
   6.248 + * FLAC__seekable_stream_decoder_set_write_callback(decoder, my_write_callback);
   6.249 + * FLAC__seekable_stream_decoder_set_metadata_callback(decoder, my_metadata_callback);
   6.250 + * FLAC__seekable_stream_decoder_set_error_callback(decoder, my_error_callback);
   6.251 + * FLAC__seekable_stream_decoder_set_client_data(decoder, my_client_data);
   6.252 + * if(FLAC__seekable_stream_decoder_init(decoder) != FLAC__SEEKABLE_STREAM_DECODER_OK) do_something;
   6.253 + * \endcode
   6.254 + *
   6.255 + * In FLAC 1.1.3 it is like this:
   6.256 + *
   6.257 + * \code
   6.258 + * FLAC__StreamDecoder *decoder = FLAC__stream_decoder_new();
   6.259 + * if(decoder == NULL) do_something;
   6.260 + * FLAC__stream_decoder_set_md5_checking(decoder, true);
   6.261 + * [... other settings ...]
   6.262 + * if(FLAC__stream_decoder_init_stream(
   6.263 + *   decoder,
   6.264 + *   my_read_callback,
   6.265 + *   my_seek_callback,      // or NULL
   6.266 + *   my_tell_callback,      // or NULL
   6.267 + *   my_length_callback,    // or NULL
   6.268 + *   my_eof_callback,       // or NULL
   6.269 + *   my_write_callback,
   6.270 + *   my_metadata_callback,  // or NULL
   6.271 + *   my_error_callback,
   6.272 + *   my_client_data
   6.273 + * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
   6.274 + * \endcode
   6.275 + *
   6.276 + * or you could do;
   6.277 + *
   6.278 + * \code
   6.279 + * [...]
   6.280 + * FILE *file = fopen("somefile.flac","rb");
   6.281 + * if(file == NULL) do_somthing;
   6.282 + * if(FLAC__stream_decoder_init_FILE(
   6.283 + *   decoder,
   6.284 + *   file,
   6.285 + *   my_write_callback,
   6.286 + *   my_metadata_callback,  // or NULL
   6.287 + *   my_error_callback,
   6.288 + *   my_client_data
   6.289 + * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
   6.290 + * \endcode
   6.291 + *
   6.292 + * or just:
   6.293 + *
   6.294 + * \code
   6.295 + * [...]
   6.296 + * if(FLAC__stream_decoder_init_file(
   6.297 + *   decoder,
   6.298 + *   "somefile.flac",
   6.299 + *   my_write_callback,
   6.300 + *   my_metadata_callback,  // or NULL
   6.301 + *   my_error_callback,
   6.302 + *   my_client_data
   6.303 + * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
   6.304 + * \endcode
   6.305 + *
   6.306 + * Another small change to the decoder is in how it handles unparseable
   6.307 + * streams.  Before, when the decoder found an unparseable stream
   6.308 + * (reserved for when the decoder encounters a stream from a future
   6.309 + * encoder that it can't parse), it changed the state to
   6.310 + * \c FLAC__STREAM_DECODER_UNPARSEABLE_STREAM.  Now the decoder instead
   6.311 + * drops sync and calls the error callback with a new error code
   6.312 + * \c FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM.  This is
   6.313 + * more robust.  If your error callback does not discriminate on the the
   6.314 + * error state, your code does not need to be changed.
   6.315 + *
   6.316 + * The encoder now has a new setting:
   6.317 + * FLAC__stream_encoder_set_apodization().  This is for setting the
   6.318 + * method used to window the data before LPC analysis.  You only need to
   6.319 + * add a call to this function if the default is not suitable.   There
   6.320 + * are also two new convenience functions that may be useful:
   6.321 + * FLAC__metadata_object_cuesheet_calculate_cddb_id() and
   6.322 + * FLAC__metadata_get_cuesheet().
   6.323 + *
   6.324 + * The \a bytes parameter to FLAC__StreamDecoderReadCallback,
   6.325 + * FLAC__StreamEncoderReadCallback, and FLAC__StreamEncoderWriteCallback
   6.326 + * is now \c size_t instead of \c unsigned.
   6.327 + */
   6.328 +
   6.329 +/** \defgroup porting_1_1_3_to_1_1_4 Porting from FLAC 1.1.3 to 1.1.4
   6.330 + *  \ingroup porting
   6.331 + *
   6.332 + *  \brief
   6.333 + *  This module describes porting from FLAC 1.1.3 to FLAC 1.1.4.
   6.334 + *
   6.335 + * There were no changes to any of the interfaces from 1.1.3 to 1.1.4.
   6.336 + * There was a slight change in the implementation of
   6.337 + * FLAC__stream_encoder_set_metadata(); the function now makes a copy
   6.338 + * of the \a metadata array of pointers so the client no longer needs
   6.339 + * to maintain it after the call.  The objects themselves that are
   6.340 + * pointed to by the array are still not copied though and must be
   6.341 + * maintained until the call to FLAC__stream_encoder_finish().
   6.342 + */
   6.343 +
   6.344 +/** \defgroup porting_1_1_4_to_1_2_0 Porting from FLAC 1.1.4 to 1.2.0
   6.345 + *  \ingroup porting
   6.346 + *
   6.347 + *  \brief
   6.348 + *  This module describes porting from FLAC 1.1.4 to FLAC 1.2.0.
   6.349 + *
   6.350 + * There were only very minor changes to the interfaces from 1.1.4 to 1.2.0.
   6.351 + * In libFLAC, \c FLAC__format_sample_rate_is_subset() was added.
   6.352 + * In libFLAC++, \c FLAC::Decoder::Stream::get_decode_position() was added.
   6.353 + *
   6.354 + * Finally, value of the constant \c FLAC__FRAME_HEADER_RESERVED_LEN
   6.355 + * has changed to reflect the conversion of one of the reserved bits
   6.356 + * into active use.  It used to be \c 2 and now is \c 1.  However the
   6.357 + * FLAC frame header length has not changed, so to skip the proper
   6.358 + * number of bits, use \c FLAC__FRAME_HEADER_RESERVED_LEN +
   6.359 + * \c FLAC__FRAME_HEADER_BLOCKING_STRATEGY_LEN
   6.360 + */
   6.361 +
   6.362 +/** \defgroup flac FLAC C API
   6.363 + *
   6.364 + * The FLAC C API is the interface to libFLAC, a set of structures
   6.365 + * describing the components of FLAC streams, and functions for
   6.366 + * encoding and decoding streams, as well as manipulating FLAC
   6.367 + * metadata in files.
   6.368 + *
   6.369 + * You should start with the format components as all other modules
   6.370 + * are dependent on it.
   6.371 + */
   6.372 +
   6.373 +#endif
     7.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     7.2 +++ b/Xcode/Frameworks/FLAC.framework/Versions/A/Headers/FLAC/assert.h	Mon Jan 09 01:58:40 2012 -0500
     7.3 @@ -0,0 +1,45 @@
     7.4 +/* libFLAC - Free Lossless Audio Codec library
     7.5 + * Copyright (C) 2001,2002,2003,2004,2005,2006,2007  Josh Coalson
     7.6 + *
     7.7 + * Redistribution and use in source and binary forms, with or without
     7.8 + * modification, are permitted provided that the following conditions
     7.9 + * are met:
    7.10 + *
    7.11 + * - Redistributions of source code must retain the above copyright
    7.12 + * notice, this list of conditions and the following disclaimer.
    7.13 + *
    7.14 + * - Redistributions in binary form must reproduce the above copyright
    7.15 + * notice, this list of conditions and the following disclaimer in the
    7.16 + * documentation and/or other materials provided with the distribution.
    7.17 + *
    7.18 + * - Neither the name of the Xiph.org Foundation nor the names of its
    7.19 + * contributors may be used to endorse or promote products derived from
    7.20 + * this software without specific prior written permission.
    7.21 + *
    7.22 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    7.23 + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    7.24 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    7.25 + * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
    7.26 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    7.27 + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    7.28 + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    7.29 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    7.30 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    7.31 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    7.32 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    7.33 + */
    7.34 +
    7.35 +#ifndef FLAC__ASSERT_H
    7.36 +#define FLAC__ASSERT_H
    7.37 +
    7.38 +/* we need this since some compilers (like MSVC) leave assert()s on release code (and we don't want to use their ASSERT) */
    7.39 +#ifdef DEBUG
    7.40 +#include <assert.h>
    7.41 +#define FLAC__ASSERT(x) assert(x)
    7.42 +#define FLAC__ASSERT_DECLARATION(x) x
    7.43 +#else
    7.44 +#define FLAC__ASSERT(x)
    7.45 +#define FLAC__ASSERT_DECLARATION(x)
    7.46 +#endif
    7.47 +
    7.48 +#endif
     8.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     8.2 +++ b/Xcode/Frameworks/FLAC.framework/Versions/A/Headers/FLAC/callback.h	Mon Jan 09 01:58:40 2012 -0500
     8.3 @@ -0,0 +1,184 @@
     8.4 +/* libFLAC - Free Lossless Audio Codec library
     8.5 + * Copyright (C) 2004,2005,2006,2007  Josh Coalson
     8.6 + *
     8.7 + * Redistribution and use in source and binary forms, with or without
     8.8 + * modification, are permitted provided that the following conditions
     8.9 + * are met:
    8.10 + *
    8.11 + * - Redistributions of source code must retain the above copyright
    8.12 + * notice, this list of conditions and the following disclaimer.
    8.13 + *
    8.14 + * - Redistributions in binary form must reproduce the above copyright
    8.15 + * notice, this list of conditions and the following disclaimer in the
    8.16 + * documentation and/or other materials provided with the distribution.
    8.17 + *
    8.18 + * - Neither the name of the Xiph.org Foundation nor the names of its
    8.19 + * contributors may be used to endorse or promote products derived from
    8.20 + * this software without specific prior written permission.
    8.21 + *
    8.22 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    8.23 + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    8.24 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    8.25 + * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
    8.26 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    8.27 + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    8.28 + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    8.29 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    8.30 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    8.31 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    8.32 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    8.33 + */
    8.34 +
    8.35 +#ifndef FLAC__CALLBACK_H
    8.36 +#define FLAC__CALLBACK_H
    8.37 +
    8.38 +#include "ordinals.h"
    8.39 +#include <stdlib.h> /* for size_t */
    8.40 +
    8.41 +/** \file include/FLAC/callback.h
    8.42 + *
    8.43 + *  \brief
    8.44 + *  This module defines the structures for describing I/O callbacks
    8.45 + *  to the other FLAC interfaces.
    8.46 + *
    8.47 + *  See the detailed documentation for callbacks in the
    8.48 + *  \link flac_callbacks callbacks \endlink module.
    8.49 + */
    8.50 +
    8.51 +/** \defgroup flac_callbacks FLAC/callback.h: I/O callback structures
    8.52 + *  \ingroup flac
    8.53 + *
    8.54 + *  \brief
    8.55 + *  This module defines the structures for describing I/O callbacks
    8.56 + *  to the other FLAC interfaces.
    8.57 + *
    8.58 + *  The purpose of the I/O callback functions is to create a common way
    8.59 + *  for the metadata interfaces to handle I/O.
    8.60 + *
    8.61 + *  Originally the metadata interfaces required filenames as the way of
    8.62 + *  specifying FLAC files to operate on.  This is problematic in some
    8.63 + *  environments so there is an additional option to specify a set of
    8.64 + *  callbacks for doing I/O on the FLAC file, instead of the filename.
    8.65 + *
    8.66 + *  In addition to the callbacks, a FLAC__IOHandle type is defined as an
    8.67 + *  opaque structure for a data source.
    8.68 + *
    8.69 + *  The callback function prototypes are similar (but not identical) to the
    8.70 + *  stdio functions fread, fwrite, fseek, ftell, feof, and fclose.  If you use
    8.71 + *  stdio streams to implement the callbacks, you can pass fread, fwrite, and
    8.72 + *  fclose anywhere a FLAC__IOCallback_Read, FLAC__IOCallback_Write, or
    8.73 + *  FLAC__IOCallback_Close is required, and a FILE* anywhere a FLAC__IOHandle
    8.74 + *  is required.  \warning You generally CANNOT directly use fseek or ftell
    8.75 + *  for FLAC__IOCallback_Seek or FLAC__IOCallback_Tell since on most systems
    8.76 + *  these use 32-bit offsets and FLAC requires 64-bit offsets to deal with
    8.77 + *  large files.  You will have to find an equivalent function (e.g. ftello),
    8.78 + *  or write a wrapper.  The same is true for feof() since this is usually
    8.79 + *  implemented as a macro, not as a function whose address can be taken.
    8.80 + *
    8.81 + * \{
    8.82 + */
    8.83 +
    8.84 +#ifdef __cplusplus
    8.85 +extern "C" {
    8.86 +#endif
    8.87 +
    8.88 +/** This is the opaque handle type used by the callbacks.  Typically
    8.89 + *  this is a \c FILE* or address of a file descriptor.
    8.90 + */
    8.91 +typedef void* FLAC__IOHandle;
    8.92 +
    8.93 +/** Signature for the read callback.
    8.94 + *  The signature and semantics match POSIX fread() implementations
    8.95 + *  and can generally be used interchangeably.
    8.96 + *
    8.97 + * \param  ptr      The address of the read buffer.
    8.98 + * \param  size     The size of the records to be read.
    8.99 + * \param  nmemb    The number of records to be read.
   8.100 + * \param  handle   The handle to the data source.
   8.101 + * \retval size_t
   8.102 + *    The number of records read.
   8.103 + */
   8.104 +typedef size_t (*FLAC__IOCallback_Read) (void *ptr, size_t size, size_t nmemb, FLAC__IOHandle handle);
   8.105 +
   8.106 +/** Signature for the write callback.
   8.107 + *  The signature and semantics match POSIX fwrite() implementations
   8.108 + *  and can generally be used interchangeably.
   8.109 + *
   8.110 + * \param  ptr      The address of the write buffer.
   8.111 + * \param  size     The size of the records to be written.
   8.112 + * \param  nmemb    The number of records to be written.
   8.113 + * \param  handle   The handle to the data source.
   8.114 + * \retval size_t
   8.115 + *    The number of records written.
   8.116 + */
   8.117 +typedef size_t (*FLAC__IOCallback_Write) (const void *ptr, size_t size, size_t nmemb, FLAC__IOHandle handle);
   8.118 +
   8.119 +/** Signature for the seek callback.
   8.120 + *  The signature and semantics mostly match POSIX fseek() WITH ONE IMPORTANT
   8.121 + *  EXCEPTION: the offset is a 64-bit type whereas fseek() is generally 'long'
   8.122 + *  and 32-bits wide.
   8.123 + *
   8.124 + * \param  handle   The handle to the data source.
   8.125 + * \param  offset   The new position, relative to \a whence
   8.126 + * \param  whence   \c SEEK_SET, \c SEEK_CUR, or \c SEEK_END
   8.127 + * \retval int
   8.128 + *    \c 0 on success, \c -1 on error.
   8.129 + */
   8.130 +typedef int (*FLAC__IOCallback_Seek) (FLAC__IOHandle handle, FLAC__int64 offset, int whence);
   8.131 +
   8.132 +/** Signature for the tell callback.
   8.133 + *  The signature and semantics mostly match POSIX ftell() WITH ONE IMPORTANT
   8.134 + *  EXCEPTION: the offset is a 64-bit type whereas ftell() is generally 'long'
   8.135 + *  and 32-bits wide.
   8.136 + *
   8.137 + * \param  handle   The handle to the data source.
   8.138 + * \retval FLAC__int64
   8.139 + *    The current position on success, \c -1 on error.
   8.140 + */
   8.141 +typedef FLAC__int64 (*FLAC__IOCallback_Tell) (FLAC__IOHandle handle);
   8.142 +
   8.143 +/** Signature for the EOF callback.
   8.144 + *  The signature and semantics mostly match POSIX feof() but WATCHOUT:
   8.145 + *  on many systems, feof() is a macro, so in this case a wrapper function
   8.146 + *  must be provided instead.
   8.147 + *
   8.148 + * \param  handle   The handle to the data source.
   8.149 + * \retval int
   8.150 + *    \c 0 if not at end of file, nonzero if at end of file.
   8.151 + */
   8.152 +typedef int (*FLAC__IOCallback_Eof) (FLAC__IOHandle handle);
   8.153 +
   8.154 +/** Signature for the close callback.
   8.155 + *  The signature and semantics match POSIX fclose() implementations
   8.156 + *  and can generally be used interchangeably.
   8.157 + *
   8.158 + * \param  handle   The handle to the data source.
   8.159 + * \retval int
   8.160 + *    \c 0 on success, \c EOF on error.
   8.161 + */
   8.162 +typedef int (*FLAC__IOCallback_Close) (FLAC__IOHandle handle);
   8.163 +
   8.164 +/** A structure for holding a set of callbacks.
   8.165 + *  Each FLAC interface that requires a FLAC__IOCallbacks structure will
   8.166 + *  describe which of the callbacks are required.  The ones that are not
   8.167 + *  required may be set to NULL.
   8.168 + *
   8.169 + *  If the seek requirement for an interface is optional, you can signify that
   8.170 + *  a data sorce is not seekable by setting the \a seek field to \c NULL.
   8.171 + */
   8.172 +typedef struct {
   8.173 +	FLAC__IOCallback_Read read;
   8.174 +	FLAC__IOCallback_Write write;
   8.175 +	FLAC__IOCallback_Seek seek;
   8.176 +	FLAC__IOCallback_Tell tell;
   8.177 +	FLAC__IOCallback_Eof eof;
   8.178 +	FLAC__IOCallback_Close close;
   8.179 +} FLAC__IOCallbacks;
   8.180 +
   8.181 +/* \} */
   8.182 +
   8.183 +#ifdef __cplusplus
   8.184 +}
   8.185 +#endif
   8.186 +
   8.187 +#endif
     9.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     9.2 +++ b/Xcode/Frameworks/FLAC.framework/Versions/A/Headers/FLAC/export.h	Mon Jan 09 01:58:40 2012 -0500
     9.3 @@ -0,0 +1,91 @@
     9.4 +/* libFLAC - Free Lossless Audio Codec library
     9.5 + * Copyright (C) 2000,2001,2002,2003,2004,2005,2006,2007  Josh Coalson
     9.6 + *
     9.7 + * Redistribution and use in source and binary forms, with or without
     9.8 + * modification, are permitted provided that the following conditions
     9.9 + * are met:
    9.10 + *
    9.11 + * - Redistributions of source code must retain the above copyright
    9.12 + * notice, this list of conditions and the following disclaimer.
    9.13 + *
    9.14 + * - Redistributions in binary form must reproduce the above copyright
    9.15 + * notice, this list of conditions and the following disclaimer in the
    9.16 + * documentation and/or other materials provided with the distribution.
    9.17 + *
    9.18 + * - Neither the name of the Xiph.org Foundation nor the names of its
    9.19 + * contributors may be used to endorse or promote products derived from
    9.20 + * this software without specific prior written permission.
    9.21 + *
    9.22 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    9.23 + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    9.24 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    9.25 + * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
    9.26 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    9.27 + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    9.28 + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    9.29 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    9.30 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    9.31 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    9.32 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    9.33 + */
    9.34 +
    9.35 +#ifndef FLAC__EXPORT_H
    9.36 +#define FLAC__EXPORT_H
    9.37 +
    9.38 +/** \file include/FLAC/export.h
    9.39 + *
    9.40 + *  \brief
    9.41 + *  This module contains #defines and symbols for exporting function
    9.42 + *  calls, and providing version information and compiled-in features.
    9.43 + *
    9.44 + *  See the \link flac_export export \endlink module.
    9.45 + */
    9.46 +
    9.47 +/** \defgroup flac_export FLAC/export.h: export symbols
    9.48 + *  \ingroup flac
    9.49 + *
    9.50 + *  \brief
    9.51 + *  This module contains #defines and symbols for exporting function
    9.52 + *  calls, and providing version information and compiled-in features.
    9.53 + *
    9.54 + *  If you are compiling with MSVC and will link to the static library
    9.55 + *  (libFLAC.lib) you should define FLAC__NO_DLL in your project to
    9.56 + *  make sure the symbols are exported properly.
    9.57 + *
    9.58 + * \{
    9.59 + */
    9.60 +
    9.61 +#if defined(FLAC__NO_DLL) || !defined(_MSC_VER)
    9.62 +#define FLAC_API
    9.63 +
    9.64 +#else
    9.65 +
    9.66 +#ifdef FLAC_API_EXPORTS
    9.67 +#define	FLAC_API	_declspec(dllexport)
    9.68 +#else
    9.69 +#define FLAC_API	_declspec(dllimport)
    9.70 +
    9.71 +#endif
    9.72 +#endif
    9.73 +
    9.74 +/** These #defines will mirror the libtool-based library version number, see
    9.75 + * http://www.gnu.org/software/libtool/manual.html#Libtool-versioning
    9.76 + */
    9.77 +#define FLAC_API_VERSION_CURRENT 10
    9.78 +#define FLAC_API_VERSION_REVISION 0 /**< see above */
    9.79 +#define FLAC_API_VERSION_AGE 2 /**< see above */
    9.80 +
    9.81 +#ifdef __cplusplus
    9.82 +extern "C" {
    9.83 +#endif
    9.84 +
    9.85 +/** \c 1 if the library has been compiled with support for Ogg FLAC, else \c 0. */
    9.86 +extern FLAC_API int FLAC_API_SUPPORTS_OGG_FLAC;
    9.87 +
    9.88 +#ifdef __cplusplus
    9.89 +}
    9.90 +#endif
    9.91 +
    9.92 +/* \} */
    9.93 +
    9.94 +#endif
    10.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    10.2 +++ b/Xcode/Frameworks/FLAC.framework/Versions/A/Headers/FLAC/format.h	Mon Jan 09 01:58:40 2012 -0500
    10.3 @@ -0,0 +1,1010 @@
    10.4 +/* libFLAC - Free Lossless Audio Codec library
    10.5 + * Copyright (C) 2000,2001,2002,2003,2004,2005,2006,2007  Josh Coalson
    10.6 + *
    10.7 + * Redistribution and use in source and binary forms, with or without
    10.8 + * modification, are permitted provided that the following conditions
    10.9 + * are met:
   10.10 + *
   10.11 + * - Redistributions of source code must retain the above copyright
   10.12 + * notice, this list of conditions and the following disclaimer.
   10.13 + *
   10.14 + * - Redistributions in binary form must reproduce the above copyright
   10.15 + * notice, this list of conditions and the following disclaimer in the
   10.16 + * documentation and/or other materials provided with the distribution.
   10.17 + *
   10.18 + * - Neither the name of the Xiph.org Foundation nor the names of its
   10.19 + * contributors may be used to endorse or promote products derived from
   10.20 + * this software without specific prior written permission.
   10.21 + *
   10.22 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   10.23 + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   10.24 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
   10.25 + * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
   10.26 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
   10.27 + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
   10.28 + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
   10.29 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
   10.30 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
   10.31 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
   10.32 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   10.33 + */
   10.34 +
   10.35 +#ifndef FLAC__FORMAT_H
   10.36 +#define FLAC__FORMAT_H
   10.37 +
   10.38 +#include "export.h"
   10.39 +#include "ordinals.h"
   10.40 +
   10.41 +#ifdef __cplusplus
   10.42 +extern "C" {
   10.43 +#endif
   10.44 +
   10.45 +/** \file include/FLAC/format.h
   10.46 + *
   10.47 + *  \brief
   10.48 + *  This module contains structure definitions for the representation
   10.49 + *  of FLAC format components in memory.  These are the basic
   10.50 + *  structures used by the rest of the interfaces.
   10.51 + *
   10.52 + *  See the detailed documentation in the
   10.53 + *  \link flac_format format \endlink module.
   10.54 + */
   10.55 +
   10.56 +/** \defgroup flac_format FLAC/format.h: format components
   10.57 + *  \ingroup flac
   10.58 + *
   10.59 + *  \brief
   10.60 + *  This module contains structure definitions for the representation
   10.61 + *  of FLAC format components in memory.  These are the basic
   10.62 + *  structures used by the rest of the interfaces.
   10.63 + *
   10.64 + *  First, you should be familiar with the
   10.65 + *  <A HREF="../format.html">FLAC format</A>.  Many of the values here
   10.66 + *  follow directly from the specification.  As a user of libFLAC, the
   10.67 + *  interesting parts really are the structures that describe the frame
   10.68 + *  header and metadata blocks.
   10.69 + *
   10.70 + *  The format structures here are very primitive, designed to store
   10.71 + *  information in an efficient way.  Reading information from the
   10.72 + *  structures is easy but creating or modifying them directly is
   10.73 + *  more complex.  For the most part, as a user of a library, editing
   10.74 + *  is not necessary; however, for metadata blocks it is, so there are
   10.75 + *  convenience functions provided in the \link flac_metadata metadata
   10.76 + *  module \endlink to simplify the manipulation of metadata blocks.
   10.77 + *
   10.78 + * \note
   10.79 + * It's not the best convention, but symbols ending in _LEN are in bits
   10.80 + * and _LENGTH are in bytes.  _LENGTH symbols are \#defines instead of
   10.81 + * global variables because they are usually used when declaring byte
   10.82 + * arrays and some compilers require compile-time knowledge of array
   10.83 + * sizes when declared on the stack.
   10.84 + *
   10.85 + * \{
   10.86 + */
   10.87 +
   10.88 +
   10.89 +/*
   10.90 +	Most of the values described in this file are defined by the FLAC
   10.91 +	format specification.  There is nothing to tune here.
   10.92 +*/
   10.93 +
   10.94 +/** The largest legal metadata type code. */
   10.95 +#define FLAC__MAX_METADATA_TYPE_CODE (126u)
   10.96 +
   10.97 +/** The minimum block size, in samples, permitted by the format. */
   10.98 +#define FLAC__MIN_BLOCK_SIZE (16u)
   10.99 +
  10.100 +/** The maximum block size, in samples, permitted by the format. */
  10.101 +#define FLAC__MAX_BLOCK_SIZE (65535u)
  10.102 +
  10.103 +/** The maximum block size, in samples, permitted by the FLAC subset for
  10.104 + *  sample rates up to 48kHz. */
  10.105 +#define FLAC__SUBSET_MAX_BLOCK_SIZE_48000HZ (4608u)
  10.106 +
  10.107 +/** The maximum number of channels permitted by the format. */
  10.108 +#define FLAC__MAX_CHANNELS (8u)
  10.109 +
  10.110 +/** The minimum sample resolution permitted by the format. */
  10.111 +#define FLAC__MIN_BITS_PER_SAMPLE (4u)
  10.112 +
  10.113 +/** The maximum sample resolution permitted by the format. */
  10.114 +#define FLAC__MAX_BITS_PER_SAMPLE (32u)
  10.115 +
  10.116 +/** The maximum sample resolution permitted by libFLAC.
  10.117 + *
  10.118 + * \warning
  10.119 + * FLAC__MAX_BITS_PER_SAMPLE is the limit of the FLAC format.  However,
  10.120 + * the reference encoder/decoder is currently limited to 24 bits because
  10.121 + * of prevalent 32-bit math, so make sure and use this value when
  10.122 + * appropriate.
  10.123 + */
  10.124 +#define FLAC__REFERENCE_CODEC_MAX_BITS_PER_SAMPLE (24u)
  10.125 +
  10.126 +/** The maximum sample rate permitted by the format.  The value is
  10.127 + *  ((2 ^ 16) - 1) * 10; see <A HREF="../format.html">FLAC format</A>
  10.128 + *  as to why.
  10.129 + */
  10.130 +#define FLAC__MAX_SAMPLE_RATE (655350u)
  10.131 +
  10.132 +/** The maximum LPC order permitted by the format. */
  10.133 +#define FLAC__MAX_LPC_ORDER (32u)
  10.134 +
  10.135 +/** The maximum LPC order permitted by the FLAC subset for sample rates
  10.136 + *  up to 48kHz. */
  10.137 +#define FLAC__SUBSET_MAX_LPC_ORDER_48000HZ (12u)
  10.138 +
  10.139 +/** The minimum quantized linear predictor coefficient precision
  10.140 + *  permitted by the format.
  10.141 + */
  10.142 +#define FLAC__MIN_QLP_COEFF_PRECISION (5u)
  10.143 +
  10.144 +/** The maximum quantized linear predictor coefficient precision
  10.145 + *  permitted by the format.
  10.146 + */
  10.147 +#define FLAC__MAX_QLP_COEFF_PRECISION (15u)
  10.148 +
  10.149 +/** The maximum order of the fixed predictors permitted by the format. */
  10.150 +#define FLAC__MAX_FIXED_ORDER (4u)
  10.151 +
  10.152 +/** The maximum Rice partition order permitted by the format. */
  10.153 +#define FLAC__MAX_RICE_PARTITION_ORDER (15u)
  10.154 +
  10.155 +/** The maximum Rice partition order permitted by the FLAC Subset. */
  10.156 +#define FLAC__SUBSET_MAX_RICE_PARTITION_ORDER (8u)
  10.157 +
  10.158 +/** The version string of the release, stamped onto the libraries and binaries.
  10.159 + *
  10.160 + * \note
  10.161 + * This does not correspond to the shared library version number, which
  10.162 + * is used to determine binary compatibility.
  10.163 + */
  10.164 +extern FLAC_API const char *FLAC__VERSION_STRING;
  10.165 +
  10.166 +/** The vendor string inserted by the encoder into the VORBIS_COMMENT block.
  10.167 + *  This is a NUL-terminated ASCII string; when inserted into the
  10.168 + *  VORBIS_COMMENT the trailing null is stripped.
  10.169 + */
  10.170 +extern FLAC_API const char *FLAC__VENDOR_STRING;
  10.171 +
  10.172 +/** The byte string representation of the beginning of a FLAC stream. */
  10.173 +extern FLAC_API const FLAC__byte FLAC__STREAM_SYNC_STRING[4]; /* = "fLaC" */
  10.174 +
  10.175 +/** The 32-bit integer big-endian representation of the beginning of
  10.176 + *  a FLAC stream.
  10.177 + */
  10.178 +extern FLAC_API const unsigned FLAC__STREAM_SYNC; /* = 0x664C6143 */
  10.179 +
  10.180 +/** The length of the FLAC signature in bits. */
  10.181 +extern FLAC_API const unsigned FLAC__STREAM_SYNC_LEN; /* = 32 bits */
  10.182 +
  10.183 +/** The length of the FLAC signature in bytes. */
  10.184 +#define FLAC__STREAM_SYNC_LENGTH (4u)
  10.185 +
  10.186 +
  10.187 +/*****************************************************************************
  10.188 + *
  10.189 + * Subframe structures
  10.190 + *
  10.191 + *****************************************************************************/
  10.192 +
  10.193 +/*****************************************************************************/
  10.194 +
  10.195 +/** An enumeration of the available entropy coding methods. */
  10.196 +typedef enum {
  10.197 +	FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE = 0,
  10.198 +	/**< Residual is coded by partitioning into contexts, each with it's own
  10.199 +	 * 4-bit Rice parameter. */
  10.200 +
  10.201 +	FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE2 = 1
  10.202 +	/**< Residual is coded by partitioning into contexts, each with it's own
  10.203 +	 * 5-bit Rice parameter. */
  10.204 +} FLAC__EntropyCodingMethodType;
  10.205 +
  10.206 +/** Maps a FLAC__EntropyCodingMethodType to a C string.
  10.207 + *
  10.208 + *  Using a FLAC__EntropyCodingMethodType as the index to this array will
  10.209 + *  give the string equivalent.  The contents should not be modified.
  10.210 + */
  10.211 +extern FLAC_API const char * const FLAC__EntropyCodingMethodTypeString[];
  10.212 +
  10.213 +
  10.214 +/** Contents of a Rice partitioned residual
  10.215 + */
  10.216 +typedef struct {
  10.217 +
  10.218 +	unsigned *parameters;
  10.219 +	/**< The Rice parameters for each context. */
  10.220 +
  10.221 +	unsigned *raw_bits;
  10.222 +	/**< Widths for escape-coded partitions.  Will be non-zero for escaped
  10.223 +	 * partitions and zero for unescaped partitions.
  10.224 +	 */
  10.225 +
  10.226 +	unsigned capacity_by_order;
  10.227 +	/**< The capacity of the \a parameters and \a raw_bits arrays
  10.228 +	 * specified as an order, i.e. the number of array elements
  10.229 +	 * allocated is 2 ^ \a capacity_by_order.
  10.230 +	 */
  10.231 +} FLAC__EntropyCodingMethod_PartitionedRiceContents;
  10.232 +
  10.233 +/** Header for a Rice partitioned residual.  (c.f. <A HREF="../format.html#partitioned_rice">format specification</A>)
  10.234 + */
  10.235 +typedef struct {
  10.236 +
  10.237 +	unsigned order;
  10.238 +	/**< The partition order, i.e. # of contexts = 2 ^ \a order. */
  10.239 +
  10.240 +	const FLAC__EntropyCodingMethod_PartitionedRiceContents *contents;
  10.241 +	/**< The context's Rice parameters and/or raw bits. */
  10.242 +
  10.243 +} FLAC__EntropyCodingMethod_PartitionedRice;
  10.244 +
  10.245 +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ORDER_LEN; /**< == 4 (bits) */
  10.246 +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN; /**< == 4 (bits) */
  10.247 +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE2_PARAMETER_LEN; /**< == 5 (bits) */
  10.248 +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_RAW_LEN; /**< == 5 (bits) */
  10.249 +
  10.250 +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ESCAPE_PARAMETER;
  10.251 +/**< == (1<<FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN)-1 */
  10.252 +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE2_ESCAPE_PARAMETER;
  10.253 +/**< == (1<<FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE2_PARAMETER_LEN)-1 */
  10.254 +
  10.255 +/** Header for the entropy coding method.  (c.f. <A HREF="../format.html#residual">format specification</A>)
  10.256 + */
  10.257 +typedef struct {
  10.258 +	FLAC__EntropyCodingMethodType type;
  10.259 +	union {
  10.260 +		FLAC__EntropyCodingMethod_PartitionedRice partitioned_rice;
  10.261 +	} data;
  10.262 +} FLAC__EntropyCodingMethod;
  10.263 +
  10.264 +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_TYPE_LEN; /**< == 2 (bits) */
  10.265 +
  10.266 +/*****************************************************************************/
  10.267 +
  10.268 +/** An enumeration of the available subframe types. */
  10.269 +typedef enum {
  10.270 +	FLAC__SUBFRAME_TYPE_CONSTANT = 0, /**< constant signal */
  10.271 +	FLAC__SUBFRAME_TYPE_VERBATIM = 1, /**< uncompressed signal */
  10.272 +	FLAC__SUBFRAME_TYPE_FIXED = 2, /**< fixed polynomial prediction */
  10.273 +	FLAC__SUBFRAME_TYPE_LPC = 3 /**< linear prediction */
  10.274 +} FLAC__SubframeType;
  10.275 +
  10.276 +/** Maps a FLAC__SubframeType to a C string.
  10.277 + *
  10.278 + *  Using a FLAC__SubframeType as the index to this array will
  10.279 + *  give the string equivalent.  The contents should not be modified.
  10.280 + */
  10.281 +extern FLAC_API const char * const FLAC__SubframeTypeString[];
  10.282 +
  10.283 +
  10.284 +/** CONSTANT subframe.  (c.f. <A HREF="../format.html#subframe_constant">format specification</A>)
  10.285 + */
  10.286 +typedef struct {
  10.287 +	FLAC__int32 value; /**< The constant signal value. */
  10.288 +} FLAC__Subframe_Constant;
  10.289 +
  10.290 +
  10.291 +/** VERBATIM subframe.  (c.f. <A HREF="../format.html#subframe_verbatim">format specification</A>)
  10.292 + */
  10.293 +typedef struct {
  10.294 +	const FLAC__int32 *data; /**< A pointer to verbatim signal. */
  10.295 +} FLAC__Subframe_Verbatim;
  10.296 +
  10.297 +
  10.298 +/** FIXED subframe.  (c.f. <A HREF="../format.html#subframe_fixed">format specification</A>)
  10.299 + */
  10.300 +typedef struct {
  10.301 +	FLAC__EntropyCodingMethod entropy_coding_method;
  10.302 +	/**< The residual coding method. */
  10.303 +
  10.304 +	unsigned order;
  10.305 +	/**< The polynomial order. */
  10.306 +
  10.307 +	FLAC__int32 warmup[FLAC__MAX_FIXED_ORDER];
  10.308 +	/**< Warmup samples to prime the predictor, length == order. */
  10.309 +
  10.310 +	const FLAC__int32 *residual;
  10.311 +	/**< The residual signal, length == (blocksize minus order) samples. */
  10.312 +} FLAC__Subframe_Fixed;
  10.313 +
  10.314 +
  10.315 +/** LPC subframe.  (c.f. <A HREF="../format.html#subframe_lpc">format specification</A>)
  10.316 + */
  10.317 +typedef struct {
  10.318 +	FLAC__EntropyCodingMethod entropy_coding_method;
  10.319 +	/**< The residual coding method. */
  10.320 +
  10.321 +	unsigned order;
  10.322 +	/**< The FIR order. */
  10.323 +
  10.324 +	unsigned qlp_coeff_precision;
  10.325 +	/**< Quantized FIR filter coefficient precision in bits. */
  10.326 +
  10.327 +	int quantization_level;
  10.328 +	/**< The qlp coeff shift needed. */
  10.329 +
  10.330 +	FLAC__int32 qlp_coeff[FLAC__MAX_LPC_ORDER];
  10.331 +	/**< FIR filter coefficients. */
  10.332 +
  10.333 +	FLAC__int32 warmup[FLAC__MAX_LPC_ORDER];
  10.334 +	/**< Warmup samples to prime the predictor, length == order. */
  10.335 +
  10.336 +	const FLAC__int32 *residual;
  10.337 +	/**< The residual signal, length == (blocksize minus order) samples. */
  10.338 +} FLAC__Subframe_LPC;
  10.339 +
  10.340 +extern FLAC_API const unsigned FLAC__SUBFRAME_LPC_QLP_COEFF_PRECISION_LEN; /**< == 4 (bits) */
  10.341 +extern FLAC_API const unsigned FLAC__SUBFRAME_LPC_QLP_SHIFT_LEN; /**< == 5 (bits) */
  10.342 +
  10.343 +
  10.344 +/** FLAC subframe structure.  (c.f. <A HREF="../format.html#subframe">format specification</A>)
  10.345 + */
  10.346 +typedef struct {
  10.347 +	FLAC__SubframeType type;
  10.348 +	union {
  10.349 +		FLAC__Subframe_Constant constant;
  10.350 +		FLAC__Subframe_Fixed fixed;
  10.351 +		FLAC__Subframe_LPC lpc;
  10.352 +		FLAC__Subframe_Verbatim verbatim;
  10.353 +	} data;
  10.354 +	unsigned wasted_bits;
  10.355 +} FLAC__Subframe;
  10.356 +
  10.357 +/** == 1 (bit)
  10.358 + *
  10.359 + * This used to be a zero-padding bit (hence the name
  10.360 + * FLAC__SUBFRAME_ZERO_PAD_LEN) but is now a reserved bit.  It still has a
  10.361 + * mandatory value of \c 0 but in the future may take on the value \c 0 or \c 1
  10.362 + * to mean something else.
  10.363 + */
  10.364 +extern FLAC_API const unsigned FLAC__SUBFRAME_ZERO_PAD_LEN;
  10.365 +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LEN; /**< == 6 (bits) */
  10.366 +extern FLAC_API const unsigned FLAC__SUBFRAME_WASTED_BITS_FLAG_LEN; /**< == 1 (bit) */
  10.367 +
  10.368 +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_CONSTANT_BYTE_ALIGNED_MASK; /**< = 0x00 */
  10.369 +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_VERBATIM_BYTE_ALIGNED_MASK; /**< = 0x02 */
  10.370 +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_FIXED_BYTE_ALIGNED_MASK; /**< = 0x10 */
  10.371 +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LPC_BYTE_ALIGNED_MASK; /**< = 0x40 */
  10.372 +
  10.373 +/*****************************************************************************/
  10.374 +
  10.375 +
  10.376 +/*****************************************************************************
  10.377 + *
  10.378 + * Frame structures
  10.379 + *
  10.380 + *****************************************************************************/
  10.381 +
  10.382 +/** An enumeration of the available channel assignments. */
  10.383 +typedef enum {
  10.384 +	FLAC__CHANNEL_ASSIGNMENT_INDEPENDENT = 0, /**< independent channels */
  10.385 +	FLAC__CHANNEL_ASSIGNMENT_LEFT_SIDE = 1, /**< left+side stereo */
  10.386 +	FLAC__CHANNEL_ASSIGNMENT_RIGHT_SIDE = 2, /**< right+side stereo */
  10.387 +	FLAC__CHANNEL_ASSIGNMENT_MID_SIDE = 3 /**< mid+side stereo */
  10.388 +} FLAC__ChannelAssignment;
  10.389 +
  10.390 +/** Maps a FLAC__ChannelAssignment to a C string.
  10.391 + *
  10.392 + *  Using a FLAC__ChannelAssignment as the index to this array will
  10.393 + *  give the string equivalent.  The contents should not be modified.
  10.394 + */
  10.395 +extern FLAC_API const char * const FLAC__ChannelAssignmentString[];
  10.396 +
  10.397 +/** An enumeration of the possible frame numbering methods. */
  10.398 +typedef enum {
  10.399 +	FLAC__FRAME_NUMBER_TYPE_FRAME_NUMBER, /**< number contains the frame number */
  10.400 +	FLAC__FRAME_NUMBER_TYPE_SAMPLE_NUMBER /**< number contains the sample number of first sample in frame */
  10.401 +} FLAC__FrameNumberType;
  10.402 +
  10.403 +/** Maps a FLAC__FrameNumberType to a C string.
  10.404 + *
  10.405 + *  Using a FLAC__FrameNumberType as the index to this array will
  10.406 + *  give the string equivalent.  The contents should not be modified.
  10.407 + */
  10.408 +extern FLAC_API const char * const FLAC__FrameNumberTypeString[];
  10.409 +
  10.410 +
  10.411 +/** FLAC frame header structure.  (c.f. <A HREF="../format.html#frame_header">format specification</A>)
  10.412 + */
  10.413 +typedef struct {
  10.414 +	unsigned blocksize;
  10.415 +	/**< The number of samples per subframe. */
  10.416 +
  10.417 +	unsigned sample_rate;
  10.418 +	/**< The sample rate in Hz. */
  10.419 +
  10.420 +	unsigned channels;
  10.421 +	/**< The number of channels (== number of subframes). */
  10.422 +
  10.423 +	FLAC__ChannelAssignment channel_assignment;
  10.424 +	/**< The channel assignment for the frame. */
  10.425 +
  10.426 +	unsigned bits_per_sample;
  10.427 +	/**< The sample resolution. */
  10.428 +
  10.429 +	FLAC__FrameNumberType number_type;
  10.430 +	/**< The numbering scheme used for the frame.  As a convenience, the
  10.431 +	 * decoder will always convert a frame number to a sample number because
  10.432 +	 * the rules are complex. */
  10.433 +
  10.434 +	union {
  10.435 +		FLAC__uint32 frame_number;
  10.436 +		FLAC__uint64 sample_number;
  10.437 +	} number;
  10.438 +	/**< The frame number or sample number of first sample in frame;
  10.439 +	 * use the \a number_type value to determine which to use. */
  10.440 +
  10.441 +	FLAC__uint8 crc;
  10.442 +	/**< CRC-8 (polynomial = x^8 + x^2 + x^1 + x^0, initialized with 0)
  10.443 +	 * of the raw frame header bytes, meaning everything before the CRC byte
  10.444 +	 * including the sync code.
  10.445 +	 */
  10.446 +} FLAC__FrameHeader;
  10.447 +
  10.448 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_SYNC; /**< == 0x3ffe; the frame header sync code */
  10.449 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_SYNC_LEN; /**< == 14 (bits) */
  10.450 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_RESERVED_LEN; /**< == 1 (bits) */
  10.451 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_BLOCKING_STRATEGY_LEN; /**< == 1 (bits) */
  10.452 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_BLOCK_SIZE_LEN; /**< == 4 (bits) */
  10.453 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_SAMPLE_RATE_LEN; /**< == 4 (bits) */
  10.454 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_CHANNEL_ASSIGNMENT_LEN; /**< == 4 (bits) */
  10.455 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_BITS_PER_SAMPLE_LEN; /**< == 3 (bits) */
  10.456 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_ZERO_PAD_LEN; /**< == 1 (bit) */
  10.457 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_CRC_LEN; /**< == 8 (bits) */
  10.458 +
  10.459 +
  10.460 +/** FLAC frame footer structure.  (c.f. <A HREF="../format.html#frame_footer">format specification</A>)
  10.461 + */
  10.462 +typedef struct {
  10.463 +	FLAC__uint16 crc;
  10.464 +	/**< CRC-16 (polynomial = x^16 + x^15 + x^2 + x^0, initialized with
  10.465 +	 * 0) of the bytes before the crc, back to and including the frame header
  10.466 +	 * sync code.
  10.467 +	 */
  10.468 +} FLAC__FrameFooter;
  10.469 +
  10.470 +extern FLAC_API const unsigned FLAC__FRAME_FOOTER_CRC_LEN; /**< == 16 (bits) */
  10.471 +
  10.472 +
  10.473 +/** FLAC frame structure.  (c.f. <A HREF="../format.html#frame">format specification</A>)
  10.474 + */
  10.475 +typedef struct {
  10.476 +	FLAC__FrameHeader header;
  10.477 +	FLAC__Subframe subframes[FLAC__MAX_CHANNELS];
  10.478 +	FLAC__FrameFooter footer;
  10.479 +} FLAC__Frame;
  10.480 +
  10.481 +/*****************************************************************************/
  10.482 +
  10.483 +
  10.484 +/*****************************************************************************
  10.485 + *
  10.486 + * Meta-data structures
  10.487 + *
  10.488 + *****************************************************************************/
  10.489 +
  10.490 +/** An enumeration of the available metadata block types. */
  10.491 +typedef enum {
  10.492 +
  10.493 +	FLAC__METADATA_TYPE_STREAMINFO = 0,
  10.494 +	/**< <A HREF="../format.html#metadata_block_streaminfo">STREAMINFO</A> block */
  10.495 +
  10.496 +	FLAC__METADATA_TYPE_PADDING = 1,
  10.497 +	/**< <A HREF="../format.html#metadata_block_padding">PADDING</A> block */
  10.498 +
  10.499 +	FLAC__METADATA_TYPE_APPLICATION = 2,
  10.500 +	/**< <A HREF="../format.html#metadata_block_application">APPLICATION</A> block */
  10.501 +
  10.502 +	FLAC__METADATA_TYPE_SEEKTABLE = 3,
  10.503 +	/**< <A HREF="../format.html#metadata_block_seektable">SEEKTABLE</A> block */
  10.504 +
  10.505 +	FLAC__METADATA_TYPE_VORBIS_COMMENT = 4,
  10.506 +	/**< <A HREF="../format.html#metadata_block_vorbis_comment">VORBISCOMMENT</A> block (a.k.a. FLAC tags) */
  10.507 +
  10.508 +	FLAC__METADATA_TYPE_CUESHEET = 5,
  10.509 +	/**< <A HREF="../format.html#metadata_block_cuesheet">CUESHEET</A> block */
  10.510 +
  10.511 +	FLAC__METADATA_TYPE_PICTURE = 6,
  10.512 +	/**< <A HREF="../format.html#metadata_block_picture">PICTURE</A> block */
  10.513 +
  10.514 +	FLAC__METADATA_TYPE_UNDEFINED = 7
  10.515 +	/**< marker to denote beginning of undefined type range; this number will increase as new metadata types are added */
  10.516 +
  10.517 +} FLAC__MetadataType;
  10.518 +
  10.519 +/** Maps a FLAC__MetadataType to a C string.
  10.520 + *
  10.521 + *  Using a FLAC__MetadataType as the index to this array will
  10.522 + *  give the string equivalent.  The contents should not be modified.
  10.523 + */
  10.524 +extern FLAC_API const char * const FLAC__MetadataTypeString[];
  10.525 +
  10.526 +
  10.527 +/** FLAC STREAMINFO structure.  (c.f. <A HREF="../format.html#metadata_block_streaminfo">format specification</A>)
  10.528 + */
  10.529 +typedef struct {
  10.530 +	unsigned min_blocksize, max_blocksize;
  10.531 +	unsigned min_framesize, max_framesize;
  10.532 +	unsigned sample_rate;
  10.533 +	unsigned channels;
  10.534 +	unsigned bits_per_sample;
  10.535 +	FLAC__uint64 total_samples;
  10.536 +	FLAC__byte md5sum[16];
  10.537 +} FLAC__StreamMetadata_StreamInfo;
  10.538 +
  10.539 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_BLOCK_SIZE_LEN; /**< == 16 (bits) */
  10.540 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_BLOCK_SIZE_LEN; /**< == 16 (bits) */
  10.541 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_FRAME_SIZE_LEN; /**< == 24 (bits) */
  10.542 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_FRAME_SIZE_LEN; /**< == 24 (bits) */
  10.543 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_SAMPLE_RATE_LEN; /**< == 20 (bits) */
  10.544 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_CHANNELS_LEN; /**< == 3 (bits) */
  10.545 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_BITS_PER_SAMPLE_LEN; /**< == 5 (bits) */
  10.546 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_TOTAL_SAMPLES_LEN; /**< == 36 (bits) */
  10.547 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MD5SUM_LEN; /**< == 128 (bits) */
  10.548 +
  10.549 +/** The total stream length of the STREAMINFO block in bytes. */
  10.550 +#define FLAC__STREAM_METADATA_STREAMINFO_LENGTH (34u)
  10.551 +
  10.552 +/** FLAC PADDING structure.  (c.f. <A HREF="../format.html#metadata_block_padding">format specification</A>)
  10.553 + */
  10.554 +typedef struct {
  10.555 +	int dummy;
  10.556 +	/**< Conceptually this is an empty struct since we don't store the
  10.557 +	 * padding bytes.  Empty structs are not allowed by some C compilers,
  10.558 +	 * hence the dummy.
  10.559 +	 */
  10.560 +} FLAC__StreamMetadata_Padding;
  10.561 +
  10.562 +
  10.563 +/** FLAC APPLICATION structure.  (c.f. <A HREF="../format.html#metadata_block_application">format specification</A>)
  10.564 + */
  10.565 +typedef struct {
  10.566 +	FLAC__byte id[4];
  10.567 +	FLAC__byte *data;
  10.568 +} FLAC__StreamMetadata_Application;
  10.569 +
  10.570 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_APPLICATION_ID_LEN; /**< == 32 (bits) */
  10.571 +
  10.572 +/** SeekPoint structure used in SEEKTABLE blocks.  (c.f. <A HREF="../format.html#seekpoint">format specification</A>)
  10.573 + */
  10.574 +typedef struct {
  10.575 +	FLAC__uint64 sample_number;
  10.576 +	/**<  The sample number of the target frame. */
  10.577 +
  10.578 +	FLAC__uint64 stream_offset;
  10.579 +	/**< The offset, in bytes, of the target frame with respect to
  10.580 +	 * beginning of the first frame. */
  10.581 +
  10.582 +	unsigned frame_samples;
  10.583 +	/**< The number of samples in the target frame. */
  10.584 +} FLAC__StreamMetadata_SeekPoint;
  10.585 +
  10.586 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_SAMPLE_NUMBER_LEN; /**< == 64 (bits) */
  10.587 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_STREAM_OFFSET_LEN; /**< == 64 (bits) */
  10.588 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_FRAME_SAMPLES_LEN; /**< == 16 (bits) */
  10.589 +
  10.590 +/** The total stream length of a seek point in bytes. */
  10.591 +#define FLAC__STREAM_METADATA_SEEKPOINT_LENGTH (18u)
  10.592 +
  10.593 +/** The value used in the \a sample_number field of
  10.594 + *  FLAC__StreamMetadataSeekPoint used to indicate a placeholder
  10.595 + *  point (== 0xffffffffffffffff).
  10.596 + */
  10.597 +extern FLAC_API const FLAC__uint64 FLAC__STREAM_METADATA_SEEKPOINT_PLACEHOLDER;
  10.598 +
  10.599 +
  10.600 +/** FLAC SEEKTABLE structure.  (c.f. <A HREF="../format.html#metadata_block_seektable">format specification</A>)
  10.601 + *
  10.602 + * \note From the format specification:
  10.603 + * - The seek points must be sorted by ascending sample number.
  10.604 + * - Each seek point's sample number must be the first sample of the
  10.605 + *   target frame.
  10.606 + * - Each seek point's sample number must be unique within the table.
  10.607 + * - Existence of a SEEKTABLE block implies a correct setting of
  10.608 + *   total_samples in the stream_info block.
  10.609 + * - Behavior is undefined when more than one SEEKTABLE block is
  10.610 + *   present in a stream.
  10.611 + */
  10.612 +typedef struct {
  10.613 +	unsigned num_points;
  10.614 +	FLAC__StreamMetadata_SeekPoint *points;
  10.615 +} FLAC__StreamMetadata_SeekTable;
  10.616 +
  10.617 +
  10.618 +/** Vorbis comment entry structure used in VORBIS_COMMENT blocks.  (c.f. <A HREF="../format.html#metadata_block_vorbis_comment">format specification</A>)
  10.619 + *
  10.620 + *  For convenience, the APIs maintain a trailing NUL character at the end of
  10.621 + *  \a entry which is not counted toward \a length, i.e.
  10.622 + *  \code strlen(entry) == length \endcode
  10.623 + */
  10.624 +typedef struct {
  10.625 +	FLAC__uint32 length;
  10.626 +	FLAC__byte *entry;
  10.627 +} FLAC__StreamMetadata_VorbisComment_Entry;
  10.628 +
  10.629 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_ENTRY_LENGTH_LEN; /**< == 32 (bits) */
  10.630 +
  10.631 +
  10.632 +/** FLAC VORBIS_COMMENT structure.  (c.f. <A HREF="../format.html#metadata_block_vorbis_comment">format specification</A>)
  10.633 + */
  10.634 +typedef struct {
  10.635 +	FLAC__StreamMetadata_VorbisComment_Entry vendor_string;
  10.636 +	FLAC__uint32 num_comments;
  10.637 +	FLAC__StreamMetadata_VorbisComment_Entry *comments;
  10.638 +} FLAC__StreamMetadata_VorbisComment;
  10.639 +
  10.640 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_NUM_COMMENTS_LEN; /**< == 32 (bits) */
  10.641 +
  10.642 +
  10.643 +/** FLAC CUESHEET track index structure.  (See the
  10.644 + * <A HREF="../format.html#cuesheet_track_index">format specification</A> for
  10.645 + * the full description of each field.)
  10.646 + */
  10.647 +typedef struct {
  10.648 +	FLAC__uint64 offset;
  10.649 +	/**< Offset in samples, relative to the track offset, of the index
  10.650 +	 * point.
  10.651 +	 */
  10.652 +
  10.653 +	FLAC__byte number;
  10.654 +	/**< The index point number. */
  10.655 +} FLAC__StreamMetadata_CueSheet_Index;
  10.656 +
  10.657 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_OFFSET_LEN; /**< == 64 (bits) */
  10.658 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_NUMBER_LEN; /**< == 8 (bits) */
  10.659 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_RESERVED_LEN; /**< == 3*8 (bits) */
  10.660 +
  10.661 +
  10.662 +/** FLAC CUESHEET track structure.  (See the
  10.663 + * <A HREF="../format.html#cuesheet_track">format specification</A> for
  10.664 + * the full description of each field.)
  10.665 + */
  10.666 +typedef struct {
  10.667 +	FLAC__uint64 offset;
  10.668 +	/**< Track offset in samples, relative to the beginning of the FLAC audio stream. */
  10.669 +
  10.670 +	FLAC__byte number;
  10.671 +	/**< The track number. */
  10.672 +
  10.673 +	char isrc[13];
  10.674 +	/**< Track ISRC.  This is a 12-digit alphanumeric code plus a trailing \c NUL byte */
  10.675 +
  10.676 +	unsigned type:1;
  10.677 +	/**< The track type: 0 for audio, 1 for non-audio. */
  10.678 +
  10.679 +	unsigned pre_emphasis:1;
  10.680 +	/**< The pre-emphasis flag: 0 for no pre-emphasis, 1 for pre-emphasis. */
  10.681 +
  10.682 +	FLAC__byte num_indices;
  10.683 +	/**< The number of track index points. */
  10.684 +
  10.685 +	FLAC__StreamMetadata_CueSheet_Index *indices;
  10.686 +	/**< NULL if num_indices == 0, else pointer to array of index points. */
  10.687 +
  10.688 +} FLAC__StreamMetadata_CueSheet_Track;
  10.689 +
  10.690 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_OFFSET_LEN; /**< == 64 (bits) */
  10.691 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUMBER_LEN; /**< == 8 (bits) */
  10.692 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_ISRC_LEN; /**< == 12*8 (bits) */
  10.693 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_TYPE_LEN; /**< == 1 (bit) */
  10.694 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_PRE_EMPHASIS_LEN; /**< == 1 (bit) */
  10.695 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_RESERVED_LEN; /**< == 6+13*8 (bits) */
  10.696 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUM_INDICES_LEN; /**< == 8 (bits) */
  10.697 +
  10.698 +
  10.699 +/** FLAC CUESHEET structure.  (See the
  10.700 + * <A HREF="../format.html#metadata_block_cuesheet">format specification</A>
  10.701 + * for the full description of each field.)
  10.702 + */
  10.703 +typedef struct {
  10.704 +	char media_catalog_number[129];
  10.705 +	/**< Media catalog number, in ASCII printable characters 0x20-0x7e.  In
  10.706 +	 * general, the media catalog number may be 0 to 128 bytes long; any
  10.707 +	 * unused characters should be right-padded with NUL characters.
  10.708 +	 */
  10.709 +
  10.710 +	FLAC__uint64 lead_in;
  10.711 +	/**< The number of lead-in samples. */
  10.712 +
  10.713 +	FLAC__bool is_cd;
  10.714 +	/**< \c true if CUESHEET corresponds to a Compact Disc, else \c false. */
  10.715 +
  10.716 +	unsigned num_tracks;
  10.717 +	/**< The number of tracks. */
  10.718 +
  10.719 +	FLAC__StreamMetadata_CueSheet_Track *tracks;
  10.720 +	/**< NULL if num_tracks == 0, else pointer to array of tracks. */
  10.721 +
  10.722 +} FLAC__StreamMetadata_CueSheet;
  10.723 +
  10.724 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_MEDIA_CATALOG_NUMBER_LEN; /**< == 128*8 (bits) */
  10.725 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_LEAD_IN_LEN; /**< == 64 (bits) */
  10.726 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_IS_CD_LEN; /**< == 1 (bit) */
  10.727 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_RESERVED_LEN; /**< == 7+258*8 (bits) */
  10.728 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_NUM_TRACKS_LEN; /**< == 8 (bits) */
  10.729 +
  10.730 +
  10.731 +/** An enumeration of the PICTURE types (see FLAC__StreamMetadataPicture and id3 v2.4 APIC tag). */
  10.732 +typedef enum {
  10.733 +	FLAC__STREAM_METADATA_PICTURE_TYPE_OTHER = 0, /**< Other */
  10.734 +	FLAC__STREAM_METADATA_PICTURE_TYPE_FILE_ICON_STANDARD = 1, /**< 32x32 pixels 'file icon' (PNG only) */
  10.735 +	FLAC__STREAM_METADATA_PICTURE_TYPE_FILE_ICON = 2, /**< Other file icon */
  10.736 +	FLAC__STREAM_METADATA_PICTURE_TYPE_FRONT_COVER = 3, /**< Cover (front) */
  10.737 +	FLAC__STREAM_METADATA_PICTURE_TYPE_BACK_COVER = 4, /**< Cover (back) */
  10.738 +	FLAC__STREAM_METADATA_PICTURE_TYPE_LEAFLET_PAGE = 5, /**< Leaflet page */
  10.739 +	FLAC__STREAM_METADATA_PICTURE_TYPE_MEDIA = 6, /**< Media (e.g. label side of CD) */
  10.740 +	FLAC__STREAM_METADATA_PICTURE_TYPE_LEAD_ARTIST = 7, /**< Lead artist/lead performer/soloist */
  10.741 +	FLAC__STREAM_METADATA_PICTURE_TYPE_ARTIST = 8, /**< Artist/performer */
  10.742 +	FLAC__STREAM_METADATA_PICTURE_TYPE_CONDUCTOR = 9, /**< Conductor */
  10.743 +	FLAC__STREAM_METADATA_PICTURE_TYPE_BAND = 10, /**< Band/Orchestra */
  10.744 +	FLAC__STREAM_METADATA_PICTURE_TYPE_COMPOSER = 11, /**< Composer */
  10.745 +	FLAC__STREAM_METADATA_PICTURE_TYPE_LYRICIST = 12, /**< Lyricist/text writer */
  10.746 +	FLAC__STREAM_METADATA_PICTURE_TYPE_RECORDING_LOCATION = 13, /**< Recording Location */
  10.747 +	FLAC__STREAM_METADATA_PICTURE_TYPE_DURING_RECORDING = 14, /**< During recording */
  10.748 +	FLAC__STREAM_METADATA_PICTURE_TYPE_DURING_PERFORMANCE = 15, /**< During performance */
  10.749 +	FLAC__STREAM_METADATA_PICTURE_TYPE_VIDEO_SCREEN_CAPTURE = 16, /**< Movie/video screen capture */
  10.750 +	FLAC__STREAM_METADATA_PICTURE_TYPE_FISH = 17, /**< A bright coloured fish */
  10.751 +	FLAC__STREAM_METADATA_PICTURE_TYPE_ILLUSTRATION = 18, /**< Illustration */
  10.752 +	FLAC__STREAM_METADATA_PICTURE_TYPE_BAND_LOGOTYPE = 19, /**< Band/artist logotype */
  10.753 +	FLAC__STREAM_METADATA_PICTURE_TYPE_PUBLISHER_LOGOTYPE = 20, /**< Publisher/Studio logotype */
  10.754 +	FLAC__STREAM_METADATA_PICTURE_TYPE_UNDEFINED
  10.755 +} FLAC__StreamMetadata_Picture_Type;
  10.756 +
  10.757 +/** Maps a FLAC__StreamMetadata_Picture_Type to a C string.
  10.758 + *
  10.759 + *  Using a FLAC__StreamMetadata_Picture_Type as the index to this array
  10.760 + *  will give the string equivalent.  The contents should not be
  10.761 + *  modified.
  10.762 + */
  10.763 +extern FLAC_API const char * const FLAC__StreamMetadata_Picture_TypeString[];
  10.764 +
  10.765 +/** FLAC PICTURE structure.  (See the
  10.766 + * <A HREF="../format.html#metadata_block_picture">format specification</A>
  10.767 + * for the full description of each field.)
  10.768 + */
  10.769 +typedef struct {
  10.770 +	FLAC__StreamMetadata_Picture_Type type;
  10.771 +	/**< The kind of picture stored. */
  10.772 +
  10.773 +	char *mime_type;
  10.774 +	/**< Picture data's MIME type, in ASCII printable characters
  10.775 +	 * 0x20-0x7e, NUL terminated.  For best compatibility with players,
  10.776 +	 * use picture data of MIME type \c image/jpeg or \c image/png.  A
  10.777 +	 * MIME type of '-->' is also allowed, in which case the picture
  10.778 +	 * data should be a complete URL.  In file storage, the MIME type is
  10.779 +	 * stored as a 32-bit length followed by the ASCII string with no NUL
  10.780 +	 * terminator, but is converted to a plain C string in this structure
  10.781 +	 * for convenience.
  10.782 +	 */
  10.783 +
  10.784 +	FLAC__byte *description;
  10.785 +	/**< Picture's description in UTF-8, NUL terminated.  In file storage,
  10.786 +	 * the description is stored as a 32-bit length followed by the UTF-8
  10.787 +	 * string with no NUL terminator, but is converted to a plain C string
  10.788 +	 * in this structure for convenience.
  10.789 +	 */
  10.790 +
  10.791 +	FLAC__uint32 width;
  10.792 +	/**< Picture's width in pixels. */
  10.793 +
  10.794 +	FLAC__uint32 height;
  10.795 +	/**< Picture's height in pixels. */
  10.796 +
  10.797 +	FLAC__uint32 depth;
  10.798 +	/**< Picture's color depth in bits-per-pixel. */
  10.799 +
  10.800 +	FLAC__uint32 colors;
  10.801 +	/**< For indexed palettes (like GIF), picture's number of colors (the
  10.802 +	 * number of palette entries), or \c 0 for non-indexed (i.e. 2^depth).
  10.803 +	 */
  10.804 +
  10.805 +	FLAC__uint32 data_length;
  10.806 +	/**< Length of binary picture data in bytes. */
  10.807 +
  10.808 +	FLAC__byte *data;
  10.809 +	/**< Binary picture data. */
  10.810 +
  10.811 +} FLAC__StreamMetadata_Picture;
  10.812 +
  10.813 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_TYPE_LEN; /**< == 32 (bits) */
  10.814 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_MIME_TYPE_LENGTH_LEN; /**< == 32 (bits) */
  10.815 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_DESCRIPTION_LENGTH_LEN; /**< == 32 (bits) */
  10.816 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_WIDTH_LEN; /**< == 32 (bits) */
  10.817 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_HEIGHT_LEN; /**< == 32 (bits) */
  10.818 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_DEPTH_LEN; /**< == 32 (bits) */
  10.819 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_COLORS_LEN; /**< == 32 (bits) */
  10.820 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_DATA_LENGTH_LEN; /**< == 32 (bits) */
  10.821 +
  10.822 +
  10.823 +/** Structure that is used when a metadata block of unknown type is loaded.
  10.824 + *  The contents are opaque.  The structure is used only internally to
  10.825 + *  correctly handle unknown metadata.
  10.826 + */
  10.827 +typedef struct {
  10.828 +	FLAC__byte *data;
  10.829 +} FLAC__StreamMetadata_Unknown;
  10.830 +
  10.831 +
  10.832 +/** FLAC metadata block structure.  (c.f. <A HREF="../format.html#metadata_block">format specification</A>)
  10.833 + */
  10.834 +typedef struct {
  10.835 +	FLAC__MetadataType type;
  10.836 +	/**< The type of the metadata block; used determine which member of the
  10.837 +	 * \a data union to dereference.  If type >= FLAC__METADATA_TYPE_UNDEFINED
  10.838 +	 * then \a data.unknown must be used. */
  10.839 +
  10.840 +	FLAC__bool is_last;
  10.841 +	/**< \c true if this metadata block is the last, else \a false */
  10.842 +
  10.843 +	unsigned length;
  10.844 +	/**< Length, in bytes, of the block data as it appears in the stream. */
  10.845 +
  10.846 +	union {
  10.847 +		FLAC__StreamMetadata_StreamInfo stream_info;
  10.848 +		FLAC__StreamMetadata_Padding padding;
  10.849 +		FLAC__StreamMetadata_Application application;
  10.850 +		FLAC__StreamMetadata_SeekTable seek_table;
  10.851 +		FLAC__StreamMetadata_VorbisComment vorbis_comment;
  10.852 +		FLAC__StreamMetadata_CueSheet cue_sheet;
  10.853 +		FLAC__StreamMetadata_Picture picture;
  10.854 +		FLAC__StreamMetadata_Unknown unknown;
  10.855 +	} data;
  10.856 +	/**< Polymorphic block data; use the \a type value to determine which
  10.857 +	 * to use. */
  10.858 +} FLAC__StreamMetadata;
  10.859 +
  10.860 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_IS_LAST_LEN; /**< == 1 (bit) */
  10.861 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_TYPE_LEN; /**< == 7 (bits) */
  10.862 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_LENGTH_LEN; /**< == 24 (bits) */
  10.863 +
  10.864 +/** The total stream length of a metadata block header in bytes. */
  10.865 +#define FLAC__STREAM_METADATA_HEADER_LENGTH (4u)
  10.866 +
  10.867 +/*****************************************************************************/
  10.868 +
  10.869 +
  10.870 +/*****************************************************************************
  10.871 + *
  10.872 + * Utility functions
  10.873 + *
  10.874 + *****************************************************************************/
  10.875 +
  10.876 +/** Tests that a sample rate is valid for FLAC.
  10.877 + *
  10.878 + * \param sample_rate  The sample rate to test for compliance.
  10.879 + * \retval FLAC__bool
  10.880 + *    \c true if the given sample rate conforms to the specification, else
  10.881 + *    \c false.
  10.882 + */
  10.883 +FLAC_API FLAC__bool FLAC__format_sample_rate_is_valid(unsigned sample_rate);
  10.884 +
  10.885 +/** Tests that a sample rate is valid for the FLAC subset.  The subset rules
  10.886 + *  for valid sample rates are slightly more complex since the rate has to
  10.887 + *  be expressible completely in the frame header.
  10.888 + *
  10.889 + * \param sample_rate  The sample rate to test for compliance.
  10.890 + * \retval FLAC__bool
  10.891 + *    \c true if the given sample rate conforms to the specification for the
  10.892 + *    subset, else \c false.
  10.893 + */
  10.894 +FLAC_API FLAC__bool FLAC__format_sample_rate_is_subset(unsigned sample_rate);
  10.895 +
  10.896 +/** Check a Vorbis comment entry name to see if it conforms to the Vorbis
  10.897 + *  comment specification.
  10.898 + *
  10.899 + *  Vorbis comment names must be composed only of characters from
  10.900 + *  [0x20-0x3C,0x3E-0x7D].
  10.901 + *
  10.902 + * \param name       A NUL-terminated string to be checked.
  10.903 + * \assert
  10.904 + *    \code name != NULL \endcode
  10.905 + * \retval FLAC__bool
  10.906 + *    \c false if entry name is illegal, else \c true.
  10.907 + */
  10.908 +FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_name_is_legal(const char *name);
  10.909 +
  10.910 +/** Check a Vorbis comment entry value to see if it conforms to the Vorbis
  10.911 + *  comment specification.
  10.912 + *
  10.913 + *  Vorbis comment values must be valid UTF-8 sequences.
  10.914 + *
  10.915 + * \param value      A string to be checked.
  10.916 + * \param length     A the length of \a value in bytes.  May be
  10.917 + *                   \c (unsigned)(-1) to indicate that \a value is a plain
  10.918 + *                   UTF-8 NUL-terminated string.
  10.919 + * \assert
  10.920 + *    \code value != NULL \endcode
  10.921 + * \retval FLAC__bool
  10.922 + *    \c false if entry name is illegal, else \c true.
  10.923 + */
  10.924 +FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_value_is_legal(const FLAC__byte *value, unsigned length);
  10.925 +
  10.926 +/** Check a Vorbis comment entry to see if it conforms to the Vorbis
  10.927 + *  comment specification.
  10.928 + *
  10.929 + *  Vorbis comment entries must be of the form 'name=value', and 'name' and
  10.930 + *  'value' must be legal according to
  10.931 + *  FLAC__format_vorbiscomment_entry_name_is_legal() and
  10.932 + *  FLAC__format_vorbiscomment_entry_value_is_legal() respectively.
  10.933 + *
  10.934 + * \param entry      An entry to be checked.
  10.935 + * \param length     The length of \a entry in bytes.
  10.936 + * \assert
  10.937 + *    \code value != NULL \endcode
  10.938 + * \retval FLAC__bool
  10.939 + *    \c false if entry name is illegal, else \c true.
  10.940 + */
  10.941 +FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_is_legal(const FLAC__byte *entry, unsigned length);
  10.942 +
  10.943 +/** Check a seek table to see if it conforms to the FLAC specification.
  10.944 + *  See the format specification for limits on the contents of the
  10.945 + *  seek table.
  10.946 + *
  10.947 + * \param seek_table  A pointer to a seek table to be checked.
  10.948 + * \assert
  10.949 + *    \code seek_table != NULL \endcode
  10.950 + * \retval FLAC__bool
  10.951 + *    \c false if seek table is illegal, else \c true.
  10.952 + */
  10.953 +FLAC_API FLAC__bool FLAC__format_seektable_is_legal(const FLAC__StreamMetadata_SeekTable *seek_table);
  10.954 +
  10.955 +/** Sort a seek table's seek points according to the format specification.
  10.956 + *  This includes a "unique-ification" step to remove duplicates, i.e.
  10.957 + *  seek points with identical \a sample_number values.  Duplicate seek
  10.958 + *  points are converted into placeholder points and sorted to the end of
  10.959 + *  the table.
  10.960 + *
  10.961 + * \param seek_table  A pointer to a seek table to be sorted.
  10.962 + * \assert
  10.963 + *    \code seek_table != NULL \endcode
  10.964 + * \retval unsigned
  10.965 + *    The number of duplicate seek points converted into placeholders.
  10.966 + */
  10.967 +FLAC_API unsigned FLAC__format_seektable_sort(FLAC__StreamMetadata_SeekTable *seek_table);
  10.968 +
  10.969 +/** Check a cue sheet to see if it conforms to the FLAC specification.
  10.970 + *  See the format specification for limits on the contents of the
  10.971 + *  cue sheet.
  10.972 + *
  10.973 + * \param cue_sheet  A pointer to an existing cue sheet to be checked.
  10.974 + * \param check_cd_da_subset  If \c true, check CUESHEET against more
  10.975 + *                   stringent requirements for a CD-DA (audio) disc.
  10.976 + * \param violation  Address of a pointer to a string.  If there is a
  10.977 + *                   violation, a pointer to a string explanation of the
  10.978 + *                   violation will be returned here. \a violation may be
  10.979 + *                   \c NULL if you don't need the returned string.  Do not
  10.980 + *                   free the returned string; it will always point to static
  10.981 + *                   data.
  10.982 + * \assert
  10.983 + *    \code cue_sheet != NULL \endcode
  10.984 + * \retval FLAC__bool
  10.985 + *    \c false if cue sheet is illegal, else \c true.
  10.986 + */
  10.987 +FLAC_API FLAC__bool FLAC__format_cuesheet_is_legal(const FLAC__StreamMetadata_CueSheet *cue_sheet, FLAC__bool check_cd_da_subset, const char **violation);
  10.988 +
  10.989 +/** Check picture data to see if it conforms to the FLAC specification.
  10.990 + *  See the format specification for limits on the contents of the
  10.991 + *  PICTURE block.
  10.992 + *
  10.993 + * \param picture    A pointer to existing picture data to be checked.
  10.994 + * \param violation  Address of a pointer to a string.  If there is a
  10.995 + *                   violation, a pointer to a string explanation of the
  10.996 + *                   violation will be returned here. \a violation may be
  10.997 + *                   \c NULL if you don't need the returned string.  Do not
  10.998 + *                   free the returned string; it will always point to static
  10.999 + *                   data.
 10.1000 + * \assert
 10.1001 + *    \code picture != NULL \endcode
 10.1002 + * \retval FLAC__bool
 10.1003 + *    \c false if picture data is illegal, else \c true.
 10.1004 + */
 10.1005 +FLAC_API FLAC__bool FLAC__format_picture_is_legal(const FLAC__StreamMetadata_Picture *picture, const char **violation);
 10.1006 +
 10.1007 +/* \} */
 10.1008 +
 10.1009 +#ifdef __cplusplus
 10.1010 +}
 10.1011 +#endif
 10.1012 +
 10.1013 +#endif
    11.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    11.2 +++ b/Xcode/Frameworks/FLAC.framework/Versions/A/Headers/FLAC/metadata.h	Mon Jan 09 01:58:40 2012 -0500
    11.3 @@ -0,0 +1,2181 @@
    11.4 +/* libFLAC - Free Lossless Audio Codec library
    11.5 + * Copyright (C) 2001,2002,2003,2004,2005,2006,2007  Josh Coalson
    11.6 + *
    11.7 + * Redistribution and use in source and binary forms, with or without
    11.8 + * modification, are permitted provided that the following conditions
    11.9 + * are met:
   11.10 + *
   11.11 + * - Redistributions of source code must retain the above copyright
   11.12 + * notice, this list of conditions and the following disclaimer.
   11.13 + *
   11.14 + * - Redistributions in binary form must reproduce the above copyright
   11.15 + * notice, this list of conditions and the following disclaimer in the
   11.16 + * documentation and/or other materials provided with the distribution.
   11.17 + *
   11.18 + * - Neither the name of the Xiph.org Foundation nor the names of its
   11.19 + * contributors may be used to endorse or promote products derived from
   11.20 + * this software without specific prior written permission.
   11.21 + *
   11.22 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   11.23 + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   11.24 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
   11.25 + * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
   11.26 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
   11.27 + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
   11.28 + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
   11.29 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
   11.30 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
   11.31 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
   11.32 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   11.33 + */
   11.34 +
   11.35 +#ifndef FLAC__METADATA_H
   11.36 +#define FLAC__METADATA_H
   11.37 +
   11.38 +#include <sys/types.h> /* for off_t */
   11.39 +#include "export.h"
   11.40 +#include "callback.h"
   11.41 +#include "format.h"
   11.42 +
   11.43 +/* --------------------------------------------------------------------
   11.44 +   (For an example of how all these routines are used, see the source
   11.45 +   code for the unit tests in src/test_libFLAC/metadata_*.c, or
   11.46 +   metaflac in src/metaflac/)
   11.47 +   ------------------------------------------------------------------*/
   11.48 +
   11.49 +/** \file include/FLAC/metadata.h
   11.50 + *
   11.51 + *  \brief
   11.52 + *  This module provides functions for creating and manipulating FLAC
   11.53 + *  metadata blocks in memory, and three progressively more powerful
   11.54 + *  interfaces for traversing and editing metadata in FLAC files.
   11.55 + *
   11.56 + *  See the detailed documentation for each interface in the
   11.57 + *  \link flac_metadata metadata \endlink module.
   11.58 + */
   11.59 +
   11.60 +/** \defgroup flac_metadata FLAC/metadata.h: metadata interfaces
   11.61 + *  \ingroup flac
   11.62 + *
   11.63 + *  \brief
   11.64 + *  This module provides functions for creating and manipulating FLAC
   11.65 + *  metadata blocks in memory, and three progressively more powerful
   11.66 + *  interfaces for traversing and editing metadata in native FLAC files.
   11.67 + *  Note that currently only the Chain interface (level 2) supports Ogg
   11.68 + *  FLAC files, and it is read-only i.e. no writing back changed
   11.69 + *  metadata to file.
   11.70 + *
   11.71 + *  There are three metadata interfaces of increasing complexity:
   11.72 + *
   11.73 + *  Level 0:
   11.74 + *  Read-only access to the STREAMINFO, VORBIS_COMMENT, CUESHEET, and
   11.75 + *  PICTURE blocks.
   11.76 + *
   11.77 + *  Level 1:
   11.78 + *  Read-write access to all metadata blocks.  This level is write-
   11.79 + *  efficient in most cases (more on this below), and uses less memory
   11.80 + *  than level 2.
   11.81 + *
   11.82 + *  Level 2:
   11.83 + *  Read-write access to all metadata blocks.  This level is write-
   11.84 + *  efficient in all cases, but uses more memory since all metadata for
   11.85 + *  the whole file is read into memory and manipulated before writing
   11.86 + *  out again.
   11.87 + *
   11.88 + *  What do we mean by efficient?  Since FLAC metadata appears at the
   11.89 + *  beginning of the file, when writing metadata back to a FLAC file
   11.90 + *  it is possible to grow or shrink the metadata such that the entire
   11.91 + *  file must be rewritten.  However, if the size remains the same during
   11.92 + *  changes or PADDING blocks are utilized, only the metadata needs to be
   11.93 + *  overwritten, which is much faster.
   11.94 + *
   11.95 + *  Efficient means the whole file is rewritten at most one time, and only
   11.96 + *  when necessary.  Level 1 is not efficient only in the case that you
   11.97 + *  cause more than one metadata block to grow or shrink beyond what can
   11.98 + *  be accomodated by padding.  In this case you should probably use level
   11.99 + *  2, which allows you to edit all the metadata for a file in memory and
  11.100 + *  write it out all at once.
  11.101 + *
  11.102 + *  All levels know how to skip over and not disturb an ID3v2 tag at the
  11.103 + *  front of the file.
  11.104 + *
  11.105 + *  All levels access files via their filenames.  In addition, level 2
  11.106 + *  has additional alternative read and write functions that take an I/O
  11.107 + *  handle and callbacks, for situations where access by filename is not
  11.108 + *  possible.
  11.109 + *
  11.110 + *  In addition to the three interfaces, this module defines functions for
  11.111 + *  creating and manipulating various metadata objects in memory.  As we see
  11.112 + *  from the Format module, FLAC metadata blocks in memory are very primitive
  11.113 + *  structures for storing information in an efficient way.  Reading
  11.114 + *  information from the structures is easy but creating or modifying them
  11.115 + *  directly is more complex.  The metadata object routines here facilitate
  11.116 + *  this by taking care of the consistency and memory management drudgery.
  11.117 + *
  11.118 + *  Unless you will be using the level 1 or 2 interfaces to modify existing
  11.119 + *  metadata however, you will not probably not need these.
  11.120 + *
  11.121 + *  From a dependency standpoint, none of the encoders or decoders require
  11.122 + *  the metadata module.  This is so that embedded users can strip out the
  11.123 + *  metadata module from libFLAC to reduce the size and complexity.
  11.124 + */
  11.125 +
  11.126 +#ifdef __cplusplus
  11.127 +extern "C" {
  11.128 +#endif
  11.129 +
  11.130 +
  11.131 +/** \defgroup flac_metadata_level0 FLAC/metadata.h: metadata level 0 interface
  11.132 + *  \ingroup flac_metadata
  11.133 + *
  11.134 + *  \brief
  11.135 + *  The level 0 interface consists of individual routines to read the
  11.136 + *  STREAMINFO, VORBIS_COMMENT, CUESHEET, and PICTURE blocks, requiring
  11.137 + *  only a filename.
  11.138 + *
  11.139 + *  They try to skip any ID3v2 tag at the head of the file.
  11.140 + *
  11.141 + * \{
  11.142 + */
  11.143 +
  11.144 +/** Read the STREAMINFO metadata block of the given FLAC file.  This function
  11.145 + *  will try to skip any ID3v2 tag at the head of the file.
  11.146 + *
  11.147 + * \param filename    The path to the FLAC file to read.
  11.148 + * \param streaminfo  A pointer to space for the STREAMINFO block.  Since
  11.149 + *                    FLAC__StreamMetadata is a simple structure with no
  11.150 + *                    memory allocation involved, you pass the address of
  11.151 + *                    an existing structure.  It need not be initialized.
  11.152 + * \assert
  11.153 + *    \code filename != NULL \endcode
  11.154 + *    \code streaminfo != NULL \endcode
  11.155 + * \retval FLAC__bool
  11.156 + *    \c true if a valid STREAMINFO block was read from \a filename.  Returns
  11.157 + *    \c false if there was a memory allocation error, a file decoder error,
  11.158 + *    or the file contained no STREAMINFO block.  (A memory allocation error
  11.159 + *    is possible because this function must set up a file decoder.)
  11.160 + */
  11.161 +FLAC_API FLAC__bool FLAC__metadata_get_streaminfo(const char *filename, FLAC__StreamMetadata *streaminfo);
  11.162 +
  11.163 +/** Read the VORBIS_COMMENT metadata block of the given FLAC file.  This
  11.164 + *  function will try to skip any ID3v2 tag at the head of the file.
  11.165 + *
  11.166 + * \param filename    The path to the FLAC file to read.
  11.167 + * \param tags        The address where the returned pointer will be
  11.168 + *                    stored.  The \a tags object must be deleted by
  11.169 + *                    the caller using FLAC__metadata_object_delete().
  11.170 + * \assert
  11.171 + *    \code filename != NULL \endcode
  11.172 + *    \code tags != NULL \endcode
  11.173 + * \retval FLAC__bool
  11.174 + *    \c true if a valid VORBIS_COMMENT block was read from \a filename,
  11.175 + *    and \a *tags will be set to the address of the metadata structure.
  11.176 + *    Returns \c false if there was a memory allocation error, a file
  11.177 + *    decoder error, or the file contained no VORBIS_COMMENT block, and
  11.178 + *    \a *tags will be set to \c NULL.
  11.179 + */
  11.180 +FLAC_API FLAC__bool FLAC__metadata_get_tags(const char *filename, FLAC__StreamMetadata **tags);
  11.181 +
  11.182 +/** Read the CUESHEET metadata block of the given FLAC file.  This
  11.183 + *  function will try to skip any ID3v2 tag at the head of the file.
  11.184 + *
  11.185 + * \param filename    The path to the FLAC file to read.
  11.186 + * \param cuesheet    The address where the returned pointer will be
  11.187 + *                    stored.  The \a cuesheet object must be deleted by
  11.188 + *                    the caller using FLAC__metadata_object_delete().
  11.189 + * \assert
  11.190 + *    \code filename != NULL \endcode
  11.191 + *    \code cuesheet != NULL \endcode
  11.192 + * \retval FLAC__bool
  11.193 + *    \c true if a valid CUESHEET block was read from \a filename,
  11.194 + *    and \a *cuesheet will be set to the address of the metadata
  11.195 + *    structure.  Returns \c false if there was a memory allocation
  11.196 + *    error, a file decoder error, or the file contained no CUESHEET
  11.197 + *    block, and \a *cuesheet will be set to \c NULL.
  11.198 + */
  11.199 +FLAC_API FLAC__bool FLAC__metadata_get_cuesheet(const char *filename, FLAC__StreamMetadata **cuesheet);
  11.200 +
  11.201 +/** Read a PICTURE metadata block of the given FLAC file.  This
  11.202 + *  function will try to skip any ID3v2 tag at the head of the file.
  11.203 + *  Since there can be more than one PICTURE block in a file, this
  11.204 + *  function takes a number of parameters that act as constraints to
  11.205 + *  the search.  The PICTURE block with the largest area matching all
  11.206 + *  the constraints will be returned, or \a *picture will be set to
  11.207 + *  \c NULL if there was no such block.
  11.208 + *
  11.209 + * \param filename    The path to the FLAC file to read.
  11.210 + * \param picture     The address where the returned pointer will be
  11.211 + *                    stored.  The \a picture object must be deleted by
  11.212 + *                    the caller using FLAC__metadata_object_delete().
  11.213 + * \param type        The desired picture type.  Use \c -1 to mean
  11.214 + *                    "any type".
  11.215 + * \param mime_type   The desired MIME type, e.g. "image/jpeg".  The
  11.216 + *                    string will be matched exactly.  Use \c NULL to
  11.217 + *                    mean "any MIME type".
  11.218 + * \param description The desired description.  The string will be
  11.219 + *                    matched exactly.  Use \c NULL to mean "any
  11.220 + *                    description".
  11.221 + * \param max_width   The maximum width in pixels desired.  Use
  11.222 + *                    \c (unsigned)(-1) to mean "any width".
  11.223 + * \param max_height  The maximum height in pixels desired.  Use
  11.224 + *                    \c (unsigned)(-1) to mean "any height".
  11.225 + * \param max_depth   The maximum color depth in bits-per-pixel desired.
  11.226 + *                    Use \c (unsigned)(-1) to mean "any depth".
  11.227 + * \param max_colors  The maximum number of colors desired.  Use
  11.228 + *                    \c (unsigned)(-1) to mean "any number of colors".
  11.229 + * \assert
  11.230 + *    \code filename != NULL \endcode
  11.231 + *    \code picture != NULL \endcode
  11.232 + * \retval FLAC__bool
  11.233 + *    \c true if a valid PICTURE block was read from \a filename,
  11.234 + *    and \a *picture will be set to the address of the metadata
  11.235 + *    structure.  Returns \c false if there was a memory allocation
  11.236 + *    error, a file decoder error, or the file contained no PICTURE
  11.237 + *    block, and \a *picture will be set to \c NULL.
  11.238 + */
  11.239 +FLAC_API FLAC__bool FLAC__metadata_get_picture(const char *filename, FLAC__StreamMetadata **picture, FLAC__StreamMetadata_Picture_Type type, const char *mime_type, const FLAC__byte *description, unsigned max_width, unsigned max_height, unsigned max_depth, unsigned max_colors);
  11.240 +
  11.241 +/* \} */
  11.242 +
  11.243 +
  11.244 +/** \defgroup flac_metadata_level1 FLAC/metadata.h: metadata level 1 interface
  11.245 + *  \ingroup flac_metadata
  11.246 + *
  11.247 + * \brief
  11.248 + * The level 1 interface provides read-write access to FLAC file metadata and
  11.249 + * operates directly on the FLAC file.
  11.250 + *
  11.251 + * The general usage of this interface is:
  11.252 + *
  11.253 + * - Create an iterator using FLAC__metadata_simple_iterator_new()
  11.254 + * - Attach it to a file using FLAC__metadata_simple_iterator_init() and check
  11.255 + *   the exit code.  Call FLAC__metadata_simple_iterator_is_writable() to
  11.256 + *   see if the file is writable, or only read access is allowed.
  11.257 + * - Use FLAC__metadata_simple_iterator_next() and
  11.258 + *   FLAC__metadata_simple_iterator_prev() to traverse the blocks.
  11.259 + *   This is does not read the actual blocks themselves.
  11.260 + *   FLAC__metadata_simple_iterator_next() is relatively fast.
  11.261 + *   FLAC__metadata_simple_iterator_prev() is slower since it needs to search
  11.262 + *   forward from the front of the file.
  11.263 + * - Use FLAC__metadata_simple_iterator_get_block_type() or
  11.264 + *   FLAC__metadata_simple_iterator_get_block() to access the actual data at
  11.265 + *   the current iterator position.  The returned object is yours to modify
  11.266 + *   and free.
  11.267 + * - Use FLAC__metadata_simple_iterator_set_block() to write a modified block
  11.268 + *   back.  You must have write permission to the original file.  Make sure to
  11.269 + *   read the whole comment to FLAC__metadata_simple_iterator_set_block()
  11.270 + *   below.
  11.271 + * - Use FLAC__metadata_simple_iterator_insert_block_after() to add new blocks.
  11.272 + *   Use the object creation functions from
  11.273 + *   \link flac_metadata_object here \endlink to generate new objects.
  11.274 + * - Use FLAC__metadata_simple_iterator_delete_block() to remove the block
  11.275 + *   currently referred to by the iterator, or replace it with padding.
  11.276 + * - Destroy the iterator with FLAC__metadata_simple_iterator_delete() when
  11.277 + *   finished.
  11.278 + *
  11.279 + * \note
  11.280 + * The FLAC file remains open the whole time between
  11.281 + * FLAC__metadata_simple_iterator_init() and
  11.282 + * FLAC__metadata_simple_iterator_delete(), so make sure you are not altering
  11.283 + * the file during this time.
  11.284 + *
  11.285 + * \note
  11.286 + * Do not modify the \a is_last, \a length, or \a type fields of returned
  11.287 + * FLAC__StreamMetadata objects.  These are managed automatically.
  11.288 + *
  11.289 + * \note
  11.290 + * If any of the modification functions
  11.291 + * (FLAC__metadata_simple_iterator_set_block(),
  11.292 + * FLAC__metadata_simple_iterator_delete_block(),
  11.293 + * FLAC__metadata_simple_iterator_insert_block_after(), etc.) return \c false,
  11.294 + * you should delete the iterator as it may no longer be valid.
  11.295 + *
  11.296 + * \{
  11.297 + */
  11.298 +
  11.299 +struct FLAC__Metadata_SimpleIterator;
  11.300 +/** The opaque structure definition for the level 1 iterator type.
  11.301 + *  See the
  11.302 + *  \link flac_metadata_level1 metadata level 1 module \endlink
  11.303 + *  for a detailed description.
  11.304 + */
  11.305 +typedef struct FLAC__Metadata_SimpleIterator FLAC__Metadata_SimpleIterator;
  11.306 +
  11.307 +/** Status type for FLAC__Metadata_SimpleIterator.
  11.308 + *
  11.309 + *  The iterator's current status can be obtained by calling FLAC__metadata_simple_iterator_status().
  11.310 + */
  11.311 +typedef enum {
  11.312 +
  11.313 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK = 0,
  11.314 +	/**< The iterator is in the normal OK state */
  11.315 +
  11.316 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT,
  11.317 +	/**< The data passed into a function violated the function's usage criteria */
  11.318 +
  11.319 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ERROR_OPENING_FILE,
  11.320 +	/**< The iterator could not open the target file */
  11.321 +
  11.322 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_A_FLAC_FILE,
  11.323 +	/**< The iterator could not find the FLAC signature at the start of the file */
  11.324 +
  11.325 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_WRITABLE,
  11.326 +	/**< The iterator tried to write to a file that was not writable */
  11.327 +
  11.328 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_BAD_METADATA,
  11.329 +	/**< The iterator encountered input that does not conform to the FLAC metadata specification */
  11.330 +
  11.331 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_READ_ERROR,
  11.332 +	/**< The iterator encountered an error while reading the FLAC file */
  11.333 +
  11.334 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_SEEK_ERROR,
  11.335 +	/**< The iterator encountered an error while seeking in the FLAC file */
  11.336 +
  11.337 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_WRITE_ERROR,
  11.338 +	/**< The iterator encountered an error while writing the FLAC file */
  11.339 +
  11.340 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_RENAME_ERROR,
  11.341 +	/**< The iterator encountered an error renaming the FLAC file */
  11.342 +
  11.343 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_UNLINK_ERROR,
  11.344 +	/**< The iterator encountered an error removing the temporary file */
  11.345 +
  11.346 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_MEMORY_ALLOCATION_ERROR,
  11.347 +	/**< Memory allocation failed */
  11.348 +
  11.349 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_INTERNAL_ERROR
  11.350 +	/**< The caller violated an assertion or an unexpected error occurred */
  11.351 +
  11.352 +} FLAC__Metadata_SimpleIteratorStatus;
  11.353 +
  11.354 +/** Maps a FLAC__Metadata_SimpleIteratorStatus to a C string.
  11.355 + *
  11.356 + *  Using a FLAC__Metadata_SimpleIteratorStatus as the index to this array
  11.357 + *  will give the string equivalent.  The contents should not be modified.
  11.358 + */
  11.359 +extern FLAC_API const char * const FLAC__Metadata_SimpleIteratorStatusString[];
  11.360 +
  11.361 +
  11.362 +/** Create a new iterator instance.
  11.363 + *
  11.364 + * \retval FLAC__Metadata_SimpleIterator*
  11.365 + *    \c NULL if there was an error allocating memory, else the new instance.
  11.366 + */
  11.367 +FLAC_API FLAC__Metadata_SimpleIterator *FLAC__metadata_simple_iterator_new(void);
  11.368 +
  11.369 +/** Free an iterator instance.  Deletes the object pointed to by \a iterator.
  11.370 + *
  11.371 + * \param iterator  A pointer to an existing iterator.
  11.372 + * \assert
  11.373 + *    \code iterator != NULL \endcode
  11.374 + */
  11.375 +FLAC_API void FLAC__metadata_simple_iterator_delete(FLAC__Metadata_SimpleIterator *iterator);
  11.376 +
  11.377 +/** Get the current status of the iterator.  Call this after a function
  11.378 + *  returns \c false to get the reason for the error.  Also resets the status
  11.379 + *  to FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK.
  11.380 + *
  11.381 + * \param iterator  A pointer to an existing iterator.
  11.382 + * \assert
  11.383 + *    \code iterator != NULL \endcode
  11.384 + * \retval FLAC__Metadata_SimpleIteratorStatus
  11.385 + *    The current status of the iterator.
  11.386 + */
  11.387 +FLAC_API FLAC__Metadata_SimpleIteratorStatus FLAC__metadata_simple_iterator_status(FLAC__Metadata_SimpleIterator *iterator);
  11.388 +
  11.389 +/** Initialize the iterator to point to the first metadata block in the
  11.390 + *  given FLAC file.
  11.391 + *
  11.392 + * \param iterator             A pointer to an existing iterator.
  11.393 + * \param filename             The path to the FLAC file.
  11.394 + * \param read_only            If \c true, the FLAC file will be opened
  11.395 + *                             in read-only mode; if \c false, the FLAC
  11.396 + *                             file will be opened for edit even if no
  11.397 + *                             edits are performed.
  11.398 + * \param preserve_file_stats  If \c true, the owner and modification
  11.399 + *                             time will be preserved even if the FLAC
  11.400 + *                             file is written to.
  11.401 + * \assert
  11.402 + *    \code iterator != NULL \endcode
  11.403 + *    \code filename != NULL \endcode
  11.404 + * \retval FLAC__bool
  11.405 + *    \c false if a memory allocation error occurs, the file can't be
  11.406 + *    opened, or another error occurs, else \c true.
  11.407 + */
  11.408 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_init(FLAC__Metadata_SimpleIterator *iterator, const char *filename, FLAC__bool read_only, FLAC__bool preserve_file_stats);
  11.409 +
  11.410 +/** Returns \c true if the FLAC file is writable.  If \c false, calls to
  11.411 + *  FLAC__metadata_simple_iterator_set_block() and
  11.412 + *  FLAC__metadata_simple_iterator_insert_block_after() will fail.
  11.413 + *
  11.414 + * \param iterator             A pointer to an existing iterator.
  11.415 + * \assert
  11.416 + *    \code iterator != NULL \endcode
  11.417 + * \retval FLAC__bool
  11.418 + *    See above.
  11.419 + */
  11.420 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_writable(const FLAC__Metadata_SimpleIterator *iterator);
  11.421 +
  11.422 +/** Moves the iterator forward one metadata block, returning \c false if
  11.423 + *  already at the end.
  11.424 + *
  11.425 + * \param iterator  A pointer to an existing initialized iterator.
  11.426 + * \assert
  11.427 + *    \code iterator != NULL \endcode
  11.428 + *    \a iterator has been successfully initialized with
  11.429 + *    FLAC__metadata_simple_iterator_init()
  11.430 + * \retval FLAC__bool
  11.431 + *    \c false if already at the last metadata block of the chain, else
  11.432 + *    \c true.
  11.433 + */
  11.434 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_next(FLAC__Metadata_SimpleIterator *iterator);
  11.435 +
  11.436 +/** Moves the iterator backward one metadata block, returning \c false if
  11.437 + *  already at the beginning.
  11.438 + *
  11.439 + * \param iterator  A pointer to an existing initialized iterator.
  11.440 + * \assert
  11.441 + *    \code iterator != NULL \endcode
  11.442 + *    \a iterator has been successfully initialized with
  11.443 + *    FLAC__metadata_simple_iterator_init()
  11.444 + * \retval FLAC__bool
  11.445 + *    \c false if already at the first metadata block of the chain, else
  11.446 + *    \c true.
  11.447 + */
  11.448 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_prev(FLAC__Metadata_SimpleIterator *iterator);
  11.449 +
  11.450 +/** Returns a flag telling if the current metadata block is the last.
  11.451 + *
  11.452 + * \param iterator  A pointer to an existing initialized iterator.
  11.453 + * \assert
  11.454 + *    \code iterator != NULL \endcode
  11.455 + *    \a iterator has been successfully initialized with
  11.456 + *    FLAC__metadata_simple_iterator_init()
  11.457 + * \retval FLAC__bool
  11.458 + *    \c true if the current metadata block is the last in the file,
  11.459 + *    else \c false.
  11.460 + */
  11.461 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_last(const FLAC__Metadata_SimpleIterator *iterator);
  11.462 +
  11.463 +/** Get the offset of the metadata block at the current position.  This
  11.464 + *  avoids reading the actual block data which can save time for large
  11.465 + *  blocks.
  11.466 + *
  11.467 + * \param iterator  A pointer to an existing initialized iterator.
  11.468 + * \assert
  11.469 + *    \code iterator != NULL \endcode
  11.470 + *    \a iterator has been successfully initialized with
  11.471 + *    FLAC__metadata_simple_iterator_init()
  11.472 + * \retval off_t
  11.473 + *    The offset of the metadata block at the current iterator position.
  11.474 + *    This is the byte offset relative to the beginning of the file of
  11.475 + *    the current metadata block's header.
  11.476 + */
  11.477 +FLAC_API off_t FLAC__metadata_simple_iterator_get_block_offset(const FLAC__Metadata_SimpleIterator *iterator);
  11.478 +
  11.479 +/** Get the type of the metadata block at the current position.  This
  11.480 + *  avoids reading the actual block data which can save time for large
  11.481 + *  blocks.
  11.482 + *
  11.483 + * \param iterator  A pointer to an existing initialized iterator.
  11.484 + * \assert
  11.485 + *    \code iterator != NULL \endcode
  11.486 + *    \a iterator has been successfully initialized with
  11.487 + *    FLAC__metadata_simple_iterator_init()
  11.488 + * \retval FLAC__MetadataType
  11.489 + *    The type of the metadata block at the current iterator position.
  11.490 + */
  11.491 +FLAC_API FLAC__MetadataType FLAC__metadata_simple_iterator_get_block_type(const FLAC__Metadata_SimpleIterator *iterator);
  11.492 +
  11.493 +/** Get the length of the metadata block at the current position.  This
  11.494 + *  avoids reading the actual block data which can save time for large
  11.495 + *  blocks.
  11.496 + *
  11.497 + * \param iterator  A pointer to an existing initialized iterator.
  11.498 + * \assert
  11.499 + *    \code iterator != NULL \endcode
  11.500 + *    \a iterator has been successfully initialized with
  11.501 + *    FLAC__metadata_simple_iterator_init()
  11.502 + * \retval unsigned
  11.503 + *    The length of the metadata block at the current iterator position.
  11.504 + *    The is same length as that in the
  11.505 + *    <a href="http://flac.sourceforge.net/format.html#metadata_block_header">metadata block header</a>,
  11.506 + *    i.e. the length of the metadata body that follows the header.
  11.507 + */
  11.508 +FLAC_API unsigned FLAC__metadata_simple_iterator_get_block_length(const FLAC__Metadata_SimpleIterator *iterator);
  11.509 +
  11.510 +/** Get the application ID of the \c APPLICATION block at the current
  11.511 + *  position.  This avoids reading the actual block data which can save
  11.512 + *  time for large blocks.
  11.513 + *
  11.514 + * \param iterator  A pointer to an existing initialized iterator.
  11.515 + * \param id        A pointer to a buffer of at least \c 4 bytes where
  11.516 + *                  the ID will be stored.
  11.517 + * \assert
  11.518 + *    \code iterator != NULL \endcode
  11.519 + *    \code id != NULL \endcode
  11.520 + *    \a iterator has been successfully initialized with
  11.521 + *    FLAC__metadata_simple_iterator_init()
  11.522 + * \retval FLAC__bool
  11.523 + *    \c true if the ID was successfully read, else \c false, in which
  11.524 + *    case you should check FLAC__metadata_simple_iterator_status() to
  11.525 + *    find out why.  If the status is
  11.526 + *    \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT, then the
  11.527 + *    current metadata block is not an \c APPLICATION block.  Otherwise
  11.528 + *    if the status is
  11.529 + *    \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_READ_ERROR or
  11.530 + *    \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_SEEK_ERROR, an I/O error
  11.531 + *    occurred and the iterator can no longer be used.
  11.532 + */
  11.533 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_get_application_id(FLAC__Metadata_SimpleIterator *iterator, FLAC__byte *id);
  11.534 +
  11.535 +/** Get the metadata block at the current position.  You can modify the
  11.536 + *  block but must use FLAC__metadata_simple_iterator_set_block() to
  11.537 + *  write it back to the FLAC file.
  11.538 + *
  11.539 + *  You must call FLAC__metadata_object_delete() on the returned object
  11.540 + *  when you are finished with it.
  11.541 + *
  11.542 + * \param iterator  A pointer to an existing initialized iterator.
  11.543 + * \assert
  11.544 + *    \code iterator != NULL \endcode
  11.545 + *    \a iterator has been successfully initialized with
  11.546 + *    FLAC__metadata_simple_iterator_init()
  11.547 + * \retval FLAC__StreamMetadata*
  11.548 + *    The current metadata block, or \c NULL if there was a memory
  11.549 + *    allocation error.
  11.550 + */
  11.551 +FLAC_API FLAC__StreamMetadata *FLAC__metadata_simple_iterator_get_block(FLAC__Metadata_SimpleIterator *iterator);
  11.552 +
  11.553 +/** Write a block back to the FLAC file.  This function tries to be
  11.554 + *  as efficient as possible; how the block is actually written is
  11.555 + *  shown by the following:
  11.556 + *
  11.557 + *  Existing block is a STREAMINFO block and the new block is a
  11.558 + *  STREAMINFO block: the new block is written in place.  Make sure
  11.559 + *  you know what you're doing when changing the values of a
  11.560 + *  STREAMINFO block.
  11.561 + *
  11.562 + *  Existing block is a STREAMINFO block and the new block is a
  11.563 + *  not a STREAMINFO block: this is an error since the first block
  11.564 + *  must be a STREAMINFO block.  Returns \c false without altering the
  11.565 + *  file.
  11.566 + *
  11.567 + *  Existing block is not a STREAMINFO block and the new block is a
  11.568 + *  STREAMINFO block: this is an error since there may be only one
  11.569 + *  STREAMINFO block.  Returns \c false without altering the file.
  11.570 + *
  11.571 + *  Existing block and new block are the same length: the existing
  11.572 + *  block will be replaced by the new block, written in place.
  11.573 + *
  11.574 + *  Existing block is longer than new block: if use_padding is \c true,
  11.575 + *  the existing block will be overwritten in place with the new
  11.576 + *  block followed by a PADDING block, if possible, to make the total
  11.577 + *  size the same as the existing block.  Remember that a padding
  11.578 + *  block requires at least four bytes so if the difference in size
  11.579 + *  between the new block and existing block is less than that, the
  11.580 + *  entire file will have to be rewritten, using the new block's
  11.581 + *  exact size.  If use_padding is \c false, the entire file will be
  11.582 + *  rewritten, replacing the existing block by the new block.
  11.583 + *
  11.584 + *  Existing block is shorter than new block: if use_padding is \c true,
  11.585 + *  the function will try and expand the new block into the following
  11.586 + *  PADDING block, if it exists and doing so won't shrink the PADDING
  11.587 + *  block to less than 4 bytes.  If there is no following PADDING
  11.588 + *  block, or it will shrink to less than 4 bytes, or use_padding is
  11.589 + *  \c false, the entire file is rewritten, replacing the existing block
  11.590 + *  with the new block.  Note that in this case any following PADDING
  11.591 + *  block is preserved as is.
  11.592 + *
  11.593 + *  After writing the block, the iterator will remain in the same
  11.594 + *  place, i.e. pointing to the new block.
  11.595 + *
  11.596 + * \param iterator     A pointer to an existing initialized iterator.
  11.597 + * \param block        The block to set.
  11.598 + * \param use_padding  See above.
  11.599 + * \assert
  11.600 + *    \code iterator != NULL \endcode
  11.601 + *    \a iterator has been successfully initialized with
  11.602 + *    FLAC__metadata_simple_iterator_init()
  11.603 + *    \code block != NULL \endcode
  11.604 + * \retval FLAC__bool
  11.605 + *    \c true if successful, else \c false.
  11.606 + */
  11.607 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_set_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding);
  11.608 +
  11.609 +/** This is similar to FLAC__metadata_simple_iterator_set_block()
  11.610 + *  except that instead of writing over an existing block, it appends
  11.611 + *  a block after the existing block.  \a use_padding is again used to
  11.612 + *  tell the function to try an expand into following padding in an
  11.613 + *  attempt to avoid rewriting the entire file.
  11.614 + *
  11.615 + *  This function will fail and return \c false if given a STREAMINFO
  11.616 + *  block.
  11.617 + *
  11.618 + *  After writing the block, the iterator will be pointing to the
  11.619 + *  new block.
  11.620 + *
  11.621 + * \param iterator     A pointer to an existing initialized iterator.
  11.622 + * \param block        The block to set.
  11.623 + * \param use_padding  See above.
  11.624 + * \assert
  11.625 + *    \code iterator != NULL \endcode
  11.626 + *    \a iterator has been successfully initialized with
  11.627 + *    FLAC__metadata_simple_iterator_init()
  11.628 + *    \code block != NULL \endcode
  11.629 + * \retval FLAC__bool
  11.630 + *    \c true if successful, else \c false.
  11.631 + */
  11.632 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_insert_block_after(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding);
  11.633 +
  11.634 +/** Deletes the block at the current position.  This will cause the
  11.635 + *  entire FLAC file to be rewritten, unless \a use_padding is \c true,
  11.636 + *  in which case the block will be replaced by an equal-sized PADDING
  11.637 + *  block.  The iterator will be left pointing to the block before the
  11.638 + *  one just deleted.
  11.639 + *
  11.640 + *  You may not delete the STREAMINFO block.
  11.641 + *
  11.642 + * \param iterator     A pointer to an existing initialized iterator.
  11.643 + * \param use_padding  See above.
  11.644 + * \assert
  11.645 + *    \code iterator != NULL \endcode
  11.646 + *    \a iterator has been successfully initialized with
  11.647 + *    FLAC__metadata_simple_iterator_init()
  11.648 + * \retval FLAC__bool
  11.649 + *    \c true if successful, else \c false.
  11.650 + */
  11.651 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_delete_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__bool use_padding);
  11.652 +
  11.653 +/* \} */
  11.654 +
  11.655 +
  11.656 +/** \defgroup flac_metadata_level2 FLAC/metadata.h: metadata level 2 interface
  11.657 + *  \ingroup flac_metadata
  11.658 + *
  11.659 + * \brief
  11.660 + * The level 2 interface provides read-write access to FLAC file metadata;
  11.661 + * all metadata is read into memory, operated on in memory, and then written
  11.662 + * to file, which is more efficient than level 1 when editing multiple blocks.
  11.663 + *
  11.664 + * Currently Ogg FLAC is supported for read only, via
  11.665 + * FLAC__metadata_chain_read_ogg() but a subsequent
  11.666 + * FLAC__metadata_chain_write() will fail.
  11.667 + *
  11.668 + * The general usage of this interface is:
  11.669 + *
  11.670 + * - Create a new chain using FLAC__metadata_chain_new().  A chain is a
  11.671 + *   linked list of FLAC metadata blocks.
  11.672 + * - Read all metadata into the the chain from a FLAC file using
  11.673 + *   FLAC__metadata_chain_read() or FLAC__metadata_chain_read_ogg() and
  11.674 + *   check the status.
  11.675 + * - Optionally, consolidate the padding using
  11.676 + *   FLAC__metadata_chain_merge_padding() or
  11.677 + *   FLAC__metadata_chain_sort_padding().
  11.678 + * - Create a new iterator using FLAC__metadata_iterator_new()
  11.679 + * - Initialize the iterator to point to the first element in the chain
  11.680 + *   using FLAC__metadata_iterator_init()
  11.681 + * - Traverse the chain using FLAC__metadata_iterator_next and
  11.682 + *   FLAC__metadata_iterator_prev().
  11.683 + * - Get a block for reading or modification using
  11.684 + *   FLAC__metadata_iterator_get_block().  The pointer to the object
  11.685 + *   inside the chain is returned, so the block is yours to modify.
  11.686 + *   Changes will be reflected in the FLAC file when you write the
  11.687 + *   chain.  You can also add and delete blocks (see functions below).
  11.688 + * - When done, write out the chain using FLAC__metadata_chain_write().
  11.689 + *   Make sure to read the whole comment to the function below.
  11.690 + * - Delete the chain using FLAC__metadata_chain_delete().
  11.691 + *
  11.692 + * \note
  11.693 + * Even though the FLAC file is not open while the chain is being
  11.694 + * manipulated, you must not alter the file externally during
  11.695 + * this time.  The chain assumes the FLAC file will not change
  11.696 + * between the time of FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg()
  11.697 + * and FLAC__metadata_chain_write().
  11.698 + *
  11.699 + * \note
  11.700 + * Do not modify the is_last, length, or type fields of returned
  11.701 + * FLAC__StreamMetadata objects.  These are managed automatically.
  11.702 + *
  11.703 + * \note
  11.704 + * The metadata objects returned by FLAC__metadata_iterator_get_block()
  11.705 + * are owned by the chain; do not FLAC__metadata_object_delete() them.
  11.706 + * In the same way, blocks passed to FLAC__metadata_iterator_set_block()
  11.707 + * become owned by the chain and they will be deleted when the chain is
  11.708 + * deleted.
  11.709 + *
  11.710 + * \{
  11.711 + */
  11.712 +
  11.713 +struct FLAC__Metadata_Chain;
  11.714 +/** The opaque structure definition for the level 2 chain type.
  11.715 + */
  11.716 +typedef struct FLAC__Metadata_Chain FLAC__Metadata_Chain;
  11.717 +
  11.718 +struct FLAC__Metadata_Iterator;
  11.719 +/** The opaque structure definition for the level 2 iterator type.
  11.720 + */
  11.721 +typedef struct FLAC__Metadata_Iterator FLAC__Metadata_Iterator;
  11.722 +
  11.723 +typedef enum {
  11.724 +	FLAC__METADATA_CHAIN_STATUS_OK = 0,
  11.725 +	/**< The chain is in the normal OK state */
  11.726 +
  11.727 +	FLAC__METADATA_CHAIN_STATUS_ILLEGAL_INPUT,
  11.728 +	/**< The data passed into a function violated the function's usage criteria */
  11.729 +
  11.730 +	FLAC__METADATA_CHAIN_STATUS_ERROR_OPENING_FILE,
  11.731 +	/**< The chain could not open the target file */
  11.732 +
  11.733 +	FLAC__METADATA_CHAIN_STATUS_NOT_A_FLAC_FILE,
  11.734 +	/**< The chain could not find the FLAC signature at the start of the file */
  11.735 +
  11.736 +	FLAC__METADATA_CHAIN_STATUS_NOT_WRITABLE,
  11.737 +	/**< The chain tried to write to a file that was not writable */
  11.738 +
  11.739 +	FLAC__METADATA_CHAIN_STATUS_BAD_METADATA,
  11.740 +	/**< The chain encountered input that does not conform to the FLAC metadata specification */
  11.741 +
  11.742 +	FLAC__METADATA_CHAIN_STATUS_READ_ERROR,
  11.743 +	/**< The chain encountered an error while reading the FLAC file */
  11.744 +
  11.745 +	FLAC__METADATA_CHAIN_STATUS_SEEK_ERROR,
  11.746 +	/**< The chain encountered an error while seeking in the FLAC file */
  11.747 +
  11.748 +	FLAC__METADATA_CHAIN_STATUS_WRITE_ERROR,
  11.749 +	/**< The chain encountered an error while writing the FLAC file */
  11.750 +
  11.751 +	FLAC__METADATA_CHAIN_STATUS_RENAME_ERROR,
  11.752 +	/**< The chain encountered an error renaming the FLAC file */
  11.753 +
  11.754 +	FLAC__METADATA_CHAIN_STATUS_UNLINK_ERROR,
  11.755 +	/**< The chain encountered an error removing the temporary file */
  11.756 +
  11.757 +	FLAC__METADATA_CHAIN_STATUS_MEMORY_ALLOCATION_ERROR,
  11.758 +	/**< Memory allocation failed */
  11.759 +
  11.760 +	FLAC__METADATA_CHAIN_STATUS_INTERNAL_ERROR,
  11.761 +	/**< The caller violated an assertion or an unexpected error occurred */
  11.762 +
  11.763 +	FLAC__METADATA_CHAIN_STATUS_INVALID_CALLBACKS,
  11.764 +	/**< One or more of the required callbacks was NULL */
  11.765 +
  11.766 +	FLAC__METADATA_CHAIN_STATUS_READ_WRITE_MISMATCH,
  11.767 +	/**< FLAC__metadata_chain_write() was called on a chain read by
  11.768 +	 *   FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(),
  11.769 +	 *   or 
  11.770 +	 *   FLAC__metadata_chain_write_with_callbacks()/FLAC__metadata_chain_write_with_callbacks_and_tempfile()
  11.771 +	 *   was called on a chain read by
  11.772 +	 *   FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg().
  11.773 +	 *   Matching read/write methods must always be used. */
  11.774 +
  11.775 +	FLAC__METADATA_CHAIN_STATUS_WRONG_WRITE_CALL
  11.776 +	/**< FLAC__metadata_chain_write_with_callbacks() was called when the
  11.777 +	 *   chain write requires a tempfile; use
  11.778 +	 *   FLAC__metadata_chain_write_with_callbacks_and_tempfile() instead.
  11.779 +	 *   Or, FLAC__metadata_chain_write_with_callbacks_and_tempfile() was
  11.780 +	 *   called when the chain write does not require a tempfile; use
  11.781 +	 *   FLAC__metadata_chain_write_with_callbacks() instead.
  11.782 +	 *   Always check FLAC__metadata_chain_check_if_tempfile_needed()
  11.783 +	 *   before writing via callbacks. */
  11.784 +
  11.785 +} FLAC__Metadata_ChainStatus;
  11.786 +
  11.787 +/** Maps a FLAC__Metadata_ChainStatus to a C string.
  11.788 + *
  11.789 + *  Using a FLAC__Metadata_ChainStatus as the index to this array
  11.790 + *  will give the string equivalent.  The contents should not be modified.
  11.791 + */
  11.792 +extern FLAC_API const char * const FLAC__Metadata_ChainStatusString[];
  11.793 +
  11.794 +/*********** FLAC__Metadata_Chain ***********/
  11.795 +
  11.796 +/** Create a new chain instance.
  11.797 + *
  11.798 + * \retval FLAC__Metadata_Chain*
  11.799 + *    \c NULL if there was an error allocating memory, else the new instance.
  11.800 + */
  11.801 +FLAC_API FLAC__Metadata_Chain *FLAC__metadata_chain_new(void);
  11.802 +
  11.803 +/** Free a chain instance.  Deletes the object pointed to by \a chain.
  11.804 + *
  11.805 + * \param chain  A pointer to an existing chain.
  11.806 + * \assert
  11.807 + *    \code chain != NULL \endcode
  11.808 + */
  11.809 +FLAC_API void FLAC__metadata_chain_delete(FLAC__Metadata_Chain *chain);
  11.810 +
  11.811 +/** Get the current status of the chain.  Call this after a function
  11.812 + *  returns \c false to get the reason for the error.  Also resets the
  11.813 + *  status to FLAC__METADATA_CHAIN_STATUS_OK.
  11.814 + *
  11.815 + * \param chain    A pointer to an existing chain.
  11.816 + * \assert
  11.817 + *    \code chain != NULL \endcode
  11.818 + * \retval FLAC__Metadata_ChainStatus
  11.819 + *    The current status of the chain.
  11.820 + */
  11.821 +FLAC_API FLAC__Metadata_ChainStatus FLAC__metadata_chain_status(FLAC__Metadata_Chain *chain);
  11.822 +
  11.823 +/** Read all metadata from a FLAC file into the chain.
  11.824 + *
  11.825 + * \param chain    A pointer to an existing chain.
  11.826 + * \param filename The path to the FLAC file to read.
  11.827 + * \assert
  11.828 + *    \code chain != NULL \endcode
  11.829 + *    \code filename != NULL \endcode
  11.830 + * \retval FLAC__bool
  11.831 + *    \c true if a valid list of metadata blocks was read from
  11.832 + *    \a filename, else \c false.  On failure, check the status with
  11.833 + *    FLAC__metadata_chain_status().
  11.834 + */
  11.835 +FLAC_API FLAC__bool FLAC__metadata_chain_read(FLAC__Metadata_Chain *chain, const char *filename);
  11.836 +
  11.837 +/** Read all metadata from an Ogg FLAC file into the chain.
  11.838 + *
  11.839 + * \note Ogg FLAC metadata data writing is not supported yet and
  11.840 + * FLAC__metadata_chain_write() will fail.
  11.841 + *
  11.842 + * \param chain    A pointer to an existing chain.
  11.843 + * \param filename The path to the Ogg FLAC file to read.
  11.844 + * \assert
  11.845 + *    \code chain != NULL \endcode
  11.846 + *    \code filename != NULL \endcode
  11.847 + * \retval FLAC__bool
  11.848 + *    \c true if a valid list of metadata blocks was read from
  11.849 + *    \a filename, else \c false.  On failure, check the status with
  11.850 + *    FLAC__metadata_chain_status().
  11.851 + */
  11.852 +FLAC_API FLAC__bool FLAC__metadata_chain_read_ogg(FLAC__Metadata_Chain *chain, const char *filename);
  11.853 +
  11.854 +/** Read all metadata from a FLAC stream into the chain via I/O callbacks.
  11.855 + *
  11.856 + *  The \a handle need only be open for reading, but must be seekable.
  11.857 + *  The equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb"
  11.858 + *  for Windows).
  11.859 + *
  11.860 + * \param chain    A pointer to an existing chain.
  11.861 + * \param handle   The I/O handle of the FLAC stream to read.  The
  11.862 + *                 handle will NOT be closed after the metadata is read;
  11.863 + *                 that is the duty of the caller.
  11.864 + * \param callbacks
  11.865 + *                 A set of callbacks to use for I/O.  The mandatory
  11.866 + *                 callbacks are \a read, \a seek, and \a tell.
  11.867 + * \assert
  11.868 + *    \code chain != NULL \endcode
  11.869 + * \retval FLAC__bool
  11.870 + *    \c true if a valid list of metadata blocks was read from
  11.871 + *    \a handle, else \c false.  On failure, check the status with
  11.872 + *    FLAC__metadata_chain_status().
  11.873 + */
  11.874 +FLAC_API FLAC__bool FLAC__metadata_chain_read_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
  11.875 +
  11.876 +/** Read all metadata from an Ogg FLAC stream into the chain via I/O callbacks.
  11.877 + *
  11.878 + *  The \a handle need only be open for reading, but must be seekable.
  11.879 + *  The equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb"
  11.880 + *  for Windows).
  11.881 + *
  11.882 + * \note Ogg FLAC metadata data writing is not supported yet and
  11.883 + * FLAC__metadata_chain_write() will fail.
  11.884 + *
  11.885 + * \param chain    A pointer to an existing chain.
  11.886 + * \param handle   The I/O handle of the Ogg FLAC stream to read.  The
  11.887 + *                 handle will NOT be closed after the metadata is read;
  11.888 + *                 that is the duty of the caller.
  11.889 + * \param callbacks
  11.890 + *                 A set of callbacks to use for I/O.  The mandatory
  11.891 + *                 callbacks are \a read, \a seek, and \a tell.
  11.892 + * \assert
  11.893 + *    \code chain != NULL \endcode
  11.894 + * \retval FLAC__bool
  11.895 + *    \c true if a valid list of metadata blocks was read from
  11.896 + *    \a handle, else \c false.  On failure, check the status with
  11.897 + *    FLAC__metadata_chain_status().
  11.898 + */
  11.899 +FLAC_API FLAC__bool FLAC__metadata_chain_read_ogg_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
  11.900 +
  11.901 +/** Checks if writing the given chain would require the use of a
  11.902 + *  temporary file, or if it could be written in place.
  11.903 + *
  11.904 + *  Under certain conditions, padding can be utilized so that writing
  11.905 + *  edited metadata back to the FLAC file does not require rewriting the
  11.906 + *  entire file.  If rewriting is required, then a temporary workfile is
  11.907 + *  required.  When writing metadata using callbacks, you must check
  11.908 + *  this function to know whether to call
  11.909 + *  FLAC__metadata_chain_write_with_callbacks() or
  11.910 + *  FLAC__metadata_chain_write_with_callbacks_and_tempfile().  When
  11.911 + *  writing with FLAC__metadata_chain_write(), the temporary file is
  11.912 + *  handled internally.
  11.913 + *
  11.914 + * \param chain    A pointer to an existing chain.
  11.915 + * \param use_padding
  11.916 + *                 Whether or not padding will be allowed to be used
  11.917 + *                 during the write.  The value of \a use_padding given
  11.918 + *                 here must match the value later passed to
  11.919 + *                 FLAC__metadata_chain_write_with_callbacks() or
  11.920 + *                 FLAC__metadata_chain_write_with_callbacks_with_tempfile().
  11.921 + * \assert
  11.922 + *    \code chain != NULL \endcode
  11.923 + * \retval FLAC__bool
  11.924 + *    \c true if writing the current chain would require a tempfile, or
  11.925 + *    \c false if metadata can be written in place.
  11.926 + */
  11.927 +FLAC_API FLAC__bool FLAC__metadata_chain_check_if_tempfile_needed(FLAC__Metadata_Chain *chain, FLAC__bool use_padding);
  11.928 +
  11.929 +/** Write all metadata out to the FLAC file.  This function tries to be as
  11.930 + *  efficient as possible; how the metadata is actually written is shown by
  11.931 + *  the following:
  11.932 + *
  11.933 + *  If the current chain is the same size as the existing metadata, the new
  11.934 + *  data is written in place.
  11.935 + *
  11.936 + *  If the current chain is longer than the existing metadata, and
  11.937 + *  \a use_padding is \c true, and the last block is a PADDING block of
  11.938 + *  sufficient length, the function will truncate the final padding block
  11.939 + *  so that the overall size of the metadata is the same as the existing
  11.940 + *  metadata, and then just rewrite the metadata.  Otherwise, if not all of
  11.941 + *  the above conditions are met, the entire FLAC file must be rewritten.
  11.942 + *  If you want to use padding this way it is a good idea to call
  11.943 + *  FLAC__metadata_chain_sort_padding() first so that you have the maximum
  11.944 + *  amount of padding to work with, unless you need to preserve ordering
  11.945 + *  of the PADDING blocks for some reason.
  11.946 + *
  11.947 + *  If the current chain is shorter than the existing metadata, and
  11.948 + *  \a use_padding is \c true, and the final block is a PADDING block, the padding
  11.949 + *  is extended to make the overall size the same as the existing data.  If
  11.950 + *  \a use_padding is \c true and the last block is not a PADDING block, a new
  11.951 + *  PADDING block is added to the end of the new data to make it the same
  11.952 + *  size as the existing data (if possible, see the note to
  11.953 + *  FLAC__metadata_simple_iterator_set_block() about the four byte limit)
  11.954 + *  and the new data is written in place.  If none of the above apply or
  11.955 + *  \a use_padding is \c false, the entire FLAC file is rewritten.
  11.956 + *
  11.957 + *  If \a preserve_file_stats is \c true, the owner and modification time will
  11.958 + *  be preserved even if the FLAC file is written.
  11.959 + *
  11.960 + *  For this write function to be used, the chain must have been read with
  11.961 + *  FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg(), not
  11.962 + *  FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks().
  11.963 + *
  11.964 + * \param chain               A pointer to an existing chain.
  11.965 + * \param use_padding         See above.
  11.966 + * \param preserve_file_stats See above.
  11.967 + * \assert
  11.968 + *    \code chain != NULL \endcode
  11.969 + * \retval FLAC__bool
  11.970 + *    \c true if the write succeeded, else \c false.  On failure,
  11.971 + *    check the status with FLAC__metadata_chain_status().
  11.972 + */
  11.973 +FLAC_API FLAC__bool FLAC__metadata_chain_write(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__bool preserve_file_stats);
  11.974 +
  11.975 +/** Write all metadata out to a FLAC stream via callbacks.
  11.976 + *
  11.977 + *  (See FLAC__metadata_chain_write() for the details on how padding is
  11.978 + *  used to write metadata in place if possible.)
  11.979 + *
  11.980 + *  The \a handle must be open for updating and be seekable.  The
  11.981 + *  equivalent minimum stdio fopen() file mode is \c "r+" (or \c "r+b"
  11.982 + *  for Windows).
  11.983 + *
  11.984 + *  For this write function to be used, the chain must have been read with
  11.985 + *  FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(),
  11.986 + *  not FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg().
  11.987 + *  Also, FLAC__metadata_chain_check_if_tempfile_needed() must have returned
  11.988 + *  \c false.
  11.989 + *
  11.990 + * \param chain        A pointer to an existing chain.
  11.991 + * \param use_padding  See FLAC__metadata_chain_write()
  11.992 + * \param handle       The I/O handle of the FLAC stream to write.  The
  11.993 + *                     handle will NOT be closed after the metadata is
  11.994 + *                     written; that is the duty of the caller.
  11.995 + * \param callbacks    A set of callbacks to use for I/O.  The mandatory
  11.996 + *                     callbacks are \a write and \a seek.
  11.997 + * \assert
  11.998 + *    \code chain != NULL \endcode
  11.999 + * \retval FLAC__bool
 11.1000 + *    \c true if the write succeeded, else \c false.  On failure,
 11.1001 + *    check the status with FLAC__metadata_chain_status().
 11.1002 + */
 11.1003 +FLAC_API FLAC__bool FLAC__metadata_chain_write_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
 11.1004 +
 11.1005 +/** Write all metadata out to a FLAC stream via callbacks.
 11.1006 + *
 11.1007 + *  (See FLAC__metadata_chain_write() for the details on how padding is
 11.1008 + *  used to write metadata in place if possible.)
 11.1009 + *
 11.1010 + *  This version of the write-with-callbacks function must be used when
 11.1011 + *  FLAC__metadata_chain_check_if_tempfile_needed() returns true.  In
 11.1012 + *  this function, you must supply an I/O handle corresponding to the
 11.1013 + *  FLAC file to edit, and a temporary handle to which the new FLAC
 11.1014 + *  file will be written.  It is the caller's job to move this temporary
 11.1015 + *  FLAC file on top of the original FLAC file to complete the metadata
 11.1016 + *  edit.
 11.1017 + *
 11.1018 + *  The \a handle must be open for reading and be seekable.  The
 11.1019 + *  equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb"
 11.1020 + *  for Windows).
 11.1021 + *
 11.1022 + *  The \a temp_handle must be open for writing.  The
 11.1023 + *  equivalent minimum stdio fopen() file mode is \c "w" (or \c "wb"
 11.1024 + *  for Windows).  It should be an empty stream, or at least positioned
 11.1025 + *  at the start-of-file (in which case it is the caller's duty to
 11.1026 + *  truncate it on return).
 11.1027 + *
 11.1028 + *  For this write function to be used, the chain must have been read with
 11.1029 + *  FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(),
 11.1030 + *  not FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg().
 11.1031 + *  Also, FLAC__metadata_chain_check_if_tempfile_needed() must have returned
 11.1032 + *  \c true.
 11.1033 + *
 11.1034 + * \param chain        A pointer to an existing chain.
 11.1035 + * \param use_padding  See FLAC__metadata_chain_write()
 11.1036 + * \param handle       The I/O handle of the original FLAC stream to read.
 11.1037 + *                     The handle will NOT be closed after the metadata is
 11.1038 + *                     written; that is the duty of the caller.
 11.1039 + * \param callbacks    A set of callbacks to use for I/O on \a handle.
 11.1040 + *                     The mandatory callbacks are \a read, \a seek, and
 11.1041 + *                     \a eof.
 11.1042 + * \param temp_handle  The I/O handle of the FLAC stream to write.  The
 11.1043 + *                     handle will NOT be closed after the metadata is
 11.1044 + *                     written; that is the duty of the caller.
 11.1045 + * \param temp_callbacks
 11.1046 + *                     A set of callbacks to use for I/O on temp_handle.
 11.1047 + *                     The only mandatory callback is \a write.
 11.1048 + * \assert
 11.1049 + *    \code chain != NULL \endcode
 11.1050 + * \retval FLAC__bool
 11.1051 + *    \c true if the write succeeded, else \c false.  On failure,
 11.1052 + *    check the status with FLAC__metadata_chain_status().
 11.1053 + */
 11.1054 +FLAC_API FLAC__bool FLAC__metadata_chain_write_with_callbacks_and_tempfile(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks, FLAC__IOHandle temp_handle, FLAC__IOCallbacks temp_callbacks);
 11.1055 +
 11.1056 +/** Merge adjacent PADDING blocks into a single block.
 11.1057 + *
 11.1058 + * \note This function does not write to the FLAC file, it only
 11.1059 + * modifies the chain.
 11.1060 + *
 11.1061 + * \warning Any iterator on the current chain will become invalid after this
 11.1062 + * call.  You should delete the iterator and get a new one.
 11.1063 + *
 11.1064 + * \param chain               A pointer to an existing chain.
 11.1065 + * \assert
 11.1066 + *    \code chain != NULL \endcode
 11.1067 + */
 11.1068 +FLAC_API void FLAC__metadata_chain_merge_padding(FLAC__Metadata_Chain *chain);
 11.1069 +
 11.1070 +/** This function will move all PADDING blocks to the end on the metadata,
 11.1071 + *  then merge them into a single block.
 11.1072 + *
 11.1073 + * \note This function does not write to the FLAC file, it only
 11.1074 + * modifies the chain.
 11.1075 + *
 11.1076 + * \warning Any iterator on the current chain will become invalid after this
 11.1077 + * call.  You should delete the iterator and get a new one.
 11.1078 + *
 11.1079 + * \param chain  A pointer to an existing chain.
 11.1080 + * \assert
 11.1081 + *    \code chain != NULL \endcode
 11.1082 + */
 11.1083 +FLAC_API void FLAC__metadata_chain_sort_padding(FLAC__Metadata_Chain *chain);
 11.1084 +
 11.1085 +
 11.1086 +/*********** FLAC__Metadata_Iterator ***********/
 11.1087 +
 11.1088 +/** Create a new iterator instance.
 11.1089 + *
 11.1090 + * \retval FLAC__Metadata_Iterator*
 11.1091 + *    \c NULL if there was an error allocating memory, else the new instance.
 11.1092 + */
 11.1093 +FLAC_API FLAC__Metadata_Iterator *FLAC__metadata_iterator_new(void);
 11.1094 +
 11.1095 +/** Free an iterator instance.  Deletes the object pointed to by \a iterator.
 11.1096 + *
 11.1097 + * \param iterator  A pointer to an existing iterator.
 11.1098 + * \assert
 11.1099 + *    \code iterator != NULL \endcode
 11.1100 + */
 11.1101 +FLAC_API void FLAC__metadata_iterator_delete(FLAC__Metadata_Iterator *iterator);
 11.1102 +
 11.1103 +/** Initialize the iterator to point to the first metadata block in the
 11.1104 + *  given chain.
 11.1105 + *
 11.1106 + * \param iterator  A pointer to an existing iterator.
 11.1107 + * \param chain     A pointer to an existing and initialized (read) chain.
 11.1108 + * \assert
 11.1109 + *    \code iterator != NULL \endcode
 11.1110 + *    \code chain != NULL \endcode
 11.1111 + */
 11.1112 +FLAC_API void FLAC__metadata_iterator_init(FLAC__Metadata_Iterator *iterator, FLAC__Metadata_Chain *chain);
 11.1113 +
 11.1114 +/** Moves the iterator forward one metadata block, returning \c false if
 11.1115 + *  already at the end.
 11.1116 + *
 11.1117 + * \param iterator  A pointer to an existing initialized iterator.
 11.1118 + * \assert
 11.1119 + *    \code iterator != NULL \endcode
 11.1120 + *    \a iterator has been successfully initialized with
 11.1121 + *    FLAC__metadata_iterator_init()
 11.1122 + * \retval FLAC__bool
 11.1123 + *    \c false if already at the last metadata block of the chain, else
 11.1124 + *    \c true.
 11.1125 + */
 11.1126 +FLAC_API FLAC__bool FLAC__metadata_iterator_next(FLAC__Metadata_Iterator *iterator);
 11.1127 +
 11.1128 +/** Moves the iterator backward one metadata block, returning \c false if
 11.1129 + *  already at the beginning.
 11.1130 + *
 11.1131 + * \param iterator  A pointer to an existing initialized iterator.
 11.1132 + * \assert
 11.1133 + *    \code iterator != NULL \endcode
 11.1134 + *    \a iterator has been successfully initialized with
 11.1135 + *    FLAC__metadata_iterator_init()
 11.1136 + * \retval FLAC__bool
 11.1137 + *    \c false if already at the first metadata block of the chain, else
 11.1138 + *    \c true.
 11.1139 + */
 11.1140 +FLAC_API FLAC__bool FLAC__metadata_iterator_prev(FLAC__Metadata_Iterator *iterator);
 11.1141 +
 11.1142 +/** Get the type of the metadata block at the current position.
 11.1143 + *
 11.1144 + * \param iterator  A pointer to an existing initialized iterator.
 11.1145 + * \assert
 11.1146 + *    \code iterator != NULL \endcode
 11.1147 + *    \a iterator has been successfully initialized with
 11.1148 + *    FLAC__metadata_iterator_init()
 11.1149 + * \retval FLAC__MetadataType
 11.1150 + *    The type of the metadata block at the current iterator position.
 11.1151 + */
 11.1152 +FLAC_API FLAC__MetadataType FLAC__metadata_iterator_get_block_type(const FLAC__Metadata_Iterator *iterator);
 11.1153 +
 11.1154 +/** Get the metadata block at the current position.  You can modify
 11.1155 + *  the block in place but must write the chain before the changes
 11.1156 + *  are reflected to the FLAC file.  You do not need to call
 11.1157 + *  FLAC__metadata_iterator_set_block() to reflect the changes;
 11.1158 + *  the pointer returned by FLAC__metadata_iterator_get_block()
 11.1159 + *  points directly into the chain.
 11.1160 + *
 11.1161 + * \warning
 11.1162 + * Do not call FLAC__metadata_object_delete() on the returned object;
 11.1163 + * to delete a block use FLAC__metadata_iterator_delete_block().
 11.1164 + *
 11.1165 + * \param iterator  A pointer to an existing initialized iterator.
 11.1166 + * \assert
 11.1167 + *    \code iterator != NULL \endcode
 11.1168 + *    \a iterator has been successfully initialized with
 11.1169 + *    FLAC__metadata_iterator_init()
 11.1170 + * \retval FLAC__StreamMetadata*
 11.1171 + *    The current metadata block.
 11.1172 + */
 11.1173 +FLAC_API FLAC__StreamMetadata *FLAC__metadata_iterator_get_block(FLAC__Metadata_Iterator *iterator);
 11.1174 +
 11.1175 +/** Set the metadata block at the current position, replacing the existing
 11.1176 + *  block.  The new block passed in becomes owned by the chain and it will be
 11.1177 + *  deleted when the chain is deleted.
 11.1178 + *
 11.1179 + * \param iterator  A pointer to an existing initialized iterator.
 11.1180 + * \param block     A pointer to a metadata block.
 11.1181 + * \assert
 11.1182 + *    \code iterator != NULL \endcode
 11.1183 + *    \a iterator has been successfully initialized with
 11.1184 + *    FLAC__metadata_iterator_init()
 11.1185 + *    \code block != NULL \endcode
 11.1186 + * \retval FLAC__bool
 11.1187 + *    \c false if the conditions in the above description are not met, or
 11.1188 + *    a memory allocation error occurs, otherwise \c true.
 11.1189 + */
 11.1190 +FLAC_API FLAC__bool FLAC__metadata_iterator_set_block(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
 11.1191 +
 11.1192 +/** Removes the current block from the chain.  If \a replace_with_padding is
 11.1193 + *  \c true, the block will instead be replaced with a padding block of equal
 11.1194 + *  size.  You can not delete the STREAMINFO block.  The iterator will be
 11.1195 + *  left pointing to the block before the one just "deleted", even if
 11.1196 + *  \a replace_with_padding is \c true.
 11.1197 + *
 11.1198 + * \param iterator              A pointer to an existing initialized iterator.
 11.1199 + * \param replace_with_padding  See above.
 11.1200 + * \assert
 11.1201 + *    \code iterator != NULL \endcode
 11.1202 + *    \a iterator has been successfully initialized with
 11.1203 + *    FLAC__metadata_iterator_init()
 11.1204 + * \retval FLAC__bool
 11.1205 + *    \c false if the conditions in the above description are not met,
 11.1206 + *    otherwise \c true.
 11.1207 + */
 11.1208 +FLAC_API FLAC__bool FLAC__metadata_iterator_delete_block(FLAC__Metadata_Iterator *iterator, FLAC__bool replace_with_padding);
 11.1209 +
 11.1210 +/** Insert a new block before the current block.  You cannot insert a block
 11.1211 + *  before the first STREAMINFO block.  You cannot insert a STREAMINFO block
 11.1212 + *  as there can be only one, the one that already exists at the head when you
 11.1213 + *  read in a chain.  The chain takes ownership of the new block and it will be
 11.1214 + *  deleted when the chain is deleted.  The iterator will be left pointing to
 11.1215 + *  the new block.
 11.1216 + *
 11.1217 + * \param iterator  A pointer to an existing initialized iterator.
 11.1218 + * \param block     A pointer to a metadata block to insert.
 11.1219 + * \assert
 11.1220 + *    \code iterator != NULL \endcode
 11.1221 + *    \a iterator has been successfully initialized with
 11.1222 + *    FLAC__metadata_iterator_init()
 11.1223 + * \retval FLAC__bool
 11.1224 + *    \c false if the conditions in the above description are not met, or
 11.1225 + *    a memory allocation error occurs, otherwise \c true.
 11.1226 + */
 11.1227 +FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_before(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
 11.1228 +
 11.1229 +/** Insert a new block after the current block.  You cannot insert a STREAMINFO
 11.1230 + *  block as there can be only one, the one that already exists at the head when
 11.1231 + *  you read in a chain.  The chain takes ownership of the new block and it will
 11.1232 + *  be deleted when the chain is deleted.  The iterator will be left pointing to
 11.1233 + *  the new block.
 11.1234 + *
 11.1235 + * \param iterator  A pointer to an existing initialized iterator.
 11.1236 + * \param block     A pointer to a metadata block to insert.
 11.1237 + * \assert
 11.1238 + *    \code iterator != NULL \endcode
 11.1239 + *    \a iterator has been successfully initialized with
 11.1240 + *    FLAC__metadata_iterator_init()
 11.1241 + * \retval FLAC__bool
 11.1242 + *    \c false if the conditions in the above description are not met, or
 11.1243 + *    a memory allocation error occurs, otherwise \c true.
 11.1244 + */
 11.1245 +FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_after(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
 11.1246 +
 11.1247 +/* \} */
 11.1248 +
 11.1249 +
 11.1250 +/** \defgroup flac_metadata_object FLAC/metadata.h: metadata object methods
 11.1251 + *  \ingroup flac_metadata
 11.1252 + *
 11.1253 + * \brief
 11.1254 + * This module contains methods for manipulating FLAC metadata objects.
 11.1255 + *
 11.1256 + * Since many are variable length we have to be careful about the memory
 11.1257 + * management.  We decree that all pointers to data in the object are
 11.1258 + * owned by the object and memory-managed by the object.
 11.1259 + *
 11.1260 + * Use the FLAC__metadata_object_new() and FLAC__metadata_object_delete()
 11.1261 + * functions to create all instances.  When using the
 11.1262 + * FLAC__metadata_object_set_*() functions to set pointers to data, set
 11.1263 + * \a copy to \c true to have the function make it's own copy of the data, or
 11.1264 + * to \c false to give the object ownership of your data.  In the latter case
 11.1265 + * your pointer must be freeable by free() and will be free()d when the object
 11.1266 + * is FLAC__metadata_object_delete()d.  It is legal to pass a null pointer as
 11.1267 + * the data pointer to a FLAC__metadata_object_set_*() function as long as
 11.1268 + * the length argument is 0 and the \a copy argument is \c false.
 11.1269 + *
 11.1270 + * The FLAC__metadata_object_new() and FLAC__metadata_object_clone() function
 11.1271 + * will return \c NULL in the case of a memory allocation error, otherwise a new
 11.1272 + * object.  The FLAC__metadata_object_set_*() functions return \c false in the
 11.1273 + * case of a memory allocation error.
 11.1274 + *
 11.1275 + * We don't have the convenience of C++ here, so note that the library relies
 11.1276 + * on you to keep the types straight.  In other words, if you pass, for
 11.1277 + * example, a FLAC__StreamMetadata* that represents a STREAMINFO block to
 11.1278 + * FLAC__metadata_object_application_set_data(), you will get an assertion
 11.1279 + * failure.
 11.1280 + *
 11.1281 + * For convenience the FLAC__metadata_object_vorbiscomment_*() functions
 11.1282 + * maintain a trailing NUL on each Vorbis comment entry.  This is not counted
 11.1283 + * toward the length or stored in the stream, but it can make working with plain
 11.1284 + * comments (those that don't contain embedded-NULs in the value) easier.
 11.1285 + * Entries passed into these functions have trailing NULs added if missing, and
 11.1286 + * returned entries are guaranteed to have a trailing NUL.
 11.1287 + *
 11.1288 + * The FLAC__metadata_object_vorbiscomment_*() functions that take a Vorbis
 11.1289 + * comment entry/name/value will first validate that it complies with the Vorbis
 11.1290 + * comment specification and return false if it does not.
 11.1291 + *
 11.1292 + * There is no need to recalculate the length field on metadata blocks you
 11.1293 + * have modified.  They will be calculated automatically before they  are
 11.1294 + * written back to a file.
 11.1295 + *
 11.1296 + * \{
 11.1297 + */
 11.1298 +
 11.1299 +
 11.1300 +/** Create a new metadata object instance of the given type.
 11.1301 + *
 11.1302 + *  The object will be "empty"; i.e. values and data pointers will be \c 0,
 11.1303 + *  with the exception of FLAC__METADATA_TYPE_VORBIS_COMMENT, which will have
 11.1304 + *  the vendor string set (but zero comments).
 11.1305 + *
 11.1306 + *  Do not pass in a value greater than or equal to
 11.1307 + *  \a FLAC__METADATA_TYPE_UNDEFINED unless you really know what you're
 11.1308 + *  doing.
 11.1309 + *
 11.1310 + * \param type  Type of object to create
 11.1311 + * \retval FLAC__StreamMetadata*
 11.1312 + *    \c NULL if there was an error allocating memory or the type code is
 11.1313 + *    greater than FLAC__MAX_METADATA_TYPE_CODE, else the new instance.
 11.1314 + */
 11.1315 +FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_new(FLAC__MetadataType type);
 11.1316 +
 11.1317 +/** Create a copy of an existing metadata object.
 11.1318 + *
 11.1319 + *  The copy is a "deep" copy, i.e. dynamically allocated data within the
 11.1320 + *  object is also copied.  The caller takes ownership of the new block and
 11.1321 + *  is responsible for freeing it with FLAC__metadata_object_delete().
 11.1322 + *
 11.1323 + * \param object  Pointer to object to copy.
 11.1324 + * \assert
 11.1325 + *    \code object != NULL \endcode
 11.1326 + * \retval FLAC__StreamMetadata*
 11.1327 + *    \c NULL if there was an error allocating memory, else the new instance.
 11.1328 + */
 11.1329 +FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_clone(const FLAC__StreamMetadata *object);
 11.1330 +
 11.1331 +/** Free a metadata object.  Deletes the object pointed to by \a object.
 11.1332 + *
 11.1333 + *  The delete is a "deep" delete, i.e. dynamically allocated data within the
 11.1334 + *  object is also deleted.
 11.1335 + *
 11.1336 + * \param object  A pointer to an existing object.
 11.1337 + * \assert
 11.1338 + *    \code object != NULL \endcode
 11.1339 + */
 11.1340 +FLAC_API void FLAC__metadata_object_delete(FLAC__StreamMetadata *object);
 11.1341 +
 11.1342 +/** Compares two metadata objects.
 11.1343 + *
 11.1344 + *  The compare is "deep", i.e. dynamically allocated data within the
 11.1345 + *  object is also compared.
 11.1346 + *
 11.1347 + * \param block1  A pointer to an existing object.
 11.1348 + * \param block2  A pointer to an existing object.
 11.1349 + * \assert
 11.1350 + *    \code block1 != NULL \endcode
 11.1351 + *    \code block2 != NULL \endcode
 11.1352 + * \retval FLAC__bool
 11.1353 + *    \c true if objects are identical, else \c false.
 11.1354 + */
 11.1355 +FLAC_API FLAC__bool FLAC__metadata_object_is_equal(const FLAC__StreamMetadata *block1, const FLAC__StreamMetadata *block2);
 11.1356 +
 11.1357 +/** Sets the application data of an APPLICATION block.
 11.1358 + *
 11.1359 + *  If \a copy is \c true, a copy of the data is stored; otherwise, the object
 11.1360 + *  takes ownership of the pointer.  The existing data will be freed if this
 11.1361 + *  function is successful, otherwise the original data will remain if \a copy
 11.1362 + *  is \c true and malloc() fails.
 11.1363 + *
 11.1364 + * \note It is safe to pass a const pointer to \a data if \a copy is \c true.
 11.1365 + *
 11.1366 + * \param object  A pointer to an existing APPLICATION object.
 11.1367 + * \param data    A pointer to the data to set.
 11.1368 + * \param length  The length of \a data in bytes.
 11.1369 + * \param copy    See above.
 11.1370 + * \assert
 11.1371 + *    \code object != NULL \endcode
 11.1372 + *    \code object->type == FLAC__METADATA_TYPE_APPLICATION \endcode
 11.1373 + *    \code (data != NULL && length > 0) ||
 11.1374 + * (data == NULL && length == 0 && copy == false) \endcode
 11.1375 + * \retval FLAC__bool
 11.1376 + *    \c false if \a copy is \c true and malloc() fails, else \c true.
 11.1377 + */
 11.1378 +FLAC_API FLAC__bool FLAC__metadata_object_application_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, unsigned length, FLAC__bool copy);
 11.1379 +
 11.1380 +/** Resize the seekpoint array.
 11.1381 + *
 11.1382 + *  If the size shrinks, elements will truncated; if it grows, new placeholder
 11.1383 + *  points will be added to the end.
 11.1384 + *
 11.1385 + * \param object          A pointer to an existing SEEKTABLE object.
 11.1386 + * \param new_num_points  The desired length of the array; may be \c 0.
 11.1387 + * \assert
 11.1388 + *    \code object != NULL \endcode
 11.1389 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 11.1390 + *    \code (object->data.seek_table.points == NULL && object->data.seek_table.num_points == 0) ||
 11.1391 + * (object->data.seek_table.points != NULL && object->data.seek_table.num_points > 0) \endcode
 11.1392 + * \retval FLAC__bool
 11.1393 + *    \c false if memory allocation error, else \c true.
 11.1394 + */
 11.1395 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_resize_points(FLAC__StreamMetadata *object, unsigned new_num_points);
 11.1396 +
 11.1397 +/** Set a seekpoint in a seektable.
 11.1398 + *
 11.1399 + * \param object     A pointer to an existing SEEKTABLE object.
 11.1400 + * \param point_num  Index into seekpoint array to set.
 11.1401 + * \param point      The point to set.
 11.1402 + * \assert
 11.1403 + *    \code object != NULL \endcode
 11.1404 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 11.1405 + *    \code object->data.seek_table.num_points > point_num \endcode
 11.1406 + */
 11.1407 +FLAC_API void FLAC__metadata_object_seektable_set_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point);
 11.1408 +
 11.1409 +/** Insert a seekpoint into a seektable.
 11.1410 + *
 11.1411 + * \param object     A pointer to an existing SEEKTABLE object.
 11.1412 + * \param point_num  Index into seekpoint array to set.
 11.1413 + * \param point      The point to set.
 11.1414 + * \assert
 11.1415 + *    \code object != NULL \endcode
 11.1416 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 11.1417 + *    \code object->data.seek_table.num_points >= point_num \endcode
 11.1418 + * \retval FLAC__bool
 11.1419 + *    \c false if memory allocation error, else \c true.
 11.1420 + */
 11.1421 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_insert_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point);
 11.1422 +
 11.1423 +/** Delete a seekpoint from a seektable.
 11.1424 + *
 11.1425 + * \param object     A pointer to an existing SEEKTABLE object.
 11.1426 + * \param point_num  Index into seekpoint array to set.
 11.1427 + * \assert
 11.1428 + *    \code object != NULL \endcode
 11.1429 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 11.1430 + *    \code object->data.seek_table.num_points > point_num \endcode
 11.1431 + * \retval FLAC__bool
 11.1432 + *    \c false if memory allocation error, else \c true.
 11.1433 + */
 11.1434 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_delete_point(FLAC__StreamMetadata *object, unsigned point_num);
 11.1435 +
 11.1436 +/** Check a seektable to see if it conforms to the FLAC specification.
 11.1437 + *  See the format specification for limits on the contents of the
 11.1438 + *  seektable.
 11.1439 + *
 11.1440 + * \param object  A pointer to an existing SEEKTABLE object.
 11.1441 + * \assert
 11.1442 + *    \code object != NULL \endcode
 11.1443 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 11.1444 + * \retval FLAC__bool
 11.1445 + *    \c false if seek table is illegal, else \c true.
 11.1446 + */
 11.1447 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_is_legal(const FLAC__StreamMetadata *object);
 11.1448 +
 11.1449 +/** Append a number of placeholder points to the end of a seek table.
 11.1450 + *
 11.1451 + * \note
 11.1452 + * As with the other ..._seektable_template_... functions, you should
 11.1453 + * call FLAC__metadata_object_seektable_template_sort() when finished
 11.1454 + * to make the seek table legal.
 11.1455 + *
 11.1456 + * \param object  A pointer to an existing SEEKTABLE object.
 11.1457 + * \param num     The number of placeholder points to append.
 11.1458 + * \assert
 11.1459 + *    \code object != NULL \endcode
 11.1460 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 11.1461 + * \retval FLAC__bool
 11.1462 + *    \c false if memory allocation fails, else \c true.
 11.1463 + */
 11.1464 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_placeholders(FLAC__StreamMetadata *object, unsigned num);
 11.1465 +
 11.1466 +/** Append a specific seek point template to the end of a seek table.
 11.1467 + *
 11.1468 + * \note
 11.1469 + * As with the other ..._seektable_template_... functions, you should
 11.1470 + * call FLAC__metadata_object_seektable_template_sort() when finished
 11.1471 + * to make the seek table legal.
 11.1472 + *
 11.1473 + * \param object  A pointer to an existing SEEKTABLE object.
 11.1474 + * \param sample_number  The sample number of the seek point template.
 11.1475 + * \assert
 11.1476 + *    \code object != NULL \endcode
 11.1477 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 11.1478 + * \retval FLAC__bool
 11.1479 + *    \c false if memory allocation fails, else \c true.
 11.1480 + */
 11.1481 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_point(FLAC__StreamMetadata *object, FLAC__uint64 sample_number);
 11.1482 +
 11.1483 +/** Append specific seek point templates to the end of a seek table.
 11.1484 + *
 11.1485 + * \note
 11.1486 + * As with the other ..._seektable_template_... functions, you should
 11.1487 + * call FLAC__metadata_object_seektable_template_sort() when finished
 11.1488 + * to make the seek table legal.
 11.1489 + *
 11.1490 + * \param object  A pointer to an existing SEEKTABLE object.
 11.1491 + * \param sample_numbers  An array of sample numbers for the seek points.
 11.1492 + * \param num     The number of seek point templates to append.
 11.1493 + * \assert
 11.1494 + *    \code object != NULL \endcode
 11.1495 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 11.1496 + * \retval FLAC__bool
 11.1497 + *    \c false if memory allocation fails, else \c true.
 11.1498 + */
 11.1499 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_points(FLAC__StreamMetadata *object, FLAC__uint64 sample_numbers[], unsigned num);
 11.1500 +
 11.1501 +/** Append a set of evenly-spaced seek point templates to the end of a
 11.1502 + *  seek table.
 11.1503 + *
 11.1504 + * \note
 11.1505 + * As with the other ..._seektable_template_... functions, you should
 11.1506 + * call FLAC__metadata_object_seektable_template_sort() when finished
 11.1507 + * to make the seek table legal.
 11.1508 + *
 11.1509 + * \param object  A pointer to an existing SEEKTABLE object.
 11.1510 + * \param num     The number of placeholder points to append.
 11.1511 + * \param total_samples  The total number of samples to be encoded;
 11.1512 + *                       the seekpoints will be spaced approximately
 11.1513 + *                       \a total_samples / \a num samples apart.
 11.1514 + * \assert
 11.1515 + *    \code object != NULL \endcode
 11.1516 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 11.1517 + *    \code total_samples > 0 \endcode
 11.1518 + * \retval FLAC__bool
 11.1519 + *    \c false if memory allocation fails, else \c true.
 11.1520 + */
 11.1521 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points(FLAC__StreamMetadata *object, unsigned num, FLAC__uint64 total_samples);
 11.1522 +
 11.1523 +/** Append a set of evenly-spaced seek point templates to the end of a
 11.1524 + *  seek table.
 11.1525 + *
 11.1526 + * \note
 11.1527 + * As with the other ..._seektable_template_... functions, you should
 11.1528 + * call FLAC__metadata_object_seektable_template_sort() when finished
 11.1529 + * to make the seek table legal.
 11.1530 + *
 11.1531 + * \param object  A pointer to an existing SEEKTABLE object.
 11.1532 + * \param samples The number of samples apart to space the placeholder
 11.1533 + *                points.  The first point will be at sample \c 0, the
 11.1534 + *                second at sample \a samples, then 2*\a samples, and
 11.1535 + *                so on.  As long as \a samples and \a total_samples
 11.1536 + *                are greater than \c 0, there will always be at least
 11.1537 + *                one seekpoint at sample \c 0.
 11.1538 + * \param total_samples  The total number of samples to be encoded;
 11.1539 + *                       the seekpoints will be spaced
 11.1540 + *                       \a samples samples apart.
 11.1541 + * \assert
 11.1542 + *    \code object != NULL \endcode
 11.1543 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 11.1544 + *    \code samples > 0 \endcode
 11.1545 + *    \code total_samples > 0 \endcode
 11.1546 + * \retval FLAC__bool
 11.1547 + *    \c false if memory allocation fails, else \c true.
 11.1548 + */
 11.1549 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points_by_samples(FLAC__StreamMetadata *object, unsigned samples, FLAC__uint64 total_samples);
 11.1550 +
 11.1551 +/** Sort a seek table's seek points according to the format specification,
 11.1552 + *  removing duplicates.
 11.1553 + *
 11.1554 + * \param object   A pointer to a seek table to be sorted.
 11.1555 + * \param compact  If \c false, behaves like FLAC__format_seektable_sort().
 11.1556 + *                 If \c true, duplicates are deleted and the seek table is
 11.1557 + *                 shrunk appropriately; the number of placeholder points
 11.1558 + *                 present in the seek table will be the same after the call
 11.1559 + *                 as before.
 11.1560 + * \assert
 11.1561 + *    \code object != NULL \endcode
 11.1562 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 11.1563 + * \retval FLAC__bool
 11.1564 + *    \c false if realloc() fails, else \c true.
 11.1565 + */
 11.1566 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_sort(FLAC__StreamMetadata *object, FLAC__bool compact);
 11.1567 +
 11.1568 +/** Sets the vendor string in a VORBIS_COMMENT block.
 11.1569 + *
 11.1570 + *  For convenience, a trailing NUL is added to the entry if it doesn't have
 11.1571 + *  one already.
 11.1572 + *
 11.1573 + *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
 11.1574 + *  takes ownership of the \c entry.entry pointer.
 11.1575 + *
 11.1576 + *  \note If this function returns \c false, the caller still owns the
 11.1577 + *  pointer.
 11.1578 + *
 11.1579 + * \param object  A pointer to an existing VORBIS_COMMENT object.
 11.1580 + * \param entry   The entry to set the vendor string to.
 11.1581 + * \param copy    See above.
 11.1582 + * \assert
 11.1583 + *    \code object != NULL \endcode
 11.1584 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
 11.1585 + *    \code (entry.entry != NULL && entry.length > 0) ||
 11.1586 + * (entry.entry == NULL && entry.length == 0) \endcode
 11.1587 + * \retval FLAC__bool
 11.1588 + *    \c false if memory allocation fails or \a entry does not comply with the
 11.1589 + *    Vorbis comment specification, else \c true.
 11.1590 + */
 11.1591 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_vendor_string(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
 11.1592 +
 11.1593 +/** Resize the comment array.
 11.1594 + *
 11.1595 + *  If the size shrinks, elements will truncated; if it grows, new empty
 11.1596 + *  fields will be added to the end.
 11.1597 + *
 11.1598 + * \param object            A pointer to an existing VORBIS_COMMENT object.
 11.1599 + * \param new_num_comments  The desired length of the array; may be \c 0.
 11.1600 + * \assert
 11.1601 + *    \code object != NULL \endcode
 11.1602 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
 11.1603 + *    \code (object->data.vorbis_comment.comments == NULL && object->data.vorbis_comment.num_comments == 0) ||
 11.1604 + * (object->data.vorbis_comment.comments != NULL && object->data.vorbis_comment.num_comments > 0) \endcode
 11.1605 + * \retval FLAC__bool
 11.1606 + *    \c false if memory allocation fails, else \c true.
 11.1607 + */
 11.1608 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_resize_comments(FLAC__StreamMetadata *object, unsigned new_num_comments);
 11.1609 +
 11.1610 +/** Sets a comment in a VORBIS_COMMENT block.
 11.1611 + *
 11.1612 + *  For convenience, a trailing NUL is added to the entry if it doesn't have
 11.1613 + *  one already.
 11.1614 + *
 11.1615 + *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
 11.1616 + *  takes ownership of the \c entry.entry pointer.
 11.1617 + *
 11.1618 + *  \note If this function returns \c false, the caller still owns the
 11.1619 + *  pointer.
 11.1620 + *
 11.1621 + * \param object       A pointer to an existing VORBIS_COMMENT object.
 11.1622 + * \param comment_num  Index into comment array to set.
 11.1623 + * \param entry        The entry to set the comment to.
 11.1624 + * \param copy         See above.
 11.1625 + * \assert
 11.1626 + *    \code object != NULL \endcode
 11.1627 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
 11.1628 + *    \code comment_num < object->data.vorbis_comment.num_comments \endcode
 11.1629 + *    \code (entry.entry != NULL && entry.length > 0) ||
 11.1630 + * (entry.entry == NULL && entry.length == 0) \endcode
 11.1631 + * \retval FLAC__bool
 11.1632 + *    \c false if memory allocation fails or \a entry does not comply with the
 11.1633 + *    Vorbis comment specification, else \c true.
 11.1634 + */
 11.1635 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
 11.1636 +
 11.1637 +/** Insert a comment in a VORBIS_COMMENT block at the given index.
 11.1638 + *
 11.1639 + *  For convenience, a trailing NUL is added to the entry if it doesn't have
 11.1640 + *  one already.
 11.1641 + *
 11.1642 + *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
 11.1643 + *  takes ownership of the \c entry.entry pointer.
 11.1644 + *
 11.1645 + *  \note If this function returns \c false, the caller still owns the
 11.1646 + *  pointer.
 11.1647 + *
 11.1648 + * \param object       A pointer to an existing VORBIS_COMMENT object.
 11.1649 + * \param comment_num  The index at which to insert the comment.  The comments
 11.1650 + *                     at and after \a comment_num move right one position.
 11.1651 + *                     To append a comment to the end, set \a comment_num to
 11.1652 + *                     \c object->data.vorbis_comment.num_comments .
 11.1653 + * \param entry        The comment to insert.
 11.1654 + * \param copy         See above.
 11.1655 + * \assert
 11.1656 + *    \code object != NULL \endcode
 11.1657 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
 11.1658 + *    \code object->data.vorbis_comment.num_comments >= comment_num \endcode
 11.1659 + *    \code (entry.entry != NULL && entry.length > 0) ||
 11.1660 + * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode
 11.1661 + * \retval FLAC__bool
 11.1662 + *    \c false if memory allocation fails or \a entry does not comply with the
 11.1663 + *    Vorbis comment specification, else \c true.
 11.1664 + */
 11.1665 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_insert_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
 11.1666 +
 11.1667 +/** Appends a comment to a VORBIS_COMMENT block.
 11.1668 + *
 11.1669 + *  For convenience, a trailing NUL is added to the entry if it doesn't have
 11.1670 + *  one already.
 11.1671 + *
 11.1672 + *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
 11.1673 + *  takes ownership of the \c entry.entry pointer.
 11.1674 + *
 11.1675 + *  \note If this function returns \c false, the caller still owns the
 11.1676 + *  pointer.
 11.1677 + *
 11.1678 + * \param object       A pointer to an existing VORBIS_COMMENT object.
 11.1679 + * \param entry        The comment to insert.
 11.1680 + * \param copy         See above.
 11.1681 + * \assert
 11.1682 + *    \code object != NULL \endcode
 11.1683 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
 11.1684 + *    \code (entry.entry != NULL && entry.length > 0) ||
 11.1685 + * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode
 11.1686 + * \retval FLAC__bool
 11.1687 + *    \c false if memory allocation fails or \a entry does not comply with the
 11.1688 + *    Vorbis comment specification, else \c true.
 11.1689 + */
 11.1690 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_append_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
 11.1691 +
 11.1692 +/** Replaces comments in a VORBIS_COMMENT block with a new one.
 11.1693 + *
 11.1694 + *  For convenience, a trailing NUL is added to the entry if it doesn't have
 11.1695 + *  one already.
 11.1696 + *
 11.1697 + *  Depending on the the value of \a all, either all or just the first comment
 11.1698 + *  whose field name(s) match the given entry's name will be replaced by the
 11.1699 + *  given entry.  If no comments match, \a entry will simply be appended.
 11.1700 + *
 11.1701 + *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
 11.1702 + *  takes ownership of the \c entry.entry pointer.
 11.1703 + *
 11.1704 + *  \note If this function returns \c false, the caller still owns the
 11.1705 + *  pointer.
 11.1706 + *
 11.1707 + * \param object       A pointer to an existing VORBIS_COMMENT object.
 11.1708 + * \param entry        The comment to insert.
 11.1709 + * \param all          If \c true, all comments whose field name matches
 11.1710 + *                     \a entry's field name will be removed, and \a entry will
 11.1711 + *                     be inserted at the position of the first matching
 11.1712 + *                     comment.  If \c false, only the first comment whose
 11.1713 + *                     field name matches \a entry's field name will be
 11.1714 + *                     replaced with \a entry.
 11.1715 + * \param copy         See above.
 11.1716 + * \assert
 11.1717 + *    \code object != NULL \endcode
 11.1718 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
 11.1719 + *    \code (entry.entry != NULL && entry.length > 0) ||
 11.1720 + * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode
 11.1721 + * \retval FLAC__bool
 11.1722 + *    \c false if memory allocation fails or \a entry does not comply with the
 11.1723 + *    Vorbis comment specification, else \c true.
 11.1724 + */
 11.1725 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_replace_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool all, FLAC__bool copy);
 11.1726 +
 11.1727 +/** Delete a comment in a VORBIS_COMMENT block at the given index.
 11.1728 + *
 11.1729 + * \param object       A pointer to an existing VORBIS_COMMENT object.
 11.1730 + * \param comment_num  The index of the comment to delete.
 11.1731 + * \assert
 11.1732 + *    \code object != NULL \endcode
 11.1733 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
 11.1734 + *    \code object->data.vorbis_comment.num_comments > comment_num \endcode
 11.1735 + * \retval FLAC__bool
 11.1736 + *    \c false if realloc() fails, else \c true.
 11.1737 + */
 11.1738 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_delete_comment(FLAC__StreamMetadata *object, unsigned comment_num);
 11.1739 +
 11.1740 +/** Creates a Vorbis comment entry from NUL-terminated name and value strings.
 11.1741 + *
 11.1742 + *  On return, the filled-in \a entry->entry pointer will point to malloc()ed
 11.1743 + *  memory and shall be owned by the caller.  For convenience the entry will
 11.1744 + *  have a terminating NUL.
 11.1745 + *
 11.1746 + * \param entry              A pointer to a Vorbis comment entry.  The entry's
 11.1747 + *                           \c entry pointer should not point to allocated
 11.1748 + *                           memory as it will be overwritten.
 11.1749 + * \param field_name         The field name in ASCII, \c NUL terminated.
 11.1750 + * \param field_value        The field value in UTF-8, \c NUL terminated.
 11.1751 + * \assert
 11.1752 + *    \code entry != NULL \endcode
 11.1753 + *    \code field_name != NULL \endcode
 11.1754 + *    \code field_value != NULL \endcode
 11.1755 + * \retval FLAC__bool
 11.1756 + *    \c false if malloc() fails, or if \a field_name or \a field_value does
 11.1757 + *    not comply with the Vorbis comment specification, else \c true.
 11.1758 + */
 11.1759 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_from_name_value_pair(FLAC__StreamMetadata_VorbisComment_Entry *entry, const char *field_name, const char *field_value);
 11.1760 +
 11.1761 +/** Splits a Vorbis comment entry into NUL-terminated name and value strings.
 11.1762 + *
 11.1763 + *  The returned pointers to name and value will be allocated by malloc()
 11.1764 + *  and shall be owned by the caller.
 11.1765 + *
 11.1766 + * \param entry              An existing Vorbis comment entry.
 11.1767 + * \param field_name         The address of where the returned pointer to the
 11.1768 + *                           field name will be stored.
 11.1769 + * \param field_value        The address of where the returned pointer to the
 11.1770 + *                           field value will be stored.
 11.1771 + * \assert
 11.1772 + *    \code (entry.entry != NULL && entry.length > 0) \endcode
 11.1773 + *    \code memchr(entry.entry, '=', entry.length) != NULL \endcode
 11.1774 + *    \code field_name != NULL \endcode
 11.1775 + *    \code field_value != NULL \endcode
 11.1776 + * \retval FLAC__bool
 11.1777 + *    \c false if memory allocation fails or \a entry does not comply with the
 11.1778 + *    Vorbis comment specification, else \c true.
 11.1779 + */
 11.1780 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_to_name_value_pair(const FLAC__StreamMetadata_VorbisComment_Entry entry, char **field_name, char **field_value);
 11.1781 +
 11.1782 +/** Check if the given Vorbis comment entry's field name matches the given
 11.1783 + *  field name.
 11.1784 + *
 11.1785 + * \param entry              An existing Vorbis comment entry.
 11.1786 + * \param field_name         The field name to check.
 11.1787 + * \param field_name_length  The length of \a field_name, not including the
 11.1788 + *                           terminating \c NUL.
 11.1789 + * \assert
 11.1790 + *    \code (entry.entry != NULL && entry.length > 0) \endcode
 11.1791 + * \retval FLAC__bool
 11.1792 + *    \c true if the field names match, else \c false
 11.1793 + */
 11.1794 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_matches(const FLAC__StreamMetadata_VorbisComment_Entry entry, const char *field_name, unsigned field_name_length);
 11.1795 +
 11.1796 +/** Find a Vorbis comment with the given field name.
 11.1797 + *
 11.1798 + *  The search begins at entry number \a offset; use an offset of 0 to
 11.1799 + *  search from the beginning of the comment array.
 11.1800 + *
 11.1801 + * \param object      A pointer to an existing VORBIS_COMMENT object.
 11.1802 + * \param offset      The offset into the comment array from where to start
 11.1803 + *                    the search.
 11.1804 + * \param field_name  The field name of the comment to find.
 11.1805 + * \assert
 11.1806 + *    \code object != NULL \endcode
 11.1807 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
 11.1808 + *    \code field_name != NULL \endcode
 11.1809 + * \retval int
 11.1810 + *    The offset in the comment array of the first comment whose field
 11.1811 + *    name matches \a field_name, or \c -1 if no match was found.
 11.1812 + */
 11.1813 +FLAC_API int FLAC__metadata_object_vorbiscomment_find_entry_from(const FLAC__StreamMetadata *object, unsigned offset, const char *field_name);
 11.1814 +
 11.1815 +/** Remove first Vorbis comment matching the given field name.
 11.1816 + *
 11.1817 + * \param object      A pointer to an existing VORBIS_COMMENT object.
 11.1818 + * \param field_name  The field name of comment to delete.
 11.1819 + * \assert
 11.1820 + *    \code object != NULL \endcode
 11.1821 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
 11.1822 + * \retval int
 11.1823 + *    \c -1 for memory allocation error, \c 0 for no matching entries,
 11.1824 + *    \c 1 for one matching entry deleted.
 11.1825 + */
 11.1826 +FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entry_matching(FLAC__StreamMetadata *object, const char *field_name);
 11.1827 +
 11.1828 +/** Remove all Vorbis comments matching the given field name.
 11.1829 + *
 11.1830 + * \param object      A pointer to an existing VORBIS_COMMENT object.
 11.1831 + * \param field_name  The field name of comments to delete.
 11.1832 + * \assert
 11.1833 + *    \code object != NULL \endcode
 11.1834 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
 11.1835 + * \retval int
 11.1836 + *    \c -1 for memory allocation error, \c 0 for no matching entries,
 11.1837 + *    else the number of matching entries deleted.
 11.1838 + */
 11.1839 +FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entries_matching(FLAC__StreamMetadata *object, const char *field_name);
 11.1840 +
 11.1841 +/** Create a new CUESHEET track instance.
 11.1842 + *
 11.1843 + *  The object will be "empty"; i.e. values and data pointers will be \c 0.
 11.1844 + *
 11.1845 + * \retval FLAC__StreamMetadata_CueSheet_Track*
 11.1846 + *    \c NULL if there was an error allocating memory, else the new instance.
 11.1847 + */
 11.1848 +FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_new(void);
 11.1849 +
 11.1850 +/** Create a copy of an existing CUESHEET track object.
 11.1851 + *
 11.1852 + *  The copy is a "deep" copy, i.e. dynamically allocated data within the
 11.1853 + *  object is also copied.  The caller takes ownership of the new object and
 11.1854 + *  is responsible for freeing it with
 11.1855 + *  FLAC__metadata_object_cuesheet_track_delete().
 11.1856 + *
 11.1857 + * \param object  Pointer to object to copy.
 11.1858 + * \assert
 11.1859 + *    \code object != NULL \endcode
 11.1860 + * \retval FLAC__StreamMetadata_CueSheet_Track*
 11.1861 + *    \c NULL if there was an error allocating memory, else the new instance.
 11.1862 + */
 11.1863 +FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_clone(const FLAC__StreamMetadata_CueSheet_Track *object);
 11.1864 +
 11.1865 +/** Delete a CUESHEET track object
 11.1866 + *
 11.1867 + * \param object       A pointer to an existing CUESHEET track object.
 11.1868 + * \assert
 11.1869 + *    \code object != NULL \endcode
 11.1870 + */
 11.1871 +FLAC_API void FLAC__metadata_object_cuesheet_track_delete(FLAC__StreamMetadata_CueSheet_Track *object);
 11.1872 +
 11.1873 +/** Resize a track's index point array.
 11.1874 + *
 11.1875 + *  If the size shrinks, elements will truncated; if it grows, new blank
 11.1876 + *  indices will be added to the end.
 11.1877 + *
 11.1878 + * \param object           A pointer to an existing CUESHEET object.
 11.1879 + * \param track_num        The index of the track to modify.  NOTE: this is not
 11.1880 + *                         necessarily the same as the track's \a number field.
 11.1881 + * \param new_num_indices  The desired length of the array; may be \c 0.
 11.1882 + * \assert
 11.1883 + *    \code object != NULL \endcode
 11.1884 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
 11.1885 + *    \code object->data.cue_sheet.num_tracks > track_num \endcode
 11.1886 + *    \code (object->data.cue_sheet.tracks[track_num].indices == NULL && object->data.cue_sheet.tracks[track_num].num_indices == 0) ||
 11.1887 + * (object->data.cue_sheet.tracks[track_num].indices != NULL && object->data.cue_sheet.tracks[track_num].num_indices > 0) \endcode
 11.1888 + * \retval FLAC__bool
 11.1889 + *    \c false if memory allocation error, else \c true.
 11.1890 + */
 11.1891 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_resize_indices(FLAC__StreamMetadata *object, unsigned track_num, unsigned new_num_indices);
 11.1892 +
 11.1893 +/** Insert an index point in a CUESHEET track at the given index.
 11.1894 + *
 11.1895 + * \param object       A pointer to an existing CUESHEET object.
 11.1896 + * \param track_num    The index of the track to modify.  NOTE: this is not
 11.1897 + *                     necessarily the same as the track's \a number field.
 11.1898 + * \param index_num    The index into the track's index array at which to
 11.1899 + *                     insert the index point.  NOTE: this is not necessarily
 11.1900 + *                     the same as the index point's \a number field.  The
 11.1901 + *                     indices at and after \a index_num move right one
 11.1902 + *                     position.  To append an index point to the end, set
 11.1903 + *                     \a index_num to
 11.1904 + *                     \c object->data.cue_sheet.tracks[track_num].num_indices .
 11.1905 + * \param index        The index point to insert.
 11.1906 + * \assert
 11.1907 + *    \code object != NULL \endcode
 11.1908 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
 11.1909 + *    \code object->data.cue_sheet.num_tracks > track_num \endcode
 11.1910 + *    \code object->data.cue_sheet.tracks[track_num].num_indices >= index_num \endcode
 11.1911 + * \retval FLAC__bool
 11.1912 + *    \c false if realloc() fails, else \c true.
 11.1913 + */
 11.1914 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num, FLAC__StreamMetadata_CueSheet_Index index);
 11.1915 +
 11.1916 +/** Insert a blank index point in a CUESHEET track at the given index.
 11.1917 + *
 11.1918 + *  A blank index point is one in which all field values are zero.
 11.1919 + *
 11.1920 + * \param object       A pointer to an existing CUESHEET object.
 11.1921 + * \param track_num    The index of the track to modify.  NOTE: this is not
 11.1922 + *                     necessarily the same as the track's \a number field.
 11.1923 + * \param index_num    The index into the track's index array at which to
 11.1924 + *                     insert the index point.  NOTE: this is not necessarily
 11.1925 + *                     the same as the index point's \a number field.  The
 11.1926 + *                     indices at and after \a index_num move right one
 11.1927 + *                     position.  To append an index point to the end, set
 11.1928 + *                     \a index_num to
 11.1929 + *                     \c object->data.cue_sheet.tracks[track_num].num_indices .
 11.1930 + * \assert
 11.1931 + *    \code object != NULL \endcode
 11.1932 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
 11.1933 + *    \code object->data.cue_sheet.num_tracks > track_num \endcode
 11.1934 + *    \code object->data.cue_sheet.tracks[track_num].num_indices >= index_num \endcode
 11.1935 + * \retval FLAC__bool
 11.1936 + *    \c false if realloc() fails, else \c true.
 11.1937 + */
 11.1938 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_blank_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num);
 11.1939 +
 11.1940 +/** Delete an index point in a CUESHEET track at the given index.
 11.1941 + *
 11.1942 + * \param object       A pointer to an existing CUESHEET object.
 11.1943 + * \param track_num    The index into the track array of the track to
 11.1944 + *                     modify.  NOTE: this is not necessarily the same
 11.1945 + *                     as the track's \a number field.
 11.1946 + * \param index_num    The index into the track's index array of the index
 11.1947 + *                     to delete.  NOTE: this is not necessarily the same
 11.1948 + *                     as the index's \a number field.
 11.1949 + * \assert
 11.1950 + *    \code object != NULL \endcode
 11.1951 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
 11.1952 + *    \code object->data.cue_sheet.num_tracks > track_num \endcode
 11.1953 + *    \code object->data.cue_sheet.tracks[track_num].num_indices > index_num \endcode
 11.1954 + * \retval FLAC__bool
 11.1955 + *    \c false if realloc() fails, else \c true.
 11.1956 + */
 11.1957 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_delete_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num);
 11.1958 +
 11.1959 +/** Resize the track array.
 11.1960 + *
 11.1961 + *  If the size shrinks, elements will truncated; if it grows, new blank
 11.1962 + *  tracks will be added to the end.
 11.1963 + *
 11.1964 + * \param object            A pointer to an existing CUESHEET object.
 11.1965 + * \param new_num_tracks    The desired length of the array; may be \c 0.
 11.1966 + * \assert
 11.1967 + *    \code object != NULL \endcode
 11.1968 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
 11.1969 + *    \code (object->data.cue_sheet.tracks == NULL && object->data.cue_sheet.num_tracks == 0) ||
 11.1970 + * (object->data.cue_sheet.tracks != NULL && object->data.cue_sheet.num_tracks > 0) \endcode
 11.1971 + * \retval FLAC__bool
 11.1972 + *    \c false if memory allocation error, else \c true.
 11.1973 + */
 11.1974 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_resize_tracks(FLAC__StreamMetadata *object, unsigned new_num_tracks);
 11.1975 +
 11.1976 +/** Sets a track in a CUESHEET block.
 11.1977 + *
 11.1978 + *  If \a copy is \c true, a copy of the track is stored; otherwise, the object
 11.1979 + *  takes ownership of the \a track pointer.
 11.1980 + *
 11.1981 + * \param object       A pointer to an existing CUESHEET object.
 11.1982 + * \param track_num    Index into track array to set.  NOTE: this is not
 11.1983 + *                     necessarily the same as the track's \a number field.
 11.1984 + * \param track        The track to set the track to.  You may safely pass in
 11.1985 + *                     a const pointer if \a copy is \c true.
 11.1986 + * \param copy         See above.
 11.1987 + * \assert
 11.1988 + *    \code object != NULL \endcode
 11.1989 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
 11.1990 + *    \code track_num < object->data.cue_sheet.num_tracks \endcode
 11.1991 + *    \code (track->indices != NULL && track->num_indices > 0) ||
 11.1992 + * (track->indices == NULL && track->num_indices == 0)
 11.1993 + * \retval FLAC__bool
 11.1994 + *    \c false if \a copy is \c true and malloc() fails, else \c true.
 11.1995 + */
 11.1996 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_set_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy);
 11.1997 +
 11.1998 +/** Insert a track in a CUESHEET block at the given index.
 11.1999 + *
 11.2000 + *  If \a copy is \c true, a copy of the track is stored; otherwise, the object
 11.2001 + *  takes ownership of the \a track pointer.
 11.2002 + *
 11.2003 + * \param object       A pointer to an existing CUESHEET object.
 11.2004 + * \param track_num    The index at which to insert the track.  NOTE: this
 11.2005 + *                     is not necessarily the same as the track's \a number
 11.2006 + *                     field.  The tracks at and after \a track_num move right
 11.2007 + *                     one position.  To append a track to the end, set
 11.2008 + *                     \a track_num to \c object->data.cue_sheet.num_tracks .
 11.2009 + * \param track        The track to insert.  You may safely pass in a const
 11.2010 + *                     pointer if \a copy is \c true.
 11.2011 + * \param copy         See above.
 11.2012 + * \assert
 11.2013 + *    \code object != NULL \endcode
 11.2014 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
 11.2015 + *    \code object->data.cue_sheet.num_tracks >= track_num \endcode
 11.2016 + * \retval FLAC__bool
 11.2017 + *    \c false if \a copy is \c true and malloc() fails, else \c true.
 11.2018 + */
 11.2019 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy);
 11.2020 +
 11.2021 +/** Insert a blank track in a CUESHEET block at the given index.
 11.2022 + *
 11.2023 + *  A blank track is one in which all field values are zero.
 11.2024 + *
 11.2025 + * \param object       A pointer to an existing CUESHEET object.
 11.2026 + * \param track_num    The index at which to insert the track.  NOTE: this
 11.2027 + *                     is not necessarily the same as the track's \a number
 11.2028 + *                     field.  The tracks at and after \a track_num move right
 11.2029 + *                     one position.  To append a track to the end, set
 11.2030 + *                     \a track_num to \c object->data.cue_sheet.num_tracks .
 11.2031 + * \assert
 11.2032 + *    \code object != NULL \endcode
 11.2033 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
 11.2034 + *    \code object->data.cue_sheet.num_tracks >= track_num \endcode
 11.2035 + * \retval FLAC__bool
 11.2036 + *    \c false if \a copy is \c true and malloc() fails, else \c true.
 11.2037 + */
 11.2038 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_blank_track(FLAC__StreamMetadata *object, unsigned track_num);
 11.2039 +
 11.2040 +/** Delete a track in a CUESHEET block at the given index.
 11.2041 + *
 11.2042 + * \param object       A pointer to an existing CUESHEET object.
 11.2043 + * \param track_num    The index into the track array of the track to
 11.2044 + *                     delete.  NOTE: this is not necessarily the same
 11.2045 + *                     as the track's \a number field.
 11.2046 + * \assert
 11.2047 + *    \code object != NULL \endcode
 11.2048 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
 11.2049 + *    \code object->data.cue_sheet.num_tracks > track_num \endcode
 11.2050 + * \retval FLAC__bool
 11.2051 + *    \c false if realloc() fails, else \c true.
 11.2052 + */
 11.2053 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_delete_track(FLAC__StreamMetadata *object, unsigned track_num);
 11.2054 +
 11.2055 +/** Check a cue sheet to see if it conforms to the FLAC specification.
 11.2056 + *  See the format specification for limits on the contents of the
 11.2057 + *  cue sheet.
 11.2058 + *
 11.2059 + * \param object     A pointer to an existing CUESHEET object.
 11.2060 + * \param check_cd_da_subset  If \c true, check CUESHEET against more
 11.2061 + *                   stringent requirements for a CD-DA (audio) disc.
 11.2062 + * \param violation  Address of a pointer to a string.  If there is a
 11.2063 + *                   violation, a pointer to a string explanation of the
 11.2064 + *                   violation will be returned here. \a violation may be
 11.2065 + *                   \c NULL if you don't need the returned string.  Do not
 11.2066 + *                   free the returned string; it will always point to static
 11.2067 + *                   data.
 11.2068 + * \assert
 11.2069 + *    \code object != NULL \endcode
 11.2070 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
 11.2071 + * \retval FLAC__bool
 11.2072 + *    \c false if cue sheet is illegal, else \c true.
 11.2073 + */
 11.2074 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_is_legal(const FLAC__StreamMetadata *object, FLAC__bool check_cd_da_subset, const char **violation);
 11.2075 +
 11.2076 +/** Calculate and return the CDDB/freedb ID for a cue sheet.  The function
 11.2077 + *  assumes the cue sheet corresponds to a CD; the result is undefined
 11.2078 + *  if the cuesheet's is_cd bit is not set.
 11.2079 + *
 11.2080 + * \param object     A pointer to an existing CUESHEET object.
 11.2081 + * \assert
 11.2082 + *    \code object != NULL \endcode
 11.2083 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
 11.2084 + * \retval FLAC__uint32
 11.2085 + *    The unsigned integer representation of the CDDB/freedb ID
 11.2086 + */
 11.2087 +FLAC_API FLAC__uint32 FLAC__metadata_object_cuesheet_calculate_cddb_id(const FLAC__StreamMetadata *object);
 11.2088 +
 11.2089 +/** Sets the MIME type of a PICTURE block.
 11.2090 + *
 11.2091 + *  If \a copy is \c true, a copy of the string is stored; otherwise, the object
 11.2092 + *  takes ownership of the pointer.  The existing string will be freed if this
 11.2093 + *  function is successful, otherwise the original string will remain if \a copy
 11.2094 + *  is \c true and malloc() fails.
 11.2095 + *
 11.2096 + * \note It is safe to pass a const pointer to \a mime_type if \a copy is \c true.
 11.2097 + *
 11.2098 + * \param object      A pointer to an existing PICTURE object.
 11.2099 + * \param mime_type   A pointer to the MIME type string.  The string must be
 11.2100 + *                    ASCII characters 0x20-0x7e, NUL-terminated.  No validation
 11.2101 + *                    is done.
 11.2102 + * \param copy        See above.
 11.2103 + * \assert
 11.2104 + *    \code object != NULL \endcode
 11.2105 + *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
 11.2106 + *    \code (mime_type != NULL) \endcode
 11.2107 + * \retval FLAC__bool
 11.2108 + *    \c false if \a copy is \c true and malloc() fails, else \c true.
 11.2109 + */
 11.2110 +FLAC_API FLAC__bool FLAC__metadata_object_picture_set_mime_type(FLAC__StreamMetadata *object, char *mime_type, FLAC__bool copy);
 11.2111 +
 11.2112 +/** Sets the description of a PICTURE block.
 11.2113 + *
 11.2114 + *  If \a copy is \c true, a copy of the string is stored; otherwise, the object
 11.2115 + *  takes ownership of the pointer.  The existing string will be freed if this
 11.2116 + *  function is successful, otherwise the original string will remain if \a copy
 11.2117 + *  is \c true and malloc() fails.
 11.2118 + *
 11.2119 + * \note It is safe to pass a const pointer to \a description if \a copy is \c true.
 11.2120 + *
 11.2121 + * \param object      A pointer to an existing PICTURE object.
 11.2122 + * \param description A pointer to the description string.  The string must be
 11.2123 + *                    valid UTF-8, NUL-terminated.  No validation is done.
 11.2124 + * \param copy        See above.
 11.2125 + * \assert
 11.2126 + *    \code object != NULL \endcode
 11.2127 + *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
 11.2128 + *    \code (description != NULL) \endcode
 11.2129 + * \retval FLAC__bool
 11.2130 + *    \c false if \a copy is \c true and malloc() fails, else \c true.
 11.2131 + */
 11.2132 +FLAC_API FLAC__bool FLAC__metadata_object_picture_set_description(FLAC__StreamMetadata *object, FLAC__byte *description, FLAC__bool copy);
 11.2133 +
 11.2134 +/** Sets the picture data of a PICTURE block.
 11.2135 + *
 11.2136 + *  If \a copy is \c true, a copy of the data is stored; otherwise, the object
 11.2137 + *  takes ownership of the pointer.  Also sets the \a data_length field of the
 11.2138 + *  metadata object to what is passed in as the \a length parameter.  The
 11.2139 + *  existing data will be freed if this function is successful, otherwise the
 11.2140 + *  original data and data_length will remain if \a copy is \c true and
 11.2141 + *  malloc() fails.
 11.2142 + *
 11.2143 + * \note It is safe to pass a const pointer to \a data if \a copy is \c true.
 11.2144 + *
 11.2145 + * \param object  A pointer to an existing PICTURE object.
 11.2146 + * \param data    A pointer to the data to set.
 11.2147 + * \param length  The length of \a data in bytes.
 11.2148 + * \param copy    See above.
 11.2149 + * \assert
 11.2150 + *    \code object != NULL \endcode
 11.2151 + *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
 11.2152 + *    \code (data != NULL && length > 0) ||
 11.2153 + * (data == NULL && length == 0 && copy == false) \endcode
 11.2154 + * \retval FLAC__bool
 11.2155 + *    \c false if \a copy is \c true and malloc() fails, else \c true.
 11.2156 + */
 11.2157 +FLAC_API FLAC__bool FLAC__metadata_object_picture_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, FLAC__uint32 length, FLAC__bool copy);
 11.2158 +
 11.2159 +/** Check a PICTURE block to see if it conforms to the FLAC specification.
 11.2160 + *  See the format specification for limits on the contents of the
 11.2161 + *  PICTURE block.
 11.2162 + *
 11.2163 + * \param object     A pointer to existing PICTURE block to be checked.
 11.2164 + * \param violation  Address of a pointer to a string.  If there is a
 11.2165 + *                   violation, a pointer to a string explanation of the
 11.2166 + *                   violation will be returned here. \a violation may be
 11.2167 + *                   \c NULL if you don't need the returned string.  Do not
 11.2168 + *                   free the returned string; it will always point to static
 11.2169 + *                   data.
 11.2170 + * \assert
 11.2171 + *    \code object != NULL \endcode
 11.2172 + *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
 11.2173 + * \retval FLAC__bool
 11.2174 + *    \c false if PICTURE block is illegal, else \c true.
 11.2175 + */
 11.2176 +FLAC_API FLAC__bool FLAC__metadata_object_picture_is_legal(const FLAC__StreamMetadata *object, const char **violation);
 11.2177 +
 11.2178 +/* \} */
 11.2179 +
 11.2180 +#ifdef __cplusplus
 11.2181 +}
 11.2182 +#endif
 11.2183 +
 11.2184 +#endif
    12.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    12.2 +++ b/Xcode/Frameworks/FLAC.framework/Versions/A/Headers/FLAC/ordinals.h	Mon Jan 09 01:58:40 2012 -0500
    12.3 @@ -0,0 +1,80 @@
    12.4 +/* libFLAC - Free Lossless Audio Codec library
    12.5 + * Copyright (C) 2000,2001,2002,2003,2004,2005,2006,2007  Josh Coalson
    12.6 + *
    12.7 + * Redistribution and use in source and binary forms, with or without
    12.8 + * modification, are permitted provided that the following conditions
    12.9 + * are met:
   12.10 + *
   12.11 + * - Redistributions of source code must retain the above copyright
   12.12 + * notice, this list of conditions and the following disclaimer.
   12.13 + *
   12.14 + * - Redistributions in binary form must reproduce the above copyright
   12.15 + * notice, this list of conditions and the following disclaimer in the
   12.16 + * documentation and/or other materials provided with the distribution.
   12.17 + *
   12.18 + * - Neither the name of the Xiph.org Foundation nor the names of its
   12.19 + * contributors may be used to endorse or promote products derived from
   12.20 + * this software without specific prior written permission.
   12.21 + *
   12.22 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   12.23 + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   12.24 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
   12.25 + * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
   12.26 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
   12.27 + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
   12.28 + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
   12.29 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
   12.30 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
   12.31 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
   12.32 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   12.33 + */
   12.34 +
   12.35 +#ifndef FLAC__ORDINALS_H
   12.36 +#define FLAC__ORDINALS_H
   12.37 +
   12.38 +#if !(defined(_MSC_VER) || defined(__BORLANDC__) || defined(__EMX__))
   12.39 +#include <inttypes.h>
   12.40 +#endif
   12.41 +
   12.42 +typedef signed char FLAC__int8;
   12.43 +typedef unsigned char FLAC__uint8;
   12.44 +
   12.45 +#if defined(_MSC_VER) || defined(__BORLANDC__)
   12.46 +typedef __int16 FLAC__int16;
   12.47 +typedef __int32 FLAC__int32;
   12.48 +typedef __int64 FLAC__int64;
   12.49 +typedef unsigned __int16 FLAC__uint16;
   12.50 +typedef unsigned __int32 FLAC__uint32;
   12.51 +typedef unsigned __int64 FLAC__uint64;
   12.52 +#elif defined(__EMX__)
   12.53 +typedef short FLAC__int16;
   12.54 +typedef long FLAC__int32;
   12.55 +typedef long long FLAC__int64;
   12.56 +typedef unsigned short FLAC__uint16;
   12.57 +typedef unsigned long FLAC__uint32;
   12.58 +typedef unsigned long long FLAC__uint64;
   12.59 +#else
   12.60 +typedef int16_t FLAC__int16;
   12.61 +typedef int32_t FLAC__int32;
   12.62 +typedef int64_t FLAC__int64;
   12.63 +typedef uint16_t FLAC__uint16;
   12.64 +typedef uint32_t FLAC__uint32;
   12.65 +typedef uint64_t FLAC__uint64;
   12.66 +#endif
   12.67 +
   12.68 +typedef int FLAC__bool;
   12.69 +
   12.70 +typedef FLAC__uint8 FLAC__byte;
   12.71 +
   12.72 +#ifdef true
   12.73 +#undef true
   12.74 +#endif
   12.75 +#ifdef false
   12.76 +#undef false
   12.77 +#endif
   12.78 +#ifndef __cplusplus
   12.79 +#define true 1
   12.80 +#define false 0
   12.81 +#endif
   12.82 +
   12.83 +#endif
    13.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    13.2 +++ b/Xcode/Frameworks/FLAC.framework/Versions/A/Headers/FLAC/stream_decoder.h	Mon Jan 09 01:58:40 2012 -0500
    13.3 @@ -0,0 +1,1559 @@
    13.4 +/* libFLAC - Free Lossless Audio Codec library
    13.5 + * Copyright (C) 2000,2001,2002,2003,2004,2005,2006,2007  Josh Coalson
    13.6 + *
    13.7 + * Redistribution and use in source and binary forms, with or without
    13.8 + * modification, are permitted provided that the following conditions
    13.9 + * are met:
   13.10 + *
   13.11 + * - Redistributions of source code must retain the above copyright
   13.12 + * notice, this list of conditions and the following disclaimer.
   13.13 + *
   13.14 + * - Redistributions in binary form must reproduce the above copyright
   13.15 + * notice, this list of conditions and the following disclaimer in the
   13.16 + * documentation and/or other materials provided with the distribution.
   13.17 + *
   13.18 + * - Neither the name of the Xiph.org Foundation nor the names of its
   13.19 + * contributors may be used to endorse or promote products derived from
   13.20 + * this software without specific prior written permission.
   13.21 + *
   13.22 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   13.23 + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   13.24 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
   13.25 + * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
   13.26 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
   13.27 + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
   13.28 + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
   13.29 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
   13.30 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
   13.31 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
   13.32 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   13.33 + */
   13.34 +
   13.35 +#ifndef FLAC__STREAM_DECODER_H
   13.36 +#define FLAC__STREAM_DECODER_H
   13.37 +
   13.38 +#include <stdio.h> /* for FILE */
   13.39 +#include "export.h"
   13.40 +#include "format.h"
   13.41 +
   13.42 +#ifdef __cplusplus
   13.43 +extern "C" {
   13.44 +#endif
   13.45 +
   13.46 +
   13.47 +/** \file include/FLAC/stream_decoder.h
   13.48 + *
   13.49 + *  \brief
   13.50 + *  This module contains the functions which implement the stream
   13.51 + *  decoder.
   13.52 + *
   13.53 + *  See the detailed documentation in the
   13.54 + *  \link flac_stream_decoder stream decoder \endlink module.
   13.55 + */
   13.56 +
   13.57 +/** \defgroup flac_decoder FLAC/ \*_decoder.h: decoder interfaces
   13.58 + *  \ingroup flac
   13.59 + *
   13.60 + *  \brief
   13.61 + *  This module describes the decoder layers provided by libFLAC.
   13.62 + *
   13.63 + * The stream decoder can be used to decode complete streams either from
   13.64 + * the client via callbacks, or directly from a file, depending on how
   13.65 + * it is initialized.  When decoding via callbacks, the client provides
   13.66 + * callbacks for reading FLAC data and writing decoded samples, and
   13.67 + * handling metadata and errors.  If the client also supplies seek-related
   13.68 + * callback, the decoder function for sample-accurate seeking within the
   13.69 + * FLAC input is also available.  When decoding from a file, the client
   13.70 + * needs only supply a filename or open \c FILE* and write/metadata/error
   13.71 + * callbacks; the rest of the callbacks are supplied internally.  For more
   13.72 + * info see the \link flac_stream_decoder stream decoder \endlink module.
   13.73 + */
   13.74 +
   13.75 +/** \defgroup flac_stream_decoder FLAC/stream_decoder.h: stream decoder interface
   13.76 + *  \ingroup flac_decoder
   13.77 + *
   13.78 + *  \brief
   13.79 + *  This module contains the functions which implement the stream
   13.80 + *  decoder.
   13.81 + *
   13.82 + * The stream decoder can decode native FLAC, and optionally Ogg FLAC
   13.83 + * (check FLAC_API_SUPPORTS_OGG_FLAC) streams and files.
   13.84 + *
   13.85 + * The basic usage of this decoder is as follows:
   13.86 + * - The program creates an instance of a decoder using
   13.87 + *   FLAC__stream_decoder_new().
   13.88 + * - The program overrides the default settings using
   13.89 + *   FLAC__stream_decoder_set_*() functions.
   13.90 + * - The program initializes the instance to validate the settings and
   13.91 + *   prepare for decoding using
   13.92 + *   - FLAC__stream_decoder_init_stream() or FLAC__stream_decoder_init_FILE()
   13.93 + *     or FLAC__stream_decoder_init_file() for native FLAC,
   13.94 + *   - FLAC__stream_decoder_init_ogg_stream() or FLAC__stream_decoder_init_ogg_FILE()
   13.95 + *     or FLAC__stream_decoder_init_ogg_file() for Ogg FLAC
   13.96 + * - The program calls the FLAC__stream_decoder_process_*() functions
   13.97 + *   to decode data, which subsequently calls the callbacks.
   13.98 + * - The program finishes the decoding with FLAC__stream_decoder_finish(),
   13.99 + *   which flushes the input and output and resets the decoder to the
  13.100 + *   uninitialized state.
  13.101 + * - The instance may be used again or deleted with
  13.102 + *   FLAC__stream_decoder_delete().
  13.103 + *
  13.104 + * In more detail, the program will create a new instance by calling
  13.105 + * FLAC__stream_decoder_new(), then call FLAC__stream_decoder_set_*()
  13.106 + * functions to override the default decoder options, and call
  13.107 + * one of the FLAC__stream_decoder_init_*() functions.
  13.108 + *
  13.109 + * There are three initialization functions for native FLAC, one for
  13.110 + * setting up the decoder to decode FLAC data from the client via
  13.111 + * callbacks, and two for decoding directly from a FLAC file.
  13.112 + *
  13.113 + * For decoding via callbacks, use FLAC__stream_decoder_init_stream().
  13.114 + * You must also supply several callbacks for handling I/O.  Some (like
  13.115 + * seeking) are optional, depending on the capabilities of the input.
  13.116 + *
  13.117 + * For decoding directly from a file, use FLAC__stream_decoder_init_FILE()
  13.118 + * or FLAC__stream_decoder_init_file().  Then you must only supply an open
  13.119 + * \c FILE* or filename and fewer callbacks; the decoder will handle
  13.120 + * the other callbacks internally.
  13.121 + *
  13.122 + * There are three similarly-named init functions for decoding from Ogg
  13.123 + * FLAC streams.  Check \c FLAC_API_SUPPORTS_OGG_FLAC to find out if the
  13.124 + * library has been built with Ogg support.
  13.125 + *
  13.126 + * Once the decoder is initialized, your program will call one of several
  13.127 + * functions to start the decoding process:
  13.128 + *
  13.129 + * - FLAC__stream_decoder_process_single() - Tells the decoder to process at
  13.130 + *   most one metadata block or audio frame and return, calling either the
  13.131 + *   metadata callback or write callback, respectively, once.  If the decoder
  13.132 + *   loses sync it will return with only the error callback being called.
  13.133 + * - FLAC__stream_decoder_process_until_end_of_metadata() - Tells the decoder
  13.134 + *   to process the stream from the current location and stop upon reaching
  13.135 + *   the first audio frame.  The client will get one metadata, write, or error
  13.136 + *   callback per metadata block, audio frame, or sync error, respectively.
  13.137 + * - FLAC__stream_decoder_process_until_end_of_stream() - Tells the decoder
  13.138 + *   to process the stream from the current location until the read callback
  13.139 + *   returns FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM or
  13.140 + *   FLAC__STREAM_DECODER_READ_STATUS_ABORT.  The client will get one metadata,
  13.141 + *   write, or error callback per metadata block, audio frame, or sync error,
  13.142 + *   respectively.
  13.143 + *
  13.144 + * When the decoder has finished decoding (normally or through an abort),
  13.145 + * the instance is finished by calling FLAC__stream_decoder_finish(), which
  13.146 + * ensures the decoder is in the correct state and frees memory.  Then the
  13.147 + * instance may be deleted with FLAC__stream_decoder_delete() or initialized
  13.148 + * again to decode another stream.
  13.149 + *
  13.150 + * Seeking is exposed through the FLAC__stream_decoder_seek_absolute() method.
  13.151 + * At any point after the stream decoder has been initialized, the client can
  13.152 + * call this function to seek to an exact sample within the stream.
  13.153 + * Subsequently, the first time the write callback is called it will be
  13.154 + * passed a (possibly partial) block starting at that sample.
  13.155 + *
  13.156 + * If the client cannot seek via the callback interface provided, but still
  13.157 + * has another way of seeking, it can flush the decoder using
  13.158 + * FLAC__stream_decoder_flush() and start feeding data from the new position
  13.159 + * through the read callback.
  13.160 + *
  13.161 + * The stream decoder also provides MD5 signature checking.  If this is
  13.162 + * turned on before initialization, FLAC__stream_decoder_finish() will
  13.163 + * report when the decoded MD5 signature does not match the one stored
  13.164 + * in the STREAMINFO block.  MD5 checking is automatically turned off
  13.165 + * (until the next FLAC__stream_decoder_reset()) if there is no signature
  13.166 + * in the STREAMINFO block or when a seek is attempted.
  13.167 + *
  13.168 + * The FLAC__stream_decoder_set_metadata_*() functions deserve special
  13.169 + * attention.  By default, the decoder only calls the metadata_callback for
  13.170 + * the STREAMINFO block.  These functions allow you to tell the decoder
  13.171 + * explicitly which blocks to parse and return via the metadata_callback
  13.172 + * and/or which to skip.  Use a FLAC__stream_decoder_set_metadata_respond_all(),
  13.173 + * FLAC__stream_decoder_set_metadata_ignore() ... or FLAC__stream_decoder_set_metadata_ignore_all(),
  13.174 + * FLAC__stream_decoder_set_metadata_respond() ... sequence to exactly specify
  13.175 + * which blocks to return.  Remember that metadata blocks can potentially
  13.176 + * be big (for example, cover art) so filtering out the ones you don't
  13.177 + * use can reduce the memory requirements of the decoder.  Also note the
  13.178 + * special forms FLAC__stream_decoder_set_metadata_respond_application(id)
  13.179 + * and FLAC__stream_decoder_set_metadata_ignore_application(id) for
  13.180 + * filtering APPLICATION blocks based on the application ID.
  13.181 + *
  13.182 + * STREAMINFO and SEEKTABLE blocks are always parsed and used internally, but
  13.183 + * they still can legally be filtered from the metadata_callback.
  13.184 + *
  13.185 + * \note
  13.186 + * The "set" functions may only be called when the decoder is in the
  13.187 + * state FLAC__STREAM_DECODER_UNINITIALIZED, i.e. after
  13.188 + * FLAC__stream_decoder_new() or FLAC__stream_decoder_finish(), but
  13.189 + * before FLAC__stream_decoder_init_*().  If this is the case they will
  13.190 + * return \c true, otherwise \c false.
  13.191 + *
  13.192 + * \note
  13.193 + * FLAC__stream_decoder_finish() resets all settings to the constructor
  13.194 + * defaults, including the callbacks.
  13.195 + *
  13.196 + * \{
  13.197 + */
  13.198 +
  13.199 +
  13.200 +/** State values for a FLAC__StreamDecoder
  13.201 + *
  13.202 + * The decoder's state can be obtained by calling FLAC__stream_decoder_get_state().
  13.203 + */
  13.204 +typedef enum {
  13.205 +
  13.206 +	FLAC__STREAM_DECODER_SEARCH_FOR_METADATA = 0,
  13.207 +	/**< The decoder is ready to search for metadata. */
  13.208 +
  13.209 +	FLAC__STREAM_DECODER_READ_METADATA,
  13.210 +	/**< The decoder is ready to or is in the process of reading metadata. */
  13.211 +
  13.212 +	FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC,
  13.213 +	/**< The decoder is ready to or is in the process of searching for the
  13.214 +	 * frame sync code.
  13.215 +	 */
  13.216 +
  13.217 +	FLAC__STREAM_DECODER_READ_FRAME,
  13.218 +	/**< The decoder is ready to or is in the process of reading a frame. */
  13.219 +
  13.220 +	FLAC__STREAM_DECODER_END_OF_STREAM,
  13.221 +	/**< The decoder has reached the end of the stream. */
  13.222 +
  13.223 +	FLAC__STREAM_DECODER_OGG_ERROR,
  13.224 +	/**< An error occurred in the underlying Ogg layer.  */
  13.225 +
  13.226 +	FLAC__STREAM_DECODER_SEEK_ERROR,
  13.227 +	/**< An error occurred while seeking.  The decoder must be flushed
  13.228 +	 * with FLAC__stream_decoder_flush() or reset with
  13.229 +	 * FLAC__stream_decoder_reset() before decoding can continue.
  13.230 +	 */
  13.231 +
  13.232 +	FLAC__STREAM_DECODER_ABORTED,
  13.233 +	/**< The decoder was aborted by the read callback. */
  13.234 +
  13.235 +	FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
  13.236 +	/**< An error occurred allocating memory.  The decoder is in an invalid
  13.237 +	 * state and can no longer be used.
  13.238 +	 */
  13.239 +
  13.240 +	FLAC__STREAM_DECODER_UNINITIALIZED
  13.241 +	/**< The decoder is in the uninitialized state; one of the
  13.242 +	 * FLAC__stream_decoder_init_*() functions must be called before samples
  13.243 +	 * can be processed.
  13.244 +	 */
  13.245 +
  13.246 +} FLAC__StreamDecoderState;
  13.247 +
  13.248 +/** Maps a FLAC__StreamDecoderState to a C string.
  13.249 + *
  13.250 + *  Using a FLAC__StreamDecoderState as the index to this array
  13.251 + *  will give the string equivalent.  The contents should not be modified.
  13.252 + */
  13.253 +extern FLAC_API const char * const FLAC__StreamDecoderStateString[];
  13.254 +
  13.255 +
  13.256 +/** Possible return values for the FLAC__stream_decoder_init_*() functions.
  13.257 + */
  13.258 +typedef enum {
  13.259 +
  13.260 +	FLAC__STREAM_DECODER_INIT_STATUS_OK = 0,
  13.261 +	/**< Initialization was successful. */
  13.262 +
  13.263 +	FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER,
  13.264 +	/**< The library was not compiled with support for the given container
  13.265 +	 * format.
  13.266 +	 */
  13.267 +
  13.268 +	FLAC__STREAM_DECODER_INIT_STATUS_INVALID_CALLBACKS,
  13.269 +	/**< A required callback was not supplied. */
  13.270 +
  13.271 +	FLAC__STREAM_DECODER_INIT_STATUS_MEMORY_ALLOCATION_ERROR,
  13.272 +	/**< An error occurred allocating memory. */
  13.273 +
  13.274 +	FLAC__STREAM_DECODER_INIT_STATUS_ERROR_OPENING_FILE,
  13.275 +	/**< fopen() failed in FLAC__stream_decoder_init_file() or
  13.276 +	 * FLAC__stream_decoder_init_ogg_file(). */
  13.277 +
  13.278 +	FLAC__STREAM_DECODER_INIT_STATUS_ALREADY_INITIALIZED
  13.279 +	/**< FLAC__stream_decoder_init_*() was called when the decoder was
  13.280 +	 * already initialized, usually because
  13.281 +	 * FLAC__stream_decoder_finish() was not called.
  13.282 +	 */
  13.283 +
  13.284 +} FLAC__StreamDecoderInitStatus;
  13.285 +
  13.286 +/** Maps a FLAC__StreamDecoderInitStatus to a C string.
  13.287 + *
  13.288 + *  Using a FLAC__StreamDecoderInitStatus as the index to this array
  13.289 + *  will give the string equivalent.  The contents should not be modified.
  13.290 + */
  13.291 +extern FLAC_API const char * const FLAC__StreamDecoderInitStatusString[];
  13.292 +
  13.293 +
  13.294 +/** Return values for the FLAC__StreamDecoder read callback.
  13.295 + */
  13.296 +typedef enum {
  13.297 +
  13.298 +	FLAC__STREAM_DECODER_READ_STATUS_CONTINUE,
  13.299 +	/**< The read was OK and decoding can continue. */
  13.300 +
  13.301 +	FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM,
  13.302 +	/**< The read was attempted while at the end of the stream.  Note that
  13.303 +	 * the client must only return this value when the read callback was
  13.304 +	 * called when already at the end of the stream.  Otherwise, if the read
  13.305 +	 * itself moves to the end of the stream, the client should still return
  13.306 +	 * the data and \c FLAC__STREAM_DECODER_READ_STATUS_CONTINUE, and then on
  13.307 +	 * the next read callback it should return
  13.308 +	 * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM with a byte count
  13.309 +	 * of \c 0.
  13.310 +	 */
  13.311 +
  13.312 +	FLAC__STREAM_DECODER_READ_STATUS_ABORT
  13.313 +	/**< An unrecoverable error occurred.  The decoder will return from the process call. */
  13.314 +
  13.315 +} FLAC__StreamDecoderReadStatus;
  13.316 +
  13.317 +/** Maps a FLAC__StreamDecoderReadStatus to a C string.
  13.318 + *
  13.319 + *  Using a FLAC__StreamDecoderReadStatus as the index to this array
  13.320 + *  will give the string equivalent.  The contents should not be modified.
  13.321 + */
  13.322 +extern FLAC_API const char * const FLAC__StreamDecoderReadStatusString[];
  13.323 +
  13.324 +
  13.325 +/** Return values for the FLAC__StreamDecoder seek callback.
  13.326 + */
  13.327 +typedef enum {
  13.328 +
  13.329 +	FLAC__STREAM_DECODER_SEEK_STATUS_OK,
  13.330 +	/**< The seek was OK and decoding can continue. */
  13.331 +
  13.332 +	FLAC__STREAM_DECODER_SEEK_STATUS_ERROR,
  13.333 +	/**< An unrecoverable error occurred.  The decoder will return from the process call. */
  13.334 +
  13.335 +	FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
  13.336 +	/**< Client does not support seeking. */
  13.337 +
  13.338 +} FLAC__StreamDecoderSeekStatus;
  13.339 +
  13.340 +/** Maps a FLAC__StreamDecoderSeekStatus to a C string.
  13.341 + *
  13.342 + *  Using a FLAC__StreamDecoderSeekStatus as the index to this array
  13.343 + *  will give the string equivalent.  The contents should not be modified.
  13.344 + */
  13.345 +extern FLAC_API const char * const FLAC__StreamDecoderSeekStatusString[];
  13.346 +
  13.347 +
  13.348 +/** Return values for the FLAC__StreamDecoder tell callback.
  13.349 + */
  13.350 +typedef enum {
  13.351 +
  13.352 +	FLAC__STREAM_DECODER_TELL_STATUS_OK,
  13.353 +	/**< The tell was OK and decoding can continue. */
  13.354 +
  13.355 +	FLAC__STREAM_DECODER_TELL_STATUS_ERROR,
  13.356 +	/**< An unrecoverable error occurred.  The decoder will return from the process call. */
  13.357 +
  13.358 +	FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
  13.359 +	/**< Client does not support telling the position. */
  13.360 +
  13.361 +} FLAC__StreamDecoderTellStatus;
  13.362 +
  13.363 +/** Maps a FLAC__StreamDecoderTellStatus to a C string.
  13.364 + *
  13.365 + *  Using a FLAC__StreamDecoderTellStatus as the index to this array
  13.366 + *  will give the string equivalent.  The contents should not be modified.
  13.367 + */
  13.368 +extern FLAC_API const char * const FLAC__StreamDecoderTellStatusString[];
  13.369 +
  13.370 +
  13.371 +/** Return values for the FLAC__StreamDecoder length callback.
  13.372 + */
  13.373 +typedef enum {
  13.374 +
  13.375 +	FLAC__STREAM_DECODER_LENGTH_STATUS_OK,
  13.376 +	/**< The length call was OK and decoding can continue. */
  13.377 +
  13.378 +	FLAC__STREAM_DECODER_LENGTH_STATUS_ERROR,
  13.379 +	/**< An unrecoverable error occurred.  The decoder will return from the process call. */
  13.380 +
  13.381 +	FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
  13.382 +	/**< Client does not support reporting the length. */
  13.383 +
  13.384 +} FLAC__StreamDecoderLengthStatus;
  13.385 +
  13.386 +/** Maps a FLAC__StreamDecoderLengthStatus to a C string.
  13.387 + *
  13.388 + *  Using a FLAC__StreamDecoderLengthStatus as the index to this array
  13.389 + *  will give the string equivalent.  The contents should not be modified.
  13.390 + */
  13.391 +extern FLAC_API const char * const FLAC__StreamDecoderLengthStatusString[];
  13.392 +
  13.393 +
  13.394 +/** Return values for the FLAC__StreamDecoder write callback.
  13.395 + */
  13.396 +typedef enum {
  13.397 +
  13.398 +	FLAC__STREAM_DECODER_WRITE_STATUS_CONTINUE,
  13.399 +	/**< The write was OK and decoding can continue. */
  13.400 +
  13.401 +	FLAC__STREAM_DECODER_WRITE_STATUS_ABORT
  13.402 +	/**< An unrecoverable error occurred.  The decoder will return from the process call. */
  13.403 +
  13.404 +} FLAC__StreamDecoderWriteStatus;
  13.405 +
  13.406 +/** Maps a FLAC__StreamDecoderWriteStatus to a C string.
  13.407 + *
  13.408 + *  Using a FLAC__StreamDecoderWriteStatus as the index to this array
  13.409 + *  will give the string equivalent.  The contents should not be modified.
  13.410 + */
  13.411 +extern FLAC_API const char * const FLAC__StreamDecoderWriteStatusString[];
  13.412 +
  13.413 +
  13.414 +/** Possible values passed back to the FLAC__StreamDecoder error callback.
  13.415 + *  \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC is the generic catch-
  13.416 + *  all.  The rest could be caused by bad sync (false synchronization on
  13.417 + *  data that is not the start of a frame) or corrupted data.  The error
  13.418 + *  itself is the decoder's best guess at what happened assuming a correct
  13.419 + *  sync.  For example \c FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER
  13.420 + *  could be caused by a correct sync on the start of a frame, but some
  13.421 + *  data in the frame header was corrupted.  Or it could be the result of
  13.422 + *  syncing on a point the stream that looked like the starting of a frame
  13.423 + *  but was not.  \c FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM
  13.424 + *  could be because the decoder encountered a valid frame made by a future
  13.425 + *  version of the encoder which it cannot parse, or because of a false
  13.426 + *  sync making it appear as though an encountered frame was generated by
  13.427 + *  a future encoder.
  13.428 + */
  13.429 +typedef enum {
  13.430 +
  13.431 +	FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC,
  13.432 +	/**< An error in the stream caused the decoder to lose synchronization. */
  13.433 +
  13.434 +	FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER,
  13.435 +	/**< The decoder encountered a corrupted frame header. */
  13.436 +
  13.437 +	FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH,
  13.438 +	/**< The frame's data did not match the CRC in the footer. */
  13.439 +
  13.440 +	FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM
  13.441 +	/**< The decoder encountered reserved fields in use in the stream. */
  13.442 +
  13.443 +} FLAC__StreamDecoderErrorStatus;
  13.444 +
  13.445 +/** Maps a FLAC__StreamDecoderErrorStatus to a C string.
  13.446 + *
  13.447 + *  Using a FLAC__StreamDecoderErrorStatus as the index to this array
  13.448 + *  will give the string equivalent.  The contents should not be modified.
  13.449 + */
  13.450 +extern FLAC_API const char * const FLAC__StreamDecoderErrorStatusString[];
  13.451 +
  13.452 +
  13.453 +/***********************************************************************
  13.454 + *
  13.455 + * class FLAC__StreamDecoder
  13.456 + *
  13.457 + ***********************************************************************/
  13.458 +
  13.459 +struct FLAC__StreamDecoderProtected;
  13.460 +struct FLAC__StreamDecoderPrivate;
  13.461 +/** The opaque structure definition for the stream decoder type.
  13.462 + *  See the \link flac_stream_decoder stream decoder module \endlink
  13.463 + *  for a detailed description.
  13.464 + */
  13.465 +typedef struct {
  13.466 +	struct FLAC__StreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
  13.467 +	struct FLAC__StreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
  13.468 +} FLAC__StreamDecoder;
  13.469 +
  13.470 +/** Signature for the read callback.
  13.471 + *
  13.472 + *  A function pointer matching this signature must be passed to
  13.473 + *  FLAC__stream_decoder_init*_stream(). The supplied function will be
  13.474 + *  called when the decoder needs more input data.  The address of the
  13.475 + *  buffer to be filled is supplied, along with the number of bytes the
  13.476 + *  buffer can hold.  The callback may choose to supply less data and
  13.477 + *  modify the byte count but must be careful not to overflow the buffer.
  13.478 + *  The callback then returns a status code chosen from
  13.479 + *  FLAC__StreamDecoderReadStatus.
  13.480 + *
  13.481 + * Here is an example of a read callback for stdio streams:
  13.482 + * \code
  13.483 + * FLAC__StreamDecoderReadStatus read_cb(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], size_t *bytes, void *client_data)
  13.484 + * {
  13.485 + *   FILE *file = ((MyClientData*)client_data)->file;
  13.486 + *   if(*bytes > 0) {
  13.487 + *     *bytes = fread(buffer, sizeof(FLAC__byte), *bytes, file);
  13.488 + *     if(ferror(file))
  13.489 + *       return FLAC__STREAM_DECODER_READ_STATUS_ABORT;
  13.490 + *     else if(*bytes == 0)
  13.491 + *       return FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM;
  13.492 + *     else
  13.493 + *       return FLAC__STREAM_DECODER_READ_STATUS_CONTINUE;
  13.494 + *   }
  13.495 + *   else
  13.496 + *     return FLAC__STREAM_DECODER_READ_STATUS_ABORT;
  13.497 + * }
  13.498 + * \endcode
  13.499 + *
  13.500 + * \note In general, FLAC__StreamDecoder functions which change the
  13.501 + * state should not be called on the \a decoder while in the callback.
  13.502 + *
  13.503 + * \param  decoder  The decoder instance calling the callback.
  13.504 + * \param  buffer   A pointer to a location for the callee to store
  13.505 + *                  data to be decoded.
  13.506 + * \param  bytes    A pointer to the size of the buffer.  On entry
  13.507 + *                  to the callback, it contains the maximum number
  13.508 + *                  of bytes that may be stored in \a buffer.  The
  13.509 + *                  callee must set it to the actual number of bytes
  13.510 + *                  stored (0 in case of error or end-of-stream) before
  13.511 + *                  returning.
  13.512 + * \param  client_data  The callee's client data set through
  13.513 + *                      FLAC__stream_decoder_init_*().
  13.514 + * \retval FLAC__StreamDecoderReadStatus
  13.515 + *    The callee's return status.  Note that the callback should return
  13.516 + *    \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM if and only if
  13.517 + *    zero bytes were read and there is no more data to be read.
  13.518 + */
  13.519 +typedef FLAC__StreamDecoderReadStatus (*FLAC__StreamDecoderReadCallback)(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], size_t *bytes, void *client_data);
  13.520 +
  13.521 +/** Signature for the seek callback.
  13.522 + *
  13.523 + *  A function pointer matching this signature may be passed to
  13.524 + *  FLAC__stream_decoder_init*_stream().  The supplied function will be
  13.525 + *  called when the decoder needs to seek the input stream.  The decoder
  13.526 + *  will pass the absolute byte offset to seek to, 0 meaning the
  13.527 + *  beginning of the stream.
  13.528 + *
  13.529 + * Here is an example of a seek callback for stdio streams:
  13.530 + * \code
  13.531 + * FLAC__StreamDecoderSeekStatus seek_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data)
  13.532 + * {
  13.533 + *   FILE *file = ((MyClientData*)client_data)->file;
  13.534 + *   if(file == stdin)
  13.535 + *     return FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED;
  13.536 + *   else if(fseeko(file, (off_t)absolute_byte_offset, SEEK_SET) < 0)
  13.537 + *     return FLAC__STREAM_DECODER_SEEK_STATUS_ERROR;
  13.538 + *   else
  13.539 + *     return FLAC__STREAM_DECODER_SEEK_STATUS_OK;
  13.540 + * }
  13.541 + * \endcode
  13.542 + *
  13.543 + * \note In general, FLAC__StreamDecoder functions which change the
  13.544 + * state should not be called on the \a decoder while in the callback.
  13.545 + *
  13.546 + * \param  decoder  The decoder instance calling the callback.
  13.547 + * \param  absolute_byte_offset  The offset from the beginning of the stream
  13.548 + *                               to seek to.
  13.549 + * \param  client_data  The callee's client data set through
  13.550 + *                      FLAC__stream_decoder_init_*().
  13.551 + * \retval FLAC__StreamDecoderSeekStatus
  13.552 + *    The callee's return status.
  13.553 + */
  13.554 +typedef FLAC__StreamDecoderSeekStatus (*FLAC__StreamDecoderSeekCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
  13.555 +
  13.556 +/** Signature for the tell callback.
  13.557 + *
  13.558 + *  A function pointer matching this signature may be passed to
  13.559 + *  FLAC__stream_decoder_init*_stream().  The supplied function will be
  13.560 + *  called when the decoder wants to know the current position of the
  13.561 + *  stream.  The callback should return the byte offset from the
  13.562 + *  beginning of the stream.
  13.563 + *
  13.564 + * Here is an example of a tell callback for stdio streams:
  13.565 + * \code
  13.566 + * FLAC__StreamDecoderTellStatus tell_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data)
  13.567 + * {
  13.568 + *   FILE *file = ((MyClientData*)client_data)->file;
  13.569 + *   off_t pos;
  13.570 + *   if(file == stdin)
  13.571 + *     return FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED;
  13.572 + *   else if((pos = ftello(file)) < 0)
  13.573 + *     return FLAC__STREAM_DECODER_TELL_STATUS_ERROR;
  13.574 + *   else {
  13.575 + *     *absolute_byte_offset = (FLAC__uint64)pos;
  13.576 + *     return FLAC__STREAM_DECODER_TELL_STATUS_OK;
  13.577 + *   }
  13.578 + * }
  13.579 + * \endcode
  13.580 + *
  13.581 + * \note In general, FLAC__StreamDecoder functions which change the
  13.582 + * state should not be called on the \a decoder while in the callback.
  13.583 + *
  13.584 + * \param  decoder  The decoder instance calling the callback.
  13.585 + * \param  absolute_byte_offset  A pointer to storage for the current offset
  13.586 + *                               from the beginning of the stream.
  13.587 + * \param  client_data  The callee's client data set through
  13.588 + *                      FLAC__stream_decoder_init_*().
  13.589 + * \retval FLAC__StreamDecoderTellStatus
  13.590 + *    The callee's return status.
  13.591 + */
  13.592 +typedef FLAC__StreamDecoderTellStatus (*FLAC__StreamDecoderTellCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
  13.593 +
  13.594 +/** Signature for the length callback.
  13.595 + *
  13.596 + *  A function pointer matching this signature may be passed to
  13.597 + *  FLAC__stream_decoder_init*_stream().  The supplied function will be
  13.598 + *  called when the decoder wants to know the total length of the stream
  13.599 + *  in bytes.
  13.600 + *
  13.601 + * Here is an example of a length callback for stdio streams:
  13.602 + * \code
  13.603 + * FLAC__StreamDecoderLengthStatus length_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data)
  13.604 + * {
  13.605 + *   FILE *file = ((MyClientData*)client_data)->file;
  13.606 + *   struct stat filestats;
  13.607 + *
  13.608 + *   if(file == stdin)
  13.609 + *     return FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED;
  13.610 + *   else if(fstat(fileno(file), &filestats) != 0)
  13.611 + *     return FLAC__STREAM_DECODER_LENGTH_STATUS_ERROR;
  13.612 + *   else {
  13.613 + *     *stream_length = (FLAC__uint64)filestats.st_size;
  13.614 + *     return FLAC__STREAM_DECODER_LENGTH_STATUS_OK;
  13.615 + *   }
  13.616 + * }
  13.617 + * \endcode
  13.618 + *
  13.619 + * \note In general, FLAC__StreamDecoder functions which change the
  13.620 + * state should not be called on the \a decoder while in the callback.
  13.621 + *
  13.622 + * \param  decoder  The decoder instance calling the callback.
  13.623 + * \param  stream_length  A pointer to storage for the length of the stream
  13.624 + *                        in bytes.
  13.625 + * \param  client_data  The callee's client data set through
  13.626 + *                      FLAC__stream_decoder_init_*().
  13.627 + * \retval FLAC__StreamDecoderLengthStatus
  13.628 + *    The callee's return status.
  13.629 + */
  13.630 +typedef FLAC__StreamDecoderLengthStatus (*FLAC__StreamDecoderLengthCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
  13.631 +
  13.632 +/** Signature for the EOF callback.
  13.633 + *
  13.634 + *  A function pointer matching this signature may be passed to
  13.635 + *  FLAC__stream_decoder_init*_stream().  The supplied function will be
  13.636 + *  called when the decoder needs to know if the end of the stream has
  13.637 + *  been reached.
  13.638 + *
  13.639 + * Here is an example of a EOF callback for stdio streams:
  13.640 + * FLAC__bool eof_cb(const FLAC__StreamDecoder *decoder, void *client_data)
  13.641 + * \code
  13.642 + * {
  13.643 + *   FILE *file = ((MyClientData*)client_data)->file;
  13.644 + *   return feof(file)? true : false;
  13.645 + * }
  13.646 + * \endcode
  13.647 + *
  13.648 + * \note In general, FLAC__StreamDecoder functions which change the
  13.649 + * state should not be called on the \a decoder while in the callback.
  13.650 + *
  13.651 + * \param  decoder  The decoder instance calling the callback.
  13.652 + * \param  client_data  The callee's client data set through
  13.653 + *                      FLAC__stream_decoder_init_*().
  13.654 + * \retval FLAC__bool
  13.655 + *    \c true if the currently at the end of the stream, else \c false.
  13.656 + */
  13.657 +typedef FLAC__bool (*FLAC__StreamDecoderEofCallback)(const FLAC__StreamDecoder *decoder, void *client_data);
  13.658 +
  13.659 +/** Signature for the write callback.
  13.660 + *
  13.661 + *  A function pointer matching this signature must be passed to one of
  13.662 + *  the FLAC__stream_decoder_init_*() functions.
  13.663 + *  The supplied function will be called when the decoder has decoded a
  13.664 + *  single audio frame.  The decoder will pass the frame metadata as well
  13.665 + *  as an array of pointers (one for each channel) pointing to the
  13.666 + *  decoded audio.
  13.667 + *
  13.668 + * \note In general, FLAC__StreamDecoder functions which change the
  13.669 + * state should not be called on the \a decoder while in the callback.
  13.670 + *
  13.671 + * \param  decoder  The decoder instance calling the callback.
  13.672 + * \param  frame    The description of the decoded frame.  See
  13.673 + *                  FLAC__Frame.
  13.674 + * \param  buffer   An array of pointers to decoded channels of data.
  13.675 + *                  Each pointer will point to an array of signed
  13.676 + *                  samples of length \a frame->header.blocksize.
  13.677 + *                  Channels will be ordered according to the FLAC
  13.678 + *                  specification; see the documentation for the
  13.679 + *                  <A HREF="../format.html#frame_header">frame header</A>.
  13.680 + * \param  client_data  The callee's client data set through
  13.681 + *                      FLAC__stream_decoder_init_*().
  13.682 + * \retval FLAC__StreamDecoderWriteStatus
  13.683 + *    The callee's return status.
  13.684 + */
  13.685 +typedef FLAC__StreamDecoderWriteStatus (*FLAC__StreamDecoderWriteCallback)(const FLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
  13.686 +
  13.687 +/** Signature for the metadata callback.
  13.688 + *
  13.689 + *  A function pointer matching this signature must be passed to one of
  13.690 + *  the FLAC__stream_decoder_init_*() functions.
  13.691 + *  The supplied function will be called when the decoder has decoded a
  13.692 + *  metadata block.  In a valid FLAC file there will always be one
  13.693 + *  \c STREAMINFO block, followed by zero or more other metadata blocks.
  13.694 + *  These will be supplied by the decoder in the same order as they
  13.695 + *  appear in the stream and always before the first audio frame (i.e.
  13.696 + *  write callback).  The metadata block that is passed in must not be
  13.697 + *  modified, and it doesn't live beyond the callback, so you should make
  13.698 + *  a copy of it with FLAC__metadata_object_clone() if you will need it
  13.699 + *  elsewhere.  Since metadata blocks can potentially be large, by
  13.700 + *  default the decoder only calls the metadata callback for the
  13.701 + *  \c STREAMINFO block; you can instruct the decoder to pass or filter
  13.702 + *  other blocks with FLAC__stream_decoder_set_metadata_*() calls.
  13.703 + *
  13.704 + * \note In general, FLAC__StreamDecoder functions which change the
  13.705 + * state should not be called on the \a decoder while in the callback.
  13.706 + *
  13.707 + * \param  decoder  The decoder instance calling the callback.
  13.708 + * \param  metadata The decoded metadata block.
  13.709 + * \param  client_data  The callee's client data set through
  13.710 + *                      FLAC__stream_decoder_init_*().
  13.711 + */
  13.712 +typedef void (*FLAC__StreamDecoderMetadataCallback)(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
  13.713 +
  13.714 +/** Signature for the error callback.
  13.715 + *
  13.716 + *  A function pointer matching this signature must be passed to one of
  13.717 + *  the FLAC__stream_decoder_init_*() functions.
  13.718 + *  The supplied function will be called whenever an error occurs during
  13.719 + *  decoding.
  13.720 + *
  13.721 + * \note In general, FLAC__StreamDecoder functions which change the
  13.722 + * state should not be called on the \a decoder while in the callback.
  13.723 + *
  13.724 + * \param  decoder  The decoder instance calling the callback.
  13.725 + * \param  status   The error encountered by the decoder.
  13.726 + * \param  client_data  The callee's client data set through
  13.727 + *                      FLAC__stream_decoder_init_*().
  13.728 + */
  13.729 +typedef void (*FLAC__StreamDecoderErrorCallback)(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
  13.730 +
  13.731 +
  13.732 +/***********************************************************************
  13.733 + *
  13.734 + * Class constructor/destructor
  13.735 + *
  13.736 + ***********************************************************************/
  13.737 +
  13.738 +/** Create a new stream decoder instance.  The instance is created with
  13.739 + *  default settings; see the individual FLAC__stream_decoder_set_*()
  13.740 + *  functions for each setting's default.
  13.741 + *
  13.742 + * \retval FLAC__StreamDecoder*
  13.743 + *    \c NULL if there was an error allocating memory, else the new instance.
  13.744 + */
  13.745 +FLAC_API FLAC__StreamDecoder *FLAC__stream_decoder_new(void);
  13.746 +
  13.747 +/** Free a decoder instance.  Deletes the object pointed to by \a decoder.
  13.748 + *
  13.749 + * \param decoder  A pointer to an existing decoder.
  13.750 + * \assert
  13.751 + *    \code decoder != NULL \endcode
  13.752 + */
  13.753 +FLAC_API void FLAC__stream_decoder_delete(FLAC__StreamDecoder *decoder);
  13.754 +
  13.755 +
  13.756 +/***********************************************************************
  13.757 + *
  13.758 + * Public class method prototypes
  13.759 + *
  13.760 + ***********************************************************************/
  13.761 +
  13.762 +/** Set the serial number for the FLAC stream within the Ogg container.
  13.763 + *  The default behavior is to use the serial number of the first Ogg
  13.764 + *  page.  Setting a serial number here will explicitly specify which
  13.765 + *  stream is to be decoded.
  13.766 + *
  13.767 + * \note
  13.768 + * This does not need to be set for native FLAC decoding.
  13.769 + *
  13.770 + * \default \c use serial number of first page
  13.771 + * \param  decoder        A decoder instance to set.
  13.772 + * \param  serial_number  See above.
  13.773 + * \assert
  13.774 + *    \code decoder != NULL \endcode
  13.775 + * \retval FLAC__bool
  13.776 + *    \c false if the decoder is already initialized, else \c true.
  13.777 + */
  13.778 +FLAC_API FLAC__bool FLAC__stream_decoder_set_ogg_serial_number(FLAC__StreamDecoder *decoder, long serial_number);
  13.779 +
  13.780 +/** Set the "MD5 signature checking" flag.  If \c true, the decoder will
  13.781 + *  compute the MD5 signature of the unencoded audio data while decoding
  13.782 + *  and compare it to the signature from the STREAMINFO block, if it
  13.783 + *  exists, during FLAC__stream_decoder_finish().
  13.784 + *
  13.785 + *  MD5 signature checking will be turned off (until the next
  13.786 + *  FLAC__stream_decoder_reset()) if there is no signature in the
  13.787 + *  STREAMINFO block or when a seek is attempted.
  13.788 + *
  13.789 + *  Clients that do not use the MD5 check should leave this off to speed
  13.790 + *  up decoding.
  13.791 + *
  13.792 + * \default \c false
  13.793 + * \param  decoder  A decoder instance to set.
  13.794 + * \param  value    Flag value (see above).
  13.795 + * \assert
  13.796 + *    \code decoder != NULL \endcode
  13.797 + * \retval FLAC__bool
  13.798 + *    \c false if the decoder is already initialized, else \c true.
  13.799 + */
  13.800 +FLAC_API FLAC__bool FLAC__stream_decoder_set_md5_checking(FLAC__StreamDecoder *decoder, FLAC__bool value);
  13.801 +
  13.802 +/** Direct the decoder to pass on all metadata blocks of type \a type.
  13.803 + *
  13.804 + * \default By default, only the \c STREAMINFO block is returned via the
  13.805 + *          metadata callback.
  13.806 + * \param  decoder  A decoder instance to set.
  13.807 + * \param  type     See above.
  13.808 + * \assert
  13.809 + *    \code decoder != NULL \endcode
  13.810 + *    \a type is valid
  13.811 + * \retval FLAC__bool
  13.812 + *    \c false if the decoder is already initialized, else \c true.
  13.813 + */
  13.814 +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
  13.815 +
  13.816 +/** Direct the decoder to pass on all APPLICATION metadata blocks of the
  13.817 + *  given \a id.
  13.818 + *
  13.819 + * \default By default, only the \c STREAMINFO block is returned via the
  13.820 + *          metadata callback.
  13.821 + * \param  decoder  A decoder instance to set.
  13.822 + * \param  id       See above.
  13.823 + * \assert
  13.824 + *    \code decoder != NULL \endcode
  13.825 + *    \code id != NULL \endcode
  13.826 + * \retval FLAC__bool
  13.827 + *    \c false if the decoder is already initialized, else \c true.
  13.828 + */
  13.829 +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
  13.830 +
  13.831 +/** Direct the decoder to pass on all metadata blocks of any type.
  13.832 + *
  13.833 + * \default By default, only the \c STREAMINFO block is returned via the
  13.834 + *          metadata callback.
  13.835 + * \param  decoder  A decoder instance to set.
  13.836 + * \assert
  13.837 + *    \code decoder != NULL \endcode
  13.838 + * \retval FLAC__bool
  13.839 + *    \c false if the decoder is already initialized, else \c true.
  13.840 + */
  13.841 +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_all(FLAC__StreamDecoder *decoder);
  13.842 +
  13.843 +/** Direct the decoder to filter out all metadata blocks of type \a type.
  13.844 + *
  13.845 + * \default By default, only the \c STREAMINFO block is returned via the
  13.846 + *          metadata callback.
  13.847 + * \param  decoder  A decoder instance to set.
  13.848 + * \param  type     See above.
  13.849 + * \assert
  13.850 + *    \code decoder != NULL \endcode
  13.851 + *    \a type is valid
  13.852 + * \retval FLAC__bool
  13.853 + *    \c false if the decoder is already initialized, else \c true.
  13.854 + */
  13.855 +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
  13.856 +
  13.857 +/** Direct the decoder to filter out all APPLICATION metadata blocks of
  13.858 + *  the given \a id.
  13.859 + *
  13.860 + * \default By default, only the \c STREAMINFO block is returned via the
  13.861 + *          metadata callback.
  13.862 + * \param  decoder  A decoder instance to set.
  13.863 + * \param  id       See above.
  13.864 + * \assert
  13.865 + *    \code decoder != NULL \endcode
  13.866 + *    \code id != NULL \endcode
  13.867 + * \retval FLAC__bool
  13.868 + *    \c false if the decoder is already initialized, else \c true.
  13.869 + */
  13.870 +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
  13.871 +
  13.872 +/** Direct the decoder to filter out all metadata blocks of any type.
  13.873 + *
  13.874 + * \default By default, only the \c STREAMINFO block is returned via the
  13.875 + *          metadata callback.
  13.876 + * \param  decoder  A decoder instance to set.
  13.877 + * \assert
  13.878 + *    \code decoder != NULL \endcode
  13.879 + * \retval FLAC__bool
  13.880 + *    \c false if the decoder is already initialized, else \c true.
  13.881 + */
  13.882 +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_all(FLAC__StreamDecoder *decoder);
  13.883 +
  13.884 +/** Get the current decoder state.
  13.885 + *
  13.886 + * \param  decoder  A decoder instance to query.
  13.887 + * \assert
  13.888 + *    \code decoder != NULL \endcode
  13.889 + * \retval FLAC__StreamDecoderState
  13.890 + *    The current decoder state.
  13.891 + */
  13.892 +FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_get_state(const FLAC__StreamDecoder *decoder);
  13.893 +
  13.894 +/** Get the current decoder state as a C string.
  13.895 + *
  13.896 + * \param  decoder  A decoder instance to query.
  13.897 + * \assert
  13.898 + *    \code decoder != NULL \endcode
  13.899 + * \retval const char *
  13.900 + *    The decoder state as a C string.  Do not modify the contents.
  13.901 + */
  13.902 +FLAC_API const char *FLAC__stream_decoder_get_resolved_state_string(const FLAC__StreamDecoder *decoder);
  13.903 +
  13.904 +/** Get the "MD5 signature checking" flag.
  13.905 + *  This is the value of the setting, not whether or not the decoder is
  13.906 + *  currently checking the MD5 (remember, it can be turned off automatically
  13.907 + *  by a seek).  When the decoder is reset the flag will be restored to the
  13.908 + *  value returned by this function.
  13.909 + *
  13.910 + * \param  decoder  A decoder instance to query.
  13.911 + * \assert
  13.912 + *    \code decoder != NULL \endcode
  13.913 + * \retval FLAC__bool
  13.914 + *    See above.
  13.915 + */
  13.916 +FLAC_API FLAC__bool FLAC__stream_decoder_get_md5_checking(const FLAC__StreamDecoder *decoder);
  13.917 +
  13.918 +/** Get the total number of samples in the stream being decoded.
  13.919 + *  Will only be valid after decoding has started and will contain the
  13.920 + *  value from the \c STREAMINFO block.  A value of \c 0 means "unknown".
  13.921 + *
  13.922 + * \param  decoder  A decoder instance to query.
  13.923 + * \assert
  13.924 + *    \code decoder != NULL \endcode
  13.925 + * \retval unsigned
  13.926 + *    See above.
  13.927 + */
  13.928 +FLAC_API FLAC__uint64 FLAC__stream_decoder_get_total_samples(const FLAC__StreamDecoder *decoder);
  13.929 +
  13.930 +/** Get the current number of channels in the stream being decoded.
  13.931 + *  Will only be valid after decoding has started and will contain the
  13.932 + *  value from the most recently decoded frame header.
  13.933 + *
  13.934 + * \param  decoder  A decoder instance to query.
  13.935 + * \assert
  13.936 + *    \code decoder != NULL \endcode
  13.937 + * \retval unsigned
  13.938 + *    See above.
  13.939 + */
  13.940 +FLAC_API unsigned FLAC__stream_decoder_get_channels(const FLAC__StreamDecoder *decoder);
  13.941 +
  13.942 +/** Get the current channel assignment in the stream being decoded.
  13.943 + *  Will only be valid after decoding has started and will contain the
  13.944 + *  value from the most recently decoded frame header.
  13.945 + *
  13.946 + * \param  decoder  A decoder instance to query.
  13.947 + * \assert
  13.948 + *    \code decoder != NULL \endcode
  13.949 + * \retval FLAC__ChannelAssignment
  13.950 + *    See above.
  13.951 + */
  13.952 +FLAC_API FLAC__ChannelAssignment FLAC__stream_decoder_get_channel_assignment(const FLAC__StreamDecoder *decoder);
  13.953 +
  13.954 +/** Get the current sample resolution in the stream being decoded.
  13.955 + *  Will only be valid after decoding has started and will contain the
  13.956 + *  value from the most recently decoded frame header.
  13.957 + *
  13.958 + * \param  decoder  A decoder instance to query.
  13.959 + * \assert
  13.960 + *    \code decoder != NULL \endcode
  13.961 + * \retval unsigned
  13.962 + *    See above.
  13.963 + */
  13.964 +FLAC_API unsigned FLAC__stream_decoder_get_bits_per_sample(const FLAC__StreamDecoder *decoder);
  13.965 +
  13.966 +/** Get the current sample rate in Hz of the stream being decoded.
  13.967 + *  Will only be valid after decoding has started and will contain the
  13.968 + *  value from the most recently decoded frame header.
  13.969 + *
  13.970 + * \param  decoder  A decoder instance to query.
  13.971 + * \assert
  13.972 + *    \code decoder != NULL \endcode
  13.973 + * \retval unsigned
  13.974 + *    See above.
  13.975 + */
  13.976 +FLAC_API unsigned FLAC__stream_decoder_get_sample_rate(const FLAC__StreamDecoder *decoder);
  13.977 +
  13.978 +/** Get the current blocksize of the stream being decoded.
  13.979 + *  Will only be valid after decoding has started and will contain the
  13.980 + *  value from the most recently decoded frame header.
  13.981 + *
  13.982 + * \param  decoder  A decoder instance to query.
  13.983 + * \assert
  13.984 + *    \code decoder != NULL \endcode
  13.985 + * \retval unsigned
  13.986 + *    See above.
  13.987 + */
  13.988 +FLAC_API unsigned FLAC__stream_decoder_get_blocksize(const FLAC__StreamDecoder *decoder);
  13.989 +
  13.990 +/** Returns the decoder's current read position within the stream.
  13.991 + *  The position is the byte offset from the start of the stream.
  13.992 + *  Bytes before this position have been fully decoded.  Note that
  13.993 + *  there may still be undecoded bytes in the decoder's read FIFO.
  13.994 + *  The returned position is correct even after a seek.
  13.995 + *
  13.996 + *  \warning This function currently only works for native FLAC,
  13.997 + *           not Ogg FLAC streams.
  13.998 + *
  13.999 + * \param  decoder   A decoder instance to query.
 13.1000 + * \param  position  Address at which to return the desired position.
 13.1001 + * \assert
 13.1002 + *    \code decoder != NULL \endcode
 13.1003 + *    \code position != NULL \endcode
 13.1004 + * \retval FLAC__bool
 13.1005 + *    \c true if successful, \c false if the stream is not native FLAC,
 13.1006 + *    or there was an error from the 'tell' callback or it returned
 13.1007 + *    \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED.
 13.1008 + */
 13.1009 +FLAC_API FLAC__bool FLAC__stream_decoder_get_decode_position(const FLAC__StreamDecoder *decoder, FLAC__uint64 *position);
 13.1010 +
 13.1011 +/** Initialize the decoder instance to decode native FLAC streams.
 13.1012 + *
 13.1013 + *  This flavor of initialization sets up the decoder to decode from a
 13.1014 + *  native FLAC stream. I/O is performed via callbacks to the client.
 13.1015 + *  For decoding from a plain file via filename or open FILE*,
 13.1016 + *  FLAC__stream_decoder_init_file() and FLAC__stream_decoder_init_FILE()
 13.1017 + *  provide a simpler interface.
 13.1018 + *
 13.1019 + *  This function should be called after FLAC__stream_decoder_new() and
 13.1020 + *  FLAC__stream_decoder_set_*() but before any of the
 13.1021 + *  FLAC__stream_decoder_process_*() functions.  Will set and return the
 13.1022 + *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
 13.1023 + *  if initialization succeeded.
 13.1024 + *
 13.1025 + * \param  decoder            An uninitialized decoder instance.
 13.1026 + * \param  read_callback      See FLAC__StreamDecoderReadCallback.  This
 13.1027 + *                            pointer must not be \c NULL.
 13.1028 + * \param  seek_callback      See FLAC__StreamDecoderSeekCallback.  This
 13.1029 + *                            pointer may be \c NULL if seeking is not
 13.1030 + *                            supported.  If \a seek_callback is not \c NULL then a
 13.1031 + *                            \a tell_callback, \a length_callback, and \a eof_callback must also be supplied.
 13.1032 + *                            Alternatively, a dummy seek callback that just
 13.1033 + *                            returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
 13.1034 + *                            may also be supplied, all though this is slightly
 13.1035 + *                            less efficient for the decoder.
 13.1036 + * \param  tell_callback      See FLAC__StreamDecoderTellCallback.  This
 13.1037 + *                            pointer may be \c NULL if not supported by the client.  If
 13.1038 + *                            \a seek_callback is not \c NULL then a
 13.1039 + *                            \a tell_callback must also be supplied.
 13.1040 + *                            Alternatively, a dummy tell callback that just
 13.1041 + *                            returns \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
 13.1042 + *                            may also be supplied, all though this is slightly
 13.1043 + *                            less efficient for the decoder.
 13.1044 + * \param  length_callback    See FLAC__StreamDecoderLengthCallback.  This
 13.1045 + *                            pointer may be \c NULL if not supported by the client.  If
 13.1046 + *                            \a seek_callback is not \c NULL then a
 13.1047 + *                            \a length_callback must also be supplied.
 13.1048 + *                            Alternatively, a dummy length callback that just
 13.1049 + *                            returns \c FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
 13.1050 + *                            may also be supplied, all though this is slightly
 13.1051 + *                            less efficient for the decoder.
 13.1052 + * \param  eof_callback       See FLAC__StreamDecoderEofCallback.  This
 13.1053 + *                            pointer may be \c NULL if not supported by the client.  If
 13.1054 + *                            \a seek_callback is not \c NULL then a
 13.1055 + *                            \a eof_callback must also be supplied.
 13.1056 + *                            Alternatively, a dummy length callback that just
 13.1057 + *                            returns \c false
 13.1058 + *                            may also be supplied, all though this is slightly
 13.1059 + *                            less efficient for the decoder.
 13.1060 + * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
 13.1061 + *                            pointer must not be \c NULL.
 13.1062 + * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
 13.1063 + *                            pointer may be \c NULL if the callback is not
 13.1064 + *                            desired.
 13.1065 + * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
 13.1066 + *                            pointer must not be \c NULL.
 13.1067 + * \param  client_data        This value will be supplied to callbacks in their
 13.1068 + *                            \a client_data argument.
 13.1069 + * \assert
 13.1070 + *    \code decoder != NULL \endcode
 13.1071 + * \retval FLAC__StreamDecoderInitStatus
 13.1072 + *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
 13.1073 + *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
 13.1074 + */
 13.1075 +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_stream(
 13.1076 +	FLAC__StreamDecoder *decoder,
 13.1077 +	FLAC__StreamDecoderReadCallback read_callback,
 13.1078 +	FLAC__StreamDecoderSeekCallback seek_callback,
 13.1079 +	FLAC__StreamDecoderTellCallback tell_callback,
 13.1080 +	FLAC__StreamDecoderLengthCallback length_callback,
 13.1081 +	FLAC__StreamDecoderEofCallback eof_callback,
 13.1082 +	FLAC__StreamDecoderWriteCallback write_callback,
 13.1083 +	FLAC__StreamDecoderMetadataCallback metadata_callback,
 13.1084 +	FLAC__StreamDecoderErrorCallback error_callback,
 13.1085 +	void *client_data
 13.1086 +);
 13.1087 +
 13.1088 +/** Initialize the decoder instance to decode Ogg FLAC streams.
 13.1089 + *
 13.1090 + *  This flavor of initialization sets up the decoder to decode from a
 13.1091 + *  FLAC stream in an Ogg container. I/O is performed via callbacks to the
 13.1092 + *  client.  For decoding from a plain file via filename or open FILE*,
 13.1093 + *  FLAC__stream_decoder_init_ogg_file() and FLAC__stream_decoder_init_ogg_FILE()
 13.1094 + *  provide a simpler interface.
 13.1095 + *
 13.1096 + *  This function should be called after FLAC__stream_decoder_new() and
 13.1097 + *  FLAC__stream_decoder_set_*() but before any of the
 13.1098 + *  FLAC__stream_decoder_process_*() functions.  Will set and return the
 13.1099 + *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
 13.1100 + *  if initialization succeeded.
 13.1101 + *
 13.1102 + *  \note Support for Ogg FLAC in the library is optional.  If this
 13.1103 + *  library has been built without support for Ogg FLAC, this function
 13.1104 + *  will return \c FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER.
 13.1105 + *
 13.1106 + * \param  decoder            An uninitialized decoder instance.
 13.1107 + * \param  read_callback      See FLAC__StreamDecoderReadCallback.  This
 13.1108 + *                            pointer must not be \c NULL.
 13.1109 + * \param  seek_callback      See FLAC__StreamDecoderSeekCallback.  This
 13.1110 + *                            pointer may be \c NULL if seeking is not
 13.1111 + *                            supported.  If \a seek_callback is not \c NULL then a
 13.1112 + *                            \a tell_callback, \a length_callback, and \a eof_callback must also be supplied.
 13.1113 + *                            Alternatively, a dummy seek callback that just
 13.1114 + *                            returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
 13.1115 + *                            may also be supplied, all though this is slightly
 13.1116 + *                            less efficient for the decoder.
 13.1117 + * \param  tell_callback      See FLAC__StreamDecoderTellCallback.  This
 13.1118 + *                            pointer may be \c NULL if not supported by the client.  If
 13.1119 + *                            \a seek_callback is not \c NULL then a
 13.1120 + *                            \a tell_callback must also be supplied.
 13.1121 + *                            Alternatively, a dummy tell callback that just
 13.1122 + *                            returns \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
 13.1123 + *                            may also be supplied, all though this is slightly
 13.1124 + *                            less efficient for the decoder.
 13.1125 + * \param  length_callback    See FLAC__StreamDecoderLengthCallback.  This
 13.1126 + *                            pointer may be \c NULL if not supported by the client.  If
 13.1127 + *                            \a seek_callback is not \c NULL then a
 13.1128 + *                            \a length_callback must also be supplied.
 13.1129 + *                            Alternatively, a dummy length callback that just
 13.1130 + *                            returns \c FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
 13.1131 + *                            may also be supplied, all though this is slightly
 13.1132 + *                            less efficient for the decoder.
 13.1133 + * \param  eof_callback       See FLAC__StreamDecoderEofCallback.  This
 13.1134 + *                            pointer may be \c NULL if not supported by the client.  If
 13.1135 + *                            \a seek_callback is not \c NULL then a
 13.1136 + *                            \a eof_callback must also be supplied.
 13.1137 + *                            Alternatively, a dummy length callback that just
 13.1138 + *                            returns \c false
 13.1139 + *                            may also be supplied, all though this is slightly
 13.1140 + *                            less efficient for the decoder.
 13.1141 + * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
 13.1142 + *                            pointer must not be \c NULL.
 13.1143 + * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
 13.1144 + *                            pointer may be \c NULL if the callback is not
 13.1145 + *                            desired.
 13.1146 + * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
 13.1147 + *                            pointer must not be \c NULL.
 13.1148 + * \param  client_data        This value will be supplied to callbacks in their
 13.1149 + *                            \a client_data argument.
 13.1150 + * \assert
 13.1151 + *    \code decoder != NULL \endcode
 13.1152 + * \retval FLAC__StreamDecoderInitStatus
 13.1153 + *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
 13.1154 + *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
 13.1155 + */
 13.1156 +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_stream(
 13.1157 +	FLAC__StreamDecoder *decoder,
 13.1158 +	FLAC__StreamDecoderReadCallback read_callback,
 13.1159 +	FLAC__StreamDecoderSeekCallback seek_callback,
 13.1160 +	FLAC__StreamDecoderTellCallback tell_callback,
 13.1161 +	FLAC__StreamDecoderLengthCallback length_callback,
 13.1162 +	FLAC__StreamDecoderEofCallback eof_callback,
 13.1163 +	FLAC__StreamDecoderWriteCallback write_callback,
 13.1164 +	FLAC__StreamDecoderMetadataCallback metadata_callback,
 13.1165 +	FLAC__StreamDecoderErrorCallback error_callback,
 13.1166 +	void *client_data
 13.1167 +);
 13.1168 +
 13.1169 +/** Initialize the decoder instance to decode native FLAC files.
 13.1170 + *
 13.1171 + *  This flavor of initialization sets up the decoder to decode from a
 13.1172 + *  plain native FLAC file.  For non-stdio streams, you must use
 13.1173 + *  FLAC__stream_decoder_init_stream() and provide callbacks for the I/O.
 13.1174 + *
 13.1175 + *  This function should be called after FLAC__stream_decoder_new() and
 13.1176 + *  FLAC__stream_decoder_set_*() but before any of the
 13.1177 + *  FLAC__stream_decoder_process_*() functions.  Will set and return the
 13.1178 + *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
 13.1179 + *  if initialization succeeded.
 13.1180 + *
 13.1181 + * \param  decoder            An uninitialized decoder instance.
 13.1182 + * \param  file               An open FLAC file.  The file should have been
 13.1183 + *                            opened with mode \c "rb" and rewound.  The file
 13.1184 + *                            becomes owned by the decoder and should not be
 13.1185 + *                            manipulated by the client while decoding.
 13.1186 + *                            Unless \a file is \c stdin, it will be closed
 13.1187 + *                            when FLAC__stream_decoder_finish() is called.
 13.1188 + *                            Note however that seeking will not work when
 13.1189 + *                            decoding from \c stdout since it is not seekable.
 13.1190 + * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
 13.1191 + *                            pointer must not be \c NULL.
 13.1192 + * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
 13.1193 + *                            pointer may be \c NULL if the callback is not
 13.1194 + *                            desired.
 13.1195 + * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
 13.1196 + *                            pointer must not be \c NULL.
 13.1197 + * \param  client_data        This value will be supplied to callbacks in their
 13.1198 + *                            \a client_data argument.
 13.1199 + * \assert
 13.1200 + *    \code decoder != NULL \endcode
 13.1201 + *    \code file != NULL \endcode
 13.1202 + * \retval FLAC__StreamDecoderInitStatus
 13.1203 + *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
 13.1204 + *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
 13.1205 + */
 13.1206 +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_FILE(
 13.1207 +	FLAC__StreamDecoder *decoder,
 13.1208 +	FILE *file,
 13.1209 +	FLAC__StreamDecoderWriteCallback write_callback,
 13.1210 +	FLAC__StreamDecoderMetadataCallback metadata_callback,
 13.1211 +	FLAC__StreamDecoderErrorCallback error_callback,
 13.1212 +	void *client_data
 13.1213 +);
 13.1214 +
 13.1215 +/** Initialize the decoder instance to decode Ogg FLAC files.
 13.1216 + *
 13.1217 + *  This flavor of initialization sets up the decoder to decode from a
 13.1218 + *  plain Ogg FLAC file.  For non-stdio streams, you must use
 13.1219 + *  FLAC__stream_decoder_init_ogg_stream() and provide callbacks for the I/O.
 13.1220 + *
 13.1221 + *  This function should be called after FLAC__stream_decoder_new() and
 13.1222 + *  FLAC__stream_decoder_set_*() but before any of the
 13.1223 + *  FLAC__stream_decoder_process_*() functions.  Will set and return the
 13.1224 + *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
 13.1225 + *  if initialization succeeded.
 13.1226 + *
 13.1227 + *  \note Support for Ogg FLAC in the library is optional.  If this
 13.1228 + *  library has been built without support for Ogg FLAC, this function
 13.1229 + *  will return \c FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER.
 13.1230 + *
 13.1231 + * \param  decoder            An uninitialized decoder instance.
 13.1232 + * \param  file               An open FLAC file.  The file should have been
 13.1233 + *                            opened with mode \c "rb" and rewound.  The file
 13.1234 + *                            becomes owned by the decoder and should not be
 13.1235 + *                            manipulated by the client while decoding.
 13.1236 + *                            Unless \a file is \c stdin, it will be closed
 13.1237 + *                            when FLAC__stream_decoder_finish() is called.
 13.1238 + *                            Note however that seeking will not work when
 13.1239 + *                            decoding from \c stdout since it is not seekable.
 13.1240 + * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
 13.1241 + *                            pointer must not be \c NULL.
 13.1242 + * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
 13.1243 + *                            pointer may be \c NULL if the callback is not
 13.1244 + *                            desired.
 13.1245 + * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
 13.1246 + *                            pointer must not be \c NULL.
 13.1247 + * \param  client_data        This value will be supplied to callbacks in their
 13.1248 + *                            \a client_data argument.
 13.1249 + * \assert
 13.1250 + *    \code decoder != NULL \endcode
 13.1251 + *    \code file != NULL \endcode
 13.1252 + * \retval FLAC__StreamDecoderInitStatus
 13.1253 + *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
 13.1254 + *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
 13.1255 + */
 13.1256 +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_FILE(
 13.1257 +	FLAC__StreamDecoder *decoder,
 13.1258 +	FILE *file,
 13.1259 +	FLAC__StreamDecoderWriteCallback write_callback,
 13.1260 +	FLAC__StreamDecoderMetadataCallback metadata_callback,
 13.1261 +	FLAC__StreamDecoderErrorCallback error_callback,
 13.1262 +	void *client_data
 13.1263 +);
 13.1264 +
 13.1265 +/** Initialize the decoder instance to decode native FLAC files.
 13.1266 + *
 13.1267 + *  This flavor of initialization sets up the decoder to decode from a plain
 13.1268 + *  native FLAC file.  If POSIX fopen() semantics are not sufficient, (for
 13.1269 + *  example, with Unicode filenames on Windows), you must use
 13.1270 + *  FLAC__stream_decoder_init_FILE(), or FLAC__stream_decoder_init_stream()
 13.1271 + *  and provide callbacks for the I/O.
 13.1272 + *
 13.1273 + *  This function should be called after FLAC__stream_decoder_new() and
 13.1274 + *  FLAC__stream_decoder_set_*() but before any of the
 13.1275 + *  FLAC__stream_decoder_process_*() functions.  Will set and return the
 13.1276 + *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
 13.1277 + *  if initialization succeeded.
 13.1278 + *
 13.1279 + * \param  decoder            An uninitialized decoder instance.
 13.1280 + * \param  filename           The name of the file to decode from.  The file will
 13.1281 + *                            be opened with fopen().  Use \c NULL to decode from
 13.1282 + *                            \c stdin.  Note that \c stdin is not seekable.
 13.1283 + * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
 13.1284 + *                            pointer must not be \c NULL.
 13.1285 + * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
 13.1286 + *                            pointer may be \c NULL if the callback is not
 13.1287 + *                            desired.
 13.1288 + * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
 13.1289 + *                            pointer must not be \c NULL.
 13.1290 + * \param  client_data        This value will be supplied to callbacks in their
 13.1291 + *                            \a client_data argument.
 13.1292 + * \assert
 13.1293 + *    \code decoder != NULL \endcode
 13.1294 + * \retval FLAC__StreamDecoderInitStatus
 13.1295 + *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
 13.1296 + *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
 13.1297 + */
 13.1298 +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_file(
 13.1299 +	FLAC__StreamDecoder *decoder,
 13.1300 +	const char *filename,
 13.1301 +	FLAC__StreamDecoderWriteCallback write_callback,
 13.1302 +	FLAC__StreamDecoderMetadataCallback metadata_callback,
 13.1303 +	FLAC__StreamDecoderErrorCallback error_callback,
 13.1304 +	void *client_data
 13.1305 +);
 13.1306 +
 13.1307 +/** Initialize the decoder instance to decode Ogg FLAC files.
 13.1308 + *
 13.1309 + *  This flavor of initialization sets up the decoder to decode from a plain
 13.1310 + *  Ogg FLAC file.  If POSIX fopen() semantics are not sufficient, (for
 13.1311 + *  example, with Unicode filenames on Windows), you must use
 13.1312 + *  FLAC__stream_decoder_init_ogg_FILE(), or FLAC__stream_decoder_init_ogg_stream()
 13.1313 + *  and provide callbacks for the I/O.
 13.1314 + *
 13.1315 + *  This function should be called after FLAC__stream_decoder_new() and
 13.1316 + *  FLAC__stream_decoder_set_*() but before any of the
 13.1317 + *  FLAC__stream_decoder_process_*() functions.  Will set and return the
 13.1318 + *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
 13.1319 + *  if initialization succeeded.
 13.1320 + *
 13.1321 + *  \note Support for Ogg FLAC in the library is optional.  If this
 13.1322 + *  library has been built without support for Ogg FLAC, this function
 13.1323 + *  will return \c FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER.
 13.1324 + *
 13.1325 + * \param  decoder            An uninitialized decoder instance.
 13.1326 + * \param  filename           The name of the file to decode from.  The file will
 13.1327 + *                            be opened with fopen().  Use \c NULL to decode from
 13.1328 + *                            \c stdin.  Note that \c stdin is not seekable.
 13.1329 + * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
 13.1330 + *                            pointer must not be \c NULL.
 13.1331 + * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
 13.1332 + *                            pointer may be \c NULL if the callback is not
 13.1333 + *                            desired.
 13.1334 + * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
 13.1335 + *                            pointer must not be \c NULL.
 13.1336 + * \param  client_data        This value will be supplied to callbacks in their
 13.1337 + *                            \a client_data argument.
 13.1338 + * \assert
 13.1339 + *    \code decoder != NULL \endcode
 13.1340 + * \retval FLAC__StreamDecoderInitStatus
 13.1341 + *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
 13.1342 + *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
 13.1343 + */
 13.1344 +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_file(
 13.1345 +	FLAC__StreamDecoder *decoder,
 13.1346 +	const char *filename,
 13.1347 +	FLAC__StreamDecoderWriteCallback write_callback,
 13.1348 +	FLAC__StreamDecoderMetadataCallback metadata_callback,
 13.1349 +	FLAC__StreamDecoderErrorCallback error_callback,
 13.1350 +	void *client_data
 13.1351 +);
 13.1352 +
 13.1353 +/** Finish the decoding process.
 13.1354 + *  Flushes the decoding buffer, releases resources, resets the decoder
 13.1355 + *  settings to their defaults, and returns the decoder state to
 13.1356 + *  FLAC__STREAM_DECODER_UNINITIALIZED.
 13.1357 + *
 13.1358 + *  In the event of a prematurely-terminated decode, it is not strictly
 13.1359 + *  necessary to call this immediately before FLAC__stream_decoder_delete()
 13.1360 + *  but it is good practice to match every FLAC__stream_decoder_init_*()
 13.1361 + *  with a FLAC__stream_decoder_finish().
 13.1362 + *
 13.1363 + * \param  decoder  An uninitialized decoder instance.
 13.1364 + * \assert
 13.1365 + *    \code decoder != NULL \endcode
 13.1366 + * \retval FLAC__bool
 13.1367 + *    \c false if MD5 checking is on AND a STREAMINFO block was available
 13.1368 + *    AND the MD5 signature in the STREAMINFO block was non-zero AND the
 13.1369 + *    signature does not match the one computed by the decoder; else
 13.1370 + *    \c true.
 13.1371 + */
 13.1372 +FLAC_API FLAC__bool FLAC__stream_decoder_finish(FLAC__StreamDecoder *decoder);
 13.1373 +
 13.1374 +/** Flush the stream input.
 13.1375 + *  The decoder's input buffer will be cleared and the state set to
 13.1376 + *  \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.  This will also turn
 13.1377 + *  off MD5 checking.
 13.1378 + *
 13.1379 + * \param  decoder  A decoder instance.
 13.1380 + * \assert
 13.1381 + *    \code decoder != NULL \endcode
 13.1382 + * \retval FLAC__bool
 13.1383 + *    \c true if successful, else \c false if a memory allocation
 13.1384 + *    error occurs (in which case the state will be set to
 13.1385 + *    \c FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR).
 13.1386 + */
 13.1387 +FLAC_API FLAC__bool FLAC__stream_decoder_flush(FLAC__StreamDecoder *decoder);
 13.1388 +
 13.1389 +/** Reset the decoding process.
 13.1390 + *  The decoder's input buffer will be cleared and the state set to
 13.1391 + *  \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.  This is similar to
 13.1392 + *  FLAC__stream_decoder_finish() except that the settings are
 13.1393 + *  preserved; there is no need to call FLAC__stream_decoder_init_*()
 13.1394 + *  before decoding again.  MD5 checking will be restored to its original
 13.1395 + *  setting.
 13.1396 + *
 13.1397 + *  If the decoder is seekable, or was initialized with
 13.1398 + *  FLAC__stream_decoder_init*_FILE() or FLAC__stream_decoder_init*_file(),
 13.1399 + *  the decoder will also attempt to seek to the beginning of the file.
 13.1400 + *  If this rewind fails, this function will return \c false.  It follows
 13.1401 + *  that FLAC__stream_decoder_reset() cannot be used when decoding from
 13.1402 + *  \c stdin.
 13.1403 + *
 13.1404 + *  If the decoder was initialized with FLAC__stream_encoder_init*_stream()
 13.1405 + *  and is not seekable (i.e. no seek callback was provided or the seek
 13.1406 + *  callback returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED), it
 13.1407 + *  is the duty of the client to start feeding data from the beginning of
 13.1408 + *  the stream on the next FLAC__stream_decoder_process() or
 13.1409 + *  FLAC__stream_decoder_process_interleaved() call.
 13.1410 + *
 13.1411 + * \param  decoder  A decoder instance.
 13.1412 + * \assert
 13.1413 + *    \code decoder != NULL \endcode
 13.1414 + * \retval FLAC__bool
 13.1415 + *    \c true if successful, else \c false if a memory allocation occurs
 13.1416 + *    (in which case the state will be set to
 13.1417 + *    \c FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR) or a seek error
 13.1418 + *    occurs (the state will be unchanged).
 13.1419 + */
 13.1420 +FLAC_API FLAC__bool FLAC__stream_decoder_reset(FLAC__StreamDecoder *decoder);
 13.1421 +
 13.1422 +/** Decode one metadata block or audio frame.
 13.1423 + *  This version instructs the decoder to decode a either a single metadata
 13.1424 + *  block or a single frame and stop, unless the callbacks return a fatal
 13.1425 + *  error or the read callback returns
 13.1426 + *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
 13.1427 + *
 13.1428 + *  As the decoder needs more input it will call the read callback.
 13.1429 + *  Depending on what was decoded, the metadata or write callback will be
 13.1430 + *  called with the decoded metadata block or audio frame.
 13.1431 + *
 13.1432 + *  Unless there is a fatal read error or end of stream, this function
 13.1433 + *  will return once one whole frame is decoded.  In other words, if the
 13.1434 + *  stream is not synchronized or points to a corrupt frame header, the
 13.1435 + *  decoder will continue to try and resync until it gets to a valid
 13.1436 + *  frame, then decode one frame, then return.  If the decoder points to
 13.1437 + *  a frame whose frame CRC in the frame footer does not match the
 13.1438 + *  computed frame CRC, this function will issue a
 13.1439 + *  FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH error to the
 13.1440 + *  error callback, and return, having decoded one complete, although
 13.1441 + *  corrupt, frame.  (Such corrupted frames are sent as silence of the
 13.1442 + *  correct length to the write callback.)
 13.1443 + *
 13.1444 + * \param  decoder  An initialized decoder instance.
 13.1445 + * \assert
 13.1446 + *    \code decoder != NULL \endcode
 13.1447 + * \retval FLAC__bool
 13.1448 + *    \c false if any fatal read, write, or memory allocation error
 13.1449 + *    occurred (meaning decoding must stop), else \c true; for more
 13.1450 + *    information about the decoder, check the decoder state with
 13.1451 + *    FLAC__stream_decoder_get_state().
 13.1452 + */
 13.1453 +FLAC_API FLAC__bool FLAC__stream_decoder_process_single(FLAC__StreamDecoder *decoder);
 13.1454 +
 13.1455 +/** Decode until the end of the metadata.
 13.1456 + *  This version instructs the decoder to decode from the current position
 13.1457 + *  and continue until all the metadata has been read, or until the
 13.1458 + *  callbacks return a fatal error or the read callback returns
 13.1459 + *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
 13.1460 + *
 13.1461 + *  As the decoder needs more input it will call the read callback.
 13.1462 + *  As each metadata block is decoded, the metadata callback will be called
 13.1463 + *  with the decoded metadata.
 13.1464 + *
 13.1465 + * \param  decoder  An initialized decoder instance.
 13.1466 + * \assert
 13.1467 + *    \code decoder != NULL \endcode
 13.1468 + * \retval FLAC__bool
 13.1469 + *    \c false if any fatal read, write, or memory allocation error
 13.1470 + *    occurred (meaning decoding must stop), else \c true; for more
 13.1471 + *    information about the decoder, check the decoder state with
 13.1472 + *    FLAC__stream_decoder_get_state().
 13.1473 + */
 13.1474 +FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_metadata(FLAC__StreamDecoder *decoder);
 13.1475 +
 13.1476 +/** Decode until the end of the stream.
 13.1477 + *  This version instructs the decoder to decode from the current position
 13.1478 + *  and continue until the end of stream (the read callback returns
 13.1479 + *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM), or until the
 13.1480 + *  callbacks return a fatal error.
 13.1481 + *
 13.1482 + *  As the decoder needs more input it will call the read callback.
 13.1483 + *  As each metadata block and frame is decoded, the metadata or write
 13.1484 + *  callback will be called with the decoded metadata or frame.
 13.1485 + *
 13.1486 + * \param  decoder  An initialized decoder instance.
 13.1487 + * \assert
 13.1488 + *    \code decoder != NULL \endcode
 13.1489 + * \retval FLAC__bool
 13.1490 + *    \c false if any fatal read, write, or memory allocation error
 13.1491 + *    occurred (meaning decoding must stop), else \c true; for more
 13.1492 + *    information about the decoder, check the decoder state with
 13.1493 + *    FLAC__stream_decoder_get_state().
 13.1494 + */
 13.1495 +FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_stream(FLAC__StreamDecoder *decoder);
 13.1496 +
 13.1497 +/** Skip one audio frame.
 13.1498 + *  This version instructs the decoder to 'skip' a single frame and stop,
 13.1499 + *  unless the callbacks return a fatal error or the read callback returns
 13.1500 + *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
 13.1501 + *
 13.1502 + *  The decoding flow is the same as what occurs when
 13.1503 + *  FLAC__stream_decoder_process_single() is called to process an audio
 13.1504 + *  frame, except that this function does not decode the parsed data into
 13.1505 + *  PCM or call the write callback.  The integrity of the frame is still
 13.1506 + *  checked the same way as in the other process functions.
 13.1507 + *
 13.1508 + *  This function will return once one whole frame is skipped, in the
 13.1509 + *  same way that FLAC__stream_decoder_process_single() will return once
 13.1510 + *  one whole frame is decoded.
 13.1511 + *
 13.1512 + *  This function can be used in more quickly determining FLAC frame
 13.1513 + *  boundaries when decoding of the actual data is not needed, for
 13.1514 + *  example when an application is separating a FLAC stream into frames
 13.1515 + *  for editing or storing in a container.  To do this, the application
 13.1516 + *  can use FLAC__stream_decoder_skip_single_frame() to quickly advance
 13.1517 + *  to the next frame, then use
 13.1518 + *  FLAC__stream_decoder_get_decode_position() to find the new frame
 13.1519 + *  boundary.
 13.1520 + *
 13.1521 + *  This function should only be called when the stream has advanced
 13.1522 + *  past all the metadata, otherwise it will return \c false.
 13.1523 + *
 13.1524 + * \param  decoder  An initialized decoder instance not in a metadata
 13.1525 + *                  state.
 13.1526 + * \assert
 13.1527 + *    \code decoder != NULL \endcode
 13.1528 + * \retval FLAC__bool
 13.1529 + *    \c false if any fatal read, write, or memory allocation error
 13.1530 + *    occurred (meaning decoding must stop), or if the decoder
 13.1531 + *    is in the FLAC__STREAM_DECODER_SEARCH_FOR_METADATA or
 13.1532 + *    FLAC__STREAM_DECODER_READ_METADATA state, else \c true; for more
 13.1533 + *    information about the decoder, check the decoder state with
 13.1534 + *    FLAC__stream_decoder_get_state().
 13.1535 + */
 13.1536 +FLAC_API FLAC__bool FLAC__stream_decoder_skip_single_frame(FLAC__StreamDecoder *decoder);
 13.1537 +
 13.1538 +/** Flush the input and seek to an absolute sample.
 13.1539 + *  Decoding will resume at the given sample.  Note that because of
 13.1540 + *  this, the next write callback may contain a partial block.  The
 13.1541 + *  client must support seeking the input or this function will fail
 13.1542 + *  and return \c false.  Furthermore, if the decoder state is
 13.1543 + *  \c FLAC__STREAM_DECODER_SEEK_ERROR, then the decoder must be flushed
 13.1544 + *  with FLAC__stream_decoder_flush() or reset with
 13.1545 + *  FLAC__stream_decoder_reset() before decoding can continue.
 13.1546 + *
 13.1547 + * \param  decoder  A decoder instance.
 13.1548 + * \param  sample   The target sample number to seek to.
 13.1549 + * \assert
 13.1550 + *    \code decoder != NULL \endcode
 13.1551 + * \retval FLAC__bool
 13.1552 + *    \c true if successful, else \c false.
 13.1553 + */
 13.1554 +FLAC_API FLAC__bool FLAC__stream_decoder_seek_absolute(FLAC__StreamDecoder *decoder, FLAC__uint64 sample);
 13.1555 +
 13.1556 +/* \} */
 13.1557 +
 13.1558 +#ifdef __cplusplus
 13.1559 +}
 13.1560 +#endif
 13.1561 +
 13.1562 +#endif
    14.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    14.2 +++ b/Xcode/Frameworks/FLAC.framework/Versions/A/Headers/FLAC/stream_encoder.h	Mon Jan 09 01:58:40 2012 -0500
    14.3 @@ -0,0 +1,1768 @@
    14.4 +/* libFLAC - Free Lossless Audio Codec library
    14.5 + * Copyright (C) 2000,2001,2002,2003,2004,2005,2006,2007  Josh Coalson
    14.6 + *
    14.7 + * Redistribution and use in source and binary forms, with or without
    14.8 + * modification, are permitted provided that the following conditions
    14.9 + * are met:
   14.10 + *
   14.11 + * - Redistributions of source code must retain the above copyright
   14.12 + * notice, this list of conditions and the following disclaimer.
   14.13 + *
   14.14 + * - Redistributions in binary form must reproduce the above copyright
   14.15 + * notice, this list of conditions and the following disclaimer in the
   14.16 + * documentation and/or other materials provided with the distribution.
   14.17 + *
   14.18 + * - Neither the name of the Xiph.org Foundation nor the names of its
   14.19 + * contributors may be used to endorse or promote products derived from
   14.20 + * this software without specific prior written permission.
   14.21 + *
   14.22 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   14.23 + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   14.24 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
   14.25 + * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
   14.26 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
   14.27 + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
   14.28 + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
   14.29 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
   14.30 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
   14.31 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
   14.32 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   14.33 + */
   14.34 +
   14.35 +#ifndef FLAC__STREAM_ENCODER_H
   14.36 +#define FLAC__STREAM_ENCODER_H
   14.37 +
   14.38 +#include <stdio.h> /* for FILE */
   14.39 +#include "export.h"
   14.40 +#include "format.h"
   14.41 +#include "stream_decoder.h"
   14.42 +
   14.43 +#ifdef __cplusplus
   14.44 +extern "C" {
   14.45 +#endif
   14.46 +
   14.47 +
   14.48 +/** \file include/FLAC/stream_encoder.h
   14.49 + *
   14.50 + *  \brief
   14.51 + *  This module contains the functions which implement the stream
   14.52 + *  encoder.
   14.53 + *
   14.54 + *  See the detailed documentation in the
   14.55 + *  \link flac_stream_encoder stream encoder \endlink module.
   14.56 + */
   14.57 +
   14.58 +/** \defgroup flac_encoder FLAC/ \*_encoder.h: encoder interfaces
   14.59 + *  \ingroup flac
   14.60 + *
   14.61 + *  \brief
   14.62 + *  This module describes the encoder layers provided by libFLAC.
   14.63 + *
   14.64 + * The stream encoder can be used to encode complete streams either to the
   14.65 + * client via callbacks, or directly to a file, depending on how it is
   14.66 + * initialized.  When encoding via callbacks, the client provides a write
   14.67 + * callback which will be called whenever FLAC data is ready to be written.
   14.68 + * If the client also supplies a seek callback, the encoder will also
   14.69 + * automatically handle the writing back of metadata discovered while
   14.70 + * encoding, like stream info, seek points offsets, etc.  When encoding to
   14.71 + * a file, the client needs only supply a filename or open \c FILE* and an
   14.72 + * optional progress callback for periodic notification of progress; the
   14.73 + * write and seek callbacks are supplied internally.  For more info see the
   14.74 + * \link flac_stream_encoder stream encoder \endlink module.
   14.75 + */
   14.76 +
   14.77 +/** \defgroup flac_stream_encoder FLAC/stream_encoder.h: stream encoder interface
   14.78 + *  \ingroup flac_encoder
   14.79 + *
   14.80 + *  \brief
   14.81 + *  This module contains the functions which implement the stream
   14.82 + *  encoder.
   14.83 + *
   14.84 + * The stream encoder can encode to native FLAC, and optionally Ogg FLAC
   14.85 + * (check FLAC_API_SUPPORTS_OGG_FLAC) streams and files.
   14.86 + *
   14.87 + * The basic usage of this encoder is as follows:
   14.88 + * - The program creates an instance of an encoder using
   14.89 + *   FLAC__stream_encoder_new().
   14.90 + * - The program overrides the default settings using
   14.91 + *   FLAC__stream_encoder_set_*() functions.  At a minimum, the following
   14.92 + *   functions should be called:
   14.93 + *   - FLAC__stream_encoder_set_channels()
   14.94 + *   - FLAC__stream_encoder_set_bits_per_sample()
   14.95 + *   - FLAC__stream_encoder_set_sample_rate()
   14.96 + *   - FLAC__stream_encoder_set_ogg_serial_number() (if encoding to Ogg FLAC)
   14.97 + *   - FLAC__stream_encoder_set_total_samples_estimate() (if known)
   14.98 + * - If the application wants to control the compression level or set its own
   14.99 + *   metadata, then the following should also be called:
  14.100 + *   - FLAC__stream_encoder_set_compression_level()
  14.101 + *   - FLAC__stream_encoder_set_verify()
  14.102 + *   - FLAC__stream_encoder_set_metadata()
  14.103 + * - The rest of the set functions should only be called if the client needs
  14.104 + *   exact control over how the audio is compressed; thorough understanding
  14.105 + *   of the FLAC format is necessary to achieve good results.
  14.106 + * - The program initializes the instance to validate the settings and
  14.107 + *   prepare for encoding using
  14.108 + *   - FLAC__stream_encoder_init_stream() or FLAC__stream_encoder_init_FILE()
  14.109 + *     or FLAC__stream_encoder_init_file() for native FLAC
  14.110 + *   - FLAC__stream_encoder_init_ogg_stream() or FLAC__stream_encoder_init_ogg_FILE()
  14.111 + *     or FLAC__stream_encoder_init_ogg_file() for Ogg FLAC
  14.112 + * - The program calls FLAC__stream_encoder_process() or
  14.113 + *   FLAC__stream_encoder_process_interleaved() to encode data, which
  14.114 + *   subsequently calls the callbacks when there is encoder data ready
  14.115 + *   to be written.
  14.116 + * - The program finishes the encoding with FLAC__stream_encoder_finish(),
  14.117 + *   which causes the encoder to encode any data still in its input pipe,
  14.118 + *   update the metadata with the final encoding statistics if output
  14.119 + *   seeking is possible, and finally reset the encoder to the
  14.120 + *   uninitialized state.
  14.121 + * - The instance may be used again or deleted with
  14.122 + *   FLAC__stream_encoder_delete().
  14.123 + *
  14.124 + * In more detail, the stream encoder functions similarly to the
  14.125 + * \link flac_stream_decoder stream decoder \endlink, but has fewer
  14.126 + * callbacks and more options.  Typically the client will create a new
  14.127 + * instance by calling FLAC__stream_encoder_new(), then set the necessary
  14.128 + * parameters with FLAC__stream_encoder_set_*(), and initialize it by
  14.129 + * calling one of the FLAC__stream_encoder_init_*() functions.
  14.130 + *
  14.131 + * Unlike the decoders, the stream encoder has many options that can
  14.132 + * affect the speed and compression ratio.  When setting these parameters
  14.133 + * you should have some basic knowledge of the format (see the
  14.134 + * <A HREF="../documentation.html#format">user-level documentation</A>
  14.135 + * or the <A HREF="../format.html">formal description</A>).  The
  14.136 + * FLAC__stream_encoder_set_*() functions themselves do not validate the
  14.137 + * values as many are interdependent.  The FLAC__stream_encoder_init_*()
  14.138 + * functions will do this, so make sure to pay attention to the state
  14.139 + * returned by FLAC__stream_encoder_init_*() to make sure that it is
  14.140 + * FLAC__STREAM_ENCODER_INIT_STATUS_OK.  Any parameters that are not set
  14.141 + * before FLAC__stream_encoder_init_*() will take on the defaults from
  14.142 + * the constructor.
  14.143 + *
  14.144 + * There are three initialization functions for native FLAC, one for
  14.145 + * setting up the encoder to encode FLAC data to the client via
  14.146 + * callbacks, and two for encoding directly to a file.
  14.147 + *
  14.148 + * For encoding via callbacks, use FLAC__stream_encoder_init_stream().
  14.149 + * You must also supply a write callback which will be called anytime
  14.150 + * there is raw encoded data to write.  If the client can seek the output
  14.151 + * it is best to also supply seek and tell callbacks, as this allows the
  14.152 + * encoder to go back after encoding is finished to write back
  14.153 + * information that was collected while encoding, like seek point offsets,
  14.154 + * frame sizes, etc.
  14.155 + *
  14.156 + * For encoding directly to a file, use FLAC__stream_encoder_init_FILE()
  14.157 + * or FLAC__stream_encoder_init_file().  Then you must only supply a
  14.158 + * filename or open \c FILE*; the encoder will handle all the callbacks
  14.159 + * internally.  You may also supply a progress callback for periodic
  14.160 + * notification of the encoding progress.
  14.161 + *
  14.162 + * There are three similarly-named init functions for encoding to Ogg
  14.163 + * FLAC streams.  Check \c FLAC_API_SUPPORTS_OGG_FLAC to find out if the
  14.164 + * library has been built with Ogg support.
  14.165 + *
  14.166 + * The call to FLAC__stream_encoder_init_*() currently will also immediately
  14.167 + * call the write callback several times, once with the \c fLaC signature,
  14.168 + * and once for each encoded metadata block.  Note that for Ogg FLAC
  14.169 + * encoding you will usually get at least twice the number of callbacks than
  14.170 + * with native FLAC, one for the Ogg page header and one for the page body.
  14.171 + *
  14.172 + * After initializing the instance, the client may feed audio data to the
  14.173 + * encoder in one of two ways:
  14.174 + *
  14.175 + * - Channel separate, through FLAC__stream_encoder_process() - The client
  14.176 + *   will pass an array of pointers to buffers, one for each channel, to
  14.177 + *   the encoder, each of the same length.  The samples need not be
  14.178 + *   block-aligned, but each channel should have the same number of samples.
  14.179 + * - Channel interleaved, through
  14.180 + *   FLAC__stream_encoder_process_interleaved() - The client will pass a single
  14.181 + *   pointer to data that is channel-interleaved (i.e. channel0_sample0,
  14.182 + *   channel1_sample0, ... , channelN_sample0, channel0_sample1, ...).
  14.183 + *   Again, the samples need not be block-aligned but they must be
  14.184 + *   sample-aligned, i.e. the first value should be channel0_sample0 and
  14.185 + *   the last value channelN_sampleM.
  14.186 + *
  14.187 + * Note that for either process call, each sample in the buffers should be a
  14.188 + * signed integer, right-justified to the resolution set by
  14.189 + * FLAC__stream_encoder_set_bits_per_sample().  For example, if the resolution
  14.190 + * is 16 bits per sample, the samples should all be in the range [-32768,32767].
  14.191 + *
  14.192 + * When the client is finished encoding data, it calls
  14.193 + * FLAC__stream_encoder_finish(), which causes the encoder to encode any
  14.194 + * data still in its input pipe, and call the metadata callback with the
  14.195 + * final encoding statistics.  Then the instance may be deleted with
  14.196 + * FLAC__stream_encoder_delete() or initialized again to encode another
  14.197 + * stream.
  14.198 + *
  14.199 + * For programs that write their own metadata, but that do not know the
  14.200 + * actual metadata until after encoding, it is advantageous to instruct
  14.201 + * the encoder to write a PADDING block of the correct size, so that
  14.202 + * instead of rewriting the whole stream after encoding, the program can
  14.203 + * just overwrite the PADDING block.  If only the maximum size of the
  14.204 + * metadata is known, the program can write a slightly larger padding
  14.205 + * block, then split it after encoding.
  14.206 + *
  14.207 + * Make sure you understand how lengths are calculated.  All FLAC metadata
  14.208 + * blocks have a 4 byte header which contains the type and length.  This
  14.209 + * length does not include the 4 bytes of the header.  See the format page
  14.210 + * for the specification of metadata blocks and their lengths.
  14.211 + *
  14.212 + * \note
  14.213 + * If you are writing the FLAC data to a file via callbacks, make sure it
  14.214 + * is open for update (e.g. mode "w+" for stdio streams).  This is because
  14.215 + * after the first encoding pass, the encoder will try to seek back to the
  14.216 + * beginning of the stream, to the STREAMINFO block, to write some data
  14.217 + * there.  (If using FLAC__stream_encoder_init*_file() or
  14.218 + * FLAC__stream_encoder_init*_FILE(), the file is managed internally.)
  14.219 + *
  14.220 + * \note
  14.221 + * The "set" functions may only be called when the encoder is in the
  14.222 + * state FLAC__STREAM_ENCODER_UNINITIALIZED, i.e. after
  14.223 + * FLAC__stream_encoder_new() or FLAC__stream_encoder_finish(), but
  14.224 + * before FLAC__stream_encoder_init_*().  If this is the case they will
  14.225 + * return \c true, otherwise \c false.
  14.226 + *
  14.227 + * \note
  14.228 + * FLAC__stream_encoder_finish() resets all settings to the constructor
  14.229 + * defaults.
  14.230 + *
  14.231 + * \{
  14.232 + */
  14.233 +
  14.234 +
  14.235 +/** State values for a FLAC__StreamEncoder.
  14.236 + *
  14.237 + * The encoder's state can be obtained by calling FLAC__stream_encoder_get_state().
  14.238 + *
  14.239 + * If the encoder gets into any other state besides \c FLAC__STREAM_ENCODER_OK
  14.240 + * or \c FLAC__STREAM_ENCODER_UNINITIALIZED, it becomes invalid for encoding and
  14.241 + * must be deleted with FLAC__stream_encoder_delete().
  14.242 + */
  14.243 +typedef enum {
  14.244 +
  14.245 +	FLAC__STREAM_ENCODER_OK = 0,
  14.246 +	/**< The encoder is in the normal OK state and samples can be processed. */
  14.247 +
  14.248 +	FLAC__STREAM_ENCODER_UNINITIALIZED,
  14.249 +	/**< The encoder is in the uninitialized state; one of the
  14.250 +	 * FLAC__stream_encoder_init_*() functions must be called before samples
  14.251 +	 * can be processed.
  14.252 +	 */
  14.253 +
  14.254 +	FLAC__STREAM_ENCODER_OGG_ERROR,
  14.255 +	/**< An error occurred in the underlying Ogg layer.  */
  14.256 +
  14.257 +	FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR,
  14.258 +	/**< An error occurred in the underlying verify stream decoder;
  14.259 +	 * check FLAC__stream_encoder_get_verify_decoder_state().
  14.260 +	 */
  14.261 +
  14.262 +	FLAC__STREAM_ENCODER_VERIFY_MISMATCH_IN_AUDIO_DATA,
  14.263 +	/**< The verify decoder detected a mismatch between the original
  14.264 +	 * audio signal and the decoded audio signal.
  14.265 +	 */
  14.266 +
  14.267 +	FLAC__STREAM_ENCODER_CLIENT_ERROR,
  14.268 +	/**< One of the callbacks returned a fatal error. */
  14.269 +
  14.270 +	FLAC__STREAM_ENCODER_IO_ERROR,
  14.271 +	/**< An I/O error occurred while opening/reading/writing a file.
  14.272 +	 * Check \c errno.
  14.273 +	 */
  14.274 +
  14.275 +	FLAC__STREAM_ENCODER_FRAMING_ERROR,
  14.276 +	/**< An error occurred while writing the stream; usually, the
  14.277 +	 * write_callback returned an error.
  14.278 +	 */
  14.279 +
  14.280 +	FLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR
  14.281 +	/**< Memory allocation failed. */
  14.282 +
  14.283 +} FLAC__StreamEncoderState;
  14.284 +
  14.285 +/** Maps a FLAC__StreamEncoderState to a C string.
  14.286 + *
  14.287 + *  Using a FLAC__StreamEncoderState as the index to this array
  14.288 + *  will give the string equivalent.  The contents should not be modified.
  14.289 + */
  14.290 +extern FLAC_API const char * const FLAC__StreamEncoderStateString[];
  14.291 +
  14.292 +
  14.293 +/** Possible return values for the FLAC__stream_encoder_init_*() functions.
  14.294 + */
  14.295 +typedef enum {
  14.296 +
  14.297 +	FLAC__STREAM_ENCODER_INIT_STATUS_OK = 0,
  14.298 +	/**< Initialization was successful. */
  14.299 +
  14.300 +	FLAC__STREAM_ENCODER_INIT_STATUS_ENCODER_ERROR,
  14.301 +	/**< General failure to set up encoder; call FLAC__stream_encoder_get_state() for cause. */
  14.302 +
  14.303 +	FLAC__STREAM_ENCODER_INIT_STATUS_UNSUPPORTED_CONTAINER,
  14.304 +	/**< The library was not compiled with support for the given container
  14.305 +	 * format.
  14.306 +	 */
  14.307 +
  14.308 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_CALLBACKS,
  14.309 +	/**< A required callback was not supplied. */
  14.310 +
  14.311 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_NUMBER_OF_CHANNELS,
  14.312 +	/**< The encoder has an invalid setting for number of channels. */
  14.313 +
  14.314 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BITS_PER_SAMPLE,
  14.315 +	/**< The encoder has an invalid setting for bits-per-sample.
  14.316 +	 * FLAC supports 4-32 bps but the reference encoder currently supports
  14.317 +	 * only up to 24 bps.
  14.318 +	 */
  14.319 +
  14.320 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_SAMPLE_RATE,
  14.321 +	/**< The encoder has an invalid setting for the input sample rate. */
  14.322 +
  14.323 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BLOCK_SIZE,
  14.324 +	/**< The encoder has an invalid setting for the block size. */
  14.325 +
  14.326 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_MAX_LPC_ORDER,
  14.327 +	/**< The encoder has an invalid setting for the maximum LPC order. */
  14.328 +
  14.329 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_QLP_COEFF_PRECISION,
  14.330 +	/**< The encoder has an invalid setting for the precision of the quantized linear predictor coefficients. */
  14.331 +
  14.332 +	FLAC__STREAM_ENCODER_INIT_STATUS_BLOCK_SIZE_TOO_SMALL_FOR_LPC_ORDER,
  14.333 +	/**< The specified block size is less than the maximum LPC order. */
  14.334 +
  14.335 +	FLAC__STREAM_ENCODER_INIT_STATUS_NOT_STREAMABLE,
  14.336 +	/**< The encoder is bound to the <A HREF="../format.html#subset">Subset</A> but other settings violate it. */
  14.337 +
  14.338 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_METADATA,
  14.339 +	/**< The metadata input to the encoder is invalid, in one of the following ways:
  14.340 +	 * - FLAC__stream_encoder_set_metadata() was called with a null pointer but a block count > 0
  14.341 +	 * - One of the metadata blocks contains an undefined type
  14.342 +	 * - It contains an illegal CUESHEET as checked by FLAC__format_cuesheet_is_legal()
  14.343 +	 * - It contains an illegal SEEKTABLE as checked by FLAC__format_seektable_is_legal()
  14.344 +	 * - It contains more than one SEEKTABLE block or more than one VORBIS_COMMENT block
  14.345 +	 */
  14.346 +
  14.347 +	FLAC__STREAM_ENCODER_INIT_STATUS_ALREADY_INITIALIZED
  14.348 +	/**< FLAC__stream_encoder_init_*() was called when the encoder was
  14.349 +	 * already initialized, usually because
  14.350 +	 * FLAC__stream_encoder_finish() was not called.
  14.351 +	 */
  14.352 +
  14.353 +} FLAC__StreamEncoderInitStatus;
  14.354 +
  14.355 +/** Maps a FLAC__StreamEncoderInitStatus to a C string.
  14.356 + *
  14.357 + *  Using a FLAC__StreamEncoderInitStatus as the index to this array
  14.358 + *  will give the string equivalent.  The contents should not be modified.
  14.359 + */
  14.360 +extern FLAC_API const char * const FLAC__StreamEncoderInitStatusString[];
  14.361 +
  14.362 +
  14.363 +/** Return values for the FLAC__StreamEncoder read callback.
  14.364 + */
  14.365 +typedef enum {
  14.366 +
  14.367 +	FLAC__STREAM_ENCODER_READ_STATUS_CONTINUE,
  14.368 +	/**< The read was OK and decoding can continue. */
  14.369 +
  14.370 +	FLAC__STREAM_ENCODER_READ_STATUS_END_OF_STREAM,
  14.371 +	/**< The read was attempted at the end of the stream. */
  14.372 +
  14.373 +	FLAC__STREAM_ENCODER_READ_STATUS_ABORT,
  14.374 +	/**< An unrecoverable error occurred. */
  14.375 +
  14.376 +	FLAC__STREAM_ENCODER_READ_STATUS_UNSUPPORTED
  14.377 +	/**< Client does not support reading back from the output. */
  14.378 +
  14.379 +} FLAC__StreamEncoderReadStatus;
  14.380 +
  14.381 +/** Maps a FLAC__StreamEncoderReadStatus to a C string.
  14.382 + *
  14.383 + *  Using a FLAC__StreamEncoderReadStatus as the index to this array
  14.384 + *  will give the string equivalent.  The contents should not be modified.
  14.385 + */
  14.386 +extern FLAC_API const char * const FLAC__StreamEncoderReadStatusString[];
  14.387 +
  14.388 +
  14.389 +/** Return values for the FLAC__StreamEncoder write callback.
  14.390 + */
  14.391 +typedef enum {
  14.392 +
  14.393 +	FLAC__STREAM_ENCODER_WRITE_STATUS_OK = 0,
  14.394 +	/**< The write was OK and encoding can continue. */
  14.395 +
  14.396 +	FLAC__STREAM_ENCODER_WRITE_STATUS_FATAL_ERROR
  14.397 +	/**< An unrecoverable error occurred.  The encoder will return from the process call. */
  14.398 +
  14.399 +} FLAC__StreamEncoderWriteStatus;
  14.400 +
  14.401 +/** Maps a FLAC__StreamEncoderWriteStatus to a C string.
  14.402 + *
  14.403 + *  Using a FLAC__StreamEncoderWriteStatus as the index to this array
  14.404 + *  will give the string equivalent.  The contents should not be modified.
  14.405 + */
  14.406 +extern FLAC_API const char * const FLAC__StreamEncoderWriteStatusString[];
  14.407 +
  14.408 +
  14.409 +/** Return values for the FLAC__StreamEncoder seek callback.
  14.410 + */
  14.411 +typedef enum {
  14.412 +
  14.413 +	FLAC__STREAM_ENCODER_SEEK_STATUS_OK,
  14.414 +	/**< The seek was OK and encoding can continue. */
  14.415 +
  14.416 +	FLAC__STREAM_ENCODER_SEEK_STATUS_ERROR,
  14.417 +	/**< An unrecoverable error occurred. */
  14.418 +
  14.419 +	FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
  14.420 +	/**< Client does not support seeking. */
  14.421 +
  14.422 +} FLAC__StreamEncoderSeekStatus;
  14.423 +
  14.424 +/** Maps a FLAC__StreamEncoderSeekStatus to a C string.
  14.425 + *
  14.426 + *  Using a FLAC__StreamEncoderSeekStatus as the index to this array
  14.427 + *  will give the string equivalent.  The contents should not be modified.
  14.428 + */
  14.429 +extern FLAC_API const char * const FLAC__StreamEncoderSeekStatusString[];
  14.430 +
  14.431 +
  14.432 +/** Return values for the FLAC__StreamEncoder tell callback.
  14.433 + */
  14.434 +typedef enum {
  14.435 +
  14.436 +	FLAC__STREAM_ENCODER_TELL_STATUS_OK,
  14.437 +	/**< The tell was OK and encoding can continue. */
  14.438 +
  14.439 +	FLAC__STREAM_ENCODER_TELL_STATUS_ERROR,
  14.440 +	/**< An unrecoverable error occurred. */
  14.441 +
  14.442 +	FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
  14.443 +	/**< Client does not support seeking. */
  14.444 +
  14.445 +} FLAC__StreamEncoderTellStatus;
  14.446 +
  14.447 +/** Maps a FLAC__StreamEncoderTellStatus to a C string.
  14.448 + *
  14.449 + *  Using a FLAC__StreamEncoderTellStatus as the index to this array
  14.450 + *  will give the string equivalent.  The contents should not be modified.
  14.451 + */
  14.452 +extern FLAC_API const char * const FLAC__StreamEncoderTellStatusString[];
  14.453 +
  14.454 +
  14.455 +/***********************************************************************
  14.456 + *
  14.457 + * class FLAC__StreamEncoder
  14.458 + *
  14.459 + ***********************************************************************/
  14.460 +
  14.461 +struct FLAC__StreamEncoderProtected;
  14.462 +struct FLAC__StreamEncoderPrivate;
  14.463 +/** The opaque structure definition for the stream encoder type.
  14.464 + *  See the \link flac_stream_encoder stream encoder module \endlink
  14.465 + *  for a detailed description.
  14.466 + */
  14.467 +typedef struct {
  14.468 +	struct FLAC__StreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
  14.469 +	struct FLAC__StreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
  14.470 +} FLAC__StreamEncoder;
  14.471 +
  14.472 +/** Signature for the read callback.
  14.473 + *
  14.474 + *  A function pointer matching this signature must be passed to
  14.475 + *  FLAC__stream_encoder_init_ogg_stream() if seeking is supported.
  14.476 + *  The supplied function will be called when the encoder needs to read back
  14.477 + *  encoded data.  This happens during the metadata callback, when the encoder
  14.478 + *  has to read, modify, and rewrite the metadata (e.g. seekpoints) gathered
  14.479 + *  while encoding.  The address of the buffer to be filled is supplied, along
  14.480 + *  with the number of bytes the buffer can hold.  The callback may choose to
  14.481 + *  supply less data and modify the byte count but must be careful not to
  14.482 + *  overflow the buffer.  The callback then returns a status code chosen from
  14.483 + *  FLAC__StreamEncoderReadStatus.
  14.484 + *
  14.485 + * Here is an example of a read callback for stdio streams:
  14.486 + * \code
  14.487 + * FLAC__StreamEncoderReadStatus read_cb(const FLAC__StreamEncoder *encoder, FLAC__byte buffer[], size_t *bytes, void *client_data)
  14.488 + * {
  14.489 + *   FILE *file = ((MyClientData*)client_data)->file;
  14.490 + *   if(*bytes > 0) {
  14.491 + *     *bytes = fread(buffer, sizeof(FLAC__byte), *bytes, file);
  14.492 + *     if(ferror(file))
  14.493 + *       return FLAC__STREAM_ENCODER_READ_STATUS_ABORT;
  14.494 + *     else if(*bytes == 0)
  14.495 + *       return FLAC__STREAM_ENCODER_READ_STATUS_END_OF_STREAM;
  14.496 + *     else
  14.497 + *       return FLAC__STREAM_ENCODER_READ_STATUS_CONTINUE;
  14.498 + *   }
  14.499 + *   else
  14.500 + *     return FLAC__STREAM_ENCODER_READ_STATUS_ABORT;
  14.501 + * }
  14.502 + * \endcode
  14.503 + *
  14.504 + * \note In general, FLAC__StreamEncoder functions which change the
  14.505 + * state should not be called on the \a encoder while in the callback.
  14.506 + *
  14.507 + * \param  encoder  The encoder instance calling the callback.
  14.508 + * \param  buffer   A pointer to a location for the callee to store
  14.509 + *                  data to be encoded.
  14.510 + * \param  bytes    A pointer to the size of the buffer.  On entry
  14.511 + *                  to the callback, it contains the maximum number
  14.512 + *                  of bytes that may be stored in \a buffer.  The
  14.513 + *                  callee must set it to the actual number of bytes
  14.514 + *                  stored (0 in case of error or end-of-stream) before
  14.515 + *                  returning.
  14.516 + * \param  client_data  The callee's client data set through
  14.517 + *                      FLAC__stream_encoder_set_client_data().
  14.518 + * \retval FLAC__StreamEncoderReadStatus
  14.519 + *    The callee's return status.
  14.520 + */
  14.521 +typedef FLAC__StreamEncoderReadStatus (*FLAC__StreamEncoderReadCallback)(const FLAC__StreamEncoder *encoder, FLAC__byte buffer[], size_t *bytes, void *client_data);
  14.522 +
  14.523 +/** Signature for the write callback.
  14.524 + *
  14.525 + *  A function pointer matching this signature must be passed to
  14.526 + *  FLAC__stream_encoder_init*_stream().  The supplied function will be called
  14.527 + *  by the encoder anytime there is raw encoded data ready to write.  It may
  14.528 + *  include metadata mixed with encoded audio frames and the data is not
  14.529 + *  guaranteed to be aligned on frame or metadata block boundaries.
  14.530 + *
  14.531 + *  The only duty of the callback is to write out the \a bytes worth of data
  14.532 + *  in \a buffer to the current position in the output stream.  The arguments
  14.533 + *  \a samples and \a current_frame are purely informational.  If \a samples
  14.534 + *  is greater than \c 0, then \a current_frame will hold the current frame
  14.535 + *  number that is being written; otherwise it indicates that the write
  14.536 + *  callback is being called to write metadata.
  14.537 + *
  14.538 + * \note
  14.539 + * Unlike when writing to native FLAC, when writing to Ogg FLAC the
  14.540 + * write callback will be called twice when writing each audio
  14.541 + * frame; once for the page header, and once for the page body.
  14.542 + * When writing the page header, the \a samples argument to the
  14.543 + * write callback will be \c 0.
  14.544 + *
  14.545 + * \note In general, FLAC__StreamEncoder functions which change the
  14.546 + * state should not be called on the \a encoder while in the callback.
  14.547 + *
  14.548 + * \param  encoder  The encoder instance calling the callback.
  14.549 + * \param  buffer   An array of encoded data of length \a bytes.
  14.550 + * \param  bytes    The byte length of \a buffer.
  14.551 + * \param  samples  The number of samples encoded by \a buffer.
  14.552 + *                  \c 0 has a special meaning; see above.
  14.553 + * \param  current_frame  The number of the current frame being encoded.
  14.554 + * \param  client_data  The callee's client data set through
  14.555 + *                      FLAC__stream_encoder_init_*().
  14.556 + * \retval FLAC__StreamEncoderWriteStatus
  14.557 + *    The callee's return status.
  14.558 + */
  14.559 +typedef FLAC__StreamEncoderWriteStatus (*FLAC__StreamEncoderWriteCallback)(const FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], size_t bytes, unsigned samples, unsigned current_frame, void *client_data);
  14.560 +
  14.561 +/** Signature for the seek callback.
  14.562 + *
  14.563 + *  A function pointer matching this signature may be passed to
  14.564 + *  FLAC__stream_encoder_init*_stream().  The supplied function will be called
  14.565 + *  when the encoder needs to seek the output stream.  The encoder will pass
  14.566 + *  the absolute byte offset to seek to, 0 meaning the beginning of the stream.
  14.567 + *
  14.568 + * Here is an example of a seek callback for stdio streams:
  14.569 + * \code
  14.570 + * FLAC__StreamEncoderSeekStatus seek_cb(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data)
  14.571 + * {
  14.572 + *   FILE *file = ((MyClientData*)client_data)->file;
  14.573 + *   if(file == stdin)
  14.574 + *     return FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED;
  14.575 + *   else if(fseeko(file, (off_t)absolute_byte_offset, SEEK_SET) < 0)
  14.576 + *     return FLAC__STREAM_ENCODER_SEEK_STATUS_ERROR;
  14.577 + *   else
  14.578 + *     return FLAC__STREAM_ENCODER_SEEK_STATUS_OK;
  14.579 + * }
  14.580 + * \endcode
  14.581 + *
  14.582 + * \note In general, FLAC__StreamEncoder functions which change the
  14.583 + * state should not be called on the \a encoder while in the callback.
  14.584 + *
  14.585 + * \param  encoder  The encoder instance calling the callback.
  14.586 + * \param  absolute_byte_offset  The offset from the beginning of the stream
  14.587 + *                               to seek to.
  14.588 + * \param  client_data  The callee's client data set through
  14.589 + *                      FLAC__stream_encoder_init_*().
  14.590 + * \retval FLAC__StreamEncoderSeekStatus
  14.591 + *    The callee's return status.
  14.592 + */
  14.593 +typedef FLAC__StreamEncoderSeekStatus (*FLAC__StreamEncoderSeekCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
  14.594 +
  14.595 +/** Signature for the tell callback.
  14.596 + *
  14.597 + *  A function pointer matching this signature may be passed to
  14.598 + *  FLAC__stream_encoder_init*_stream().  The supplied function will be called
  14.599 + *  when the encoder needs to know the current position of the output stream.
  14.600 + *
  14.601 + * \warning
  14.602 + * The callback must return the true current byte offset of the output to
  14.603 + * which the encoder is writing.  If you are buffering the output, make
  14.604 + * sure and take this into account.  If you are writing directly to a
  14.605 + * FILE* from your write callback, ftell() is sufficient.  If you are
  14.606 + * writing directly to a file descriptor from your write callback, you
  14.607 + * can use lseek(fd, SEEK_CUR, 0).  The encoder may later seek back to
  14.608 + * these points to rewrite metadata after encoding.
  14.609 + *
  14.610 + * Here is an example of a tell callback for stdio streams:
  14.611 + * \code
  14.612 + * FLAC__StreamEncoderTellStatus tell_cb(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data)
  14.613 + * {
  14.614 + *   FILE *file = ((MyClientData*)client_data)->file;
  14.615 + *   off_t pos;
  14.616 + *   if(file == stdin)
  14.617 + *     return FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED;
  14.618 + *   else if((pos = ftello(file)) < 0)
  14.619 + *     return FLAC__STREAM_ENCODER_TELL_STATUS_ERROR;
  14.620 + *   else {
  14.621 + *     *absolute_byte_offset = (FLAC__uint64)pos;
  14.622 + *     return FLAC__STREAM_ENCODER_TELL_STATUS_OK;
  14.623 + *   }
  14.624 + * }
  14.625 + * \endcode
  14.626 + *
  14.627 + * \note In general, FLAC__StreamEncoder functions which change the
  14.628 + * state should not be called on the \a encoder while in the callback.
  14.629 + *
  14.630 + * \param  encoder  The encoder instance calling the callback.
  14.631 + * \param  absolute_byte_offset  The address at which to store the current
  14.632 + *                               position of the output.
  14.633 + * \param  client_data  The callee's client data set through
  14.634 + *                      FLAC__stream_encoder_init_*().
  14.635 + * \retval FLAC__StreamEncoderTellStatus
  14.636 + *    The callee's return status.
  14.637 + */
  14.638 +typedef FLAC__StreamEncoderTellStatus (*FLAC__StreamEncoderTellCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
  14.639 +
  14.640 +/** Signature for the metadata callback.
  14.641 + *
  14.642 + *  A function pointer matching this signature may be passed to
  14.643 + *  FLAC__stream_encoder_init*_stream().  The supplied function will be called
  14.644 + *  once at the end of encoding with the populated STREAMINFO structure.  This
  14.645 + *  is so the client can seek back to the beginning of the file and write the
  14.646 + *  STREAMINFO block with the correct statistics after encoding (like
  14.647 + *  minimum/maximum frame size and total samples).
  14.648 + *
  14.649 + * \note In general, FLAC__StreamEncoder functions which change the
  14.650 + * state should not be called on the \a encoder while in the callback.
  14.651 + *
  14.652 + * \param  encoder      The encoder instance calling the callback.
  14.653 + * \param  metadata     The final populated STREAMINFO block.
  14.654 + * \param  client_data  The callee's client data set through
  14.655 + *                      FLAC__stream_encoder_init_*().
  14.656 + */
  14.657 +typedef void (*FLAC__StreamEncoderMetadataCallback)(const FLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data);
  14.658 +
  14.659 +/** Signature for the progress callback.
  14.660 + *
  14.661 + *  A function pointer matching this signature may be passed to
  14.662 + *  FLAC__stream_encoder_init*_file() or FLAC__stream_encoder_init*_FILE().
  14.663 + *  The supplied function will be called when the encoder has finished
  14.664 + *  writing a frame.  The \c total_frames_estimate argument to the
  14.665 + *  callback will be based on the value from
  14.666 + *  FLAC__stream_encoder_set_total_samples_estimate().
  14.667 + *
  14.668 + * \note In general, FLAC__StreamEncoder functions which change the
  14.669 + * state should not be called on the \a encoder while in the callback.
  14.670 + *
  14.671 + * \param  encoder          The encoder instance calling the callback.
  14.672 + * \param  bytes_written    Bytes written so far.
  14.673 + * \param  samples_written  Samples written so far.
  14.674 + * \param  frames_written   Frames written so far.
  14.675 + * \param  total_frames_estimate  The estimate of the total number of
  14.676 + *                                frames to be written.
  14.677 + * \param  client_data      The callee's client data set through
  14.678 + *                          FLAC__stream_encoder_init_*().
  14.679 + */
  14.680 +typedef void (*FLAC__StreamEncoderProgressCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data);
  14.681 +
  14.682 +
  14.683 +/***********************************************************************
  14.684 + *
  14.685 + * Class constructor/destructor
  14.686 + *
  14.687 + ***********************************************************************/
  14.688 +
  14.689 +/** Create a new stream encoder instance.  The instance is created with
  14.690 + *  default settings; see the individual FLAC__stream_encoder_set_*()
  14.691 + *  functions for each setting's default.
  14.692 + *
  14.693 + * \retval FLAC__StreamEncoder*
  14.694 + *    \c NULL if there was an error allocating memory, else the new instance.
  14.695 + */
  14.696 +FLAC_API FLAC__StreamEncoder *FLAC__stream_encoder_new(void);
  14.697 +
  14.698 +/** Free an encoder instance.  Deletes the object pointed to by \a encoder.
  14.699 + *
  14.700 + * \param encoder  A pointer to an existing encoder.
  14.701 + * \assert
  14.702 + *    \code encoder != NULL \endcode
  14.703 + */
  14.704 +FLAC_API void FLAC__stream_encoder_delete(FLAC__StreamEncoder *encoder);
  14.705 +
  14.706 +
  14.707 +/***********************************************************************
  14.708 + *
  14.709 + * Public class method prototypes
  14.710 + *
  14.711 + ***********************************************************************/
  14.712 +
  14.713 +/** Set the serial number for the FLAC stream to use in the Ogg container.
  14.714 + *
  14.715 + * \note
  14.716 + * This does not need to be set for native FLAC encoding.
  14.717 + *
  14.718 + * \note
  14.719 + * It is recommended to set a serial number explicitly as the default of '0'
  14.720 + * may collide with other streams.
  14.721 + *
  14.722 + * \default \c 0
  14.723 + * \param  encoder        An encoder instance to set.
  14.724 + * \param  serial_number  See above.
  14.725 + * \assert
  14.726 + *    \code encoder != NULL \endcode
  14.727 + * \retval FLAC__bool
  14.728 + *    \c false if the encoder is already initialized, else \c true.
  14.729 + */
  14.730 +FLAC_API FLAC__bool FLAC__stream_encoder_set_ogg_serial_number(FLAC__StreamEncoder *encoder, long serial_number);
  14.731 +
  14.732 +/** Set the "verify" flag.  If \c true, the encoder will verify it's own
  14.733 + *  encoded output by feeding it through an internal decoder and comparing
  14.734 + *  the original signal against the decoded signal.  If a mismatch occurs,
  14.735 + *  the process call will return \c false.  Note that this will slow the
  14.736 + *  encoding process by the extra time required for decoding and comparison.
  14.737 + *
  14.738 + * \default \c false
  14.739 + * \param  encoder  An encoder instance to set.
  14.740 + * \param  value    Flag value (see above).
  14.741 + * \assert
  14.742 + *    \code encoder != NULL \endcode
  14.743 + * \retval FLAC__bool
  14.744 + *    \c false if the encoder is already initialized, else \c true.
  14.745 + */
  14.746 +FLAC_API FLAC__bool FLAC__stream_encoder_set_verify(FLAC__StreamEncoder *encoder, FLAC__bool value);
  14.747 +
  14.748 +/** Set the <A HREF="../format.html#subset">Subset</A> flag.  If \c true,
  14.749 + *  the encoder will comply with the Subset and will check the
  14.750 + *  settings during FLAC__stream_encoder_init_*() to see if all settings
  14.751 + *  comply.  If \c false, the settings may take advantage of the full
  14.752 + *  range that the format allows.
  14.753 + *
  14.754 + *  Make sure you know what it entails before setting this to \c false.
  14.755 + *
  14.756 + * \default \c true
  14.757 + * \param  encoder  An encoder instance to set.
  14.758 + * \param  value    Flag value (see above).
  14.759 + * \assert
  14.760 + *    \code encoder != NULL \endcode
  14.761 + * \retval FLAC__bool
  14.762 + *    \c false if the encoder is already initialized, else \c true.
  14.763 + */
  14.764 +FLAC_API FLAC__bool FLAC__stream_encoder_set_streamable_subset(FLAC__StreamEncoder *encoder, FLAC__bool value);
  14.765 +
  14.766 +/** Set the number of channels to be encoded.
  14.767 + *
  14.768 + * \default \c 2
  14.769 + * \param  encoder  An encoder instance to set.
  14.770 + * \param  value    See above.
  14.771 + * \assert
  14.772 + *    \code encoder != NULL \endcode
  14.773 + * \retval FLAC__bool
  14.774 + *    \c false if the encoder is already initialized, else \c true.
  14.775 + */
  14.776 +FLAC_API FLAC__bool FLAC__stream_encoder_set_channels(FLAC__StreamEncoder *encoder, unsigned value);
  14.777 +
  14.778 +/** Set the sample resolution of the input to be encoded.
  14.779 + *
  14.780 + * \warning
  14.781 + * Do not feed the encoder data that is wider than the value you
  14.782 + * set here or you will generate an invalid stream.
  14.783 + *
  14.784 + * \default \c 16
  14.785 + * \param  encoder  An encoder instance to set.
  14.786 + * \param  value    See above.
  14.787 + * \assert
  14.788 + *    \code encoder != NULL \endcode
  14.789 + * \retval FLAC__bool
  14.790 + *    \c false if the encoder is already initialized, else \c true.
  14.791 + */
  14.792 +FLAC_API FLAC__bool FLAC__stream_encoder_set_bits_per_sample(FLAC__StreamEncoder *encoder, unsigned value);
  14.793 +
  14.794 +/** Set the sample rate (in Hz) of the input to be encoded.
  14.795 + *
  14.796 + * \default \c 44100
  14.797 + * \param  encoder  An encoder instance to set.
  14.798 + * \param  value    See above.
  14.799 + * \assert
  14.800 + *    \code encoder != NULL \endcode
  14.801 + * \retval FLAC__bool
  14.802 + *    \c false if the encoder is already initialized, else \c true.
  14.803 + */
  14.804 +FLAC_API FLAC__bool FLAC__stream_encoder_set_sample_rate(FLAC__StreamEncoder *encoder, unsigned value);
  14.805 +
  14.806 +/** Set the compression level
  14.807 + *
  14.808 + * The compression level is roughly proportional to the amount of effort
  14.809 + * the encoder expends to compress the file.  A higher level usually
  14.810 + * means more computation but higher compression.  The default level is
  14.811 + * suitable for most applications.
  14.812 + *
  14.813 + * Currently the levels range from \c 0 (fastest, least compression) to
  14.814 + * \c 8 (slowest, most compression).  A value larger than \c 8 will be
  14.815 + * treated as \c 8.
  14.816 + *
  14.817 + * This function automatically calls the following other \c _set_
  14.818 + * functions with appropriate values, so the client does not need to
  14.819 + * unless it specifically wants to override them:
  14.820 + * - FLAC__stream_encoder_set_do_mid_side_stereo()
  14.821 + * - FLAC__stream_encoder_set_loose_mid_side_stereo()
  14.822 + * - FLAC__stream_encoder_set_apodization()
  14.823 + * - FLAC__stream_encoder_set_max_lpc_order()
  14.824 + * - FLAC__stream_encoder_set_qlp_coeff_precision()
  14.825 + * - FLAC__stream_encoder_set_do_qlp_coeff_prec_search()
  14.826 + * - FLAC__stream_encoder_set_do_escape_coding()
  14.827 + * - FLAC__stream_encoder_set_do_exhaustive_model_search()
  14.828 + * - FLAC__stream_encoder_set_min_residual_partition_order()
  14.829 + * - FLAC__stream_encoder_set_max_residual_partition_order()
  14.830 + * - FLAC__stream_encoder_set_rice_parameter_search_dist()
  14.831 + *
  14.832 + * The actual values set for each level are:
  14.833 + * <table>
  14.834 + * <tr>
  14.835 + *  <td><b>level</b><td>
  14.836 + *  <td>do mid-side stereo<td>
  14.837 + *  <td>loose mid-side stereo<td>
  14.838 + *  <td>apodization<td>
  14.839 + *  <td>max lpc order<td>
  14.840 + *  <td>qlp coeff precision<td>
  14.841 + *  <td>qlp coeff prec search<td>
  14.842 + *  <td>escape coding<td>
  14.843 + *  <td>exhaustive model search<td>
  14.844 + *  <td>min residual partition order<td>
  14.845 + *  <td>max residual partition order<td>
  14.846 + *  <td>rice parameter search dist<td>
  14.847 + * </tr>
  14.848 + * <tr>  <td><b>0</b><td>  <td>false<td>  <td>false<td>  <td>tukey(0.5)<td>  <td>0<td>   <td>0<td>  <td>false<td>  <td>false<td>  <td>false<td>  <td>0<td>  <td>3<td>  <td>0<td>  </tr>
  14.849 + * <tr>  <td><b>1</b><td>  <td>true<td>   <td>true<td>   <td>tukey(0.5)<td>  <td>0<td>   <td>0<td>  <td>false<td>  <td>false<td>  <td>false<td>  <td>0<td>  <td>3<td>  <td>0<td>  </tr>
  14.850 + * <tr>  <td><b>2</b><td>  <td>true<td>   <td>false<td>  <td>tukey(0.5)<td>  <td>0<td>   <td>0<td>  <td>false<td>  <td>false<td>  <td>false<td>  <td>0<td>  <td>3<td>  <td>0<td>  </tr>
  14.851 + * <tr>  <td><b>3</b><td>  <td>false<td>  <td>false<td>  <td>tukey(0.5)<td>  <td>6<td>   <td>0<td>  <td>false<td>  <td>false<td>  <td>false<td>  <td>0<td>  <td>4<td>  <td>0<td>  </tr>
  14.852 + * <tr>  <td><b>4</b><td>  <td>true<td>   <td>true<td>   <td>tukey(0.5)<td>  <td>8<td>   <td>0<td>  <td>false<td>  <td>false<td>  <td>false<td>  <td>0<td>  <td>4<td>  <td>0<td>  </tr>
  14.853 + * <tr>  <td><b>5</b><td>  <td>true<td>   <td>false<td>  <td>tukey(0.5)<td>  <td>8<td>   <td>0<td>  <td>false<td>  <td>false<td>  <td>false<td>  <td>0<td>  <td>5<td>  <td>0<td>  </tr>
  14.854 + * <tr>  <td><b>6</b><td>  <td>true<td>   <td>false<td>  <td>tukey(0.5)<td>  <td>8<td>   <td>0<td>  <td>false<td>  <td>false<td>  <td>false<td>  <td>0<td>  <td>6<td>  <td>0<td>  </tr>
  14.855 + * <tr>  <td><b>7</b><td>  <td>true<td>   <td>false<td>  <td>tukey(0.5)<td>  <td>8<td>   <td>0<td>  <td>false<td>  <td>false<td>  <td>true<td>   <td>0<td>  <td>6<td>  <td>0<td>  </tr>
  14.856 + * <tr>  <td><b>8</b><td>  <td>true<td>   <td>false<td>  <td>tukey(0.5)<td>  <td>12<td>  <td>0<td>  <td>false<td>  <td>false<td>  <td>true<td>   <td>0<td>  <td>6<td>  <td>0<td>  </tr>
  14.857 + * </table>
  14.858 + *
  14.859 + * \default \c 5
  14.860 + * \param  encoder  An encoder instance to set.
  14.861 + * \param  value    See above.
  14.862 + * \assert
  14.863 + *    \code encoder != NULL \endcode
  14.864 + * \retval FLAC__bool
  14.865 + *    \c false if the encoder is already initialized, else \c true.
  14.866 + */
  14.867 +FLAC_API FLAC__bool FLAC__stream_encoder_set_compression_level(FLAC__StreamEncoder *encoder, unsigned value);
  14.868 +
  14.869 +/** Set the blocksize to use while encoding.
  14.870 + *
  14.871 + * The number of samples to use per frame.  Use \c 0 to let the encoder
  14.872 + * estimate a blocksize; this is usually best.
  14.873 + *
  14.874 + * \default \c 0
  14.875 + * \param  encoder  An encoder instance to set.
  14.876 + * \param  value    See above.
  14.877 + * \assert
  14.878 + *    \code encoder != NULL \endcode
  14.879 + * \retval FLAC__bool
  14.880 + *    \c false if the encoder is already initialized, else \c true.
  14.881 + */
  14.882 +FLAC_API FLAC__bool FLAC__stream_encoder_set_blocksize(FLAC__StreamEncoder *encoder, unsigned value);
  14.883 +
  14.884 +/** Set to \c true to enable mid-side encoding on stereo input.  The
  14.885 + *  number of channels must be 2 for this to have any effect.  Set to
  14.886 + *  \c false to use only independent channel coding.
  14.887 + *
  14.888 + * \default \c false
  14.889 + * \param  encoder  An encoder instance to set.
  14.890 + * \param  value    Flag value (see above).
  14.891 + * \assert
  14.892 + *    \code encoder != NULL \endcode
  14.893 + * \retval FLAC__bool
  14.894 + *    \c false if the encoder is already initialized, else \c true.
  14.895 + */
  14.896 +FLAC_API FLAC__bool FLAC__stream_encoder_set_do_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value);
  14.897 +
  14.898 +/** Set to \c true to enable adaptive switching between mid-side and
  14.899 + *  left-right encoding on stereo input.  Set to \c false to use
  14.900 + *  exhaustive searching.  Setting this to \c true requires
  14.901 + *  FLAC__stream_encoder_set_do_mid_side_stereo() to also be set to
  14.902 + *  \c true in order to have any effect.
  14.903 + *
  14.904 + * \default \c false
  14.905 + * \param  encoder  An encoder instance to set.
  14.906 + * \param  value    Flag value (see above).
  14.907 + * \assert
  14.908 + *    \code encoder != NULL \endcode
  14.909 + * \retval FLAC__bool
  14.910 + *    \c false if the encoder is already initialized, else \c true.
  14.911 + */
  14.912 +FLAC_API FLAC__bool FLAC__stream_encoder_set_loose_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value);
  14.913 +
  14.914 +/** Sets the apodization function(s) the encoder will use when windowing
  14.915 + *  audio data for LPC analysis.
  14.916 + *
  14.917 + * The \a specification is a plain ASCII string which specifies exactly
  14.918 + * which functions to use.  There may be more than one (up to 32),
  14.919 + * separated by \c ';' characters.  Some functions take one or more
  14.920 + * comma-separated arguments in parentheses.
  14.921 + *
  14.922 + * The available functions are \c bartlett, \c bartlett_hann,
  14.923 + * \c blackman, \c blackman_harris_4term_92db, \c connes, \c flattop,
  14.924 + * \c gauss(STDDEV), \c hamming, \c hann, \c kaiser_bessel, \c nuttall,
  14.925 + * \c rectangle, \c triangle, \c tukey(P), \c welch.
  14.926 + *
  14.927 + * For \c gauss(STDDEV), STDDEV specifies the standard deviation
  14.928 + * (0<STDDEV<=0.5).
  14.929 + *
  14.930 + * For \c tukey(P), P specifies the fraction of the window that is
  14.931 + * tapered (0<=P<=1).  P=0 corresponds to \c rectangle and P=1
  14.932 + * corresponds to \c hann.
  14.933 + *
  14.934 + * Example specifications are \c "blackman" or
  14.935 + * \c "hann;triangle;tukey(0.5);tukey(0.25);tukey(0.125)"
  14.936 + *
  14.937 + * Any function that is specified erroneously is silently dropped.  Up
  14.938 + * to 32 functions are kept, the rest are dropped.  If the specification
  14.939 + * is empty the encoder defaults to \c "tukey(0.5)".
  14.940 + *
  14.941 + * When more than one function is specified, then for every subframe the
  14.942 + * encoder will try each of them separately and choose the window that
  14.943 + * results in the smallest compressed subframe.
  14.944 + *
  14.945 + * Note that each function specified causes the encoder to occupy a
  14.946 + * floating point array in which to store the window.
  14.947 + *
  14.948 + * \default \c "tukey(0.5)"
  14.949 + * \param  encoder        An encoder instance to set.
  14.950 + * \param  specification  See above.
  14.951 + * \assert
  14.952 + *    \code encoder != NULL \endcode
  14.953 + *    \code specification != NULL \endcode
  14.954 + * \retval FLAC__bool
  14.955 + *    \c false if the encoder is already initialized, else \c true.
  14.956 + */
  14.957 +FLAC_API FLAC__bool FLAC__stream_encoder_set_apodization(FLAC__StreamEncoder *encoder, const char *specification);
  14.958 +
  14.959 +/** Set the maximum LPC order, or \c 0 to use only the fixed predictors.
  14.960 + *
  14.961 + * \default \c 0
  14.962 + * \param  encoder  An encoder instance to set.
  14.963 + * \param  value    See above.
  14.964 + * \assert
  14.965 + *    \code encoder != NULL \endcode
  14.966 + * \retval FLAC__bool
  14.967 + *    \c false if the encoder is already initialized, else \c true.
  14.968 + */
  14.969 +FLAC_API FLAC__bool FLAC__stream_encoder_set_max_lpc_order(FLAC__StreamEncoder *encoder, unsigned value);
  14.970 +
  14.971 +/** Set the precision, in bits, of the quantized linear predictor
  14.972 + *  coefficients, or \c 0 to let the encoder select it based on the
  14.973 + *  blocksize.
  14.974 + *
  14.975 + * \note
  14.976 + * In the current implementation, qlp_coeff_precision + bits_per_sample must
  14.977 + * be less than 32.
  14.978 + *
  14.979 + * \default \c 0
  14.980 + * \param  encoder  An encoder instance to set.
  14.981 + * \param  value    See above.
  14.982 + * \assert
  14.983 + *    \code encoder != NULL \endcode
  14.984 + * \retval FLAC__bool
  14.985 + *    \c false if the encoder is already initialized, else \c true.
  14.986 + */
  14.987 +FLAC_API FLAC__bool FLAC__stream_encoder_set_qlp_coeff_precision(FLAC__StreamEncoder *encoder, unsigned value);
  14.988 +
  14.989 +/** Set to \c false to use only the specified quantized linear predictor
  14.990 + *  coefficient precision, or \c true to search neighboring precision
  14.991 + *  values and use the best one.
  14.992 + *
  14.993 + * \default \c false
  14.994 + * \param  encoder  An encoder instance to set.
  14.995 + * \param  value    See above.
  14.996 + * \assert
  14.997 + *    \code encoder != NULL \endcode
  14.998 + * \retval FLAC__bool
  14.999 + *    \c false if the encoder is already initialized, else \c true.
 14.1000 + */
 14.1001 +FLAC_API FLAC__bool FLAC__stream_encoder_set_do_qlp_coeff_prec_search(FLAC__StreamEncoder *encoder, FLAC__bool value);
 14.1002 +
 14.1003 +/** Deprecated.  Setting this value has no effect.
 14.1004 + *
 14.1005 + * \default \c false
 14.1006 + * \param  encoder  An encoder instance to set.
 14.1007 + * \param  value    See above.
 14.1008 + * \assert
 14.1009 + *    \code encoder != NULL \endcode
 14.1010 + * \retval FLAC__bool
 14.1011 + *    \c false if the encoder is already initialized, else \c true.
 14.1012 + */
 14.1013 +FLAC_API FLAC__bool FLAC__stream_encoder_set_do_escape_coding(FLAC__StreamEncoder *encoder, FLAC__bool value);
 14.1014 +
 14.1015 +/** Set to \c false to let the encoder estimate the best model order
 14.1016 + *  based on the residual signal energy, or \c true to force the
 14.1017 + *  encoder to evaluate all order models and select the best.
 14.1018 + *
 14.1019 + * \default \c false
 14.1020 + * \param  encoder  An encoder instance to set.
 14.1021 + * \param  value    See above.
 14.1022 + * \assert
 14.1023 + *    \code encoder != NULL \endcode
 14.1024 + * \retval FLAC__bool
 14.1025 + *    \c false if the encoder is already initialized, else \c true.
 14.1026 + */
 14.1027 +FLAC_API FLAC__bool FLAC__stream_encoder_set_do_exhaustive_model_search(FLAC__StreamEncoder *encoder, FLAC__bool value);
 14.1028 +
 14.1029 +/** Set the minimum partition order to search when coding the residual.
 14.1030 + *  This is used in tandem with
 14.1031 + *  FLAC__stream_encoder_set_max_residual_partition_order().
 14.1032 + *
 14.1033 + *  The partition order determines the context size in the residual.
 14.1034 + *  The context size will be approximately <tt>blocksize / (2 ^ order)</tt>.
 14.1035 + *
 14.1036 + *  Set both min and max values to \c 0 to force a single context,
 14.1037 + *  whose Rice parameter is based on the residual signal variance.
 14.1038 + *  Otherwise, set a min and max order, and the encoder will search
 14.1039 + *  all orders, using the mean of each context for its Rice parameter,
 14.1040 + *  and use the best.
 14.1041 + *
 14.1042 + * \default \c 0
 14.1043 + * \param  encoder  An encoder instance to set.
 14.1044 + * \param  value    See above.
 14.1045 + * \assert
 14.1046 + *    \code encoder != NULL \endcode
 14.1047 + * \retval FLAC__bool
 14.1048 + *    \c false if the encoder is already initialized, else \c true.
 14.1049 + */
 14.1050 +FLAC_API FLAC__bool FLAC__stream_encoder_set_min_residual_partition_order(FLAC__StreamEncoder *encoder, unsigned value);
 14.1051 +
 14.1052 +/** Set the maximum partition order to search when coding the residual.
 14.1053 + *  This is used in tandem with
 14.1054 + *  FLAC__stream_encoder_set_min_residual_partition_order().
 14.1055 + *
 14.1056 + *  The partition order determines the context size in the residual.
 14.1057 + *  The context size will be approximately <tt>blocksize / (2 ^ order)</tt>.
 14.1058 + *
 14.1059 + *  Set both min and max values to \c 0 to force a single context,
 14.1060 + *  whose Rice parameter is based on the residual signal variance.
 14.1061 + *  Otherwise, set a min and max order, and the encoder will search
 14.1062 + *  all orders, using the mean of each context for its Rice parameter,
 14.1063 + *  and use the best.
 14.1064 + *
 14.1065 + * \default \c 0
 14.1066 + * \param  encoder  An encoder instance to set.
 14.1067 + * \param  value    See above.
 14.1068 + * \assert
 14.1069 + *    \code encoder != NULL \endcode
 14.1070 + * \retval FLAC__bool
 14.1071 + *    \c false if the encoder is already initialized, else \c true.
 14.1072 + */
 14.1073 +FLAC_API FLAC__bool FLAC__stream_encoder_set_max_residual_partition_order(FLAC__StreamEncoder *encoder, unsigned value);
 14.1074 +
 14.1075 +/** Deprecated.  Setting this value has no effect.
 14.1076 + *
 14.1077 + * \default \c 0
 14.1078 + * \param  encoder  An encoder instance to set.
 14.1079 + * \param  value    See above.
 14.1080 + * \assert
 14.1081 + *    \code encoder != NULL \endcode
 14.1082 + * \retval FLAC__bool
 14.1083 + *    \c false if the encoder is already initialized, else \c true.
 14.1084 + */
 14.1085 +FLAC_API FLAC__bool FLAC__stream_encoder_set_rice_parameter_search_dist(FLAC__StreamEncoder *encoder, unsigned value);
 14.1086 +
 14.1087 +/** Set an estimate of the total samples that will be encoded.
 14.1088 + *  This is merely an estimate and may be set to \c 0 if unknown.
 14.1089 + *  This value will be written to the STREAMINFO block before encoding,
 14.1090 + *  and can remove the need for the caller to rewrite the value later
 14.1091 + *  if the value is known before encoding.
 14.1092 + *
 14.1093 + * \default \c 0
 14.1094 + * \param  encoder  An encoder instance to set.
 14.1095 + * \param  value    See above.
 14.1096 + * \assert
 14.1097 + *    \code encoder != NULL \endcode
 14.1098 + * \retval FLAC__bool
 14.1099 + *    \c false if the encoder is already initialized, else \c true.
 14.1100 + */
 14.1101 +FLAC_API FLAC__bool FLAC__stream_encoder_set_total_samples_estimate(FLAC__StreamEncoder *encoder, FLAC__uint64 value);
 14.1102 +
 14.1103 +/** Set the metadata blocks to be emitted to the stream before encoding.
 14.1104 + *  A value of \c NULL, \c 0 implies no metadata; otherwise, supply an
 14.1105 + *  array of pointers to metadata blocks.  The array is non-const since
 14.1106 + *  the encoder may need to change the \a is_last flag inside them, and
 14.1107 + *  in some cases update seek point offsets.  Otherwise, the encoder will
 14.1108 + *  not modify or free the blocks.  It is up to the caller to free the
 14.1109 + *  metadata blocks after encoding finishes.
 14.1110 + *
 14.1111 + * \note
 14.1112 + * The encoder stores only copies of the pointers in the \a metadata array;
 14.1113 + * the metadata blocks themselves must survive at least until after
 14.1114 + * FLAC__stream_encoder_finish() returns.  Do not free the blocks until then.
 14.1115 + *
 14.1116 + * \note
 14.1117 + * The STREAMINFO block is always written and no STREAMINFO block may
 14.1118 + * occur in the supplied array.
 14.1119 + *
 14.1120 + * \note
 14.1121 + * By default the encoder does not create a SEEKTABLE.  If one is supplied
 14.1122 + * in the \a metadata array, but the client has specified that it does not
 14.1123 + * support seeking, then the SEEKTABLE will be written verbatim.  However
 14.1124 + * by itself this is not very useful as the client will not know the stream
 14.1125 + * offsets for the seekpoints ahead of time.  In order to get a proper
 14.1126 + * seektable the client must support seeking.  See next note.
 14.1127 + *
 14.1128 + * \note
 14.1129 + * SEEKTABLE blocks are handled specially.  Since you will not know
 14.1130 + * the values for the seek point stream offsets, you should pass in
 14.1131 + * a SEEKTABLE 'template', that is, a SEEKTABLE object with the
 14.1132 + * required sample numbers (or placeholder points), with \c 0 for the
 14.1133 + * \a frame_samples and \a stream_offset fields for each point.  If the
 14.1134 + * client has specified that it supports seeking by providing a seek
 14.1135 + * callback to FLAC__stream_encoder_init_stream() or both seek AND read
 14.1136 + * callback to FLAC__stream_encoder_init_ogg_stream() (or by using
 14.1137 + * FLAC__stream_encoder_init*_file() or FLAC__stream_encoder_init*_FILE()),
 14.1138 + * then while it is encoding the encoder will fill the stream offsets in
 14.1139 + * for you and when encoding is finished, it will seek back and write the
 14.1140 + * real values into the SEEKTABLE block in the stream.  There are helper
 14.1141 + * routines for manipulating seektable template blocks; see metadata.h:
 14.1142 + * FLAC__metadata_object_seektable_template_*().  If the client does
 14.1143 + * not support seeking, the SEEKTABLE will have inaccurate offsets which
 14.1144 + * will slow down or remove the ability to seek in the FLAC stream.
 14.1145 + *
 14.1146 + * \note
 14.1147 + * The encoder instance \b will modify the first \c SEEKTABLE block
 14.1148 + * as it transforms the template to a valid seektable while encoding,
 14.1149 + * but it is still up to the caller to free all metadata blocks after
 14.1150 + * encoding.
 14.1151 + *
 14.1152 + * \note
 14.1153 + * A VORBIS_COMMENT block may be supplied.  The vendor string in it
 14.1154 + * will be ignored.  libFLAC will use it's own vendor string. libFLAC
 14.1155 + * will not modify the passed-in VORBIS_COMMENT's vendor string, it
 14.1156 + * will simply write it's own into the stream.  If no VORBIS_COMMENT
 14.1157 + * block is present in the \a metadata array, libFLAC will write an
 14.1158 + * empty one, containing only the vendor string.
 14.1159 + *
 14.1160 + * \note The Ogg FLAC mapping requires that the VORBIS_COMMENT block be
 14.1161 + * the second metadata block of the stream.  The encoder already supplies
 14.1162 + * the STREAMINFO block automatically.  If \a metadata does not contain a
 14.1163 + * VORBIS_COMMENT block, the encoder will supply that too.  Otherwise, if
 14.1164 + * \a metadata does contain a VORBIS_COMMENT block and it is not the
 14.1165 + * first, the init function will reorder \a metadata by moving the
 14.1166 + * VORBIS_COMMENT block to the front; the relative ordering of the other