merge down from merged-API-layer branch: cvs -q up -dP -j API_LAYER_MERGING_BASELINE...
authorJosh Coalson <jcoalson@users.sourceforce.net>
Wed, 13 Sep 2006 01:42:27 +0000 (01:42 +0000)
committerJosh Coalson <jcoalson@users.sourceforce.net>
Wed, 13 Sep 2006 01:42:27 +0000 (01:42 +0000)
156 files changed:
FLAC.dsw
README
configure.in
doc/html/changelog.html
include/FLAC++/decoder.h
include/FLAC++/encoder.h
include/FLAC/Makefile.am
include/FLAC/all.h
include/FLAC/file_decoder.h [deleted file]
include/FLAC/file_encoder.h [deleted file]
include/FLAC/metadata.h
include/FLAC/seekable_stream_decoder.h [deleted file]
include/FLAC/seekable_stream_encoder.h [deleted file]
include/FLAC/stream_decoder.h
include/FLAC/stream_encoder.h
include/Makefile.am
include/OggFLAC++/decoder.h
include/OggFLAC++/encoder.h
include/OggFLAC/Makefile.am
include/OggFLAC/all.h
include/OggFLAC/file_decoder.h [deleted file]
include/OggFLAC/file_encoder.h [deleted file]
include/OggFLAC/seekable_stream_decoder.h [deleted file]
include/OggFLAC/seekable_stream_encoder.h [deleted file]
include/OggFLAC/stream_decoder.h
include/OggFLAC/stream_encoder.h
include/test_libs_common/Makefile.am [new file with mode: 0644]
include/test_libs_common/file_utils_flac.h [moved from src/test_libFLAC++/file_utils.h with 100% similarity]
include/test_libs_common/file_utils_oggflac.h [moved from src/test_libOggFLAC++/file_utils.h with 100% similarity]
include/test_libs_common/metadata_utils.h [moved from src/test_libFLAC++/metadata_utils.h with 100% similarity]
src/Makefile.am
src/Makefile.lite
src/flac/decode.c
src/flac/encode.c
src/flac/main.c
src/libFLAC++/Makefile.am
src/libFLAC++/Makefile.lite
src/libFLAC++/file_decoder.cpp
src/libFLAC++/file_encoder.cpp
src/libFLAC++/libFLAC++_dynamic.dsp
src/libFLAC++/libFLAC++_static.dsp
src/libFLAC++/seekable_stream_decoder.cpp [deleted file]
src/libFLAC++/seekable_stream_encoder.cpp [deleted file]
src/libFLAC++/stream_decoder.cpp
src/libFLAC++/stream_encoder.cpp
src/libFLAC/Makefile.am
src/libFLAC/Makefile.lite
src/libFLAC/file_decoder.c [deleted file]
src/libFLAC/file_encoder.c [deleted file]
src/libFLAC/include/protected/Makefile.am
src/libFLAC/include/protected/all.h
src/libFLAC/include/protected/file_decoder.h [deleted file]
src/libFLAC/include/protected/file_encoder.h [deleted file]
src/libFLAC/include/protected/seekable_stream_decoder.h [deleted file]
src/libFLAC/include/protected/seekable_stream_encoder.h [deleted file]
src/libFLAC/include/protected/stream_decoder.h
src/libFLAC/include/protected/stream_encoder.h
src/libFLAC/libFLAC_dynamic.dsp
src/libFLAC/libFLAC_static.dsp
src/libFLAC/metadata_iterators.c
src/libFLAC/metadata_object.c
src/libFLAC/seekable_stream_decoder.c [deleted file]
src/libFLAC/seekable_stream_encoder.c [deleted file]
src/libFLAC/stream_decoder.c
src/libFLAC/stream_encoder.c
src/libOggFLAC++/Makefile.am
src/libOggFLAC++/Makefile.lite
src/libOggFLAC++/file_decoder.cpp
src/libOggFLAC++/file_encoder.cpp
src/libOggFLAC++/libOggFLAC++_dynamic.dsp
src/libOggFLAC++/libOggFLAC++_static.dsp
src/libOggFLAC++/seekable_stream_decoder.cpp [deleted file]
src/libOggFLAC++/seekable_stream_encoder.cpp [deleted file]
src/libOggFLAC++/stream_decoder.cpp
src/libOggFLAC++/stream_encoder.cpp
src/libOggFLAC/Makefile.am
src/libOggFLAC/Makefile.lite
src/libOggFLAC/file_decoder.c [deleted file]
src/libOggFLAC/file_encoder.c [deleted file]
src/libOggFLAC/include/private/ogg_decoder_aspect.h
src/libOggFLAC/include/private/ogg_helper.h
src/libOggFLAC/include/protected/Makefile.am
src/libOggFLAC/include/protected/all.h
src/libOggFLAC/include/protected/file_decoder.h [deleted file]
src/libOggFLAC/include/protected/file_encoder.h [deleted file]
src/libOggFLAC/include/protected/seekable_stream_decoder.h [deleted file]
src/libOggFLAC/include/protected/seekable_stream_encoder.h [deleted file]
src/libOggFLAC/include/protected/stream_encoder.h
src/libOggFLAC/libOggFLAC_dynamic.dsp
src/libOggFLAC/libOggFLAC_static.dsp
src/libOggFLAC/ogg_decoder_aspect.c
src/libOggFLAC/ogg_encoder_aspect.c
src/libOggFLAC/ogg_helper.c
src/libOggFLAC/seekable_stream_decoder.c [deleted file]
src/libOggFLAC/seekable_stream_encoder.c [deleted file]
src/libOggFLAC/stream_decoder.c
src/libOggFLAC/stream_encoder.c
src/metaflac/operations_shorthand_seektable.c
src/plugin_winamp2/in_flac.c
src/plugin_winamp2/playback.c
src/plugin_winamp2/playback.h
src/plugin_xmms/http.c
src/plugin_xmms/http.h
src/plugin_xmms/plugin.c
src/share/grabbag/replaygain.c
src/share/grabbag/seektable.c
src/test_libFLAC++/Makefile.am
src/test_libFLAC++/Makefile.lite
src/test_libFLAC++/README [deleted file]
src/test_libFLAC++/decoders.cpp
src/test_libFLAC++/encoders.cpp
src/test_libFLAC++/metadata_manip.cpp
src/test_libFLAC++/metadata_utils.c [deleted file]
src/test_libFLAC++/test_libFLAC++.dsp
src/test_libFLAC/Makefile.am
src/test_libFLAC/Makefile.lite
src/test_libFLAC/decoders.c
src/test_libFLAC/encoders.c
src/test_libFLAC/file_utils.c [deleted file]
src/test_libFLAC/file_utils.h [deleted file]
src/test_libFLAC/metadata_manip.c
src/test_libFLAC/metadata_object.c
src/test_libFLAC/metadata_utils.c [deleted file]
src/test_libFLAC/metadata_utils.h [deleted file]
src/test_libFLAC/test_libFLAC.dsp
src/test_libOggFLAC++/Makefile.am
src/test_libOggFLAC++/Makefile.lite
src/test_libOggFLAC++/README [deleted file]
src/test_libOggFLAC++/decoders.cpp
src/test_libOggFLAC++/encoders.cpp
src/test_libOggFLAC++/metadata_utils.h [deleted file]
src/test_libOggFLAC++/test_libOggFLAC++.dsp
src/test_libOggFLAC/Makefile.am
src/test_libOggFLAC/Makefile.lite
src/test_libOggFLAC/README [deleted file]
src/test_libOggFLAC/decoders.c
src/test_libOggFLAC/encoders.c
src/test_libOggFLAC/file_utils.c [deleted file]
src/test_libOggFLAC/file_utils.h [deleted file]
src/test_libOggFLAC/metadata_utils.c [deleted file]
src/test_libOggFLAC/metadata_utils.h [deleted file]
src/test_libOggFLAC/test_libOggFLAC.dsp
src/test_libs_common/Makefile.am [new file with mode: 0644]
src/test_libs_common/Makefile.lite [new file with mode: 0644]
src/test_libs_common/README [new file with mode: 0644]
src/test_libs_common/file_utils_flac.c [moved from src/test_libFLAC++/file_utils.c with 93% similarity]
src/test_libs_common/file_utils_oggflac.c [moved from src/test_libOggFLAC++/file_utils.c with 88% similarity]
src/test_libs_common/metadata_utils.c [moved from src/test_libOggFLAC++/metadata_utils.c with 99% similarity]
src/test_libs_common/test_libs_common_static.dsp [new file with mode: 0644]
src/test_seeking/main.c
test/cuesheets/Makefile.am
test/flac-to-flac-metadata-test-files/Makefile.am
test/flac-to-flac-metadata-test-files/case03c-expect.meta
test/flac-to-flac-metadata-test-files/case04c-expect.meta
test/metaflac-test-files/case07-expect.meta
test/test_seeking.sh

index 5546a6e..71eccec 100644 (file)
--- a/FLAC.dsw
+++ b/FLAC.dsw
@@ -81,6 +81,9 @@ Package=<4>
     Project_Dep_Name libOggFLAC++_static\r
     End Project Dependency\r
     Begin Project Dependency\r
+    Project_Dep_Name test_libs_common_static\r
+    End Project Dependency\r
+    Begin Project Dependency\r
     Project_Dep_Name plugin_common_static\r
     End Project Dependency\r
     Begin Project Dependency\r
@@ -159,6 +162,9 @@ Package=<4>
     Project_Dep_Name libOggFLAC++_static\r
     End Project Dependency\r
     Begin Project Dependency\r
+    Project_Dep_Name test_libs_common_static\r
+    End Project Dependency\r
+    Begin Project Dependency\r
     Project_Dep_Name plugin_common_static\r
     End Project Dependency\r
     Begin Project Dependency\r
@@ -498,6 +504,24 @@ Package=<4>
 \r
 ###############################################################################\r
 \r
+Project: "test_libs_common"=.\src\test_libs_common\test_libs_common_static.dsp - Package Owner=<4>\r
+\r
+Package=<5>\r
+{{{\r
+}}}\r
+\r
+Package=<4>\r
+{{{\r
+    Begin Project Dependency\r
+    Project_Dep_Name libFLAC_static\r
+    End Project Dependency\r
+    Begin Project Dependency\r
+    Project_Dep_Name libOggFLAC_static\r
+    End Project Dependency\r
+}}}\r
+\r
+###############################################################################\r
+\r
 Project: "test_libFLAC"=.\src\test_libFLAC\test_libFLAC.dsp - Package Owner=<4>\r
 \r
 Package=<5>\r
@@ -509,6 +533,9 @@ Package=<4>
     Begin Project Dependency\r
     Project_Dep_Name libFLAC_static\r
     End Project Dependency\r
+    Begin Project Dependency\r
+    Project_Dep_Name test_libs_common_static\r
+    End Project Dependency\r
 }}}\r
 \r
 ###############################################################################\r
@@ -524,6 +551,9 @@ Package=<4>
     Begin Project Dependency\r
     Project_Dep_Name libFLAC++_static\r
     End Project Dependency\r
+    Begin Project Dependency\r
+    Project_Dep_Name test_libs_common_static\r
+    End Project Dependency\r
 }}}\r
 \r
 ###############################################################################\r
@@ -539,6 +569,9 @@ Package=<4>
     Begin Project Dependency\r
     Project_Dep_Name libOggFLAC_static\r
     End Project Dependency\r
+    Begin Project Dependency\r
+    Project_Dep_Name test_libs_common_static\r
+    End Project Dependency\r
 }}}\r
 \r
 ###############################################################################\r
@@ -554,6 +587,9 @@ Package=<4>
     Begin Project Dependency\r
     Project_Dep_Name libOggFLAC++_static\r
     End Project Dependency\r
+    Begin Project Dependency\r
+    Project_Dep_Name test_libs_common_static\r
+    End Project Dependency\r
 }}}\r
 \r
 ###############################################################################\r
diff --git a/README b/README
index 1f9c72a..d3438c4 100644 (file)
--- a/README
+++ b/README
@@ -241,17 +241,18 @@ configure.in and src/libFLAC/Makefile.am; the following dependency
 graph shows which modules may be pruned without breaking things
 further down:
 
-file_encoder.h
-       stream_encoder.h
-               format.h
+stream_encoder.h
+       stream_decoder.h
+       format.h
 
-file_decoder.h
-       seekable_stream_decoder.h
-               stream_decoder.h
-                       format.h
+stream_decoder.h
+       format.h
 
 metadata.h
        format.h
 
+In other words, for pure decoding applications, both the stream encoder
+and metadata editing interfaces can be safely removed.
+
 There is a section dedicated to embedded use in the libFLAC API
 HTML documentation (see doc/html/api/index.html).
index 7dce4e7..30ac4d6 100644 (file)
@@ -314,6 +314,7 @@ AC_CONFIG_FILES([ \
        src/share/utf8/Makefile \
        src/test_grabbag/Makefile \
        src/test_grabbag/cuesheet/Makefile \
+       src/test_libs_common/Makefile \
        src/test_libFLAC/Makefile \
        src/test_libFLAC++/Makefile \
        src/test_libOggFLAC/Makefile \
@@ -327,6 +328,7 @@ AC_CONFIG_FILES([ \
        include/OggFLAC++/Makefile \
        include/share/Makefile \
        include/share/grabbag/Makefile \
+       include/test_libs_common/Makefile \
        doc/Makefile \
        doc/html/Makefile \
        doc/html/images/Makefile \
@@ -334,6 +336,8 @@ AC_CONFIG_FILES([ \
        man/Makefile \
        test/Makefile \
        test/cuesheets/Makefile \
+       test/flac-to-flac-metadata-test-files/Makefile \
+       test/metaflac-test-files/Makefile \
        build/Makefile \
        obj/Makefile \
        obj/debug/Makefile \
index edfaa15..de28f62 100644 (file)
@@ -53,7 +53,7 @@
        </div>
        <div class="box_header"></div>
        <div class="box_body">
-               This is an informal changelog, a summary of changes in each release.  Particulary important for developers is the precise description of changes to the library interfaces.
+               This is an informal changelog, a summary of changes in each release.  Particulary important for developers is the precise description of changes to the library interfaces.  See also the <a href="http://flac.sourceforge.net/api/group__porting.html">porting guide</a> for specific instructions on porting to newer versions of FLAC.
 
                <br /><br />
 
@@ -68,6 +68,7 @@
                                        <li>Large file (&gt;2GB) support everywhere</li>
                                        <li>Much better recovery for corrupted files</li>
                                        <li><span class="commandname">flac</span> now supports FLAC as input to the encoder (i.e. can re-encode FLAC to FLAC) and preserve all the metadata like tags, etc.</li>
+                                       <li>In the developer libraries, the interface has been simplfied by merging the three decoding layers into a single class; ditto for the encoders.</li>
                                </ul>
                        </li>
                        <li>
                                </ul>
                        </li>
                        <li>
-                               Interface changes:
+                               Interface changes (see also the <a href="http://flac.sourceforge.net/api/group__porting__1__1__2__to__1__1__3.html">porting guide</a> for specific instructions on porting to FLAC 1.1.3):
                                <ul>
                                        <li>
+                                               all libraries;
+                                               <ul>
+                                                       <li>Merged seekable stream decoder and file decoder into the stream decoder.</li>
+                                                       <li>Merged seekable stream encoder and file encoder into the stream encoder.</li>
+                                               </ul>
+                                       </li>
+                                       <li>
                                                libFLAC:
                                                <ul>
-                                                       <li><b>Added</b> FLAC__*_encoder_set_apodization()</li>
+                                                       <li><b>Added</b> FLAC__stream_encoder_set_apodization()</li>
                                                        <li><b>Added</b> FLAC__metadata_object_cuesheet_calculate_cddb_id()</li>
                                                        <li><b>Added</b> FLAC__metadata_get_cuesheet()</li>
                                                        <li><b>Changed</b> FLAC__StreamDecoderState: removed state FLAC__STREAM_DECODER_UNPARSEABLE_STREAM</li>
                                        <li>
                                                libFLAC++:
                                                <ul>
-                                                       <li><b>Added</b> FLAC::*::Encoder::set_apodization()</li>
+                                                       <li><b>Added</b> FLAC::Encoder::Stream::set_apodization()</li>
                                                        <li><b>Added</b> FLAC::Metadata::CueSheet::calculate_cddb_id()</li>
                                                        <li><b>Added</b> FLAC::Metadata::get_cuesheet()</li>
                                                </ul>
                                        <li>
                                                libOggFLAC:
                                                <ul>
-                                                       <li><b>Added</b> OggFLAC__*_encoder_set_apodization()</li>
+                                                       <li><b>Added</b> OggFLAC__stream_encoder_set_apodization()</li>
                                                        <li><b>Added</b> OggFLAC__metadata_object_cuesheet_calculate_cddb_id()</li>
                                                        <li><b>Added</b> OggFLAC__metadata_get_cuesheet()</li>
                                                </ul>
                                        <li>
                                                libOggFLAC++:
                                                <ul>
-                                                       <li><b>Added</b> OggFLAC::*::Encoder::set_apodization()</li>
+                                                       <li><b>Added</b> OggFLAC::Encoder::Stream::set_apodization()</li>
                                                        <li><b>Added</b> OggFLAC::Metadata::CueSheet::calculate_cddb_id()</li>
                                                        <li><b>Added</b> OggFLAC::Metadata::get_cuesheet()</li>
                                                </ul>
index aba733f..5143311 100644 (file)
@@ -34,8 +34,7 @@
 
 #include "export.h"
 
-#include "FLAC/file_decoder.h"
-#include "FLAC/seekable_stream_decoder.h"
+#include <string>
 #include "FLAC/stream_decoder.h"
 
 
  *  \ingroup flacpp
  *
  *  \brief
- *  This module describes the three decoder layers provided by libFLAC++.
+ *  This module describes the decoder layers provided by libFLAC++.
  *
  * The libFLAC++ decoder classes are object wrappers around their
- * counterparts in libFLAC.  All three decoding layers available in
+ * counterparts in libFLAC.  All decoding layers available in
  * libFLAC are also provided here.  The interface is very similar;
  * make sure to read the \link flac_decoder libFLAC decoder module \endlink.
  *
- * The only real difference here is that instead of passing in C function
- * pointers for callbacks, you inherit from the decoder class and provide
- * implementations for the callbacks in the derived class; because of this
- * there is no need for a 'client_data' property.
+ * There are only two significant differences here.  First, instead of
+ * passing in C function pointers for callbacks, you inherit from the
+ * decoder class and provide implementations for the callbacks in your
+ * derived class; because of this there is no need for a 'client_data'
+ * property.
+ *
+ * Second, there are two stream decoder classes.  FLAC::Decoder::Stream
+ * is used for the same cases that FLAC__stream_decoder_init_stream() is
+ * used, and FLAC::Decoder::File is used for the same cases that
+ * FLAC__stream_decoder_init_FILE() and FLAC__stream_decoder_init_file()
+ * are used.
  */
 
 namespace FLAC {
        namespace Decoder {
 
-               // ============================================================
-               //
-               //  Equivalent: FLAC__StreamDecoder
-               //
-               // ============================================================
-
                /** \defgroup flacpp_stream_decoder FLAC++/decoder.h: stream decoder class
                 *  \ingroup flacpp_decoder
                 *
                 *  \brief
                 *  This class wraps the ::FLAC__StreamDecoder.
                 *
-                * See the \link flac_stream_decoder libFLAC stream decoder module \endlink.
+                * See the \link flac_stream_decoder libFLAC stream decoder module \endlink
+                * for basic usage.
                 *
                 * \{
                 */
 
-               /** This class wraps the ::FLAC__StreamDecoder.
+               /** This class wraps the ::FLAC__StreamDecoder.  If you are
+                *  decoding from a file, FLAC::Decoder::File may be more
+                *  convenient.
+                *
+                * The usage of this class is similar to FLAC__StreamDecoder,
+                * except instead of providing callbacks to
+                * FLAC__stream_decoder_init_stream(), you will inherit from this
+                * class and override the virtual callback functions with your
+                * own implementations, then call Stream::init().  The rest of
+                * the calls work the same as in the C layer.
+                *
+                * Only the read, write, and error callbacks are mandatory.  The
+                * others are optional; this class provides default
+                * implementations that do nothing.  In order for seeking to work
+                * you must overide seek_callback(), tell_callback(),
+                * length_callback(), and eof_callback().
                 */
                class FLACPP_API Stream {
                public:
@@ -103,42 +119,74 @@ namespace FLAC {
                        Stream();
                        virtual ~Stream();
 
+                       /** Call after construction to check the that the object was created
+                        *  successfully.  If not, use get_state() to find out why not.
+                        *
+                        * \{
+                        */
                        bool is_valid() const;
                        inline operator bool() const { return is_valid(); }
-
-                       bool set_metadata_respond(::FLAC__MetadataType type);
-                       bool set_metadata_respond_application(const FLAC__byte id[4]);
-                       bool set_metadata_respond_all();
-                       bool set_metadata_ignore(::FLAC__MetadataType type);
-                       bool set_metadata_ignore_application(const FLAC__byte id[4]);
-                       bool set_metadata_ignore_all();
-
-                       State get_state() const;
-                       unsigned get_channels() const;
-                       ::FLAC__ChannelAssignment get_channel_assignment() const;
-                       unsigned get_bits_per_sample() const;
-                       unsigned get_sample_rate() const;
-                       unsigned get_blocksize() const;
+                       /* \} */
+
+                       bool set_md5_checking(bool value);                             ///< See FLAC__stream_decoder_set_md5_checking()
+                       bool set_metadata_respond(::FLAC__MetadataType type);          ///< See FLAC__stream_decoder_set_metadata_respond()
+                       bool set_metadata_respond_application(const FLAC__byte id[4]); ///< See FLAC__stream_decoder_set_metadata_respond_application()
+                       bool set_metadata_respond_all();                               ///< See FLAC__stream_decoder_set_metadata_respond_all()
+                       bool set_metadata_ignore(::FLAC__MetadataType type);           ///< See FLAC__stream_decoder_set_metadata_ignore()
+                       bool set_metadata_ignore_application(const FLAC__byte id[4]);  ///< See FLAC__stream_decoder_set_metadata_ignore_application()
+                       bool set_metadata_ignore_all();                                ///< See FLAC__stream_decoder_set_metadata_ignore_all()
+
+                       State get_state() const;                                  ///< See FLAC__stream_decoder_get_state()
+                       bool get_md5_checking() const;                            ///< See FLAC__stream_decoder_get_md5_checking()
+                       FLAC__uint64 get_total_samples() const;                   ///< See FLAC__stream_decoder_get_total_samples()
+                       unsigned get_channels() const;                            ///< See FLAC__stream_decoder_get_channels()
+                       ::FLAC__ChannelAssignment get_channel_assignment() const; ///< See FLAC__stream_decoder_get_channel_assignment()
+                       unsigned get_bits_per_sample() const;                     ///< See FLAC__stream_decoder_get_bits_per_sample()
+                       unsigned get_sample_rate() const;                         ///< See FLAC__stream_decoder_get_sample_rate()
+                       unsigned get_blocksize() const;                           ///< See FLAC__stream_decoder_get_blocksize()
 
                        /** Initialize the instance; as with the C interface,
                         *  init() should be called after construction and 'set'
                         *  calls but before any of the 'process' calls.
+                        *
+                        *  See FLAC__stream_decoder_init_stream().
                         */
-                       State init();
+                       ::FLAC__StreamDecoderInitStatus init();
+
+                       void finish(); ///< See FLAC__stream_decoder_finish()
 
-                       void finish();
+                       bool flush(); ///< See FLAC__stream_decoder_flush()
+                       bool reset(); ///< See FLAC__stream_decoder_reset()
 
-                       bool flush();
-                       bool reset();
+                       bool process_single();                ///< See FLAC__stream_decoder_process_single()
+                       bool process_until_end_of_metadata(); ///< See FLAC__stream_decoder_process_until_end_of_metadata()
+                       bool process_until_end_of_stream();   ///< See FLAC__stream_decoder_process_until_end_of_stream()
+                       bool skip_single_frame();             ///< See FLAC__stream_decoder_skip_single_frame()
 
-                       bool process_single();
-                       bool process_until_end_of_metadata();
-                       bool process_until_end_of_stream();
-                       bool skip_single_frame();
+                       bool seek_absolute(FLAC__uint64 sample); ///< See FLAC__stream_decoder_seek_absolute()
                protected:
+                       /// see FLAC__StreamDecoderReadCallback
                        virtual ::FLAC__StreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes) = 0;
+
+                       /// see FLAC__StreamDecoderSeekCallback
+                       virtual ::FLAC__StreamDecoderSeekStatus seek_callback(FLAC__uint64 absolute_byte_offset);
+
+                       /// see FLAC__StreamDecoderTellCallback
+                       virtual ::FLAC__StreamDecoderTellStatus tell_callback(FLAC__uint64 *absolute_byte_offset);
+
+                       /// see FLAC__StreamDecoderLengthCallback
+                       virtual ::FLAC__StreamDecoderLengthStatus length_callback(FLAC__uint64 *stream_length);
+
+                       /// see FLAC__StreamDecoderEofCallback
+                       virtual bool eof_callback();
+
+                       /// see FLAC__StreamDecoderWriteCallback
                        virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
-                       virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
+
+                       /// see FLAC__StreamDecoderMetadataCallback
+                       virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata);
+
+                       /// see FLAC__StreamDecoderErrorCallback
                        virtual void error_callback(::FLAC__StreamDecoderErrorStatus status) = 0;
 
 #if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
@@ -146,12 +194,16 @@ namespace FLAC {
                        friend State;
 #endif
                        ::FLAC__StreamDecoder *decoder_;
-               private:
+
                        static ::FLAC__StreamDecoderReadStatus read_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
+                       static ::FLAC__StreamDecoderSeekStatus seek_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
+                       static ::FLAC__StreamDecoderTellStatus tell_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
+                       static ::FLAC__StreamDecoderLengthStatus length_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
+                       static FLAC__bool eof_callback_(const ::FLAC__StreamDecoder *decoder, void *client_data);
                        static ::FLAC__StreamDecoderWriteStatus write_callback_(const ::FLAC__StreamDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
                        static void metadata_callback_(const ::FLAC__StreamDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
                        static void error_callback_(const ::FLAC__StreamDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
-
+               private:
                        // Private and undefined so you can't use them:
                        Stream(const Stream &);
                        void operator=(const Stream &);
@@ -159,186 +211,56 @@ namespace FLAC {
 
                /* \} */
 
-               // ============================================================
-               //
-               //  Equivalent: FLAC__SeekableStreamDecoder
-               //
-               // ============================================================
-
-               /** \defgroup flacpp_seekable_stream_decoder FLAC++/decoder.h: seekable stream decoder class
+               /** \defgroup flacpp_file_decoder FLAC++/decoder.h: file decoder class
                 *  \ingroup flacpp_decoder
                 *
                 *  \brief
-                *  This class wraps the ::FLAC__SeekableStreamDecoder.
+                *  This class wraps the ::FLAC__StreamDecoder.
                 *
-                * See the \link flac_seekable_stream_decoder libFLAC seekable stream decoder module \endlink.
+                * See the \link flac_stream_decoder libFLAC stream decoder module \endlink
+                * for basic usage.
                 *
                 * \{
                 */
 
-               /** This class wraps the ::FLAC__SeekableStreamDecoder.
-                */
-               class FLACPP_API SeekableStream {
-               public:
-                       class FLACPP_API State {
-                       public:
-                               inline State(::FLAC__SeekableStreamDecoderState state): state_(state) { }
-                               inline operator ::FLAC__SeekableStreamDecoderState() const { return state_; }
-                               inline const char *as_cstring() const { return ::FLAC__SeekableStreamDecoderStateString[state_]; }
-                               inline const char *resolved_as_cstring(const SeekableStream &decoder) const { return ::FLAC__seekable_stream_decoder_get_resolved_state_string(decoder.decoder_); }
-                       protected:
-                               ::FLAC__SeekableStreamDecoderState state_;
-                       };
-
-                       SeekableStream();
-                       virtual ~SeekableStream();
-
-                       bool is_valid() const;
-                       inline operator bool() const { return is_valid(); }
-
-                       bool set_md5_checking(bool value);
-                       bool set_metadata_respond(::FLAC__MetadataType type);
-                       bool set_metadata_respond_application(const FLAC__byte id[4]);
-                       bool set_metadata_respond_all();
-                       bool set_metadata_ignore(::FLAC__MetadataType type);
-                       bool set_metadata_ignore_application(const FLAC__byte id[4]);
-                       bool set_metadata_ignore_all();
-
-                       State get_state() const;
-                       Stream::State get_stream_decoder_state() const;
-                       bool get_md5_checking() const;
-                       unsigned get_channels() const;
-                       ::FLAC__ChannelAssignment get_channel_assignment() const;
-                       unsigned get_bits_per_sample() const;
-                       unsigned get_sample_rate() const;
-                       unsigned get_blocksize() const;
-
-                       State init();
-
-                       bool finish();
-
-                       bool flush();
-                       bool reset();
-
-                       bool process_single();
-                       bool process_until_end_of_metadata();
-                       bool process_until_end_of_stream();
-                       bool skip_single_frame();
-
-                       bool seek_absolute(FLAC__uint64 sample);
-               protected:
-                       virtual ::FLAC__SeekableStreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes) = 0;
-                       virtual ::FLAC__SeekableStreamDecoderSeekStatus seek_callback(FLAC__uint64 absolute_byte_offset) = 0;
-                       virtual ::FLAC__SeekableStreamDecoderTellStatus tell_callback(FLAC__uint64 *absolute_byte_offset) = 0;
-                       virtual ::FLAC__SeekableStreamDecoderLengthStatus length_callback(FLAC__uint64 *stream_length) = 0;
-                       virtual bool eof_callback() = 0;
-                       virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
-                       virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
-                       virtual void error_callback(::FLAC__StreamDecoderErrorStatus status) = 0;
-
-#if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
-                       // lame hack: some MSVC/GCC versions can't see a protected decoder_ from nested State::resolved_as_cstring()
-                       friend State;
-#endif
-                       ::FLAC__SeekableStreamDecoder *decoder_;
-               private:
-                       static ::FLAC__SeekableStreamDecoderReadStatus read_callback_(const ::FLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
-                       static ::FLAC__SeekableStreamDecoderSeekStatus seek_callback_(const ::FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
-                       static ::FLAC__SeekableStreamDecoderTellStatus tell_callback_(const ::FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
-                       static ::FLAC__SeekableStreamDecoderLengthStatus length_callback_(const ::FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
-                       static FLAC__bool eof_callback_(const ::FLAC__SeekableStreamDecoder *decoder, void *client_data);
-                       static ::FLAC__StreamDecoderWriteStatus write_callback_(const ::FLAC__SeekableStreamDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
-                       static void metadata_callback_(const ::FLAC__SeekableStreamDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
-                       static void error_callback_(const ::FLAC__SeekableStreamDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
-
-                       // Private and undefined so you can't use them:
-                       SeekableStream(const SeekableStream &);
-                       void operator=(const SeekableStream &);
-               };
-
-               /* \} */
-
-               // ============================================================
-               //
-               //  Equivalent: FLAC__FileDecoder
-               //
-               // ============================================================
-
-               /** \defgroup flacpp_file_decoder FLAC++/decoder.h: file decoder class
-                *  \ingroup flacpp_decoder
+               /** This class wraps the ::FLAC__StreamDecoder.  If you are
+                *  not decoding from a file, you may need to use
+                *  FLAC::Decoder::Stream.
                 *
-                *  \brief
-                *  This class wraps the ::FLAC__FileDecoder.
-                *
-                * See the \link flac_file_decoder libFLAC file decoder module \endlink.
+                * The usage of this class is similar to FLAC__StreamDecoder,
+                * except instead of providing callbacks to
+                * FLAC__stream_decoder_init_FILE() or
+                * FLAC__stream_decoder_init_file(), you will inherit from this
+                * class and override the virtual callback functions with your
+                * own implementations, then call File::init().  The rest of
+                * the calls work the same as in the C layer.
                 *
-                * \{
-                */
-
-               /** This class wraps the ::FLAC__FileDecoder.
+                * Only the write, and error callbacks from FLAC::Decoder::Stream
+                * are mandatory.  The others are optional; this class provides
+                * full working implementations for all other callbacks and
+                * supports seeking.
                 */
-               class FLACPP_API File {
+               class FLACPP_API File: public Stream {
                public:
-                       class FLACPP_API State {
-                       public:
-                               inline State(::FLAC__FileDecoderState state): state_(state) { }
-                               inline operator ::FLAC__FileDecoderState() const { return state_; }
-                               inline const char *as_cstring() const { return ::FLAC__FileDecoderStateString[state_]; }
-                               inline const char *resolved_as_cstring(const File &decoder) const { return ::FLAC__file_decoder_get_resolved_state_string(decoder.decoder_); }
-                       protected:
-                               ::FLAC__FileDecoderState state_;
-                       };
-
                        File();
                        virtual ~File();
 
-                       bool is_valid() const;
-                       inline operator bool() const { return is_valid(); }
-
-                       bool set_md5_checking(bool value);
-                       bool set_filename(const char *value); //!< 'value' may not be \c NULL; use "-" for stdin
-                       bool set_metadata_respond(::FLAC__MetadataType type);
-                       bool set_metadata_respond_application(const FLAC__byte id[4]);
-                       bool set_metadata_respond_all();
-                       bool set_metadata_ignore(::FLAC__MetadataType type);
-                       bool set_metadata_ignore_application(const FLAC__byte id[4]);
-                       bool set_metadata_ignore_all();
-
-                       State get_state() const;
-                       SeekableStream::State get_seekable_stream_decoder_state() const;
-                       Stream::State get_stream_decoder_state() const;
-                       bool get_md5_checking() const;
-                       unsigned get_channels() const;
-                       ::FLAC__ChannelAssignment get_channel_assignment() const;
-                       unsigned get_bits_per_sample() const;
-                       unsigned get_sample_rate() const;
-                       unsigned get_blocksize() const;
-
-                       State init();
-
-                       bool finish();
-
-                       bool process_single();
-                       bool process_until_end_of_metadata();
-                       bool process_until_end_of_file();
-                       bool skip_single_frame();
-
-                       bool seek_absolute(FLAC__uint64 sample);
+                       /** Initialize the instance; as with the C interface,
+                        *  init() should be called after construction and 'set'
+                        *  calls but before any of the 'process' calls.
+                        *
+                        *  See FLAC__stream_decoder_init_FILE() and
+                        *  FLAC__stream_decoder_init_file().
+                        *  \{
+                        */
+                       ::FLAC__StreamDecoderInitStatus init(FILE *file);
+                       ::FLAC__StreamDecoderInitStatus init(const char *filename);
+                       ::FLAC__StreamDecoderInitStatus init(const std::string &filename);
+                       /*  \} */
                protected:
-                       virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
-                       virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
-                       virtual void error_callback(::FLAC__StreamDecoderErrorStatus status) = 0;
-
-#if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
-                       // lame hack: some MSVC/GCC versions can't see a protected decoder_ from nested State::resolved_as_cstring()
-                       friend State;
-#endif
-                       ::FLAC__FileDecoder *decoder_;
+                       // this is a dummy implementation to satisfy the pure virtual in Stream that is actually supplied internally by the C layer
+                       virtual ::FLAC__StreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes);
                private:
-                       static ::FLAC__StreamDecoderWriteStatus write_callback_(const ::FLAC__FileDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
-                       static void metadata_callback_(const ::FLAC__FileDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
-                       static void error_callback_(const ::FLAC__FileDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
-
                        // Private and undefined so you can't use them:
                        File(const File &);
                        void operator=(const File &);
index 88768ae..4e31011 100644 (file)
@@ -34,8 +34,6 @@
 
 #include "export.h"
 
-#include "FLAC/file_encoder.h"
-#include "FLAC/seekable_stream_encoder.h"
 #include "FLAC/stream_encoder.h"
 #include "decoder.h"
 #include "metadata.h"
  *  \ingroup flacpp
  *
  *  \brief
- *  This module describes the three encoder layers provided by libFLAC++.
+ *  This module describes the encoder layers provided by libFLAC++.
  *
  * The libFLAC++ encoder classes are object wrappers around their
- * counterparts in libFLAC.  All three encoding layers available in
+ * counterparts in libFLAC.  All decoding layers available in
  * libFLAC are also provided here.  The interface is very similar;
  * make sure to read the \link flac_encoder libFLAC encoder module \endlink.
  *
- * The only real difference here is that instead of passing in C function
- * pointers for callbacks, you inherit from the encoder class and provide
- * implementations for the callbacks in the derived class; because of this
- * there is no need for a 'client_data' property.
+ * There are only two significant differences here.  First, instead of
+ * passing in C function pointers for callbacks, you inherit from the
+ * encoder class and provide implementations for the callbacks in your
+ * derived class; because of this there is no need for a 'client_data'
+ * property.
+ *
+ * Second, there are two stream encoder classes.  FLAC::Encoder::Stream
+ * is used for the same cases that FLAC__stream_encoder_init_stream() is
+ * used, and FLAC::Encoder::File is used for the same cases that
+ * FLAC__stream_encoder_init_FILE() and FLAC__stream_encoder_init_file()
+ * are used.
  */
 
 namespace FLAC {
        namespace Encoder {
 
-               // ============================================================
-               //
-               //  Equivalent: FLAC__StreamEncoder
-               //
-               // ============================================================
-
                /** \defgroup flacpp_stream_encoder FLAC++/encoder.h: stream encoder class
                 *  \ingroup flacpp_encoder
                 *
                 *  \brief
                 *  This class wraps the ::FLAC__StreamEncoder.
                 *
-                * See the \link flac_stream_encoder libFLAC stream encoder module \endlink.
+                * See the \link flac_stream_encoder libFLAC stream encoder module \endlink
+                * for basic usage.
                 *
                 * \{
                 */
 
-               /** This class wraps the ::FLAC__StreamEncoder.
+               /** This class wraps the ::FLAC__StreamEncoder.  If you are
+                *  encoding to a file, FLAC::Encoder::File may be more
+                *  convenient.
+                *
+                * The usage of this class is similar to FLAC__StreamEncoder,
+                * except instead of providing callbacks to
+                * FLAC__stream_encoder_init_stream(), you will inherit from this
+                * class and override the virtual callback functions with your
+                * own implementations, then call Stream::init().  The rest of
+                * the calls work the same as in the C layer.
+                *
+                * Only the write callback is mandatory.  The others are
+                * optional; this class provides default implementations that do
+                * nothing.  In order for some STREAMINFO and SEEKTABLE data to
+                * be written properly, you must overide seek_callback() and
+                * tell_callback(); see FLAC__stream_encoder_init_stream() as to
+                * why.
                 */
                class FLACPP_API Stream {
                public:
@@ -105,70 +121,93 @@ namespace FLAC {
                        Stream();
                        virtual ~Stream();
 
+                       /** Call after construction to check the that the object was created
+                        *  successfully.  If not, use get_state() to find out why not.
+                        *
+                        * \{
+                        */
                        bool is_valid() const;
                        inline operator bool() const { return is_valid(); }
+                       /* \} */
+
+                       bool set_verify(bool value);                            ///< See FLAC__stream_encoder_set_verify()
+                       bool set_streamable_subset(bool value);                 ///< See FLAC__stream_encoder_set_streamable_subset()
+                       bool set_do_mid_side_stereo(bool value);                ///< See FLAC__stream_encoder_set_do_mid_side_stereo()
+                       bool set_loose_mid_side_stereo(bool value);             ///< See FLAC__stream_encoder_set_loose_mid_side_stereo()
+                       bool set_channels(unsigned value);                      ///< See FLAC__stream_encoder_set_channels()
+                       bool set_bits_per_sample(unsigned value);               ///< See FLAC__stream_encoder_set_bits_per_sample()
+                       bool set_sample_rate(unsigned value);                   ///< See FLAC__stream_encoder_set_sample_rate()
+                       bool set_blocksize(unsigned value);                     ///< See FLAC__stream_encoder_set_blocksize()
+                       bool set_apodization(const char *specification);        ///< See FLAC__stream_encoder_set_apodization()
+                       bool set_max_lpc_order(unsigned value);                 ///< See FLAC__stream_encoder_set_max_lpc_order()
+                       bool set_qlp_coeff_precision(unsigned value);           ///< See FLAC__stream_encoder_set_qlp_coeff_precision()
+                       bool set_do_qlp_coeff_prec_search(bool value);          ///< See FLAC__stream_encoder_set_do_qlp_coeff_prec_search()
+                       bool set_do_escape_coding(bool value);                  ///< See FLAC__stream_encoder_set_do_escape_coding()
+                       bool set_do_exhaustive_model_search(bool value);        ///< See FLAC__stream_encoder_set_do_exhaustive_model_search()
+                       bool set_min_residual_partition_order(unsigned value);  ///< See FLAC__stream_encoder_set_min_residual_partition_order()
+                       bool set_max_residual_partition_order(unsigned value);  ///< See FLAC__stream_encoder_set_max_residual_partition_order()
+                       bool set_rice_parameter_search_dist(unsigned value);    ///< See FLAC__stream_encoder_set_rice_parameter_search_dist()
+                       bool set_total_samples_estimate(FLAC__uint64 value);    ///< See FLAC__stream_encoder_set_total_samples_estimate()
+                       bool set_metadata(::FLAC__StreamMetadata **metadata, unsigned num_blocks);    ///< See FLAC__stream_encoder_set_metadata()
+                       bool set_metadata(FLAC::Metadata::Prototype **metadata, unsigned num_blocks); ///< See FLAC__stream_encoder_set_metadata()
+
+                       State    get_state() const;                              ///< See FLAC__stream_encoder_get_state()
+                       Decoder::Stream::State get_verify_decoder_state() const; ///< See FLAC__stream_encoder_get_verify_decoder_state()
+                       void get_verify_decoder_error_stats(FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got); ///< See FLAC__stream_encoder_get_verify_decoder_error_stats()
+                       bool     get_verify() const;                       ///< See FLAC__stream_encoder_get_verify()
+                       bool     get_streamable_subset() const;            ///< See FLAC__stream_encoder_get_streamable_subset()
+                       bool     get_do_mid_side_stereo() const;           ///< See FLAC__stream_encoder_get_do_mid_side_stereo()
+                       bool     get_loose_mid_side_stereo() const;        ///< See FLAC__stream_encoder_get_loose_mid_side_stereo()
+                       unsigned get_channels() const;                     ///< See FLAC__stream_encoder_get_channels()
+                       unsigned get_bits_per_sample() const;              ///< See FLAC__stream_encoder_get_bits_per_sample()
+                       unsigned get_sample_rate() const;                  ///< See FLAC__stream_encoder_get_sample_rate()
+                       unsigned get_blocksize() const;                    ///< See FLAC__stream_encoder_get_blocksize()
+                       unsigned get_max_lpc_order() const;                ///< See FLAC__stream_encoder_get_max_lpc_order()
+                       unsigned get_qlp_coeff_precision() const;          ///< See FLAC__stream_encoder_get_qlp_coeff_precision()
+                       bool     get_do_qlp_coeff_prec_search() const;     ///< See FLAC__stream_encoder_get_do_qlp_coeff_prec_search()
+                       bool     get_do_escape_coding() const;             ///< See FLAC__stream_encoder_get_do_escape_coding()
+                       bool     get_do_exhaustive_model_search() const;   ///< See FLAC__stream_encoder_get_do_exhaustive_model_search()
+                       unsigned get_min_residual_partition_order() const; ///< See FLAC__stream_encoder_get_min_residual_partition_order()
+                       unsigned get_max_residual_partition_order() const; ///< See FLAC__stream_encoder_get_max_residual_partition_order()
+                       unsigned get_rice_parameter_search_dist() const;   ///< See FLAC__stream_encoder_get_rice_parameter_search_dist()
+                       FLAC__uint64 get_total_samples_estimate() const;   ///< See FLAC__stream_encoder_get_total_samples_estimate()
+
+                       /** Initialize the instance; as with the C interface,
+                        *  init() should be called after construction and 'set'
+                        *  calls but before any of the 'process' calls.
+                        *
+                        *  See FLAC__stream_encoder_init_stream().
+                        */
+                       ::FLAC__StreamEncoderInitStatus init();
+
+                       void finish(); ///< See FLAC__stream_encoder_finish()
+
+                       bool process(const FLAC__int32 * const buffer[], unsigned samples);     ///< See FLAC__stream_encoder_process()
+                       bool process_interleaved(const FLAC__int32 buffer[], unsigned samples); ///< See FLAC__stream_encoder_process_interleaved()
+               protected:
+                       /// See FLAC__StreamEncoderWriteCallback
+                       virtual ::FLAC__StreamEncoderWriteStatus write_callback(const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame) = 0;
 
-                       bool set_verify(bool value);
-                       bool set_streamable_subset(bool value);
-                       bool set_do_mid_side_stereo(bool value);
-                       bool set_loose_mid_side_stereo(bool value);
-                       bool set_channels(unsigned value);
-                       bool set_bits_per_sample(unsigned value);
-                       bool set_sample_rate(unsigned value);
-                       bool set_blocksize(unsigned value);
-                       bool set_apodization(const char *specification);
-                       bool set_max_lpc_order(unsigned value);
-                       bool set_qlp_coeff_precision(unsigned value);
-                       bool set_do_qlp_coeff_prec_search(bool value);
-                       bool set_do_escape_coding(bool value);
-                       bool set_do_exhaustive_model_search(bool value);
-                       bool set_min_residual_partition_order(unsigned value);
-                       bool set_max_residual_partition_order(unsigned value);
-                       bool set_rice_parameter_search_dist(unsigned value);
-                       bool set_total_samples_estimate(FLAC__uint64 value);
-                       bool set_metadata(::FLAC__StreamMetadata **metadata, unsigned num_blocks);
-                       bool set_metadata(FLAC::Metadata::Prototype **metadata, unsigned num_blocks);
-
-                       State    get_state() const;
-                       Decoder::Stream::State get_verify_decoder_state() const;
-                       void get_verify_decoder_error_stats(FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
-                       bool     get_verify() const;
-                       bool     get_streamable_subset() const;
-                       bool     get_do_mid_side_stereo() const;
-                       bool     get_loose_mid_side_stereo() const;
-                       unsigned get_channels() const;
-                       unsigned get_bits_per_sample() const;
-                       unsigned get_sample_rate() const;
-                       unsigned get_blocksize() const;
-                       unsigned get_max_lpc_order() const;
-                       unsigned get_qlp_coeff_precision() const;
-                       bool     get_do_qlp_coeff_prec_search() const;
-                       bool     get_do_escape_coding() const;
-                       bool     get_do_exhaustive_model_search() const;
-                       unsigned get_min_residual_partition_order() const;
-                       unsigned get_max_residual_partition_order() const;
-                       unsigned get_rice_parameter_search_dist() const;
-                       FLAC__uint64 get_total_samples_estimate() const;
+                       /// See FLAC__StreamEncoderSeekCallback
+                       virtual ::FLAC__StreamEncoderSeekStatus seek_callback(FLAC__uint64 absolute_byte_offset);
 
-                       State init();
+                       /// See FLAC__StreamEncoderTellCallback
+                       virtual ::FLAC__StreamEncoderTellStatus tell_callback(FLAC__uint64 *absolute_byte_offset);
 
-                       void finish();
-
-                       bool process(const FLAC__int32 * const buffer[], unsigned samples);
-                       bool process_interleaved(const FLAC__int32 buffer[], unsigned samples);
-               protected:
-                       virtual ::FLAC__StreamEncoderWriteStatus write_callback(const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame) = 0;
-                       virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
+                       /// See FLAC__StreamEncoderTellCallback
+                       virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata);
 
 #if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
                        // lame hack: some MSVC/GCC versions can't see a protected encoder_ from nested State::resolved_as_cstring()
                        friend State;
 #endif
                        ::FLAC__StreamEncoder *encoder_;
-               private:
+
                        static ::FLAC__StreamEncoderWriteStatus write_callback_(const ::FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
+                       static ::FLAC__StreamEncoderSeekStatus seek_callback_(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
+                       static ::FLAC__StreamEncoderTellStatus tell_callback_(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
                        static void metadata_callback_(const ::FLAC__StreamEncoder *encoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
-
+               private:
                        // Private and undefined so you can't use them:
                        Stream(const Stream &);
                        void operator=(const Stream &);
@@ -176,200 +215,61 @@ namespace FLAC {
 
                /* \} */
 
-               /** \defgroup flacpp_seekable_stream_encoder FLAC++/encoder.h: seekable stream encoder class
+               /** \defgroup flacpp_file_encoder FLAC++/encoder.h: file encoder class
                 *  \ingroup flacpp_encoder
                 *
                 *  \brief
-                *  This class wraps the ::FLAC__SeekableStreamEncoder.
+                *  This class wraps the ::FLAC__StreamEncoder.
                 *
-                * See the \link flac_seekable_stream_encoder libFLAC seekable stream encoder module \endlink.
+                * See the \link flac_stream_encoder libFLAC stream encoder module \endlink
+                * for basic usage.
                 *
                 * \{
                 */
 
-               /** This class wraps the ::FLAC__SeekableStreamEncoder.
-                */
-               class FLACPP_API SeekableStream {
-               public:
-                       class FLACPP_API State {
-                       public:
-                               inline State(::FLAC__SeekableStreamEncoderState state): state_(state) { }
-                               inline operator ::FLAC__SeekableStreamEncoderState() const { return state_; }
-                               inline const char *as_cstring() const { return ::FLAC__SeekableStreamEncoderStateString[state_]; }
-                               inline const char *resolved_as_cstring(const SeekableStream &encoder) const { return ::FLAC__seekable_stream_encoder_get_resolved_state_string(encoder.encoder_); }
-                       protected:
-                               ::FLAC__SeekableStreamEncoderState state_;
-                       };
-
-                       SeekableStream();
-                       virtual ~SeekableStream();
-
-                       bool is_valid() const;
-                       inline operator bool() const { return is_valid(); }
-
-                       bool set_verify(bool value);
-                       bool set_streamable_subset(bool value);
-                       bool set_do_mid_side_stereo(bool value);
-                       bool set_loose_mid_side_stereo(bool value);
-                       bool set_channels(unsigned value);
-                       bool set_bits_per_sample(unsigned value);
-                       bool set_sample_rate(unsigned value);
-                       bool set_blocksize(unsigned value);
-                       bool set_apodization(const char *specification);
-                       bool set_max_lpc_order(unsigned value);
-                       bool set_qlp_coeff_precision(unsigned value);
-                       bool set_do_qlp_coeff_prec_search(bool value);
-                       bool set_do_escape_coding(bool value);
-                       bool set_do_exhaustive_model_search(bool value);
-                       bool set_min_residual_partition_order(unsigned value);
-                       bool set_max_residual_partition_order(unsigned value);
-                       bool set_rice_parameter_search_dist(unsigned value);
-                       bool set_total_samples_estimate(FLAC__uint64 value);
-                       bool set_metadata(::FLAC__StreamMetadata **metadata, unsigned num_blocks);
-                       bool set_metadata(FLAC::Metadata::Prototype **metadata, unsigned num_blocks);
-
-                       State    get_state() const;
-                       Stream::State get_stream_encoder_state() const;
-                       Decoder::Stream::State get_verify_decoder_state() const;
-                       void get_verify_decoder_error_stats(FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
-                       bool     get_verify() const;
-                       bool     get_streamable_subset() const;
-                       bool     get_do_mid_side_stereo() const;
-                       bool     get_loose_mid_side_stereo() const;
-                       unsigned get_channels() const;
-                       unsigned get_bits_per_sample() const;
-                       unsigned get_sample_rate() const;
-                       unsigned get_blocksize() const;
-                       unsigned get_max_lpc_order() const;
-                       unsigned get_qlp_coeff_precision() const;
-                       bool     get_do_qlp_coeff_prec_search() const;
-                       bool     get_do_escape_coding() const;
-                       bool     get_do_exhaustive_model_search() const;
-                       unsigned get_min_residual_partition_order() const;
-                       unsigned get_max_residual_partition_order() const;
-                       unsigned get_rice_parameter_search_dist() const;
-                       FLAC__uint64 get_total_samples_estimate() const;
-
-                       State init();
-
-                       void finish();
-
-                       bool process(const FLAC__int32 * const buffer[], unsigned samples);
-                       bool process_interleaved(const FLAC__int32 buffer[], unsigned samples);
-               protected:
-                       virtual ::FLAC__SeekableStreamEncoderSeekStatus seek_callback(FLAC__uint64 absolute_byte_offset) = 0;
-                       virtual ::FLAC__SeekableStreamEncoderTellStatus tell_callback(FLAC__uint64 *absolute_byte_offset) = 0;
-                       virtual ::FLAC__StreamEncoderWriteStatus write_callback(const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame) = 0;
-
-#if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
-                       // lame hack: some MSVC/GCC versions can't see a protected encoder_ from nested State::resolved_as_cstring()
-                       friend State;
-#endif
-                       ::FLAC__SeekableStreamEncoder *encoder_;
-               private:
-                       static ::FLAC__SeekableStreamEncoderSeekStatus seek_callback_(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
-                       static ::FLAC__SeekableStreamEncoderTellStatus tell_callback_(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
-                       static ::FLAC__StreamEncoderWriteStatus write_callback_(const FLAC__SeekableStreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
-
-                       // Private and undefined so you can't use them:
-                       SeekableStream(const SeekableStream &);
-                       void operator=(const SeekableStream &);
-               };
-
-               /* \} */
-
-               /** \defgroup flacpp_file_encoder FLAC++/encoder.h: file encoder class
-                *  \ingroup flacpp_encoder
+               /** This class wraps the ::FLAC__StreamEncoder.  If you are
+                *  not encoding to a file, you may need to use
+                *  FLAC::Encoder::Stream.
                 *
-                *  \brief
-                *  This class wraps the ::FLAC__FileEncoder.
-                *
-                * See the \link flac_file_encoder libFLAC file encoder module \endlink.
+                * The usage of this class is similar to FLAC__StreamEncoder,
+                * except instead of providing callbacks to
+                * FLAC__stream_encoder_init_FILE() or
+                * FLAC__stream_encoder_init_file(), you will inherit from this
+                * class and override the virtual callback functions with your
+                * own implementations, then call File::init().  The rest of
+                * the calls work the same as in the C layer.
                 *
-                * \{
-                */
-
-               /** This class wraps the ::FLAC__FileEncoder.
+                * There are no mandatory callbacks; all the callbacks from
+                * FLAC::Encoder::Stream are implemented here fully and support
+                * full post-encode STREAMINFO and SEEKTABLE updating.  There is
+                * only an optional progress callback which you may override to
+                * get periodic reports on the progress of the encode.
                 */
-               class FLACPP_API File {
+               class FLACPP_API File: public Stream {
                public:
-                       class FLACPP_API State {
-                       public:
-                               inline State(::FLAC__FileEncoderState state): state_(state) { }
-                               inline operator ::FLAC__FileEncoderState() const { return state_; }
-                               inline const char *as_cstring() const { return ::FLAC__FileEncoderStateString[state_]; }
-                               inline const char *resolved_as_cstring(const File &encoder) const { return ::FLAC__file_encoder_get_resolved_state_string(encoder.encoder_); }
-                       protected:
-                               ::FLAC__FileEncoderState state_;
-                       };
-
+                       /** Initialize the instance; as with the C interface,
+                        *  init() should be called after construction and 'set'
+                        *  calls but before any of the 'process' calls.
+                        *
+                        *  See FLAC__stream_encoder_init_FILE() and
+                        *  FLAC__stream_encoder_init_file().
+                        *  \{
+                        */
                        File();
                        virtual ~File();
+                       /*  \} */
 
-                       bool is_valid() const;
-                       inline operator bool() const { return is_valid(); }
-
-                       bool set_verify(bool value);
-                       bool set_streamable_subset(bool value);
-                       bool set_do_mid_side_stereo(bool value);
-                       bool set_loose_mid_side_stereo(bool value);
-                       bool set_channels(unsigned value);
-                       bool set_bits_per_sample(unsigned value);
-                       bool set_sample_rate(unsigned value);
-                       bool set_blocksize(unsigned value);
-                       bool set_apodization(const char *specification);
-                       bool set_max_lpc_order(unsigned value);
-                       bool set_qlp_coeff_precision(unsigned value);
-                       bool set_do_qlp_coeff_prec_search(bool value);
-                       bool set_do_escape_coding(bool value);
-                       bool set_do_exhaustive_model_search(bool value);
-                       bool set_min_residual_partition_order(unsigned value);
-                       bool set_max_residual_partition_order(unsigned value);
-                       bool set_rice_parameter_search_dist(unsigned value);
-                       bool set_total_samples_estimate(FLAC__uint64 value);
-                       bool set_metadata(::FLAC__StreamMetadata **metadata, unsigned num_blocks);
-                       bool set_metadata(FLAC::Metadata::Prototype **metadata, unsigned num_blocks);
-                       bool set_filename(const char *value);
-
-                       State    get_state() const;
-                       SeekableStream::State get_seekable_stream_encoder_state() const;
-                       Stream::State get_stream_encoder_state() const;
-                       Decoder::Stream::State get_verify_decoder_state() const;
-                       void get_verify_decoder_error_stats(FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
-                       bool     get_verify() const;
-                       bool     get_streamable_subset() const;
-                       bool     get_do_mid_side_stereo() const;
-                       bool     get_loose_mid_side_stereo() const;
-                       unsigned get_channels() const;
-                       unsigned get_bits_per_sample() const;
-                       unsigned get_sample_rate() const;
-                       unsigned get_blocksize() const;
-                       unsigned get_max_lpc_order() const;
-                       unsigned get_qlp_coeff_precision() const;
-                       bool     get_do_qlp_coeff_prec_search() const;
-                       bool     get_do_escape_coding() const;
-                       bool     get_do_exhaustive_model_search() const;
-                       unsigned get_min_residual_partition_order() const;
-                       unsigned get_max_residual_partition_order() const;
-                       unsigned get_rice_parameter_search_dist() const;
-                       FLAC__uint64 get_total_samples_estimate() const;
-
-                       State init();
-
-                       void finish();
-
-                       bool process(const FLAC__int32 * const buffer[], unsigned samples);
-                       bool process_interleaved(const FLAC__int32 buffer[], unsigned samples);
+                       ::FLAC__StreamEncoderInitStatus init(FILE *file);
+                       ::FLAC__StreamEncoderInitStatus init(const char *filename);
+                       ::FLAC__StreamEncoderInitStatus init(const std::string &filename);
                protected:
+                       /// See FLAC__StreamEncoderProgressCallback
                        virtual void progress_callback(FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate);
 
-#if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
-                       // lame hack: some MSVC/GCC versions can't see a protected encoder_ from nested State::resolved_as_cstring()
-                       friend State;
-#endif
-                       ::FLAC__FileEncoder *encoder_;
+                       /// This is a dummy implementation to satisfy the pure virtual in Stream that is actually supplied internally by the C layer
+                       virtual ::FLAC__StreamEncoderWriteStatus write_callback(const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame);
                private:
-                       static void progress_callback_(const ::FLAC__FileEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data);
+                       static void progress_callback_(const ::FLAC__StreamEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data);
 
                        // Private and undefined so you can't use them:
                        File(const Stream &);
index 6d93500..a7a1681 100644 (file)
@@ -35,12 +35,8 @@ flaccinclude_HEADERS = \
        assert.h \
        callback.h \
        export.h \
-       file_decoder.h \
-       file_encoder.h \
        format.h \
        metadata.h \
        ordinals.h \
-       seekable_stream_decoder.h \
-       seekable_stream_encoder.h \
        stream_decoder.h \
        stream_encoder.h
index 918cabe..e022d11 100644 (file)
 
 #include "assert.h"
 #include "callback.h"
-#include "file_decoder.h"
-#include "file_encoder.h"
 #include "format.h"
 #include "metadata.h"
 #include "ordinals.h"
-#include "seekable_stream_decoder.h"
-#include "seekable_stream_encoder.h"
 #include "stream_decoder.h"
 #include "stream_encoder.h"
 
  * individual functions.  You can see different views of the individual
  * functions through the links in top bar across this page.
  *
+ * \section porting_guide Porting Guide
+ *
+ * Starting with FLAC 1.1.3 a \link porting Porting Guide \endlink
+ * has been introduced which gives detailed instructions on how to
+ * port your code to newer versions of FLAC.
+ *
  * \section embedded_developers Embedded Developers
  *
  * libFLAC has grown larger over time as more functionality has been
  * will greatly reduce the size of the library.
  */
 
+/** \defgroup porting Porting Guide for New Versions
+ *
+ * This module describes differences in the library interfaces from
+ * version to version.  It assists in the porting of code that uses
+ * the libraries to newer versions of FLAC.
+ */
+
+/** \defgroup porting_1_1_2_to_1_1_3 Porting from FLAC 1.1.2 to 1.1.3
+ *  \ingroup porting
+ *
+ *  \brief
+ *  This module describes porting from FLAC 1.1.2 to FLAC 1.1.3.
+ *
+ * The main change between the APIs in 1.1.2 and 1.1.3 is that the three
+ * decoding layers and three encoding layers have been merged into a
+ * single stream decoder and stream encoder.  That is, the functionality
+ * of FLAC__SeekableStreamDecoder and FLAC__FileDecoder has been merged
+ * into FLAC__StreamDecoder, and FLAC__SeekableStreamEncoder and
+ * FLAC__FileEncoder into FLAC__StreamEncoder.  Only the
+ * FLAC__StreamDecoder and FLAC__StreamEncoder remain.  This can
+ * simplify code that needs to process both seekable and non-seekable
+ * streams.
+ *
+ * Instead of creating an encoder or decoder of a certain layer, now the
+ * client will always create a FLAC__StreamEncoder or
+ * FLAC__StreamDecoder.  The different layers are differentiated by the
+ * initialization function.  For example, for the decoder,
+ * FLAC__stream_decoder_init() has been replaced by
+ * FLAC__stream_decoder_init_stream().  This init function takes
+ * callbacks for the I/O, and the seeking callbacks are optional.  This
+ * allows the client to use the same object for seekable and
+ * non-seekable streams.  For decoding a FLAC file directly, the client
+ * can use FLAC__stream_decoder_init_file() and pass just a filename
+ * and fewer callbacks; most of the other callbacks are supplied
+ * internally.  For situations where fopen()ing by filename is not
+ * possible (e.g. Unicode filenames on Windows) the client can instead
+ * open the file itself and supply the FILE* to
+ * FLAC__stream_decoder_init_FILE().  The init functions now returns a
+ * FLAC__StreamDecoderInitStatus instead of FLAC__StreamDecoderState.
+ * Since the callbacks and client data are now passed to the init
+ * function, the FLAC__stream_decoder_set_*_callback() functions and
+ * FLAC__stream_decoder_set_client_data() are no longer needed.  The
+ * rest of the calls to the decoder are the same as before.
+ *
+ * As an example, in FLAC 1.1.2 a seekable stream decoder would be set
+ * up like so:
+ *@@@@@@CHECK@@@@@@
+ * \code
+ * FLAC__SeekableStreamDecoder *decoder = FLAC__seekable_stream_decoder_new();
+ * if(decoder == NULL) do something;
+ * FLAC__seekable_stream_decoder_set_md5_checking(decoder, true);
+ * [... other settings ...]
+ * FLAC__seekable_stream_decoder_set_read_callback(decoder, my_read_callback);
+ * FLAC__seekable_stream_decoder_set_seek_callback(decoder, my_seek_callback);
+ * FLAC__seekable_stream_decoder_set_tell_callback(decoder, my_tell_callback);
+ * FLAC__seekable_stream_decoder_set_length_callback(decoder, my_length_callback);
+ * FLAC__seekable_stream_decoder_set_eof_callback(decoder, my_eof_callback);
+ * FLAC__seekable_stream_decoder_set_write_callback(decoder, my_write_callback);
+ * FLAC__seekable_stream_decoder_set_metadata_callback(decoder, my_metadata_callback);
+ * FLAC__seekable_stream_decoder_set_error_callback(decoder, my_error_callback);
+ * FLAC__seekable_stream_decoder_set_client_data(decoder, my_client_data);
+ * if(FLAC__seekable_stream_decoder_init(decoder) != FLAC__SEEKABLE_STREAM_DECODER_OK) do something;
+ * \endcode
+ *
+ * In FLAC 1.1.3 it is like this:
+ *
+ * \code
+ * FLAC__StreamDecoder *decoder = FLAC__stream_decoder_new();
+ * if(decoder == NULL) do something;
+ * FLAC__stream_decoder_set_md5_checking(decoder, true);
+ * [... other settings ...]
+ * if(FLAC__stream_decoder_init_stream(
+ *   decoder,
+ *   my_read_callback,
+ *   my_seek_callback,      // or NULL
+ *   my_tell_callback,      // or NULL
+ *   my_length_callback,    // or NULL
+ *   my_eof_callback,       // or NULL
+ *   my_write_callback,
+ *   my_metadata_callback,  // or NULL
+ *   my_error_callback,
+ *   my_client_data,
+ * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do something;
+ * \endcode
+ *
+ * or you could do;
+ *
+ * \code
+ * [...]
+ * FILE *file = fopen("somefile.flac","rb");
+ * if(file == NULL) do somthing;
+ * if(FLAC__stream_decoder_init_FILE(
+ *   decoder,
+ *   file,
+ *   my_write_callback,
+ *   my_metadata_callback,  // or NULL
+ *   my_error_callback,
+ *   my_client_data,
+ * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do something;
+ * \endcode
+ *
+ * or just:
+ *
+ * \code
+ * [...]
+ * if(FLAC__stream_decoder_init_FILE(
+ *   decoder,
+ *   "somefile.flac",
+ *   my_write_callback,
+ *   my_metadata_callback,  // or NULL
+ *   my_error_callback,
+ *   my_client_data,
+ * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do something;
+ * \endcode
+ *
+ * Another small change to the decoder is in how it handles unparseable
+ * streams.  Before, when the decoder found an unparseable stream
+ * (reserved for when the decoder encounters a stream from a future
+ * encoder that it can't parse), it changed the state to
+ * \c FLAC__STREAM_DECODER_UNPARSEABLE_STREAM.  Now the decoder instead
+ * drops sync and calls the error callback with a new error code
+ * \c FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM.  This is
+ * more robust.  If your error callback does not discriminate on the the
+ * error state, your code does not need to be changed.
+ *
+ * The encoder now has a new setting:
+ * FLAC__stream_encoder_set_apodization().  This is for setting the
+ * method used to window the data before LPC analysis.  You only need to
+ * add a call to this function if the default is not   There are also
+ * two new convenience functions that may be useful:
+ * FLAC__metadata_object_cuesheet_calculate_cddb_id() and
+ * FLAC__metadata_get_cuesheet().
+ */
+
 /** \defgroup flac FLAC C API
  *
  * The FLAC C API is the interface to libFLAC, a set of structures
diff --git a/include/FLAC/file_decoder.h b/include/FLAC/file_decoder.h
deleted file mode 100644 (file)
index 9c83b0d..0000000
+++ /dev/null
@@ -1,660 +0,0 @@
-/* libFLAC - Free Lossless Audio Codec library
- * Copyright (C) 2000,2001,2002,2003,2004,2005,2006 Josh Coalson
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions
- * are met:
- *
- * - Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
- *
- * - Redistributions in binary form must reproduce the above copyright
- * notice, this list of conditions and the following disclaimer in the
- * documentation and/or other materials provided with the distribution.
- *
- * - Neither the name of the Xiph.org Foundation nor the names of its
- * contributors may be used to endorse or promote products derived from
- * this software without specific prior written permission.
- *
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
- * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
- * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
- * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
- * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
- * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
- * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
- * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- */
-
-#ifndef FLAC__FILE_DECODER_H
-#define FLAC__FILE_DECODER_H
-
-#include "export.h"
-#include "seekable_stream_decoder.h"
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-
-/** \file include/FLAC/file_decoder.h
- *
- *  \brief
- *  This module contains the functions which implement the file
- *  decoder.
- *
- *  See the detailed documentation in the
- *  \link flac_file_decoder file decoder \endlink module.
- */
-
-/** \defgroup flac_file_decoder FLAC/file_decoder.h: file decoder interface
- *  \ingroup flac_decoder
- *
- *  \brief
- *  This module contains the functions which implement the file
- *  decoder.
- *
- * The basic usage of this decoder is as follows:
- * - The program creates an instance of a decoder using
- *   FLAC__file_decoder_new().
- * - The program overrides the default settings and sets callbacks for
- *   writing, error reporting, and metadata reporting using
- *   FLAC__file_decoder_set_*() functions.
- * - The program initializes the instance to validate the settings and
- *   prepare for decoding using FLAC__file_decoder_init().
- * - The program calls the FLAC__file_decoder_process_*() functions
- *   to decode data, which subsequently calls the callbacks.
- * - The program finishes the decoding with FLAC__file_decoder_finish(),
- *   which flushes the input and output and resets the decoder to the
- *   uninitialized state.
- * - The instance may be used again or deleted with
- *   FLAC__file_decoder_delete().
- *
- * The file decoder is a trivial wrapper around the
- * \link flac_seekable_stream_decoder seekable stream decoder \endlink
- * meant to simplfy the process of decoding from a standard file.  The
- * file decoder supplies all but the Write/Metadata/Error callbacks.
- * The user needs only to provide the path to the file and the file
- * decoder handles the rest.
- *
- * Like the seekable stream decoder, seeking is exposed through the
- * FLAC__file_decoder_seek_absolute() method.  At any point after the file
- * decoder has been initialized, the user can call this function to seek to
- * an exact sample within the file.  Subsequently, the first time the write
- * callback is called it will be passed a (possibly partial) block starting
- * at that sample.
- *
- * The file decoder also inherits MD5 signature checking from the seekable
- * stream decoder.  If this is turned on before initialization,
- * FLAC__file_decoder_finish() will report when the decoded MD5 signature
- * does not match the one stored in the STREAMINFO block.  MD5 checking is
- * automatically turned off if there is no signature in the STREAMINFO
- * block or when a seek is attempted.
- *
- * Make sure to read the detailed descriptions of the
- * \link flac_seekable_stream_decoder seekable stream decoder module \endlink
- * and \link flac_stream_decoder stream decoder module \endlink
- * since the file decoder inherits much of its behavior from them.
- *
- * \note
- * The "set" functions may only be called when the decoder is in the
- * state FLAC__FILE_DECODER_UNINITIALIZED, i.e. after
- * FLAC__file_decoder_new() or FLAC__file_decoder_finish(), but
- * before FLAC__file_decoder_init().  If this is the case they will
- * return \c true, otherwise \c false.
- *
- * \note
- * FLAC__file_decoder_finish() resets all settings to the constructor
- * defaults, including the callbacks.
- *
- * \{
- */
-
-
-/** State values for a FLAC__FileDecoder
- *
- *  The decoder's state can be obtained by calling FLAC__file_decoder_get_state().
- */
-typedef enum {
-
-       FLAC__FILE_DECODER_OK = 0,
-       /**< The decoder is in the normal OK state. */
-
-       FLAC__FILE_DECODER_END_OF_FILE,
-       /**< The decoder has reached the end of the file. */
-
-       FLAC__FILE_DECODER_ERROR_OPENING_FILE,
-       /**< An error occurred opening the input file. */
-
-       FLAC__FILE_DECODER_MEMORY_ALLOCATION_ERROR,
-       /**< An error occurred allocating memory. */
-
-       FLAC__FILE_DECODER_SEEK_ERROR,
-       /**< An error occurred while seeking. */
-
-       FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR,
-       /**< An error occurred in the underlying seekable stream decoder. */
-
-       FLAC__FILE_DECODER_ALREADY_INITIALIZED,
-       /**< FLAC__file_decoder_init() was called when the decoder was already
-        * initialized, usually because FLAC__file_decoder_finish() was not
-        * called.
-        */
-
-       FLAC__FILE_DECODER_INVALID_CALLBACK,
-       /**< FLAC__file_decoder_init() was called without all callbacks
-        * being set.
-        */
-
-       FLAC__FILE_DECODER_UNINITIALIZED
-       /**< The decoder is in the uninitialized state. */
-
-} FLAC__FileDecoderState;
-
-/** Maps a FLAC__FileDecoderState to a C string.
- *
- *  Using a FLAC__FileDecoderState as the index to this array
- *  will give the string equivalent.  The contents should not be modified.
- */
-extern FLAC_API const char * const FLAC__FileDecoderStateString[];
-
-
-/***********************************************************************
- *
- * class FLAC__FileDecoder : public FLAC__StreamDecoder
- *
- ***********************************************************************/
-
-struct FLAC__FileDecoderProtected;
-struct FLAC__FileDecoderPrivate;
-/** The opaque structure definition for the file decoder type.  See the
- *  \link flac_file_decoder file decoder module \endlink for a detailed
- *  description.
- */
-typedef struct {
-       struct FLAC__FileDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
-       struct FLAC__FileDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
-} FLAC__FileDecoder;
-
-/** Signature for the write callback.
- *  See FLAC__file_decoder_set_write_callback()
- *  and FLAC__SeekableStreamDecoderWriteCallback for more info.
- *
- * \param  decoder  The decoder instance calling the callback.
- * \param  frame    The description of the decoded frame.
- * \param  buffer   An array of pointers to decoded channels of data.
- * \param  client_data  The callee's client data set through
- *                      FLAC__file_decoder_set_client_data().
- * \retval FLAC__StreamDecoderWriteStatus
- *    The callee's return status.
- */
-typedef FLAC__StreamDecoderWriteStatus (*FLAC__FileDecoderWriteCallback)(const FLAC__FileDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
-
-/** Signature for the metadata callback.
- *  See FLAC__file_decoder_set_metadata_callback()
- *  and FLAC__SeekableStreamDecoderMetadataCallback for more info.
- *
- * \param  decoder  The decoder instance calling the callback.
- * \param  metadata The decoded metadata block.
- * \param  client_data  The callee's client data set through
- *                      FLAC__file_decoder_set_client_data().
- */
-typedef void (*FLAC__FileDecoderMetadataCallback)(const FLAC__FileDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
-
-/** Signature for the error callback.
- *  See FLAC__file_decoder_set_error_callback()
- *  and FLAC__SeekableStreamDecoderErrorCallback for more info.
- *
- * \param  decoder  The decoder instance calling the callback.
- * \param  status   The error encountered by the decoder.
- * \param  client_data  The callee's client data set through
- *                      FLAC__file_decoder_set_client_data().
- */
-typedef void (*FLAC__FileDecoderErrorCallback)(const FLAC__FileDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
-
-
-/***********************************************************************
- *
- * Class constructor/destructor
- *
- ***********************************************************************/
-
-/** Create a new file decoder instance.  The instance is created with
- *  default settings; see the individual FLAC__file_decoder_set_*()
- *  functions for each setting's default.
- *
- * \retval FLAC__FileDecoder*
- *    \c NULL if there was an error allocating memory, else the new instance.
- */
-FLAC_API FLAC__FileDecoder *FLAC__file_decoder_new();
-
-/** Free a decoder instance.  Deletes the object pointed to by \a decoder.
- *
- * \param decoder  A pointer to an existing decoder.
- * \assert
- *    \code decoder != NULL \endcode
- */
-FLAC_API void FLAC__file_decoder_delete(FLAC__FileDecoder *decoder);
-
-
-/***********************************************************************
- *
- * Public class method prototypes
- *
- ***********************************************************************/
-
-/** Set the "MD5 signature checking" flag.
- *  This is inherited from FLAC__SeekableStreamDecoder; see
- *  FLAC__seekable_stream_decoder_set_md5_checking().
- *
- * \default \c false
- * \param  decoder  A decoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_decoder_set_md5_checking(FLAC__FileDecoder *decoder, FLAC__bool value);
-
-/** Set the input file name to decode.
- *
- * \default \c "-"
- * \param  decoder  A decoder instance to set.
- * \param  value    The input file name, or "-" for \c stdin.
- * \assert
- *    \code decoder != NULL \endcode
- *    \code value != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, or there was a memory
- *    allocation error, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_decoder_set_filename(FLAC__FileDecoder *decoder, const char *value);
-
-/** Set the write callback.
- *  This is inherited from FLAC__SeekableStreamDecoder; see
- *  FLAC__seekable_stream_decoder_set_write_callback().
- *
- * \note
- * The callback is mandatory and must be set before initialization.
- *
- * \default \c NULL
- * \param  decoder  A decoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code decoder != NULL \endcode
- *    \code value != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_decoder_set_write_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderWriteCallback value);
-
-/** Set the metadata callback.
- *  This is inherited from FLAC__SeekableStreamDecoder; see
- *  FLAC__seekable_stream_decoder_set_metadata_callback().
- *
- * \note
- * The callback is mandatory and must be set before initialization.
- *
- * \default \c NULL
- * \param  decoder  A decoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code decoder != NULL \endcode
- *    \code value != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderMetadataCallback value);
-
-/** Set the error callback.
- *  This is inherited from FLAC__SeekableStreamDecoder; see
- *  FLAC__seekable_stream_decoder_set_error_callback().
- *
- * \note
- * The callback is mandatory and must be set before initialization.
- *
- * \default \c NULL
- * \param  decoder  A decoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code decoder != NULL \endcode
- *    \code value != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_decoder_set_error_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderErrorCallback value);
-
-/** Set the client data to be passed back to callbacks.
- *  This value will be supplied to callbacks in their \a client_data
- *  argument.
- *
- * \default \c NULL
- * \param  decoder  A decoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_decoder_set_client_data(FLAC__FileDecoder *decoder, void *value);
-
-/** This is inherited from FLAC__SeekableStreamDecoder; see
- *  FLAC__seekable_stream_decoder_set_metadata_respond().
- *
- * \default By default, only the \c STREAMINFO block is returned via the
- *          metadata callback.
- * \param  decoder  A decoder instance to set.
- * \param  type     See above.
- * \assert
- *    \code decoder != NULL \endcode
- *    \a type is valid
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond(FLAC__FileDecoder *decoder, FLAC__MetadataType type);
-
-/** This is inherited from FLAC__SeekableStreamDecoder; see
- *  FLAC__seekable_stream_decoder_set_metadata_respond_application().
- *
- * \default By default, only the \c STREAMINFO block is returned via the
- *          metadata callback.
- * \param  decoder  A decoder instance to set.
- * \param  id       See above.
- * \assert
- *    \code decoder != NULL \endcode
- *    \code id != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond_application(FLAC__FileDecoder *decoder, const FLAC__byte id[4]);
-
-/** This is inherited from FLAC__SeekableStreamDecoder; see
- *  FLAC__seekable_stream_decoder_set_metadata_respond_all().
- *
- * \default By default, only the \c STREAMINFO block is returned via the
- *          metadata callback.
- * \param  decoder  A decoder instance to set.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond_all(FLAC__FileDecoder *decoder);
-
-/** This is inherited from FLAC__SeekableStreamDecoder; see
- *  FLAC__seekable_stream_decoder_set_metadata_ignore().
- *
- * \default By default, only the \c STREAMINFO block is returned via the
- *          metadata callback.
- * \param  decoder  A decoder instance to set.
- * \param  type     See above.
- * \assert
- *    \code decoder != NULL \endcode
- *    \a type is valid
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore(FLAC__FileDecoder *decoder, FLAC__MetadataType type);
-
-/** This is inherited from FLAC__SeekableStreamDecoder; see
- *  FLAC__seekable_stream_decoder_set_metadata_ignore_application().
- *
- * \default By default, only the \c STREAMINFO block is returned via the
- *          metadata callback.
- * \param  decoder  A decoder instance to set.
- * \param  id       See above.
- * \assert
- *    \code decoder != NULL \endcode
- *    \code id != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore_application(FLAC__FileDecoder *decoder, const FLAC__byte id[4]);
-
-/** This is inherited from FLAC__SeekableStreamDecoder; see
- *  FLAC__seekable_stream_decoder_set_metadata_ignore_all().
- *
- * \default By default, only the \c STREAMINFO block is returned via the
- *          metadata callback.
- * \param  decoder  A decoder instance to set.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore_all(FLAC__FileDecoder *decoder);
-
-/** Get the current decoder state.
- *
- * \param  decoder  A decoder instance to query.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__FileDecoderState
- *    The current decoder state.
- */
-FLAC_API FLAC__FileDecoderState FLAC__file_decoder_get_state(const FLAC__FileDecoder *decoder);
-
-/** Get the state of the underlying seekable stream decoder.
- *  Useful when the file decoder state is
- *  \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR.
- *
- * \param  decoder  A decoder instance to query.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__SeekableStreamDecoderState
- *    The seekable stream decoder state.
- */
-FLAC_API FLAC__SeekableStreamDecoderState FLAC__file_decoder_get_seekable_stream_decoder_state(const FLAC__FileDecoder *decoder);
-
-/** Get the state of the underlying stream decoder.
- *  Useful when the file decoder state is
- *  \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR and the seekable stream
- *  decoder state is \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
- *
- * \param  decoder  A decoder instance to query.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__StreamDecoderState
- *    The seekable stream decoder state.
- */
-FLAC_API FLAC__StreamDecoderState FLAC__file_decoder_get_stream_decoder_state(const FLAC__FileDecoder *decoder);
-
-/** Get the current decoder state as a C string.
- *  This version automatically resolves
- *  \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR by getting the
- *  seekable stream decoder's state.
- *
- * \param  decoder  A decoder instance to query.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval const char *
- *    The decoder state as a C string.  Do not modify the contents.
- */
-FLAC_API const char *FLAC__file_decoder_get_resolved_state_string(const FLAC__FileDecoder *decoder);
-
-/** Get the "MD5 signature checking" flag.
- *  This is inherited from FLAC__SeekableStreamDecoder; see
- *  FLAC__seekable_stream_decoder_get_md5_checking().
- *
- * \param  decoder  A decoder instance to query.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    See above.
- */
-FLAC_API FLAC__bool FLAC__file_decoder_get_md5_checking(const FLAC__FileDecoder *decoder);
-
-/** This is inherited from FLAC__SeekableStreamDecoder; see
- *  FLAC__seekable_stream_decoder_get_channels().
- *
- * \param  decoder  A decoder instance to query.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval unsigned
- *    See above.
- */
-FLAC_API unsigned FLAC__file_decoder_get_channels(const FLAC__FileDecoder *decoder);
-
-/** This is inherited from FLAC__SeekableStreamDecoder; see
- *  FLAC__seekable_stream_decoder_get_channel_assignment().
- *
- * \param  decoder  A decoder instance to query.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__ChannelAssignment
- *    See above.
- */
-FLAC_API FLAC__ChannelAssignment FLAC__file_decoder_get_channel_assignment(const FLAC__FileDecoder *decoder);
-
-/** This is inherited from FLAC__SeekableStreamDecoder; see
- *  FLAC__seekable_stream_decoder_get_bits_per_sample().
- *
- * \param  decoder  A decoder instance to query.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval unsigned
- *    See above.
- */
-FLAC_API unsigned FLAC__file_decoder_get_bits_per_sample(const FLAC__FileDecoder *decoder);
-
-/** This is inherited from FLAC__SeekableStreamDecoder; see
- *  FLAC__seekable_stream_decoder_get_sample_rate().
- *
- * \param  decoder  A decoder instance to query.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval unsigned
- *    See above.
- */
-FLAC_API unsigned FLAC__file_decoder_get_sample_rate(const FLAC__FileDecoder *decoder);
-
-/** This is inherited from FLAC__SeekableStreamDecoder; see
- *  FLAC__seekable_stream_decoder_get_blocksize().
- *
- * \param  decoder  A decoder instance to query.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval unsigned
- *    See above.
- */
-FLAC_API unsigned FLAC__file_decoder_get_blocksize(const FLAC__FileDecoder *decoder);
-
-/** This is inherited from FLAC__SeekableStreamDecoder; see
- *  FLAC__seekable_stream_decoder_get_decode_position().
- *
- * \param  decoder   A decoder instance to query.
- * \param  position  Address at which to return the desired position.
- * \assert
- *    \code decoder != NULL \endcode
- *    \code position != NULL \endcode
- * \retval FLAC__bool
- *    \c true if successful, \c false if there was an error from
- *    the 'tell' callback.
- */
-FLAC_API FLAC__bool FLAC__file_decoder_get_decode_position(const FLAC__FileDecoder *decoder, FLAC__uint64 *position);
-
-/** Initialize the decoder instance.
- *  Should be called after FLAC__file_decoder_new() and
- *  FLAC__file_decoder_set_*() but before any of the
- *  FLAC__file_decoder_process_*() functions.  Will set and return
- *  the decoder state, which will be FLAC__FILE_DECODER_OK if
- *  initialization succeeded.
- *
- * \param  decoder  An uninitialized decoder instance.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__FileDecoderState
- *    \c FLAC__FILE_DECODER_OK if initialization was successful; see
- *    FLAC__FileDecoderState for the meanings of other return values.
- */
-FLAC_API FLAC__FileDecoderState FLAC__file_decoder_init(FLAC__FileDecoder *decoder);
-
-/** Finish the decoding process.
- *  Flushes the decoding buffer, releases resources, resets the decoder
- *  settings to their defaults, and returns the decoder state to
- *  FLAC__FILE_DECODER_UNINITIALIZED.
- *
- *  In the event of a prematurely-terminated decode, it is not strictly
- *  necessary to call this immediately before FLAC__file_decoder_delete()
- *  but it is good practice to match every FLAC__file_decoder_init() with
- *  a FLAC__file_decoder_finish().
- *
- * \param  decoder  An uninitialized decoder instance.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if MD5 checking is on AND a STREAMINFO block was available
- *    AND the MD5 signature in the STREAMINFO block was non-zero AND the
- *    signature does not match the one computed by the decoder; else
- *    \c true.
- */
-FLAC_API FLAC__bool FLAC__file_decoder_finish(FLAC__FileDecoder *decoder);
-
-/** This is inherited from FLAC__SeekableStreamDecoder; see
- *  FLAC__seekable_stream_decoder_process_single().
- *
- * \param  decoder  A decoder instance.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    See above.
- */
-FLAC_API FLAC__bool FLAC__file_decoder_process_single(FLAC__FileDecoder *decoder);
-
-/** This is inherited from FLAC__SeekableStreamDecoder; see
- *  FLAC__seekable_stream_decoder_process_until_end_of_metadata().
- *
- * \param  decoder  A decoder instance.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    See above.
- */
-FLAC_API FLAC__bool FLAC__file_decoder_process_until_end_of_metadata(FLAC__FileDecoder *decoder);
-
-/** This is inherited from FLAC__SeekableStreamDecoder; see
- *  FLAC__seekable_stream_decoder_process_until_end_of_stream().
- *
- * \param  decoder  A decoder instance.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    See above.
- */
-FLAC_API FLAC__bool FLAC__file_decoder_process_until_end_of_file(FLAC__FileDecoder *decoder);
-
-/** This is inherited from FLAC__SeekableStreamDecoder; see
- *  FLAC__seekable_stream_decoder_skip_single_frame().
- *
- * \param  decoder  A decoder instance.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    See above.
- */
-FLAC_API FLAC__bool FLAC__file_decoder_skip_single_frame(FLAC__FileDecoder *decoder);
-
-/** Flush the input and seek to an absolute sample.
- *  This is inherited from FLAC__SeekableStreamDecoder; see
- *  FLAC__seekable_stream_decoder_seek_absolute().
- *
- * \param  decoder  A decoder instance.
- * \param  sample   The target sample number to seek to.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    \c true if successful, else \c false.
- */
-FLAC_API FLAC__bool FLAC__file_decoder_seek_absolute(FLAC__FileDecoder *decoder, FLAC__uint64 sample);
-
-/* \} */
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif
diff --git a/include/FLAC/file_encoder.h b/include/FLAC/file_encoder.h
deleted file mode 100644 (file)
index e0e206d..0000000
+++ /dev/null
@@ -1,886 +0,0 @@
-/* libFLAC - Free Lossless Audio Codec library
- * Copyright (C) 2002,2003,2004,2005,2006 Josh Coalson
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions
- * are met:
- *
- * - Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
- *
- * - Redistributions in binary form must reproduce the above copyright
- * notice, this list of conditions and the following disclaimer in the
- * documentation and/or other materials provided with the distribution.
- *
- * - Neither the name of the Xiph.org Foundation nor the names of its
- * contributors may be used to endorse or promote products derived from
- * this software without specific prior written permission.
- *
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
- * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
- * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
- * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
- * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
- * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
- * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
- * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- */
-
-#ifndef FLAC__FILE_ENCODER_H
-#define FLAC__FILE_ENCODER_H
-
-#include "export.h"
-#include "seekable_stream_encoder.h"
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-
-/** \file include/FLAC/file_encoder.h
- *
- *  \brief
- *  This module contains the functions which implement the file
- *  encoder.
- *
- *  See the detailed documentation in the
- *  \link flac_file_encoder file encoder \endlink module.
- */
-
-/** \defgroup flac_file_encoder FLAC/file_encoder.h: file encoder interface
- *  \ingroup flac_encoder
- *
- *  \brief
- *  This module contains the functions which implement the file
- *  encoder.
- *
- * The basic usage of this encoder is as follows:
- * - The program creates an instance of an encoder using
- *   FLAC__file_encoder_new().
- * - The program overrides the default settings using
- *   FLAC__file_encoder_set_*() functions.
- * - The program initializes the instance to validate the settings and
- *   prepare for encoding using FLAC__file_encoder_init().
- * - The program calls FLAC__file_encoder_process() or
- *   FLAC__file_encoder_process_interleaved() to encode data, which
- *   subsequently writes data to the output file.
- * - The program finishes the encoding with FLAC__file_encoder_finish(),
- *   which causes the encoder to encode any data still in its input pipe,
- *   rewind and write the STREAMINFO metadata to file, and finally reset
- *   the encoder to the uninitialized state.
- * - The instance may be used again or deleted with
- *   FLAC__file_encoder_delete().
- *
- * The file encoder is a wrapper around the
- * \link flac_seekable_stream_encoder seekable stream encoder \endlink which supplies all
- * callbacks internally; the user need specify only the filename.
- *
- * Make sure to read the detailed description of the
- * \link flac_seekable_stream_encoder seekable stream encoder module \endlink since the
- * \link flac_stream_encoder stream encoder module \endlink since the
- * file encoder inherits much of its behavior from them.
- *
- * \note
- * The "set" functions may only be called when the encoder is in the
- * state FLAC__FILE_ENCODER_UNINITIALIZED, i.e. after
- * FLAC__file_encoder_new() or FLAC__file_encoder_finish(), but
- * before FLAC__file_encoder_init().  If this is the case they will
- * return \c true, otherwise \c false.
- *
- * \note
- * FLAC__file_encoder_finish() resets all settings to the constructor
- * defaults.
- *
- * \{
- */
-
-
-/** State values for a FLAC__FileEncoder
- *
- *  The encoder's state can be obtained by calling FLAC__file_encoder_get_state().
- */
-typedef enum {
-
-       FLAC__FILE_ENCODER_OK = 0,
-       /**< The encoder is in the normal OK state. */
-
-       FLAC__FILE_ENCODER_NO_FILENAME,
-       /**< FLAC__file_encoder_init() was called without first calling
-        * FLAC__file_encoder_set_filename().
-        */
-
-       FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR,
-       /**< An error occurred in the underlying seekable stream encoder;
-        * check FLAC__file_encoder_get_seekable_stream_encoder_state().
-        */
-
-       FLAC__FILE_ENCODER_FATAL_ERROR_WHILE_WRITING,
-       /**< A fatal error occurred while writing to the encoded file. */
-
-       FLAC__FILE_ENCODER_ERROR_OPENING_FILE,
-       /**< An error occurred opening the output file for writing. */
-
-       FLAC__FILE_ENCODER_MEMORY_ALLOCATION_ERROR,
-       /**< Memory allocation failed. */
-
-       FLAC__FILE_ENCODER_ALREADY_INITIALIZED,
-       /**< FLAC__file_encoder_init() was called when the encoder was
-        * already initialized, usually because
-        * FLAC__file_encoder_finish() was not called.
-        */
-
-       FLAC__FILE_ENCODER_UNINITIALIZED
-       /**< The encoder is in the uninitialized state. */
-
-} FLAC__FileEncoderState;
-
-/** Maps a FLAC__FileEncoderState to a C string.
- *
- *  Using a FLAC__FileEncoderState as the index to this array
- *  will give the string equivalent.  The contents should not be modified.
- */
-extern FLAC_API const char * const FLAC__FileEncoderStateString[];
-
-
-/***********************************************************************
- *
- * class FLAC__FileEncoder
- *
- ***********************************************************************/
-
-struct FLAC__FileEncoderProtected;
-struct FLAC__FileEncoderPrivate;
-/** The opaque structure definition for the file encoder type.
- *  See the \link flac_file_encoder file encoder module \endlink
- *  for a detailed description.
- */
-typedef struct {
-       struct FLAC__FileEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
-       struct FLAC__FileEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
-} FLAC__FileEncoder;
-
-/** Signature for the progress callback.
- *  See FLAC__file_encoder_set_progress_callback() for more info.
- *
- * \param  encoder          The encoder instance calling the callback.
- * \param  bytes_written    Bytes written so far.
- * \param  samples_written  Samples written so far.
- * \param  frames_written   Frames written so far.
- * \param  total_frames_estimate  The estimate of the total number of
- *                                frames to be written.
- * \param  client_data      The callee's client data set through
- *                          FLAC__file_encoder_set_client_data().
- */
-typedef void (*FLAC__FileEncoderProgressCallback)(const FLAC__FileEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data);
-
-
-/***********************************************************************
- *
- * Class constructor/destructor
- *
- ***********************************************************************/
-
-/** Create a new file encoder instance.  The instance is created with
- *  default settings; see the individual FLAC__file_encoder_set_*()
- *  functions for each setting's default.
- *
- * \retval FLAC__FileEncoder*
- *    \c NULL if there was an error allocating memory, else the new instance.
- */
-FLAC_API FLAC__FileEncoder *FLAC__file_encoder_new();
-
-/** Free an encoder instance.  Deletes the object pointed to by \a encoder.
- *
- * \param encoder  A pointer to an existing encoder.
- * \assert
- *    \code encoder != NULL \endcode
- */
-FLAC_API void FLAC__file_encoder_delete(FLAC__FileEncoder *encoder);
-
-/***********************************************************************
- *
- * Public class method prototypes
- *
- ***********************************************************************/
-
-/** This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_set_verify().
- *
- * \default \c true
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_encoder_set_verify(FLAC__FileEncoder *encoder, FLAC__bool value);
-
-/** This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_set_streamable_subset().
- *
- * \default \c true
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_encoder_set_streamable_subset(FLAC__FileEncoder *encoder, FLAC__bool value);
-
-/** This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_set_do_mid_side_stereo().
- *
- * \default \c false
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_encoder_set_do_mid_side_stereo(FLAC__FileEncoder *encoder, FLAC__bool value);
-
-/** This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_set_loose_mid_side_stereo().
- *
- * \default \c false
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_encoder_set_loose_mid_side_stereo(FLAC__FileEncoder *encoder, FLAC__bool value);
-
-/** This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_set_channels().
- *
- * \default \c 2
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_encoder_set_channels(FLAC__FileEncoder *encoder, unsigned value);
-
-/** This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_set_bits_per_sample().
- *
- * \warning
- * Do not feed the encoder data that is wider than the value you
- * set here or you will generate an invalid stream.
- *
- * \default \c 16
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_encoder_set_bits_per_sample(FLAC__FileEncoder *encoder, unsigned value);
-
-/** This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_set_sample_rate().
- *
- * \default \c 44100
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_encoder_set_sample_rate(FLAC__FileEncoder *encoder, unsigned value);
-
-/** This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_set_blocksize().
- *
- * \default \c 1152
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_encoder_set_blocksize(FLAC__FileEncoder *encoder, unsigned value);
-
-/** This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_set_apodization().
- *
- * \default \c 0
- * \param  encoder        An encoder instance to set.
- * \param  specification  See above.
- * \assert
- *    \code encoder != NULL \endcode
- *    \code specification != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-/* @@@@add to unit tests*/
-FLAC_API FLAC__bool FLAC__file_encoder_set_apodization(FLAC__FileEncoder *encoder, const char *specification);
-
-/** This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_set_max_lpc_order().
- *
- * \default \c 0
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_encoder_set_max_lpc_order(FLAC__FileEncoder *encoder, unsigned value);
-
-/** This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_set_qlp_coeff_precision().
- *
- * \note
- * In the current implementation, qlp_coeff_precision + bits_per_sample must
- * be less than 32.
- *
- * \default \c 0
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_encoder_set_qlp_coeff_precision(FLAC__FileEncoder *encoder, unsigned value);
-
-/** This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search().
- *
- * \default \c false
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_encoder_set_do_qlp_coeff_prec_search(FLAC__FileEncoder *encoder, FLAC__bool value);
-
-/** This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_set_do_escape_coding().
- *
- * \default \c false
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_encoder_set_do_escape_coding(FLAC__FileEncoder *encoder, FLAC__bool value);
-
-/** This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_set_do_exhaustive_model_search().
- *
- * \default \c false
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_encoder_set_do_exhaustive_model_search(FLAC__FileEncoder *encoder, FLAC__bool value);
-
-/** This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_set_min_residual_partition_order().
- *
- * \default \c 0
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_encoder_set_min_residual_partition_order(FLAC__FileEncoder *encoder, unsigned value);
-
-/** This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_set_max_residual_partition_order().
- *
- * \default \c 0
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_encoder_set_max_residual_partition_order(FLAC__FileEncoder *encoder, unsigned value);
-
-/** This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_set_rice_parameter_search_dist().
- *
- * \default \c 0
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_encoder_set_rice_parameter_search_dist(FLAC__FileEncoder *encoder, unsigned value);
-
-/** This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_set_total_samples_estimate().
- *
- * \default \c 0
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_encoder_set_total_samples_estimate(FLAC__FileEncoder *encoder, FLAC__uint64 value);
-
-/** This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_set_metadata().
- *
- * \default \c NULL, 0
- * \param  encoder     An encoder instance to set.
- * \param  metadata    See above.
- * \param  num_blocks  See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_encoder_set_metadata(FLAC__FileEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
-
-/** Set the output file name encode to.
- *
- * \note
- * The filename is mandatory and must be set before initialization.
- *
- * \note
- * Unlike the FLAC__FileDecoder, the filename does not interpret "-" for
- * \c stdout; writing to \c stdout is not relevant in the file encoder.
- *
- * \default \c NULL
- * \param  encoder  A encoder instance to set.
- * \param  value    The output file name.
- * \assert
- *    \code encoder != NULL \endcode
- *    \code value != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, or there was a memory
- *    allocation error, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_encoder_set_filename(FLAC__FileEncoder *encoder, const char *value);
-
-/** Set the progress callback.
- *  The supplied function will be called when the encoder has finished
- *  writing a frame.  The \c total_frames_estimate argument to the callback
- *  will be based on the value from
- *  FLAC__file_encoder_set_total_samples_estimate().
- *
- * \note
- * Unlike most other callbacks, the progress callback is \b not mandatory
- * and need not be set before initialization.
- *
- * \default \c NULL
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- *    \code value != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_encoder_set_progress_callback(FLAC__FileEncoder *encoder, FLAC__FileEncoderProgressCallback value);
-
-/** Set the client data to be passed back to callbacks.
- *  This value will be supplied to callbacks in their \a client_data
- *  argument.
- *
- * \default \c NULL
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__file_encoder_set_client_data(FLAC__FileEncoder *encoder, void *value);
-
-/** Get the current encoder state.
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__FileEncoderState
- *    The current encoder state.
- */
-FLAC_API FLAC__FileEncoderState FLAC__file_encoder_get_state(const FLAC__FileEncoder *encoder);
-
-/** Get the state of the underlying seekable stream encoder.
- *  Useful when the file encoder state is
- *  \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR.
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__SeekableStreamEncoderState
- *    The seekable stream encoder state.
- */
-FLAC_API FLAC__SeekableStreamEncoderState FLAC__file_encoder_get_seekable_stream_encoder_state(const FLAC__FileEncoder *encoder);
-
-/** Get the state of the underlying stream encoder.
- *  Useful when the file encoder state is
- *  \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR and the seekable stream
- *  encoder state is \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR.
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__StreamEncoderState
- *    The seekable stream encoder state.
- */
-FLAC_API FLAC__StreamEncoderState FLAC__file_encoder_get_stream_encoder_state(const FLAC__FileEncoder *encoder);
-
-/** Get the state of the underlying stream encoder's verify decoder.
- *  Useful when the file encoder state is
- *  \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR and the seekable stream
- *  encoder state is \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and
- *  the stream encoder state is \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__StreamDecoderState
- *    The stream encoder state.
- */
-FLAC_API FLAC__StreamDecoderState FLAC__file_encoder_get_verify_decoder_state(const FLAC__FileEncoder *encoder);
-
-/** Get the current encoder state as a C string.
- *  This version automatically resolves
- *  \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR by getting the
- *  seekable stream encoder's state.
- *
- * \param  encoder  A encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval const char *
- *    The encoder state as a C string.  Do not modify the contents.
- */
-FLAC_API const char *FLAC__file_encoder_get_resolved_state_string(const FLAC__FileEncoder *encoder);
-
-/** Get relevant values about the nature of a verify decoder error.
- *  Inherited from FLAC__seekable_stream_encoder_get_verify_decoder_error_stats().
- *  Useful when the file encoder state is
- *  \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR and the seekable stream
- *  encoder state is
- *  \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and the
- *  stream encoder state is
- *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
- *
- * \param  encoder  An encoder instance to query.
- * \param  absolute_sample  The absolute sample number of the mismatch.
- * \param  frame_number  The number of the frame in which the mismatch occurred.
- * \param  channel       The channel in which the mismatch occurred.
- * \param  sample        The number of the sample (relative to the frame) in
- *                       which the mismatch occurred.
- * \param  expected      The expected value for the sample in question.
- * \param  got           The actual value returned by the decoder.
- * \assert
- *    \code encoder != NULL \endcode
- */
-FLAC_API void FLAC__file_encoder_get_verify_decoder_error_stats(const FLAC__FileEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
-
-/** Get the "verify" flag.
- *  This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_get_verify().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    See FLAC__file_encoder_set_verify().
- */
-FLAC_API FLAC__bool FLAC__file_encoder_get_verify(const FLAC__FileEncoder *encoder);
-
-/** Get the "streamable subset" flag.
- *  This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_get_streamable_subset().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    See FLAC__file_encoder_set_streamable_subset().
- */
-FLAC_API FLAC__bool FLAC__file_encoder_get_streamable_subset(const FLAC__FileEncoder *encoder);
-
-/** Get the "mid/side stereo coding" flag.
- *  This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_get_do_mid_side_stereo().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    See FLAC__file_encoder_get_do_mid_side_stereo().
- */
-FLAC_API FLAC__bool FLAC__file_encoder_get_do_mid_side_stereo(const FLAC__FileEncoder *encoder);
-
-/** Get the "adaptive mid/side switching" flag.
- *  This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_get_loose_mid_side_stereo().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    See FLAC__file_encoder_set_loose_mid_side_stereo().
- */
-FLAC_API FLAC__bool FLAC__file_encoder_get_loose_mid_side_stereo(const FLAC__FileEncoder *encoder);
-
-/** Get the number of input channels being processed.
- *  This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_get_channels().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval unsigned
- *    See FLAC__file_encoder_set_channels().
- */
-FLAC_API unsigned FLAC__file_encoder_get_channels(const FLAC__FileEncoder *encoder);
-
-/** Get the input sample resolution setting.
- *  This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_get_bits_per_sample().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval unsigned
- *    See FLAC__file_encoder_set_bits_per_sample().
- */
-FLAC_API unsigned FLAC__file_encoder_get_bits_per_sample(const FLAC__FileEncoder *encoder);
-
-/** Get the input sample rate setting.
- *  This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_get_sample_rate().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval unsigned
- *    See FLAC__file_encoder_set_sample_rate().
- */
-FLAC_API unsigned FLAC__file_encoder_get_sample_rate(const FLAC__FileEncoder *encoder);
-
-/** Get the blocksize setting.
- *  This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_get_blocksize().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval unsigned
- *    See FLAC__file_encoder_set_blocksize().
- */
-FLAC_API unsigned FLAC__file_encoder_get_blocksize(const FLAC__FileEncoder *encoder);
-
-/** Get the maximum LPC order setting.
- *  This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_get_max_lpc_order().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval unsigned
- *    See FLAC__file_encoder_set_max_lpc_order().
- */
-FLAC_API unsigned FLAC__file_encoder_get_max_lpc_order(const FLAC__FileEncoder *encoder);
-
-/** Get the quantized linear predictor coefficient precision setting.
- *  This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_get_qlp_coeff_precision().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval unsigned
- *    See FLAC__file_encoder_set_qlp_coeff_precision().
- */
-FLAC_API unsigned FLAC__file_encoder_get_qlp_coeff_precision(const FLAC__FileEncoder *encoder);
-
-/** Get the qlp coefficient precision search flag.
- *  This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    See FLAC__file_encoder_set_do_qlp_coeff_prec_search().
- */
-FLAC_API FLAC__bool FLAC__file_encoder_get_do_qlp_coeff_prec_search(const FLAC__FileEncoder *encoder);
-
-/** Get the "escape coding" flag.
- *  This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_get_do_escape_coding().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    See FLAC__file_encoder_set_do_escape_coding().
- */
-FLAC_API FLAC__bool FLAC__file_encoder_get_do_escape_coding(const FLAC__FileEncoder *encoder);
-
-/** Get the exhaustive model search flag.
- *  This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_get_do_exhaustive_model_search().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    See FLAC__file_encoder_set_do_exhaustive_model_search().
- */
-FLAC_API FLAC__bool FLAC__file_encoder_get_do_exhaustive_model_search(const FLAC__FileEncoder *encoder);
-
-/** Get the minimum residual partition order setting.
- *  This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_get_min_residual_partition_order().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval unsigned
- *    See FLAC__file_encoder_set_min_residual_partition_order().
- */
-FLAC_API unsigned FLAC__file_encoder_get_min_residual_partition_order(const FLAC__FileEncoder *encoder);
-
-/** Get maximum residual partition order setting.
- *  This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_get_max_residual_partition_order().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval unsigned
- *    See FLAC__file_encoder_set_max_residual_partition_order().
- */
-FLAC_API unsigned FLAC__file_encoder_get_max_residual_partition_order(const FLAC__FileEncoder *encoder);
-
-/** Get the Rice parameter search distance setting.
- *  This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_get_rice_parameter_search_dist().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval unsigned
- *    See FLAC__file_encoder_set_rice_parameter_search_dist().
- */
-FLAC_API unsigned FLAC__file_encoder_get_rice_parameter_search_dist(const FLAC__FileEncoder *encoder);
-
-/** Get the previously set estimate of the total samples to be encoded.
- *  This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_get_total_samples_estimate().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__uint64
- *    See FLAC__file_encoder_set_total_samples_estimate().
- */
-FLAC_API FLAC__uint64 FLAC__file_encoder_get_total_samples_estimate(const FLAC__FileEncoder *encoder);
-
-/** Initialize the encoder instance.
- *  Should be called after FLAC__file_encoder_new() and
- *  FLAC__file_encoder_set_*() but before FLAC__file_encoder_process()
- *  or FLAC__file_encoder_process_interleaved().  Will set and return
- *  the encoder state, which will be FLAC__FILE_ENCODER_OK if
- *  initialization succeeded.
- *
- * \param  encoder  An uninitialized encoder instance.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__FileEncoderState
- *    \c FLAC__FILE_ENCODER_OK if initialization was successful; see
- *    FLAC__FileEncoderState for the meanings of other return values.
- */
-FLAC_API FLAC__FileEncoderState FLAC__file_encoder_init(FLAC__FileEncoder *encoder);
-
-/** Finish the encoding process.
- *  Flushes the encoding buffer, releases resources, resets the encoder
- *  settings to their defaults, and returns the encoder state to
- *  FLAC__FILE_ENCODER_UNINITIALIZED.
- *
- *  In the event of a prematurely-terminated encode, it is not strictly
- *  necessary to call this immediately before FLAC__file_encoder_delete()
- *  but it is good practice to match every FLAC__file_encoder_init()
- *  with a FLAC__file_encoder_finish().
- *
- * \param  encoder  An uninitialized encoder instance.
- * \assert
- *    \code encoder != NULL \endcode
- */
-FLAC_API void FLAC__file_encoder_finish(FLAC__FileEncoder *encoder);
-
-/** Submit data for encoding.
- *  This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_process().
- *
- * \param  encoder  An initialized encoder instance in the OK state.
- * \param  buffer   An array of pointers to each channel's signal.
- * \param  samples  The number of samples in one channel.
- * \assert
- *    \code encoder != NULL \endcode
- *    \code FLAC__file_encoder_get_state(encoder) == FLAC__FILE_ENCODER_OK \endcode
- * \retval FLAC__bool
- *    \c true if successful, else \c false; in this case, check the
- *    encoder state with FLAC__file_encoder_get_state() to see what
- *    went wrong.
- */
-FLAC_API FLAC__bool FLAC__file_encoder_process(FLAC__FileEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
-
-/** Submit data for encoding.
- *  This is inherited from FLAC__SeekableStreamEncoder; see
- *  FLAC__seekable_stream_encoder_process_interleaved().
- *
- * \param  encoder  An initialized encoder instance in the OK state.
- * \param  buffer   An array of channel-interleaved data (see above).
- * \param  samples  The number of samples in one channel, the same as for
- *                  FLAC__file_encoder_process().  For example, if
- *                  encoding two channels, \c 1000 \a samples corresponds
- *                  to a \a buffer of 2000 values.
- * \assert
- *    \code encoder != NULL \endcode
- *    \code FLAC__file_encoder_get_state(encoder) == FLAC__FILE_ENCODER_OK \endcode
- * \retval FLAC__bool
- *    \c true if successful, else \c false; in this case, check the
- *    encoder state with FLAC__file_encoder_get_state() to see what
- *    went wrong.
- */
-FLAC_API FLAC__bool FLAC__file_encoder_process_interleaved(FLAC__FileEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
-
-/* \} */
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif
index 5979a00..e5799de 100644 (file)
@@ -1338,11 +1338,40 @@ FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_points(FLAC_
  * \assert
  *    \code object != NULL \endcode
  *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
+ *    \code total_samples > 0 \endcode
  * \retval FLAC__bool
  *    \c false if memory allocation fails, else \c true.
  */
 FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points(FLAC__StreamMetadata *object, unsigned num, FLAC__uint64 total_samples);
 
+/** Append a set of evenly-spaced seek point templates to the end of a
+ *  seek table.
+ *
+ * \note
+ * As with the other ..._seektable_template_... functions, you should
+ * call FLAC__metadata_object_seektable_template_sort() when finished
+ * to make the seek table legal.
+ *
+ * \param object  A pointer to an existing SEEKTABLE object.
+ * \param samples The number of samples apart to space the placeholder
+ *                points.  The first point will be at sample \c 0, the
+ *                second at sample \a samples, then 2*\a samples, and
+ *                so on.  As long as \a samples and \a total_samples
+ *                are greater than \c 0, there will always be at least
+ *                one seekpoint at sample \0.
+ * \param total_samples  The total number of samples to be encoded;
+ *                       the seekpoints will be spaced
+ *                       \a samples samples apart.
+ * \assert
+ *    \code object != NULL \endcode
+ *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
+ *    \code samples > 0 \endcode
+ *    \code total_samples > 0 \endcode
+ * \retval FLAC__bool
+ *    \c false if memory allocation fails, else \c true.
+ */
+FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points_by_samples(FLAC__StreamMetadata *object, unsigned samples, FLAC__uint64 total_samples);
+
 /** Sort a seek table's seek points according to the format specification,
  *  removing duplicates.
  *
diff --git a/include/FLAC/seekable_stream_decoder.h b/include/FLAC/seekable_stream_decoder.h
deleted file mode 100644 (file)
index 336f830..0000000
+++ /dev/null
@@ -1,931 +0,0 @@
-/* libFLAC - Free Lossless Audio Codec library
- * Copyright (C) 2000,2001,2002,2003,2004,2005,2006 Josh Coalson
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions
- * are met:
- *
- * - Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
- *
- * - Redistributions in binary form must reproduce the above copyright
- * notice, this list of conditions and the following disclaimer in the
- * documentation and/or other materials provided with the distribution.
- *
- * - Neither the name of the Xiph.org Foundation nor the names of its
- * contributors may be used to endorse or promote products derived from
- * this software without specific prior written permission.
- *
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
- * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
- * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
- * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
- * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
- * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
- * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
- * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- */
-
-#ifndef FLAC__SEEKABLE_STREAM_DECODER_H
-#define FLAC__SEEKABLE_STREAM_DECODER_H
-
-#include "export.h"
-#include "stream_decoder.h"
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-
-/** \file include/FLAC/seekable_stream_decoder.h
- *
- *  \brief
- *  This module contains the functions which implement the seekable stream
- *  decoder.
- *
- *  See the detailed documentation in the
- *  \link flac_seekable_stream_decoder seekable stream decoder \endlink module.
- */
-
-/** \defgroup flac_seekable_stream_decoder FLAC/seekable_stream_decoder.h: seekable stream decoder interface
- *  \ingroup flac_decoder
- *
- *  \brief
- *  This module contains the functions which implement the seekable stream
- *  decoder.
- *
- * The basic usage of this decoder is as follows:
- * - The program creates an instance of a decoder using
- *   FLAC__seekable_stream_decoder_new().
- * - The program overrides the default settings and sets callbacks for
- *   reading, writing, seeking, error reporting, and metadata reporting
- *   using FLAC__seekable_stream_decoder_set_*() functions.
- * - The program initializes the instance to validate the settings and
- *   prepare for decoding using FLAC__seekable_stream_decoder_init().
- * - The program calls the FLAC__seekable_stream_decoder_process_*()
- *   functions to decode data, which subsequently calls the callbacks.
- * - The program finishes the decoding with
- *   FLAC__seekable_stream_decoder_finish(), which flushes the input and
- *   output and resets the decoder to the uninitialized state.
- * - The instance may be used again or deleted with
- *   FLAC__seekable_stream_decoder_delete().
- *
- * The seekable stream decoder is a wrapper around the
- * \link flac_stream_decoder stream decoder \endlink which also provides
- * seeking capability.  In addition to the Read/Write/Metadata/Error
- * callbacks of the stream decoder, the user must also provide the following:
- *
- * - Seek callback - This function will be called when the decoder wants to
- *   seek to an absolute position in the stream.
- * - Tell callback - This function will be called when the decoder wants to
- *   know the current absolute position of the stream.
- * - Length callback - This function will be called when the decoder wants
- *   to know length of the stream.  The seeking algorithm currently requires
- *   that the overall stream length be known.
- * - EOF callback - This function will be called when the decoder wants to
- *   know if it is at the end of the stream.  This could be synthesized from
- *   the tell and length callbacks but it may be more expensive that way, so
- *   there is a separate callback for it.
- *
- * Seeking is exposed through the
- * FLAC__seekable_stream_decoder_seek_absolute() method.  At any point after
- * the seekable stream decoder has been initialized, the user can call this
- * function to seek to an exact sample within the stream.  Subsequently, the
- * first time the write callback is called it will be passed a (possibly
- * partial) block starting at that sample.
- *
- * The seekable stream decoder also provides MD5 signature checking.  If
- * this is turned on before initialization,
- * FLAC__seekable_stream_decoder_finish() will report when the decoded MD5
- * signature does not match the one stored in the STREAMINFO block.  MD5
- * checking is automatically turned off (until the next
- * FLAC__seekable_stream_decoder_reset()) if there is no signature in the
- * STREAMINFO block or when a seek is attempted.
- *
- * Make sure to read the detailed description of the
- * \link flac_stream_decoder stream decoder module \endlink since the
- * seekable stream decoder inherits much of its behavior.
- *
- * \note
- * The "set" functions may only be called when the decoder is in the
- * state FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED, i.e. after
- * FLAC__seekable_stream_decoder_new() or
- * FLAC__seekable_stream_decoder_finish(), but before
- * FLAC__seekable_stream_decoder_init().  If this is the case they will
- * return \c true, otherwise \c false.
- *
- * \note
- * FLAC__stream_decoder_finish() resets all settings to the constructor
- * defaults, including the callbacks.
- *
- * \{
- */
-
-
-/** State values for a FLAC__SeekableStreamDecoder
- *
- *  The decoder's state can be obtained by calling FLAC__seekable_stream_decoder_get_state().
- */
-typedef enum {
-
-       FLAC__SEEKABLE_STREAM_DECODER_OK = 0,
-       /**< The decoder is in the normal OK state. */
-
-       FLAC__SEEKABLE_STREAM_DECODER_SEEKING,
-       /**< The decoder is in the process of seeking. */
-
-       FLAC__SEEKABLE_STREAM_DECODER_END_OF_STREAM,
-       /**< The decoder has reached the end of the stream. */
-
-       FLAC__SEEKABLE_STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
-       /**< An error occurred allocating memory. */
-
-       FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR,
-       /**< An error occurred in the underlying stream decoder. */
-
-       FLAC__SEEKABLE_STREAM_DECODER_READ_ERROR,
-       /**< The read callback returned an error. */
-
-       FLAC__SEEKABLE_STREAM_DECODER_SEEK_ERROR,
-       /**< An error occurred while seeking or the seek or tell
-        * callback returned an error.
-        */
-
-       FLAC__SEEKABLE_STREAM_DECODER_ALREADY_INITIALIZED,
-       /**< FLAC__seekable_stream_decoder_init() was called when the
-        * decoder was already initialized, usually because
-        * FLAC__seekable_stream_decoder_finish() was not called.
-        */
-
-       FLAC__SEEKABLE_STREAM_DECODER_INVALID_CALLBACK,
-       /**< FLAC__seekable_stream_decoder_init() was called without all
-        * callbacks being set.
-        */
-
-       FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED
-       /**< The decoder is in the uninitialized state. */
-
-} FLAC__SeekableStreamDecoderState;
-
-/** Maps a FLAC__SeekableStreamDecoderState to a C string.
- *
- *  Using a FLAC__SeekableStreamDecoderState as the index to this array
- *  will give the string equivalent.  The contents should not be modified.
- */
-extern FLAC_API const char * const FLAC__SeekableStreamDecoderStateString[];
-
-
-/** Return values for the FLAC__SeekableStreamDecoder read callback.
- */
-typedef enum {
-
-       FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_OK,
-       /**< The read was OK and decoding can continue. */
-
-       FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_ERROR
-       /**< An unrecoverable error occurred.  The decoder will return from the process call. */
-
-} FLAC__SeekableStreamDecoderReadStatus;
-
-/** Maps a FLAC__SeekableStreamDecoderReadStatus to a C string.
- *
- *  Using a FLAC__SeekableStreamDecoderReadStatus as the index to this array
- *  will give the string equivalent.  The contents should not be modified.
- */
-extern FLAC_API const char * const FLAC__SeekableStreamDecoderReadStatusString[];
-
-
-/** Return values for the FLAC__SeekableStreamDecoder seek callback.
- */
-typedef enum {
-
-       FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_OK,
-       /**< The seek was OK and decoding can continue. */
-
-       FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_ERROR
-       /**< An unrecoverable error occurred.  The decoder will return from the process call. */
-
-} FLAC__SeekableStreamDecoderSeekStatus;
-
-/** Maps a FLAC__SeekableStreamDecoderSeekStatus to a C string.
- *
- *  Using a FLAC__SeekableStreamDecoderSeekStatus as the index to this array
- *  will give the string equivalent.  The contents should not be modified.
- */
-extern FLAC_API const char * const FLAC__SeekableStreamDecoderSeekStatusString[];
-
-
-/** Return values for the FLAC__SeekableStreamDecoder tell callback.
- */
-typedef enum {
-
-       FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_OK,
-       /**< The tell was OK and decoding can continue. */
-
-       FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_ERROR
-       /**< An unrecoverable error occurred.  The decoder will return from the process call. */
-
-} FLAC__SeekableStreamDecoderTellStatus;
-
-/** Maps a FLAC__SeekableStreamDecoderTellStatus to a C string.
- *
- *  Using a FLAC__SeekableStreamDecoderTellStatus as the index to this array
- *  will give the string equivalent.  The contents should not be modified.
- */
-extern FLAC_API const char * const FLAC__SeekableStreamDecoderTellStatusString[];
-
-
-/** Return values for the FLAC__SeekableStreamDecoder length callback.
- */
-typedef enum {
-
-       FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_OK,
-       /**< The length call was OK and decoding can continue. */
-
-       FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_ERROR
-       /**< An unrecoverable error occurred.  The decoder will return from the process call. */
-
-} FLAC__SeekableStreamDecoderLengthStatus;
-
-/** Maps a FLAC__SeekableStreamDecoderLengthStatus to a C string.
- *
- *  Using a FLAC__SeekableStreamDecoderLengthStatus as the index to this array
- *  will give the string equivalent.  The contents should not be modified.
- */
-extern FLAC_API const char * const FLAC__SeekableStreamDecoderLengthStatusString[];
-
-
-/***********************************************************************
- *
- * class FLAC__SeekableStreamDecoder : public FLAC__StreamDecoder
- *
- ***********************************************************************/
-
-struct FLAC__SeekableStreamDecoderProtected;
-struct FLAC__SeekableStreamDecoderPrivate;
-/** The opaque structure definition for the seekable stream decoder type.
- *  See the
- *  \link flac_seekable_stream_decoder seekable stream decoder module \endlink
- *  for a detailed description.
- */
-typedef struct {
-       struct FLAC__SeekableStreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
-       struct FLAC__SeekableStreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
-} FLAC__SeekableStreamDecoder;
-
-/** Signature for the read callback.
- *  See FLAC__seekable_stream_decoder_set_read_callback()
- *  and FLAC__StreamDecoderReadCallback for more info.
- *
- * \param  decoder  The decoder instance calling the callback.
- * \param  buffer   A pointer to a location for the callee to store
- *                  data to be decoded.
- * \param  bytes    A pointer to the size of the buffer.
- * \param  client_data  The callee's client data set through
- *                      FLAC__seekable_stream_decoder_set_client_data().
- * \retval FLAC__SeekableStreamDecoderReadStatus
- *    The callee's return status.
- */
-typedef FLAC__SeekableStreamDecoderReadStatus (*FLAC__SeekableStreamDecoderReadCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
-
-/** Signature for the seek callback.
- *  See FLAC__seekable_stream_decoder_set_seek_callback() for more info.
- *
- * \param  decoder  The decoder instance calling the callback.
- * \param  absolute_byte_offset  The offset from the beginning of the stream
- *                               to seek to.
- * \param  client_data  The callee's client data set through
- *                      FLAC__seekable_stream_decoder_set_client_data().
- * \retval FLAC__SeekableStreamDecoderSeekStatus
- *    The callee's return status.
- */
-typedef FLAC__SeekableStreamDecoderSeekStatus (*FLAC__SeekableStreamDecoderSeekCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
-
-/** Signature for the tell callback.
- *  See FLAC__seekable_stream_decoder_set_tell_callback() for more info.
- *
- * \param  decoder  The decoder instance calling the callback.
- * \param  absolute_byte_offset  A pointer to storage for the current offset
- *                               from the beginning of the stream.
- * \param  client_data  The callee's client data set through
- *                      FLAC__seekable_stream_decoder_set_client_data().
- * \retval FLAC__SeekableStreamDecoderTellStatus
- *    The callee's return status.
- */
-typedef FLAC__SeekableStreamDecoderTellStatus (*FLAC__SeekableStreamDecoderTellCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
-
-/** Signature for the length callback.
- *  See FLAC__seekable_stream_decoder_set_length_callback() for more info.
- *
- * \param  decoder  The decoder instance calling the callback.
- * \param  stream_length  A pointer to storage for the length of the stream
- *                        in bytes.
- * \param  client_data  The callee's client data set through
- *                      FLAC__seekable_stream_decoder_set_client_data().
- * \retval FLAC__SeekableStreamDecoderLengthStatus
- *    The callee's return status.
- */
-typedef FLAC__SeekableStreamDecoderLengthStatus (*FLAC__SeekableStreamDecoderLengthCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
-
-/** Signature for the EOF callback.
- *  See FLAC__seekable_stream_decoder_set_eof_callback() for more info.
- *
- * \param  decoder  The decoder instance calling the callback.
- * \param  client_data  The callee's client data set through
- *                      FLAC__seekable_stream_decoder_set_client_data().
- * \retval FLAC__bool
- *    \c true if the currently at the end of the stream, else \c false.
- */
-typedef FLAC__bool (*FLAC__SeekableStreamDecoderEofCallback)(const FLAC__SeekableStreamDecoder *decoder, void *client_data);
-
-/** Signature for the write callback.
- *  See FLAC__seekable_stream_decoder_set_write_callback()
- *  and FLAC__StreamDecoderWriteCallback for more info.
- *
- * \param  decoder  The decoder instance calling the callback.
- * \param  frame    The description of the decoded frame.
- * \param  buffer   An array of pointers to decoded channels of data.
- * \param  client_data  The callee's client data set through
- *                      FLAC__seekable_stream_decoder_set_client_data().
- * \retval FLAC__StreamDecoderWriteStatus
- *    The callee's return status.
- */
-typedef FLAC__StreamDecoderWriteStatus (*FLAC__SeekableStreamDecoderWriteCallback)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
-
-/** Signature for the metadata callback.
- *  See FLAC__seekable_stream_decoder_set_metadata_callback()
- *  and FLAC__StreamDecoderMetadataCallback for more info.
- *
- * \param  decoder  The decoder instance calling the callback.
- * \param  metadata The decoded metadata block.
- * \param  client_data  The callee's client data set through
- *                      FLAC__seekable_stream_decoder_set_client_data().
- */
-typedef void (*FLAC__SeekableStreamDecoderMetadataCallback)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
-
-/** Signature for the error callback.
- *  See FLAC__seekable_stream_decoder_set_error_callback()
- *  and FLAC__StreamDecoderErrorCallback for more info.
- *
- * \param  decoder  The decoder instance calling the callback.
- * \param  status   The error encountered by the decoder.
- * \param  client_data  The callee's client data set through
- *                      FLAC__seekable_stream_decoder_set_client_data().
- */
-typedef void (*FLAC__SeekableStreamDecoderErrorCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
-
-
-/***********************************************************************
- *
- * Class constructor/destructor
- *
- ***********************************************************************/
-
-/** Create a new seekable stream decoder instance.  The instance is created
- *  with default settings; see the individual
- *  FLAC__seekable_stream_decoder_set_*() functions for each setting's
- *  default.
- *
- * \retval FLAC__SeekableStreamDecoder*
- *    \c NULL if there was an error allocating memory, else the new instance.
- */
-FLAC_API FLAC__SeekableStreamDecoder *FLAC__seekable_stream_decoder_new();
-
-/** Free a decoder instance.  Deletes the object pointed to by \a decoder.
- *
- * \param decoder  A pointer to an existing decoder.
- * \assert
- *    \code decoder != NULL \endcode
- */
-FLAC_API void FLAC__seekable_stream_decoder_delete(FLAC__SeekableStreamDecoder *decoder);
-
-
-/***********************************************************************
- *
- * Public class method prototypes
- *
- ***********************************************************************/
-
-/** Set the "MD5 signature checking" flag.  If \c true, the decoder will
- *  compute the MD5 signature of the unencoded audio data while decoding
- *  and compare it to the signature from the STREAMINFO block, if it
- *  exists, during FLAC__seekable_stream_decoder_finish().
- *
- *  MD5 signature checking will be turned off (until the next
- *  FLAC__seekable_stream_decoder_reset()) if there is no signature in
- *  the STREAMINFO block or when a seek is attempted.
- *
- * \default \c false
- * \param  decoder  A decoder instance to set.
- * \param  value    Flag value (see above).
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_md5_checking(FLAC__SeekableStreamDecoder *decoder, FLAC__bool value);
-
-/** Set the read callback.
- *  This is inherited from FLAC__StreamDecoder; see
- *  FLAC__stream_decoder_set_read_callback().
- *
- * \note
- * The callback is mandatory and must be set before initialization.
- *
- * \default \c NULL
- * \param  decoder  A decoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code decoder != NULL \endcode
- *    \code value != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_read_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderReadCallback value);
-
-/** Set the seek callback.
- *  The supplied function will be called when the decoder needs to seek
- *  the input stream.  The decoder will pass the absolute byte offset
- *  to seek to, 0 meaning the beginning of the stream.
- *
- * \note
- * The callback is mandatory and must be set before initialization.
- *
- * \default \c NULL
- * \param  decoder  A decoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code decoder != NULL \endcode
- *    \code value != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_seek_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderSeekCallback value);
-
-/** Set the tell callback.
- *  The supplied function will be called when the decoder wants to know
- *  the current position of the stream.  The callback should return the
- *  byte offset from the beginning of the stream.
- *
- * \note
- * The callback is mandatory and must be set before initialization.
- *
- * \default \c NULL
- * \param  decoder  A decoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code decoder != NULL \endcode
- *    \code value != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_tell_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderTellCallback value);
-
-/** Set the length callback.
- *  The supplied function will be called when the decoder wants to know
- *  the total length of the stream in bytes.
- *
- * \note
- * The callback is mandatory and must be set before initialization.
- *
- * \default \c NULL
- * \param  decoder  A decoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code decoder != NULL \endcode
- *    \code value != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_length_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderLengthCallback value);
-
-/** Set the eof callback.
- *  The supplied function will be called when the decoder needs to know
- *  if the end of the stream has been reached.
- *
- * \note
- * The callback is mandatory and must be set before initialization.
- *
- * \default \c NULL
- * \param  decoder  A decoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code decoder != NULL \endcode
- *    \code value != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_eof_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderEofCallback value);
-
-/** Set the write callback.
- *  This is inherited from FLAC__StreamDecoder; see
- *  FLAC__stream_decoder_set_write_callback().
- *
- * \note
- * The callback is mandatory and must be set before initialization.
- *
- * \default \c NULL
- * \param  decoder  A decoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code decoder != NULL \endcode
- *    \code value != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_write_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderWriteCallback value);
-
-/** Set the metadata callback.
- *  This is inherited from FLAC__StreamDecoder; see
- *  FLAC__stream_decoder_set_metadata_callback().
- *
- * \note
- * The callback is mandatory and must be set before initialization.
- *
- * \default \c NULL
- * \param  decoder  A decoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code decoder != NULL \endcode
- *    \code value != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderMetadataCallback value);
-
-/** Set the error callback.
- *  This is inherited from FLAC__StreamDecoder; see
- *  FLAC__stream_decoder_set_error_callback().
- *
- * \note
- * The callback is mandatory and must be set before initialization.
- *
- * \default \c NULL
- * \param  decoder  A decoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code decoder != NULL \endcode
- *    \code value != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_error_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderErrorCallback value);
-
-/** Set the client data to be passed back to callbacks.
- *  This value will be supplied to callbacks in their \a client_data
- *  argument.
- *
- * \default \c NULL
- * \param  decoder  A decoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_client_data(FLAC__SeekableStreamDecoder *decoder, void *value);
-
-/** This is inherited from FLAC__StreamDecoder; see
- *  FLAC__stream_decoder_set_metadata_respond().
- *
- * \default By default, only the \c STREAMINFO block is returned via the
- *          metadata callback.
- * \param  decoder  A decoder instance to set.
- * \param  type     See above.
- * \assert
- *    \code decoder != NULL \endcode
- *    \a type is valid
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond(FLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type);
-
-/** This is inherited from FLAC__StreamDecoder; see
- *  FLAC__stream_decoder_set_metadata_respond_application().
- *
- * \default By default, only the \c STREAMINFO block is returned via the
- *          metadata callback.
- * \param  decoder  A decoder instance to set.
- * \param  id       See above.
- * \assert
- *    \code decoder != NULL \endcode
- *    \code id != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond_application(FLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
-
-/** This is inherited from FLAC__StreamDecoder; see
- *  FLAC__stream_decoder_set_metadata_respond_all().
- *
- * \default By default, only the \c STREAMINFO block is returned via the
- *          metadata callback.
- * \param  decoder  A decoder instance to set.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond_all(FLAC__SeekableStreamDecoder *decoder);
-
-/** This is inherited from FLAC__StreamDecoder; see
- *  FLAC__stream_decoder_set_metadata_ignore().
- *
- * \default By default, only the \c STREAMINFO block is returned via the
- *          metadata callback.
- * \param  decoder  A decoder instance to set.
- * \param  type     See above.
- * \assert
- *    \code decoder != NULL \endcode
- *    \a type is valid
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore(FLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type);
-
-/** This is inherited from FLAC__StreamDecoder; see
- *  FLAC__stream_decoder_set_metadata_ignore_application().
- *
- * \default By default, only the \c STREAMINFO block is returned via the
- *          metadata callback.
- * \param  decoder  A decoder instance to set.
- * \param  id       See above.
- * \assert
- *    \code decoder != NULL \endcode
- *    \code id != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore_application(FLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
-
-/** This is inherited from FLAC__StreamDecoder; see
- *  FLAC__stream_decoder_set_metadata_ignore_all().
- *
- * \default By default, only the \c STREAMINFO block is returned via the
- *          metadata callback.
- * \param  decoder  A decoder instance to set.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore_all(FLAC__SeekableStreamDecoder *decoder);
-
-/** Get the current decoder state.
- *
- * \param  decoder  A decoder instance to query.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__SeekableStreamDecoderState
- *    The current decoder state.
- */
-FLAC_API FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_get_state(const FLAC__SeekableStreamDecoder *decoder);
-
-/** Get the state of the underlying stream decoder.
- *  Useful when the seekable stream decoder state is
- *  \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
- *
- * \param  decoder  A decoder instance to query.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__StreamDecoderState
- *    The stream decoder state.
- */
-FLAC_API FLAC__StreamDecoderState FLAC__seekable_stream_decoder_get_stream_decoder_state(const FLAC__SeekableStreamDecoder *decoder);
-
-/** Get the current decoder state as a C string.
- *  This version automatically resolves
- *  \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR by getting the
- *  stream decoder's state.
- *
- * \param  decoder  A decoder instance to query.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval const char *
- *    The decoder state as a C string.  Do not modify the contents.
- */
-FLAC_API const char *FLAC__seekable_stream_decoder_get_resolved_state_string(const FLAC__SeekableStreamDecoder *decoder);
-
-/** Get the "MD5 signature checking" flag.
- *  This is the value of the setting, not whether or not the decoder is
- *  currently checking the MD5 (remember, it can be turned off automatically
- *  by a seek).  When the decoder is reset the flag will be restored to the
- *  value returned by this function.
- *
- * \param  decoder  A decoder instance to query.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    See above.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_get_md5_checking(const FLAC__SeekableStreamDecoder *decoder);
-
-/** This is inherited from FLAC__StreamDecoder; see
- *  FLAC__stream_decoder_get_channels().
- *
- * \param  decoder  A decoder instance to query.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval unsigned
- *    See above.
- */
-FLAC_API unsigned FLAC__seekable_stream_decoder_get_channels(const FLAC__SeekableStreamDecoder *decoder);
-
-/** This is inherited from FLAC__StreamDecoder; see
- *  FLAC__stream_decoder_get_channel_assignment().
- *
- * \param  decoder  A decoder instance to query.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__ChannelAssignment
- *    See above.
- */
-FLAC_API FLAC__ChannelAssignment FLAC__seekable_stream_decoder_get_channel_assignment(const FLAC__SeekableStreamDecoder *decoder);
-
-/** This is inherited from FLAC__StreamDecoder; see
- *  FLAC__stream_decoder_get_bits_per_sample().
- *
- * \param  decoder  A decoder instance to query.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval unsigned
- *    See above.
- */
-FLAC_API unsigned FLAC__seekable_stream_decoder_get_bits_per_sample(const FLAC__SeekableStreamDecoder *decoder);
-
-/** This is inherited from FLAC__StreamDecoder; see
- *  FLAC__stream_decoder_get_sample_rate().
- *
- * \param  decoder  A decoder instance to query.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval unsigned
- *    See above.
- */
-FLAC_API unsigned FLAC__seekable_stream_decoder_get_sample_rate(const FLAC__SeekableStreamDecoder *decoder);
-
-/** This is inherited from FLAC__StreamDecoder; see
- *  FLAC__stream_decoder_get_blocksize().
- *
- * \param  decoder  A decoder instance to query.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval unsigned
- *    See above.
- */
-FLAC_API unsigned FLAC__seekable_stream_decoder_get_blocksize(const FLAC__SeekableStreamDecoder *decoder);
-
-/** Returns the decoder's current read position within the stream.
- *  The position is the byte offset from the start of the stream.
- *  Bytes before this position have been fully decoded.  Note that
- *  there may still be undecoded bytes in the decoder's read FIFO.
- *  The returned position is correct even after a seek.
- *
- * \param  decoder   A decoder instance to query.
- * \param  position  Address at which to return the desired position.
- * \assert
- *    \code decoder != NULL \endcode
- *    \code position != NULL \endcode
- * \retval FLAC__bool
- *    \c true if successful, \c false if there was an error from
- *    the 'tell' callback.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_get_decode_position(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *position);
-
-/** Initialize the decoder instance.
- *  Should be called after FLAC__seekable_stream_decoder_new() and
- *  FLAC__seekable_stream_decoder_set_*() but before any of the
- *  FLAC__seekable_stream_decoder_process_*() functions.  Will set and return
- *  the decoder state, which will be FLAC__SEEKABLE_STREAM_DECODER_OK
- *  if initialization succeeded.
- *
- * \param  decoder  An uninitialized decoder instance.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__SeekableStreamDecoderState
- *    \c FLAC__SEEKABLE_STREAM_DECODER_OK if initialization was
- *    successful; see FLAC__SeekableStreamDecoderState for the meanings
- *    of other return values.
- */
-FLAC_API FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_init(FLAC__SeekableStreamDecoder *decoder);
-
-/** Finish the decoding process.
- *  Flushes the decoding buffer, releases resources, resets the decoder
- *  settings to their defaults, and returns the decoder state to
- *  FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED.
- *
- *  In the event of a prematurely-terminated decode, it is not strictly
- *  necessary to call this immediately before
- *  FLAC__seekable_stream_decoder_delete() but it is good practice to match
- *  every FLAC__seekable_stream_decoder_init() with a
- *  FLAC__seekable_stream_decoder_finish().
- *
- * \param  decoder  An uninitialized decoder instance.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if MD5 checking is on AND a STREAMINFO block was available
- *    AND the MD5 signature in the STREAMINFO block was non-zero AND the
- *    signature does not match the one computed by the decoder; else
- *    \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_finish(FLAC__SeekableStreamDecoder *decoder);
-
-/** Flush the stream input.
- *  The decoder's input buffer will be cleared and the state set to
- *  \c FLAC__SEEKABLE_STREAM_DECODER_OK.  This will also turn off MD5
- *  checking.
- *
- * \param  decoder  A decoder instance.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    \c true if successful, else \c false if a memory allocation
- *    or stream decoder error occurs.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_flush(FLAC__SeekableStreamDecoder *decoder);
-
-/** Reset the decoding process.
- *  The decoder's input buffer will be cleared and the state set to
- *  \c FLAC__SEEKABLE_STREAM_DECODER_OK.  This is similar to
- *  FLAC__seekable_stream_decoder_finish() except that the settings are
- *  preserved; there is no need to call FLAC__seekable_stream_decoder_init()
- *  before decoding again.  MD5 checking will be restored to its original
- *  setting.
- *
- * \param  decoder  A decoder instance.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    \c true if successful, else \c false if a memory allocation
- *    or stream decoder error occurs.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_reset(FLAC__SeekableStreamDecoder *decoder);
-
-/** This is inherited from FLAC__StreamDecoder; see
- *  FLAC__stream_decoder_process_single().
- *
- * \param  decoder  A decoder instance.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    See above.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_single(FLAC__SeekableStreamDecoder *decoder);
-
-/** This is inherited from FLAC__StreamDecoder; see
- *  FLAC__stream_decoder_process_until_end_of_metadata().
- *
- * \param  decoder  A decoder instance.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    See above.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_metadata(FLAC__SeekableStreamDecoder *decoder);
-
-/** This is inherited from FLAC__StreamDecoder; see
- *  FLAC__stream_decoder_process_until_end_of_stream().
- *
- * \param  decoder  A decoder instance.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    See above.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_stream(FLAC__SeekableStreamDecoder *decoder);
-
-/** This is inherited from FLAC__StreamDecoder; see
- *  FLAC__stream_decoder_skip_single_frame().
- *
- * \param  decoder  A decoder instance.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    See above.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_skip_single_frame(FLAC__SeekableStreamDecoder *decoder);
-
-/** Flush the input and seek to an absolute sample.
- *  Decoding will resume at the given sample.  Note that because of
- *  this, the next write callback may contain a partial block.
- *
- * \param  decoder  A decoder instance.
- * \param  sample   The target sample number to seek to.
- * \assert
- *    \code decoder != NULL \endcode
- * \retval FLAC__bool
- *    \c true if successful, else \c false.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_decoder_seek_absolute(FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 sample);
-
-/* \} */
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif
diff --git a/include/FLAC/seekable_stream_encoder.h b/include/FLAC/seekable_stream_encoder.h
deleted file mode 100644 (file)
index 08ede6e..0000000
+++ /dev/null
@@ -1,1007 +0,0 @@
-/* libFLAC - Free Lossless Audio Codec library
- * Copyright (C) 2002,2003,2004,2005,2006 Josh Coalson
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions
- * are met:
- *
- * - Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
- *
- * - Redistributions in binary form must reproduce the above copyright
- * notice, this list of conditions and the following disclaimer in the
- * documentation and/or other materials provided with the distribution.
- *
- * - Neither the name of the Xiph.org Foundation nor the names of its
- * contributors may be used to endorse or promote products derived from
- * this software without specific prior written permission.
- *
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
- * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
- * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
- * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
- * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
- * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
- * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
- * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- */
-
-#ifndef FLAC__SEEKABLE_STREAM_ENCODER_H
-#define FLAC__SEEKABLE_STREAM_ENCODER_H
-
-#include "export.h"
-#include "stream_encoder.h"
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-
-/** \file include/FLAC/seekable_stream_encoder.h
- *
- *  \brief
- *  This module contains the functions which implement the seekable stream
- *  encoder.
- *
- *  See the detailed documentation in the
- *  \link flac_seekable_stream_encoder seekable stream encoder \endlink module.
- */
-
-/** \defgroup flac_seekable_stream_encoder FLAC/seekable_stream_encoder.h: seekable stream encoder interface
- *  \ingroup flac_encoder
- *
- *  \brief
- *  This module contains the functions which implement the seekable stream
- *  encoder.
- *
- * The basic usage of this encoder is as follows:
- * - The program creates an instance of an encoder using
- *   FLAC__seekable_stream_encoder_new().
- * - The program overrides the default settings and sets callbacks using
- *   FLAC__seekable_stream_encoder_set_*() functions.
- * - The program initializes the instance to validate the settings and
- *   prepare for encoding using FLAC__seekable_stream_encoder_init().
- * - The program calls FLAC__seekable_stream_encoder_process() or
- *   FLAC__seekable_stream_encoder_process_interleaved() to encode data, which
- *   subsequently calls the callbacks when there is encoder data ready
- *   to be written.
- * - The program finishes the encoding with FLAC__seekable_stream_encoder_finish(),
- *   which causes the encoder to encode any data still in its input pipe,
- *   rewrite the metadata with the final encoding statistics, and finally
- *   reset the encoder to the uninitialized state.
- * - The instance may be used again or deleted with
- *   FLAC__seekable_stream_encoder_delete().
- *
- * The seekable stream encoder is a wrapper around the
- * \link flac_stream_encoder stream encoder \endlink with callbacks for
- * seeking the output and reporting the output stream position.  This
- * allows the encoder to go back and rewrite some of the metadata after
- * encoding if necessary, and provides the metadata callback of the stream
- * encoder internally.  However, you must provide seek and tell callbacks
- * (see FLAC__seekable_stream_encoder_set_seek_callback() and
- * FLAC__seekable_stream_encoder_set_tell_callback()).
- *
- * Make sure to read the detailed description of the
- * \link flac_stream_encoder stream encoder module \endlink since the
- * seekable stream encoder inherits much of its behavior.
- *
- * \note
- * If you are writing the FLAC data to a file, make sure it is open
- * for update (e.g. mode "w+" for stdio streams).  This is because after
- * the first encoding pass, the encoder will try to seek back to the
- * beginning of the stream, to the STREAMINFO block, to write some data
- * there.
- *
- * \note
- * The "set" functions may only be called when the encoder is in the
- * state FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED, i.e. after
- * FLAC__seekable_stream_encoder_new() or FLAC__seekable_stream_encoder_finish(), but
- * before FLAC__seekable_stream_encoder_init().  If this is the case they will
- * return \c true, otherwise \c false.
- *
- * \note
- * FLAC__seekable_stream_encoder_finish() resets all settings to the constructor
- * defaults, including the callbacks.
- *
- * \{
- */
-
-
-/** State values for a FLAC__SeekableStreamEncoder
- *
- *  The encoder's state can be obtained by calling FLAC__seekable_stream_encoder_get_state().
- */
-typedef enum {
-
-       FLAC__SEEKABLE_STREAM_ENCODER_OK = 0,
-       /**< The encoder is in the normal OK state. */
-
-       FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR,
-       /**< An error occurred in the underlying stream encoder;
-        * check FLAC__seekable_stream_encoder_get_stream_encoder_state().
-        */
-
-       FLAC__SEEKABLE_STREAM_ENCODER_MEMORY_ALLOCATION_ERROR,
-       /**< Memory allocation failed. */
-
-       FLAC__SEEKABLE_STREAM_ENCODER_WRITE_ERROR,
-       /**< The write callback returned an error. */
-
-       FLAC__SEEKABLE_STREAM_ENCODER_READ_ERROR,
-       /**< The read callback returned an error. */
-
-       FLAC__SEEKABLE_STREAM_ENCODER_SEEK_ERROR,
-       /**< The seek callback returned an error. */
-
-       FLAC__SEEKABLE_STREAM_ENCODER_TELL_ERROR,
-       /**< The tell callback returned an error. */
-
-       FLAC__SEEKABLE_STREAM_ENCODER_ALREADY_INITIALIZED,
-       /**< FLAC__seekable_stream_encoder_init() was called when the encoder was
-        * already initialized, usually because
-        * FLAC__seekable_stream_encoder_finish() was not called.
-        */
-
-       FLAC__SEEKABLE_STREAM_ENCODER_INVALID_CALLBACK,
-       /**< FLAC__seekable_stream_encoder_init() was called without all
-        * callbacks being set.
-        */
-
-       FLAC__SEEKABLE_STREAM_ENCODER_INVALID_SEEKTABLE,
-       /**< An invalid seek table was passed is the metadata to
-        * FLAC__seekable_stream_encoder_set_metadata().
-        */
-
-       FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED
-       /**< The encoder is in the uninitialized state. */
-
-} FLAC__SeekableStreamEncoderState;
-
-/** Maps a FLAC__SeekableStreamEncoderState to a C string.
- *
- *  Using a FLAC__SeekableStreamEncoderState as the index to this array
- *  will give the string equivalent.  The contents should not be modified.
- */
-extern FLAC_API const char * const FLAC__SeekableStreamEncoderStateString[];
-
-
-/** Return values for the FLAC__SeekableStreamEncoder seek callback.
- */
-typedef enum {
-
-       FLAC__SEEKABLE_STREAM_ENCODER_SEEK_STATUS_OK,
-       /**< The seek was OK and encoding can continue. */
-
-       FLAC__SEEKABLE_STREAM_ENCODER_SEEK_STATUS_ERROR
-       /**< An unrecoverable error occurred.  The encoder will return from the process call. */
-
-} FLAC__SeekableStreamEncoderSeekStatus;
-
-/** Maps a FLAC__SeekableStreamEncoderSeekStatus to a C string.
- *
- *  Using a FLAC__SeekableStreamEncoderSeekStatus as the index to this array
- *  will give the string equivalent.  The contents should not be modified.
- */
-extern FLAC_API const char * const FLAC__SeekableStreamEncoderSeekStatusString[];
-
-
-/** Return values for the FLAC__SeekableStreamEncoder tell callback.
- */
-typedef enum {
-
-       FLAC__SEEKABLE_STREAM_ENCODER_TELL_STATUS_OK,
-       /**< The tell was OK and encoding can continue. */
-
-       FLAC__SEEKABLE_STREAM_ENCODER_TELL_STATUS_ERROR
-       /**< An unrecoverable error occurred.  The encoder will return from the process call. */
-
-} FLAC__SeekableStreamEncoderTellStatus;
-
-/** Maps a FLAC__SeekableStreamEncoderTellStatus to a C string.
- *
- *  Using a FLAC__SeekableStreamEncoderTellStatus as the index to this array
- *  will give the string equivalent.  The contents should not be modified.
- */
-extern FLAC_API const char * const FLAC__SeekableStreamEncoderTellStatusString[];
-
-
-/***********************************************************************
- *
- * class FLAC__SeekableStreamEncoder
- *
- ***********************************************************************/
-
-struct FLAC__SeekableStreamEncoderProtected;
-struct FLAC__SeekableStreamEncoderPrivate;
-/** The opaque structure definition for the seekable stream encoder type.
- *  See the \link flac_seekable_stream_encoder seekable stream encoder module \endlink
- *  for a detailed description.
- */
-typedef struct {
-       struct FLAC__SeekableStreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
-       struct FLAC__SeekableStreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
-} FLAC__SeekableStreamEncoder;
-
-/** Signature for the seek callback.
- *  See FLAC__seekable_stream_encoder_set_seek_callback() for more info.
- *
- * \param  encoder  The encoder instance calling the callback.
- * \param  absolute_byte_offset  The offset from the beginning of the stream
- *                               to seek to.
- * \param  client_data  The callee's client data set through
- *                      FLAC__seekable_stream_encoder_set_client_data().
- * \retval FLAC__SeekableStreamEncoderSeekStatus
- *    The callee's return status.
- */
-typedef FLAC__SeekableStreamEncoderSeekStatus (*FLAC__SeekableStreamEncoderSeekCallback)(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
-
-/** Signature for the tell callback.
- *  See FLAC__seekable_stream_encoder_set_tell_callback() for more info.
- *
- * \warning
- * The callback must return the true current byte offset of the output to
- * which the encoder is writing.  If you are buffering the output, make
- * sure and take this into account.  If you are writing directly to a
- * FILE* from your write callback, ftell() is sufficient.  If you are
- * writing directly to a file descriptor from your write callback, you
- * can use lseek(fd, SEEK_CUR, 0).  The encoder may later seek back to
- * these points to rewrite metadata after encoding.
- *
- * \param  encoder  The encoder instance calling the callback.
- * \param  absolute_byte_offset  The address at which to store the current
- *                               position of the output.
- * \param  client_data  The callee's client data set through
- *                      FLAC__seekable_stream_encoder_set_client_data().
- * \retval FLAC__SeekableStreamEncoderTellStatus
- *    The callee's return status.
- */
-typedef FLAC__SeekableStreamEncoderTellStatus (*FLAC__SeekableStreamEncoderTellCallback)(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
-
-/** Signature for the write callback.
- *  See FLAC__seekable_stream_encoder_set_write_callback()
- *  and FLAC__StreamEncoderWriteCallback for more info.
- *
- * \param  encoder  The encoder instance calling the callback.
- * \param  buffer   An array of encoded data of length \a bytes.
- * \param  bytes    The byte length of \a buffer.
- * \param  samples  The number of samples encoded by \a buffer.
- *                  \c 0 has a special meaning; see
- *                  FLAC__stream_encoder_set_write_callback().
- * \param  current_frame  The number of current frame being encoded.
- * \param  client_data  The callee's client data set through
- *                      FLAC__seekable_stream_encoder_set_client_data().
- * \retval FLAC__StreamEncoderWriteStatus
- *    The callee's return status.
- */
-typedef FLAC__StreamEncoderWriteStatus (*FLAC__SeekableStreamEncoderWriteCallback)(const FLAC__SeekableStreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
-
-
-/***********************************************************************
- *
- * Class constructor/destructor
- *
- ***********************************************************************/
-
-/** Create a new seekable stream encoder instance.  The instance is created with
- *  default settings; see the individual FLAC__seekable_stream_encoder_set_*()
- *  functions for each setting's default.
- *
- * \retval FLAC__SeekableStreamEncoder*
- *    \c NULL if there was an error allocating memory, else the new instance.
- */
-FLAC_API FLAC__SeekableStreamEncoder *FLAC__seekable_stream_encoder_new();
-
-/** Free an encoder instance.  Deletes the object pointed to by \a encoder.
- *
- * \param encoder  A pointer to an existing encoder.
- * \assert
- *    \code encoder != NULL \endcode
- */
-FLAC_API void FLAC__seekable_stream_encoder_delete(FLAC__SeekableStreamEncoder *encoder);
-
-/***********************************************************************
- *
- * Public class method prototypes
- *
- ***********************************************************************/
-
-/** This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_set_verify().
- *
- * \default \c true
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_verify(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
-
-/** This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_set_streamable_subset().
- *
- * \default \c true
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_streamable_subset(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
-
-/** This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_set_do_mid_side_stereo().
- *
- * \default \c false
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_mid_side_stereo(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
-
-/** This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_set_loose_mid_side_stereo().
- *
- * \default \c false
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_loose_mid_side_stereo(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
-
-/** This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_set_channels().
- *
- * \default \c 2
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_channels(FLAC__SeekableStreamEncoder *encoder, unsigned value);
-
-/** This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_set_bits_per_sample().
- *
- * \warning
- * Do not feed the encoder data that is wider than the value you
- * set here or you will generate an invalid stream.
- *
- * \default \c 16
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_bits_per_sample(FLAC__SeekableStreamEncoder *encoder, unsigned value);
-
-/** This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_set_sample_rate().
- *
- * \default \c 44100
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_sample_rate(FLAC__SeekableStreamEncoder *encoder, unsigned value);
-
-/** This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_set_blocksize().
- *
- * \default \c 1152
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_blocksize(FLAC__SeekableStreamEncoder *encoder, unsigned value);
-
-/** This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_set_apodization().
- *
- * \default \c 0
- * \param  encoder        An encoder instance to set.
- * \param  specification  See above.
- * \assert
- *    \code encoder != NULL \endcode
- *    \code specification != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-/* @@@@add to unit tests*/
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_apodization(FLAC__SeekableStreamEncoder *encoder, const char *specification);
-
-/** This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_set_max_lpc_order().
- *
- * \default \c 0
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_max_lpc_order(FLAC__SeekableStreamEncoder *encoder, unsigned value);
-
-/** This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_set_qlp_coeff_precision().
- *
- * \note
- * In the current implementation, qlp_coeff_precision + bits_per_sample must
- * be less than 32.
- *
- * \default \c 0
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_qlp_coeff_precision(FLAC__SeekableStreamEncoder *encoder, unsigned value);
-
-/** This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_set_do_qlp_coeff_prec_search().
- *
- * \default \c false
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
-
-/** This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_set_do_escape_coding().
- *
- * \default \c false
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_escape_coding(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
-
-/** This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_set_do_exhaustive_model_search().
- *
- * \default \c false
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_exhaustive_model_search(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
-
-/** This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_set_min_residual_partition_order().
- *
- * \default \c 0
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_min_residual_partition_order(FLAC__SeekableStreamEncoder *encoder, unsigned value);
-
-/** This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_set_max_residual_partition_order().
- *
- * \default \c 0
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_max_residual_partition_order(FLAC__SeekableStreamEncoder *encoder, unsigned value);
-
-/** This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_set_rice_parameter_search_dist().
- *
- * \default \c 0
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_rice_parameter_search_dist(FLAC__SeekableStreamEncoder *encoder, unsigned value);
-
-/** This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_set_total_samples_estimate().
- *
- * \default \c 0
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_total_samples_estimate(FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 value);
-
-/** This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_set_metadata().
- *
- * \note
- * SEEKTABLE blocks are handled specially.  Since you will not know
- * the values for the seek point stream offsets, you should pass in
- * a SEEKTABLE 'template', that is, a SEEKTABLE object with the
- * required sample numbers (or placeholder points), with \c 0 for the
- * \a frame_samples and \a stream_offset fields for each point.  While
- * encoding, the encoder will fill them in for you and when encoding
- * is finished, it will seek back and write the real values into the
- * SEEKTABLE block in the stream.  There are helper routines for
- * manipulating seektable template blocks; see metadata.h:
- * FLAC__metadata_object_seektable_template_*().
- *
- * \note
- * The encoder instance \b will modify the first \c SEEKTABLE block
- * as it transforms the template to a valid seektable while encoding,
- * but it is still up to the caller to free all metadata blocks after
- * encoding.
- *
- * \default \c NULL, 0
- * \param  encoder     An encoder instance to set.
- * \param  metadata    See above.
- * \param  num_blocks  See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_metadata(FLAC__SeekableStreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
-
-/** Set the seek callback.
- *  The supplied function will be called when the encoder needs to seek
- *  the output stream.  The encoder will pass the absolute byte offset
- *  to seek to, 0 meaning the beginning of the stream.
- *
- * \note
- * The callback is mandatory and must be set before initialization.
- *
- * \default \c NULL
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- *    \code value != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_seek_callback(FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderSeekCallback value);
-
-/** Set the tell callback.
- *  The supplied function will be called when the encoder needs to know
- *  the current position of the output stream.
- *
- * \note
- * The callback is mandatory and must be set before initialization.
- *
- * \default \c NULL
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- *    \code value != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_tell_callback(FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderTellCallback value);
-
-/** Set the write callback.
- *  This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_set_write_callback().
- *
- * \note
- * The callback is mandatory and must be set before initialization.
- *
- * \default \c NULL
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- *    \code value != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_write_callback(FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderWriteCallback value);
-
-/** Set the client data to be passed back to callbacks.
- *  This value will be supplied to callbacks in their \a client_data
- *  argument.
- *
- * \default \c NULL
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_client_data(FLAC__SeekableStreamEncoder *encoder, void *value);
-
-/** Get the current encoder state.
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__SeekableStreamEncoderState
- *    The current encoder state.
- */
-FLAC_API FLAC__SeekableStreamEncoderState FLAC__seekable_stream_encoder_get_state(const FLAC__SeekableStreamEncoder *encoder);
-
-/** Get the state of the underlying stream encoder.
- *  Useful when the seekable stream encoder state is
- *  \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR.
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__StreamEncoderState
- *    The stream encoder state.
- */
-FLAC_API FLAC__StreamEncoderState FLAC__seekable_stream_encoder_get_stream_encoder_state(const FLAC__SeekableStreamEncoder *encoder);
-
-/** Get the state of the underlying stream encoder's verify decoder.
- *  Useful when the seekable stream encoder state is
- *  \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and the
- *  stream encoder state is \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__StreamDecoderState
- *    The stream encoder state.
- */
-FLAC_API FLAC__StreamDecoderState FLAC__seekable_stream_encoder_get_verify_decoder_state(const FLAC__SeekableStreamEncoder *encoder);
-
-/** Get the current encoder state as a C string.
- *  This version automatically resolves
- *  \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR by getting the
- *  stream encoder's state.
- *
- * \param  encoder  A encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval const char *
- *    The encoder state as a C string.  Do not modify the contents.
- */
-FLAC_API const char *FLAC__seekable_stream_encoder_get_resolved_state_string(const FLAC__SeekableStreamEncoder *encoder);
-
-/** Get relevant values about the nature of a verify decoder error.
- *  Inherited from FLAC__stream_encoder_get_verify_decoder_error_stats().
- *  Useful when the seekable stream encoder state is
- *  \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and the
- *  stream encoder state is
- *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
- *
- * \param  encoder  An encoder instance to query.
- * \param  absolute_sample  The absolute sample number of the mismatch.
- * \param  frame_number  The number of the frame in which the mismatch occurred.
- * \param  channel       The channel in which the mismatch occurred.
- * \param  sample        The number of the sample (relative to the frame) in
- *                       which the mismatch occurred.
- * \param  expected      The expected value for the sample in question.
- * \param  got           The actual value returned by the decoder.
- * \assert
- *    \code encoder != NULL \endcode
- */
-FLAC_API void FLAC__seekable_stream_encoder_get_verify_decoder_error_stats(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
-
-/** Get the "verify" flag.
- *  This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_get_verify().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    See FLAC__seekable_stream_encoder_set_verify().
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_verify(const FLAC__SeekableStreamEncoder *encoder);
-
-/** Get the "streamable subset" flag.
- *  This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_get_streamable_subset().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    See FLAC__seekable_stream_encoder_set_streamable_subset().
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_streamable_subset(const FLAC__SeekableStreamEncoder *encoder);
-
-/** Get the "mid/side stereo coding" flag.
- *  This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_get_do_mid_side_stereo().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    See FLAC__seekable_stream_encoder_get_do_mid_side_stereo().
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_mid_side_stereo(const FLAC__SeekableStreamEncoder *encoder);
-
-/** Get the "adaptive mid/side switching" flag.
- *  This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_get_loose_mid_side_stereo().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    See FLAC__seekable_stream_encoder_set_loose_mid_side_stereo().
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_loose_mid_side_stereo(const FLAC__SeekableStreamEncoder *encoder);
-
-/** Get the number of input channels being processed.
- *  This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_get_channels().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval unsigned
- *    See FLAC__seekable_stream_encoder_set_channels().
- */
-FLAC_API unsigned FLAC__seekable_stream_encoder_get_channels(const FLAC__SeekableStreamEncoder *encoder);
-
-/** Get the input sample resolution setting.
- *  This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_get_bits_per_sample().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval unsigned
- *    See FLAC__seekable_stream_encoder_set_bits_per_sample().
- */
-FLAC_API unsigned FLAC__seekable_stream_encoder_get_bits_per_sample(const FLAC__SeekableStreamEncoder *encoder);
-
-/** Get the input sample rate setting.
- *  This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_get_sample_rate().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval unsigned
- *    See FLAC__seekable_stream_encoder_set_sample_rate().
- */
-FLAC_API unsigned FLAC__seekable_stream_encoder_get_sample_rate(const FLAC__SeekableStreamEncoder *encoder);
-
-/** Get the blocksize setting.
- *  This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_get_blocksize().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval unsigned
- *    See FLAC__seekable_stream_encoder_set_blocksize().
- */
-FLAC_API unsigned FLAC__seekable_stream_encoder_get_blocksize(const FLAC__SeekableStreamEncoder *encoder);
-
-/** Get the maximum LPC order setting.
- *  This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_get_max_lpc_order().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval unsigned
- *    See FLAC__seekable_stream_encoder_set_max_lpc_order().
- */
-FLAC_API unsigned FLAC__seekable_stream_encoder_get_max_lpc_order(const FLAC__SeekableStreamEncoder *encoder);
-
-/** Get the quantized linear predictor coefficient precision setting.
- *  This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_get_qlp_coeff_precision().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval unsigned
- *    See FLAC__seekable_stream_encoder_set_qlp_coeff_precision().
- */
-FLAC_API unsigned FLAC__seekable_stream_encoder_get_qlp_coeff_precision(const FLAC__SeekableStreamEncoder *encoder);
-
-/** Get the qlp coefficient precision search flag.
- *  This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_get_do_qlp_coeff_prec_search().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    See FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search().
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search(const FLAC__SeekableStreamEncoder *encoder);
-
-/** Get the "escape coding" flag.
- *  This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_get_do_escape_coding().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    See FLAC__seekable_stream_encoder_set_do_escape_coding().
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_escape_coding(const FLAC__SeekableStreamEncoder *encoder);
-
-/** Get the exhaustive model search flag.
- *  This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_get_do_exhaustive_model_search().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    See FLAC__seekable_stream_encoder_set_do_exhaustive_model_search().
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_exhaustive_model_search(const FLAC__SeekableStreamEncoder *encoder);
-
-/** Get the minimum residual partition order setting.
- *  This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_get_min_residual_partition_order().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval unsigned
- *    See FLAC__seekable_stream_encoder_set_min_residual_partition_order().
- */
-FLAC_API unsigned FLAC__seekable_stream_encoder_get_min_residual_partition_order(const FLAC__SeekableStreamEncoder *encoder);
-
-/** Get maximum residual partition order setting.
- *  This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_get_max_residual_partition_order().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval unsigned
- *    See FLAC__seekable_stream_encoder_set_max_residual_partition_order().
- */
-FLAC_API unsigned FLAC__seekable_stream_encoder_get_max_residual_partition_order(const FLAC__SeekableStreamEncoder *encoder);
-
-/** Get the Rice parameter search distance setting.
- *  This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_get_rice_parameter_search_dist().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval unsigned
- *    See FLAC__seekable_stream_encoder_set_rice_parameter_search_dist().
- */
-FLAC_API unsigned FLAC__seekable_stream_encoder_get_rice_parameter_search_dist(const FLAC__SeekableStreamEncoder *encoder);
-
-/** Get the previously set estimate of the total samples to be encoded.
- *  This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_get_total_samples_estimate().
- *
- * \param  encoder  An encoder instance to query.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__uint64
- *    See FLAC__seekable_stream_encoder_set_total_samples_estimate().
- */
-FLAC_API FLAC__uint64 FLAC__seekable_stream_encoder_get_total_samples_estimate(const FLAC__SeekableStreamEncoder *encoder);
-
-/** Initialize the encoder instance.
- *  Should be called after FLAC__seekable_stream_encoder_new() and
- *  FLAC__seekable_stream_encoder_set_*() but before FLAC__seekable_stream_encoder_process()
- *  or FLAC__seekable_stream_encoder_process_interleaved().  Will set and return
- *  the encoder state, which will be FLAC__SEEKABLE_STREAM_ENCODER_OK if
- *  initialization succeeded.
- *
- *  The call to FLAC__seekable_stream_encoder_init() currently will also immediately
- *  call the write callback with the \c fLaC signature and all the encoded
- *  metadata.
- *
- * \param  encoder  An uninitialized encoder instance.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__SeekableStreamEncoderState
- *    \c FLAC__SEEKABLE_STREAM_ENCODER_OK if initialization was successful; see
- *    FLAC__SeekableStreamEncoderState for the meanings of other return values.
- */
-FLAC_API FLAC__SeekableStreamEncoderState FLAC__seekable_stream_encoder_init(FLAC__SeekableStreamEncoder *encoder);
-
-/** Finish the encoding process.
- *  Flushes the encoding buffer, releases resources, resets the encoder
- *  settings to their defaults, and returns the encoder state to
- *  FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED.
- *
- *  In the event of a prematurely-terminated encode, it is not strictly
- *  necessary to call this immediately before FLAC__seekable_stream_encoder_delete()
- *  but it is good practice to match every FLAC__seekable_stream_encoder_init()
- *  with a FLAC__seekable_stream_encoder_finish().
- *
- * \param  encoder  An uninitialized encoder instance.
- * \assert
- *    \code encoder != NULL \endcode
- */
-FLAC_API void FLAC__seekable_stream_encoder_finish(FLAC__SeekableStreamEncoder *encoder);
-
-/** Submit data for encoding.
- *  This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_process().
- *
- * \param  encoder  An initialized encoder instance in the OK state.
- * \param  buffer   An array of pointers to each channel's signal.
- * \param  samples  The number of samples in one channel.
- * \assert
- *    \code encoder != NULL \endcode
- *    \code FLAC__seekable_stream_encoder_get_state(encoder) == FLAC__SEEKABLE_STREAM_ENCODER_OK \endcode
- * \retval FLAC__bool
- *    \c true if successful, else \c false; in this case, check the
- *    encoder state with FLAC__seekable_stream_encoder_get_state() to see what
- *    went wrong.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_process(FLAC__SeekableStreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
-
-/** Submit data for encoding.
- *  This is inherited from FLAC__StreamEncoder; see
- *  FLAC__stream_encoder_process_interleaved().
- *
- * \param  encoder  An initialized encoder instance in the OK state.
- * \param  buffer   An array of channel-interleaved data (see above).
- * \param  samples  The number of samples in one channel, the same as for
- *                  FLAC__seekable_stream_encoder_process().  For example, if
- *                  encoding two channels, \c 1000 \a samples corresponds
- *                  to a \a buffer of 2000 values.
- * \assert
- *    \code encoder != NULL \endcode
- *    \code FLAC__seekable_stream_encoder_get_state(encoder) == FLAC__SEEKABLE_STREAM_ENCODER_OK \endcode
- * \retval FLAC__bool
- *    \c true if successful, else \c false; in this case, check the
- *    encoder state with FLAC__seekable_stream_encoder_get_state() to see what
- *    went wrong.
- */
-FLAC_API FLAC__bool FLAC__seekable_stream_encoder_process_interleaved(FLAC__SeekableStreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
-
-/* \} */
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif
index fb12acc..95947af 100644 (file)
@@ -32,6 +32,7 @@
 #ifndef FLAC__STREAM_DECODER_H
 #define FLAC__STREAM_DECODER_H
 
+#include <stdio.h> /* for FILE */
 #include "export.h"
 #include "format.h"
 
@@ -54,24 +55,22 @@ extern "C" {
  *  \ingroup flac
  *
  *  \brief
- *  This module describes the three decoder layers provided by libFLAC.
- *
- * For decoding FLAC streams, libFLAC provides three layers of access.  The
- * lowest layer is non-seekable stream-level decoding, the next is seekable
- * stream-level decoding, and the highest layer is file-level decoding.  The
- * interfaces are described in the \link flac_stream_decoder stream decoder
- * \endlink, \link flac_seekable_stream_decoder seekable stream decoder
- * \endlink, and \link flac_file_decoder file decoder \endlink modules
- * respectively.  Typically you will choose the highest layer that your input
- * source will support.
- *
- * The stream decoder relies on callbacks for all input and output and has no
- * provisions for seeking.  The seekable stream decoder wraps the stream
- * decoder and exposes functions for seeking.  However, you must provide
- * extra callbacks for seek-related operations on your stream, like seek and
- * tell.  The file decoder wraps the seekable stream decoder and supplies
- * most of the callbacks internally, simplifying the processing of standard
- * files.
+ *  This module describes the two decoder layers provided by libFLAC.
+ *
+ * libFLAC provides two ways of decoding FLAC streams.  There is a @@@@@@frame decoder which decodes single frames at a time, and a stream decoder which decodes whole streams.
+ *
+ * @@@@@@TODO frame decoder
+ *
+ * The stream decoder can be used decode complete streams either from the
+ * client via callbacks, or directly from a file, depending on how it is
+ * initialized.  When decoding via callbacks, the client provides
+ * callbacks for reading FLAC data and writing decoded samples, and
+ * handling metadata and errors.  If the client also supplies seek-related
+ * callback, the decoder function for sample-accurate seeking within the
+ * FLAC input is also available.  When decoding from a file, the client
+ * needs only supply a filename or open \c FILE* and write/metadata/error
+ * callbacks; the rest of the callbacks are supplied internally.  For more
+ * info see the \link flac_stream_decoder stream decoder \endlink module.
  */
 
 /** \defgroup flac_stream_decoder FLAC/stream_decoder.h: stream decoder interface
@@ -84,11 +83,12 @@ extern "C" {
  * The basic usage of this decoder is as follows:
  * - The program creates an instance of a decoder using
  *   FLAC__stream_decoder_new().
- * - The program overrides the default settings and sets callbacks for
- *   reading, writing, error reporting, and metadata reporting using
+ * - The program overrides the default settings using
  *   FLAC__stream_decoder_set_*() functions.
  * - The program initializes the instance to validate the settings and
- *   prepare for decoding using FLAC__stream_decoder_init().
+ *   prepare for decoding using FLAC__stream_decoder_init() or
+ *   FLAC__stream_decoder_init_FILE() or FLAC__stream_decoder_init_file(),
+ *   depending on the nature of the input.
  * - The program calls the FLAC__stream_decoder_process_*() functions
  *   to decode data, which subsequently calls the callbacks.
  * - The program finishes the decoding with FLAC__stream_decoder_finish(),
@@ -99,33 +99,21 @@ extern "C" {
  *
  * In more detail, the program will create a new instance by calling
  * FLAC__stream_decoder_new(), then call FLAC__stream_decoder_set_*()
- * functions to set the callbacks and client data, and call
- * FLAC__stream_decoder_init().  The required callbacks are:
- *
- * - Read callback - This function will be called when the decoder needs
- *   more input data.  The address of the buffer to be filled is supplied,
- *   along with the number of bytes the buffer can hold.  The callback may
- *   choose to supply less data and modify the byte count but must be careful
- *   not to overflow the buffer.  The callback then returns a status code
- *   chosen from FLAC__StreamDecoderReadStatus.
- * - Write callback - This function will be called when the decoder has
- *   decoded a single frame of data.  The decoder will pass the frame
- *   metadata as well as an array of pointers (one for each channel)
- *   pointing to the decoded audio.
- * - Metadata callback - This function will be called when the decoder has
- *   decoded a metadata block.  In a valid FLAC file there will always be
- *   one STREAMINFO block, followed by zero or more other metadata
- *   blocks.  These will be supplied by the decoder in the same order as
- *   they appear in the stream and always before the first audio frame
- *   (i.e. write callback).  The metadata block that is passed in must not
- *   be modified, and it doesn't live beyond the callback, so you should
- *   make a copy of it with FLAC__metadata_object_clone() if you will need
- *   it elsewhere.  Since metadata blocks can potentially be large, by
- *   default the decoder only calls the metadata callback for the STREAMINFO
- *   block; you can instruct the decoder to pass or filter other blocks with
- *   FLAC__stream_decoder_set_metadata_*() calls.
- * - Error callback - This function will be called whenever an error occurs
- *   during decoding.
+ * functions to override the default decoder options, and call
+ * on of the FLAC__stream_decoder_init_*() functions.
+ *
+ * There are three initialization functions, one for setting up the decoder
+ * to decode FLAC data from the client via callbacks, and two for decoding
+ * directly from a FLAC file.
+ *
+ * For decoding via callbacks, use FLAC__stream_decoder_init_stream().
+ * You must also supply several callbacks for handling I/O.  Some (like
+ * seeking) are optional, depending on the capabilities of the input.
+ *
+ * For decoding directly from a file, use FLAC__stream_decoder_init_FILE()
+ * or FLAC__stream_decoder_init_file().  Then you must only supply a
+ * filename or open \c FILE* and fewer callbacks; the decoder will handle
+ * the other callbacks internally.
  *
  * Once the decoder is initialized, your program will call one of several
  * functions to start the decoding process:
@@ -151,11 +139,23 @@ extern "C" {
  * instance may be deleted with FLAC__stream_decoder_delete() or initialized
  * again to decode another stream.
  *
- * Note that the stream decoder has no real concept of stream position, it
- * just converts data.  To seek within a stream the callbacks have only to
- * flush the decoder using FLAC__stream_decoder_flush() and start feeding
- * data from the new position through the read callback.  The seekable
- * stream decoder does just this.
+ * Seeking is exposed through the FLAC__stream_decoder_seek_absolute() method.
+ * At any point after the stream decoder has been initialized, the user can
+ * call this function to seek to an exact sample within the stream.
+ * Subsequently, the first time the write callback is called it will be
+ * passed a (possibly partial) block starting at that sample.
+ *
+ * If the client cannot seek via the callback interface provided, but still
+ * has another way of seeking, it can flush the decoder using
+ * FLAC__stream_decoder_flush() and start feeding data from the new position
+ * through the read callback.
+ *
+ * The stream decoder also provides MD5 signature checking.  If this is
+ * turned on before initialization, FLAC__stream_decoder_finish() will
+ * report when the decoded MD5 signature does not match the one stored
+ * in the STREAMINFO block.  MD5 checking is automatically turned off
+ * (until the next FLAC__stream_decoder_reset()) if there is no signature
+ * in the STREAMINFO block or when a seek is attempted.
  *
  * The FLAC__stream_decoder_set_metadata_*() functions deserve special
  * attention.  By default, the decoder only calls the metadata_callback for
@@ -191,7 +191,7 @@ extern "C" {
 
 /** State values for a FLAC__StreamDecoder
  *
- *  The decoder's state can be obtained by calling FLAC__stream_decoder_get_state().
+ * The decoder's state can be obtained by calling FLAC__stream_decoder_get_state().
  */
 typedef enum {
 
@@ -202,7 +202,9 @@ typedef enum {
        /**< The decoder is ready to or is in the process of reading metadata. */
 
        FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC,
-       /**< The decoder is ready to or is in the process of searching for the frame sync code. */
+       /**< The decoder is ready to or is in the process of searching for the
+        * frame sync code.
+        */
 
        FLAC__STREAM_DECODER_READ_FRAME,
        /**< The decoder is ready to or is in the process of reading a frame. */
@@ -210,23 +212,25 @@ typedef enum {
        FLAC__STREAM_DECODER_END_OF_STREAM,
        /**< The decoder has reached the end of the stream. */
 
+       FLAC__STREAM_DECODER_SEEK_ERROR,
+       /**< An error occurred while seeking.  The decoder must be flushed
+        * with FLAC__stream_decoder_flush() or reset with
+        * FLAC__stream_decoder_reset() before decoding can continue.
+        */
+
        FLAC__STREAM_DECODER_ABORTED,
        /**< The decoder was aborted by the read callback. */
 
        FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
-       /**< An error occurred allocating memory. */
-
-       FLAC__STREAM_DECODER_ALREADY_INITIALIZED,
-       /**< FLAC__stream_decoder_init() was called when the decoder was
-        * already initialized, usually because
-        * FLAC__stream_decoder_finish() was not called.
+       /**< An error occurred allocating memory.  The decoder is in an invalid
+        * state and can no longer be used.
         */
 
-       FLAC__STREAM_DECODER_INVALID_CALLBACK,
-       /**< FLAC__stream_decoder_init() was called without all callbacks being set. */
-
        FLAC__STREAM_DECODER_UNINITIALIZED
-       /**< The decoder is in the uninitialized state. */
+       /**< The decoder is in the uninitialized state; one of the
+        * FLAC__stream_decoder_init_*() functions must be called before samples
+        * can be processed.
+        */
 
 } FLAC__StreamDecoderState;
 
@@ -238,6 +242,38 @@ typedef enum {
 extern FLAC_API const char * const FLAC__StreamDecoderStateString[];
 
 
+/** Possible return values for the FLAC__stream_decoder_init_*() functions.
+ */
+typedef enum {
+
+       FLAC__STREAM_DECODER_INIT_STATUS_OK = 0,
+       /**< Initialization was successful. */
+
+       FLAC__STREAM_DECODER_INIT_STATUS_INVALID_CALLBACKS,
+       /**< A required callback was not supplied. */
+
+       FLAC__STREAM_DECODER_INIT_STATUS_MEMORY_ALLOCATION_ERROR,
+       /**< An error occurred allocating memory. */
+
+       FLAC__STREAM_DECODER_INIT_STATUS_ERROR_OPENING_FILE,
+       /**< fopen() failed in FLAC__stream_decoder_init_file(). */
+
+       FLAC__STREAM_DECODER_INIT_STATUS_ALREADY_INITIALIZED
+       /**< FLAC__stream_decoder_init_*() was called when the decoder was
+        * already initialized, usually because
+        * FLAC__stream_decoder_finish() was not called.
+        */
+
+} FLAC__StreamDecoderInitStatus;
+
+/** Maps a FLAC__StreamDecoderInitStatus to a C string.
+ *
+ *  Using a FLAC__StreamDecoderInitStatus as the index to this array
+ *  will give the string equivalent.  The contents should not be modified.
+ */
+extern FLAC_API const char * const FLAC__StreamDecoderInitStatusString[];
+
+
 /** Return values for the FLAC__StreamDecoder read callback.
  */
 typedef enum {
@@ -246,7 +282,15 @@ typedef enum {
        /**< The read was OK and decoding can continue. */
 
        FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM,
-       /**< The read was attempted at the end of the stream. */
+       /**< The read was attempted while at the end of the stream.  Note that
+        * the client must only return this value when the read callback was
+        * called when already at the end of the stream.  Otherwise, if the read
+        * itself moves to the end of the stream, the client should still return
+        * the data and \c FLAC__STREAM_DECODER_READ_STATUS_CONTINUE, and then on
+        * the next read callback it should return
+        * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM with a byte count
+        * of \c 0.
+        */
 
        FLAC__STREAM_DECODER_READ_STATUS_ABORT
        /**< An unrecoverable error occurred.  The decoder will return from the process call. */
@@ -261,6 +305,75 @@ typedef enum {
 extern FLAC_API const char * const FLAC__StreamDecoderReadStatusString[];
 
 
+/** Return values for the FLAC__StreamDecoder seek callback.
+ */
+typedef enum {
+
+       FLAC__STREAM_DECODER_SEEK_STATUS_OK,
+       /**< The seek was OK and decoding can continue. */
+
+       FLAC__STREAM_DECODER_SEEK_STATUS_ERROR,
+       /**< An unrecoverable error occurred.  The decoder will return from the process call. */
+
+       FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
+       /**< Client does not support seeking. */
+
+} FLAC__StreamDecoderSeekStatus;
+
+/** Maps a FLAC__StreamDecoderSeekStatus to a C string.
+ *
+ *  Using a FLAC__StreamDecoderSeekStatus as the index to this array
+ *  will give the string equivalent.  The contents should not be modified.
+ */
+extern FLAC_API const char * const FLAC__StreamDecoderSeekStatusString[];
+
+
+/** Return values for the FLAC__StreamDecoder tell callback.
+ */
+typedef enum {
+
+       FLAC__STREAM_DECODER_TELL_STATUS_OK,
+       /**< The tell was OK and decoding can continue. */
+
+       FLAC__STREAM_DECODER_TELL_STATUS_ERROR,
+       /**< An unrecoverable error occurred.  The decoder will return from the process call. */
+
+       FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
+       /**< Client does not support telling the position. */
+
+} FLAC__StreamDecoderTellStatus;
+
+/** Maps a FLAC__StreamDecoderTellStatus to a C string.
+ *
+ *  Using a FLAC__StreamDecoderTellStatus as the index to this array
+ *  will give the string equivalent.  The contents should not be modified.
+ */
+extern FLAC_API const char * const FLAC__StreamDecoderTellStatusString[];
+
+
+/** Return values for the FLAC__StreamDecoder length callback.
+ */
+typedef enum {
+
+       FLAC__STREAM_DECODER_LENGTH_STATUS_OK,
+       /**< The length call was OK and decoding can continue. */
+
+       FLAC__STREAM_DECODER_LENGTH_STATUS_ERROR,
+       /**< An unrecoverable error occurred.  The decoder will return from the process call. */
+
+       FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
+       /**< Client does not support reporting the length. */
+
+} FLAC__StreamDecoderLengthStatus;
+
+/** Maps a FLAC__StreamDecoderLengthStatus to a C string.
+ *
+ *  Using a FLAC__StreamDecoderLengthStatus as the index to this array
+ *  will give the string equivalent.  The contents should not be modified.
+ */
+extern FLAC_API const char * const FLAC__StreamDecoderLengthStatusString[];
+
+
 /** Return values for the FLAC__StreamDecoder write callback.
  */
 typedef enum {
@@ -338,7 +451,18 @@ typedef struct {
 } FLAC__StreamDecoder;
 
 /** Signature for the read callback.
- *  See FLAC__stream_decoder_set_read_callback() for more info.
+ *
+ *  A function pointer matching this signature must be passed to
+ *  FLAC__stream_decoder_init_stream(). The supplied function will be
+ *  called when the decoder needs more input data.  The address of the
+ *  buffer to be filled is supplied, along with the number of bytes the
+ *  buffer can hold.  The callback may choose to supply less data and
+ *  modify the byte count but must be careful not to overflow the buffer.
+ *  The callback then returns a status code chosen from
+ *  FLAC__StreamDecoderReadStatus.
+ *
+ * \note In general, FLAC__StreamDecoder functions which change the
+ * state should not be called on the \a decoder while in the callback.
  *
  * \param  decoder  The decoder instance calling the callback.
  * \param  buffer   A pointer to a location for the callee to store
@@ -350,14 +474,103 @@ typedef struct {
  *                  stored (0 in case of error or end-of-stream) before
  *                  returning.
  * \param  client_data  The callee's client data set through
- *                      FLAC__stream_decoder_set_client_data().
+ *                      FLAC__stream_decoder_init_*().
  * \retval FLAC__StreamDecoderReadStatus
  *    The callee's return status.
  */
 typedef FLAC__StreamDecoderReadStatus (*FLAC__StreamDecoderReadCallback)(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
 
+/** Signature for the seek callback.
+ *
+ *  A function pointer matching this signature may be passed to
+ *  FLAC__stream_decoder_init_stream().  The supplied function will be
+ *  called when the decoder needs to seek the input stream.  The decoder
+ *  will pass the absolute byte offset to seek to, 0 meaning the
+ *  beginning of the stream.
+ *
+ * \note In general, FLAC__StreamDecoder functions which change the
+ * state should not be called on the \a decoder while in the callback.
+ *
+ * \param  decoder  The decoder instance calling the callback.
+ * \param  absolute_byte_offset  The offset from the beginning of the stream
+ *                               to seek to.
+ * \param  client_data  The callee's client data set through
+ *                      FLAC__stream_decoder_init_*().
+ * \retval FLAC__StreamDecoderSeekStatus
+ *    The callee's return status.
+ */
+typedef FLAC__StreamDecoderSeekStatus (*FLAC__StreamDecoderSeekCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
+
+/** Signature for the tell callback.
+ *
+ *  A function pointer matching this signature may be passed to
+ *  FLAC__stream_decoder_init_stream().  The supplied function will be
+ *  called when the decoder wants to know the current position of the
+ *  stream.  The callback should return the byte offset from the
+ *  beginning of the stream.
+ *
+ * \note In general, FLAC__StreamDecoder functions which change the
+ * state should not be called on the \a decoder while in the callback.
+ *
+ * \param  decoder  The decoder instance calling the callback.
+ * \param  absolute_byte_offset  A pointer to storage for the current offset
+ *                               from the beginning of the stream.
+ * \param  client_data  The callee's client data set through
+ *                      FLAC__stream_decoder_init_*().
+ * \retval FLAC__StreamDecoderTellStatus
+ *    The callee's return status.
+ */
+typedef FLAC__StreamDecoderTellStatus (*FLAC__StreamDecoderTellCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
+
+/** Signature for the length callback.
+ *
+ *  A function pointer matching this signature may be passed to
+ *  FLAC__stream_decoder_init_stream().  The supplied function will be
+ *  called when the decoder wants to know the total length of the stream
+ *  in bytes.
+ *
+ * \note In general, FLAC__StreamDecoder functions which change the
+ * state should not be called on the \a decoder while in the callback.
+ *
+ * \param  decoder  The decoder instance calling the callback.
+ * \param  stream_length  A pointer to storage for the length of the stream
+ *                        in bytes.
+ * \param  client_data  The callee's client data set through
+ *                      FLAC__stream_decoder_init_*().
+ * \retval FLAC__StreamDecoderLengthStatus
+ *    The callee's return status.
+ */
+typedef FLAC__StreamDecoderLengthStatus (*FLAC__StreamDecoderLengthCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
+
+/** Signature for the EOF callback.
+ *
+ *  A function pointer matching this signature may be passed to
+ *  FLAC__stream_decoder_init_stream().  The supplied function will be
+ *  called when the decoder needs to know if the end of the stream has
+ *  been reached.
+ *
+ * \note In general, FLAC__StreamDecoder functions which change the
+ * state should not be called on the \a decoder while in the callback.
+ *
+ * \param  decoder  The decoder instance calling the callback.
+ * \param  client_data  The callee's client data set through
+ *                      FLAC__stream_decoder_init_*().
+ * \retval FLAC__bool
+ *    \c true if the currently at the end of the stream, else \c false.
+ */
+typedef FLAC__bool (*FLAC__StreamDecoderEofCallback)(const FLAC__StreamDecoder *decoder, void *client_data);
+
 /** Signature for the write callback.
- *  See FLAC__stream_decoder_set_write_callback() for more info.
+ *
+ *  A function pointer matching this signature must be passed to one of
+ *  the FLAC__stream_decoder_init_*() functions.
+ *  The supplied function will be called when the decoder has decoded a
+ *  single audio frame.  The decoder will pass the frame metadata as well
+ *  as an array of pointers (one for each channel) pointing to the
+ *  decoded audio.
+ *
+ * \note In general, FLAC__StreamDecoder functions which change the
+ * state should not be called on the \a decoder while in the callback.
  *
  * \param  decoder  The decoder instance calling the callback.
  * \param  frame    The description of the decoded frame.  See
@@ -369,29 +582,53 @@ typedef FLAC__StreamDecoderReadStatus (*FLAC__StreamDecoderReadCallback)(const F
  *                  except for stereo streams; in this case channel
  *                  0 is left and 1 is right.
  * \param  client_data  The callee's client data set through
- *                      FLAC__stream_decoder_set_client_data().
+ *                      FLAC__stream_decoder_init_*().
  * \retval FLAC__StreamDecoderWriteStatus
  *    The callee's return status.
  */
 typedef FLAC__StreamDecoderWriteStatus (*FLAC__StreamDecoderWriteCallback)(const FLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
 
 /** Signature for the metadata callback.
- *  See FLAC__stream_decoder_set_metadata_callback() for more info.
+ *
+ *  A function pointer matching this signature must be passed to one of
+ *  the FLAC__stream_decoder_init_*() functions.
+ *  The supplied function will be called when the decoder has decoded a
+ *  metadata block.  In a valid FLAC file there will always be one
+ *  \c STREAMINFO block, followed by zero or more other metadata blocks.
+ *  These will be supplied by the decoder in the same order as they
+ *  appear in the stream and always before the first audio frame (i.e.
+ *  write callback).  The metadata block that is passed in must not be
+ *  modified, and it doesn't live beyond the callback, so you should make
+ *  a copy of it with FLAC__metadata_object_clone() if you will need it
+ *  elsewhere.  Since metadata blocks can potentially be large, by
+ *  default the decoder only calls the metadata callback for the
+ *  \c STREAMINFO block; you can instruct the decoder to pass or filter
+ *  other blocks with FLAC__stream_decoder_set_metadata_*() calls.
+ *
+ * \note In general, FLAC__StreamDecoder functions which change the
+ * state should not be called on the \a decoder while in the callback.
  *
  * \param  decoder  The decoder instance calling the callback.
  * \param  metadata The decoded metadata block.
  * \param  client_data  The callee's client data set through
- *                      FLAC__stream_decoder_set_client_data().
+ *                      FLAC__stream_decoder_init_*().
  */
 typedef void (*FLAC__StreamDecoderMetadataCallback)(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
 
 /** Signature for the error callback.
- *  See FLAC__stream_decoder_set_error_callback() for more info.
+ *
+ *  A function pointer matching this signature must be passed to one of
+ *  the FLAC__stream_decoder_init_*() functions.
+ *  The supplied function will be called whenever an error occurs during
+ *  decoding.
+ *
+ * \note In general, FLAC__StreamDecoder functions which change the
+ * state should not be called on the \a decoder while in the callback.
  *
  * \param  decoder  The decoder instance calling the callback.
  * \param  status   The error encountered by the decoder.
  * \param  client_data  The callee's client data set through
- *                      FLAC__stream_decoder_set_client_data().
+ *                      FLAC__stream_decoder_init_*().
  */
 typedef void (*FLAC__StreamDecoderErrorCallback)(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
 
@@ -426,107 +663,27 @@ FLAC_API void FLAC__stream_decoder_delete(FLAC__StreamDecoder *decoder);
  *
  ***********************************************************************/
 
-/** Set the read callback.
- *  The supplied function will be called when the decoder needs more input
- *  data.  The address of the buffer to be filled is supplied, along with
- *  the number of bytes the buffer can hold.  The callback may choose to
- *  supply less data and modify the byte count but must be careful not to
- *  overflow the buffer.  The callback then returns a status code chosen
- *  from FLAC__StreamDecoderReadStatus.
- *
- * \note
- * The callback is mandatory and must be set before initialization.
- *
- * \default \c NULL
- * \param  decoder  A decoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code decoder != NULL \endcode
- *    \code value != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__stream_decoder_set_read_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderReadCallback value);
-
-/** Set the write callback.
- *  The supplied function will be called when the decoder has decoded a
- *  single frame of data.  The decoder will pass the frame metadata as
- *  well as an array of pointers (one for each channel) pointing to the
- *  decoded audio.
- *
- * \note
- * The callback is mandatory and must be set before initialization.
- *
- * \default \c NULL
- * \param  decoder  A decoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code decoder != NULL \endcode
- *    \code value != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__stream_decoder_set_write_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderWriteCallback value);
-
-/** Set the metadata callback.
- *  The supplied function will be called when the decoder has decoded a metadata
- *  block.  In a valid FLAC file there will always be one STREAMINFO block,
- *  followed by zero or more other metadata blocks.  These will be supplied
- *  by the decoder in the same order as they appear in the stream and always
- *  before the first audio frame (i.e. write callback).  The metadata block
- *  that is passed in must not be modified, and it doesn't live beyond the
- *  callback, so you should make a copy of it with
- *  FLAC__metadata_object_clone() if you will need it elsewhere.  Since
- *  metadata blocks can potentially be large, by default the decoder only
- *  calls the metadata callback for the STREAMINFO block; you can instruct
- *  the decoder to pass or filter other blocks with
- *  FLAC__stream_decoder_set_metadata_*() calls.
- *
- * \note
- * The callback is mandatory and must be set before initialization.
- *
- * \default \c NULL
- * \param  decoder  A decoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code decoder != NULL \endcode
- *    \code value != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderMetadataCallback value);
-
-/** Set the error callback.
- *  The supplied function will be called whenever an error occurs during
- *  decoding.
+/** Set the "MD5 signature checking" flag.  If \c true, the decoder will
+ *  compute the MD5 signature of the unencoded audio data while decoding
+ *  and compare it to the signature from the STREAMINFO block, if it
+ *  exists, during FLAC__stream_decoder_finish().
  *
- * \note
- * The callback is mandatory and must be set before initialization.
+ *  MD5 signature checking will be turned off (until the next
+ *  FLAC__stream_decoder_reset()) if there is no signature in the
+ *  STREAMINFO block or when a seek is attempted.
  *
- * \default \c NULL
- * \param  decoder  A decoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code decoder != NULL \endcode
- *    \code value != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the decoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__stream_decoder_set_error_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorCallback value);
-
-/** Set the client data to be passed back to callbacks.
- *  This value will be supplied to callbacks in their \a client_data
- *  argument.
+ *  Clients that do not use the MD5 check should leave this off to speed
+ *  up decoding.
  *
- * \default \c NULL
+ * \default \c false
  * \param  decoder  A decoder instance to set.
- * \param  value    See above.
+ * \param  value    Flag value (see above).
  * \assert
  *    \code decoder != NULL \endcode
  * \retval FLAC__bool
  *    \c false if the decoder is already initialized, else \c true.
  */
-FLAC_API FLAC__bool FLAC__stream_decoder_set_client_data(FLAC__StreamDecoder *decoder, void *value);
+FLAC_API FLAC__bool FLAC__stream_decoder_set_md5_checking(FLAC__StreamDecoder *decoder, FLAC__bool value);
 
 /** Direct the decoder to pass on all metadata blocks of type \a type.
  *
@@ -630,6 +787,32 @@ FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_get_state(const FLAC__Str
  */
 FLAC_API const char *FLAC__stream_decoder_get_resolved_state_string(const FLAC__StreamDecoder *decoder);
 
+/** Get the "MD5 signature checking" flag.
+ *  This is the value of the setting, not whether or not the decoder is
+ *  currently checking the MD5 (remember, it can be turned off automatically
+ *  by a seek).  When the decoder is reset the flag will be restored to the
+ *  value returned by this function.
+ *
+ * \param  decoder  A decoder instance to query.
+ * \assert
+ *    \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ *    See above.
+ */
+FLAC_API FLAC__bool FLAC__stream_decoder_get_md5_checking(const FLAC__StreamDecoder *decoder);
+
+/** Get the total number of samples in the stream being decoded.
+ *  Will only be valid after decoding has started and will contain the
+ *  value from the \c STREAMINFO block.  A value of \c 0 means "unknown".
+ *
+ * \param  decoder  A decoder instance to query.
+ * \assert
+ *    \code decoder != NULL \endcode
+ * \retval unsigned
+ *    See above.
+ */
+FLAC_API FLAC__uint64 FLAC__stream_decoder_get_total_samples(const FLAC__StreamDecoder *decoder);
+
 /** Get the current number of channels in the stream being decoded.
  *  Will only be valid after decoding has started and will contain the
  *  value from the most recently decoded frame header.
@@ -690,22 +873,187 @@ FLAC_API unsigned FLAC__stream_decoder_get_sample_rate(const FLAC__StreamDecoder
  */
 FLAC_API unsigned FLAC__stream_decoder_get_blocksize(const FLAC__StreamDecoder *decoder);
 
+/** Returns the decoder's current read position within the stream.
+ *  The position is the byte offset from the start of the stream.
+ *  Bytes before this position have been fully decoded.  Note that
+ *  there may still be undecoded bytes in the decoder's read FIFO.
+ *  The returned position is correct even after a seek.
+ *
+ * \param  decoder   A decoder instance to query.
+ * \param  position  Address at which to return the desired position.
+ * \assert
+ *    \code decoder != NULL \endcode
+ *    \code position != NULL \endcode
+ * \retval FLAC__bool
+ *    \c true if successful, \c false if there was an error from
+ *    the 'tell' callback or it returned
+ *    \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED.
+ */
+FLAC_API FLAC__bool FLAC__stream_decoder_get_decode_position(const FLAC__StreamDecoder *decoder, FLAC__uint64 *position);
+
 /** Initialize the decoder instance.
- *  Should be called after FLAC__stream_decoder_new() and
+ *
+ *  This flavor of initialization sets up the decoder to decode from a stream.
+ *  I/O is performed via callbacks to the client.  For decoding from a plain file
+ *  via filename or open FILE*, FLAC__stream_decoder_init_file() and
+ *  FLAC__stream_decoder_init_FILE() provide a simpler interface.
+ *
+ *  This function should be called after FLAC__stream_decoder_new() and
  *  FLAC__stream_decoder_set_*() but before any of the
  *  FLAC__stream_decoder_process_*() functions.  Will set and return the
  *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
  *  if initialization succeeded.
  *
- * \param  decoder  An uninitialized decoder instance.
+ * \param  decoder            An uninitialized decoder instance.
+ * \param  read_callback      See FLAC__StreamDecoderReadCallback.  This
+ *                            pointer must not be \c NULL.
+ * \param  seek_callback      See FLAC__StreamDecoderSeekCallback.  This
+ *                            pointer may be \c NULL if seeking is not
+ *                            supported.  If \a seek_callback is not \c NULL then a
+ *                            \a tell_callback, \a length_callback, and \a eof_callback must also be supplied.
+ *                            Alternatively, a dummy seek callback that just
+ *                            returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
+ *                            may also be supplied, all though this is slightly
+ *                            less efficient for the decoder.
+ * \param  tell_callback      See FLAC__StreamDecoderTellCallback.  This
+ *                            pointer may be \c NULL if not supported by the client.  If
+ *                            \a seek_callback is not \c NULL then a
+ *                            \a tell_callback must also be supplied.
+ *                            Alternatively, a dummy tell callback that just
+ *                            returns \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
+ *                            may also be supplied, all though this is slightly
+ *                            less efficient for the decoder.
+ * \param  length_callback    See FLAC__StreamDecoderLengthCallback.  This
+ *                            pointer may be \c NULL if not supported by the client.  If
+ *                            \a seek_callback is not \c NULL then a
+ *                            \a length_callback must also be supplied.
+ *                            Alternatively, a dummy length callback that just
+ *                            returns \c FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
+ *                            may also be supplied, all though this is slightly
+ *                            less efficient for the decoder.
+ * \param  eof_callback       See FLAC__StreamDecoderEofCallback.  This
+ *                            pointer may be \c NULL if not supported by the client.  If
+ *                            \a seek_callback is not \c NULL then a
+ *                            \a eof_callback must also be supplied.
+ *                            Alternatively, a dummy length callback that just
+ *                            returns \c false
+ *                            may also be supplied, all though this is slightly
+ *                            less efficient for the decoder.
+ * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
+ *                            pointer must not be \c NULL.
+ * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
+ *                            pointer may be \c NULL if the callback is not
+ *                            desired.
+ * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
+ *                            pointer must not be \c NULL.
+ * \param  client_data        This value will be supplied to callbacks in their
+ *                            \a client_data argument.
  * \assert
  *    \code decoder != NULL \endcode
- * \retval FLAC__StreamDecoderState
- *    \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA if initialization was
- *    successful; see FLAC__StreamDecoderState for the meanings of other
- *    return values.
+ * \retval FLAC__StreamDecoderInitStatus
+ *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
+ *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
+ */
+FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_stream(
+       FLAC__StreamDecoder *decoder,
+       FLAC__StreamDecoderReadCallback read_callback,
+       FLAC__StreamDecoderSeekCallback seek_callback,
+       FLAC__StreamDecoderTellCallback tell_callback,
+       FLAC__StreamDecoderLengthCallback length_callback,
+       FLAC__StreamDecoderEofCallback eof_callback,
+       FLAC__StreamDecoderWriteCallback write_callback,
+       FLAC__StreamDecoderMetadataCallback metadata_callback,
+       FLAC__StreamDecoderErrorCallback error_callback,
+       void *client_data
+);
+
+/** Initialize the decoder instance.
+ *
+ *  This flavor of initialization sets up the decoder to decode from a plain
+ *  file.  For non-stdio streams, you must use
+ *  FLAC__stream_decoder_init_stream() and provide callbacks for the I/O.
+ *
+ *  This function should be called after FLAC__stream_decoder_new() and
+ *  FLAC__stream_decoder_set_*() but before any of the
+ *  FLAC__stream_decoder_process_*() functions.  Will set and return the
+ *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
+ *  if initialization succeeded.
+ *
+ * \param  decoder            An uninitialized decoder instance.
+ * \param  file               An open FLAC file.  The file should have been
+ *                            opened with mode \c "rb" and rewound.  The file
+ *                            becomes owned by the decoder and should not be
+ *                            manipulated by the client while decoding.
+ *                            Unless \a file is \c stdin, it will be closed
+ *                            when FLAC__stream_decoder_finish() is called.
+ *                            Note however that seeking will not work when
+ *                            decoding from \c stdout since it is not seekable.
+ * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
+ *                            pointer must not be \c NULL.
+ * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
+ *                            pointer may be \c NULL if the callback is not
+ *                            desired.
+ * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
+ *                            pointer must not be \c NULL.
+ * \param  client_data        This value will be supplied to callbacks in their
+ *                            \a client_data argument.
+ * \assert
+ *    \code decoder != NULL \endcode
+ *    \code file != NULL \endcode
+ * \retval FLAC__StreamDecoderInitStatus
+ *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
+ *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
  */
-FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_init(FLAC__StreamDecoder *decoder);
+FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_FILE(
+       FLAC__StreamDecoder *decoder,
+       FILE *file,
+       FLAC__StreamDecoderWriteCallback write_callback,
+       FLAC__StreamDecoderMetadataCallback metadata_callback,
+       FLAC__StreamDecoderErrorCallback error_callback,
+       void *client_data
+);
+
+/** Initialize the decoder instance.
+ *
+ *  This flavor of initialization sets up the decoder to decode from a plain
+ *  file.  If POSIX fopen() semantics are not sufficient, (for example, with
+ *  Unicode filenames on Windows), you must use
+ *  FLAC__stream_decoder_init_FILE(), or FLAC__stream_decoder_init_stream()
+ *  and provide callbacks for the I/O.
+ *
+ *  This function should be called after FLAC__stream_decoder_new() and
+ *  FLAC__stream_decoder_set_*() but before any of the
+ *  FLAC__stream_decoder_process_*() functions.  Will set and return the
+ *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
+ *  if initialization succeeded.
+ *
+ * \param  decoder            An uninitialized decoder instance.
+ * \param  filename           The name of the file to decode from.  The file will
+ *                            be opened with fopen().  Use \c NULL to decode from
+ *                            \c stdin.  Note that \c stdin is not seekable.
+ * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
+ *                            pointer must not be \c NULL.
+ * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
+ *                            pointer may be \c NULL if the callback is not
+ *                            desired.
+ * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
+ *                            pointer must not be \c NULL.
+ * \param  client_data        This value will be supplied to callbacks in their
+ *                            \a client_data argument.
+ * \assert
+ *    \code decoder != NULL \endcode
+ * \retval FLAC__StreamDecoderInitStatus
+ *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
+ *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
+ */
+FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_file(
+       FLAC__StreamDecoder *decoder,
+       const char *filename,
+       FLAC__StreamDecoderWriteCallback write_callback,
+       FLAC__StreamDecoderMetadataCallback metadata_callback,
+       FLAC__StreamDecoderErrorCallback error_callback,
+       void *client_data
+);
 
 /** Finish the decoding process.
  *  Flushes the decoding buffer, releases resources, resets the decoder
@@ -720,19 +1068,26 @@ FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_init(FLAC__StreamDecoder
  * \param  decoder  An uninitialized decoder instance.
  * \assert
  *    \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ *    \c false if MD5 checking is on AND a STREAMINFO block was available
+ *    AND the MD5 signature in the STREAMINFO block was non-zero AND the
+ *    signature does not match the one computed by the decoder; else
+ *    \c true.
  */
-FLAC_API void FLAC__stream_decoder_finish(FLAC__StreamDecoder *decoder);
+FLAC_API FLAC__bool FLAC__stream_decoder_finish(FLAC__StreamDecoder *decoder);
 
 /** Flush the stream input.
  *  The decoder's input buffer will be cleared and the state set to
- *  \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.
+ *  \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.  This will also turn
+ *  off MD5 checking.
  *
  * \param  decoder  A decoder instance.
  * \assert
  *    \code decoder != NULL \endcode
  * \retval FLAC__bool
  *    \c true if successful, else \c false if a memory allocation
- *    error occurs.
+ *    error occurs (in which case the state will be set to
+ *    \c FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR).
  */
 FLAC_API FLAC__bool FLAC__stream_decoder_flush(FLAC__StreamDecoder *decoder);
 
@@ -741,14 +1096,31 @@ FLAC_API FLAC__bool FLAC__stream_decoder_flush(FLAC__StreamDecoder *decoder);
  *  \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.  This is similar to
  *  FLAC__stream_decoder_finish() except that the settings are
  *  preserved; there is no need to call FLAC__stream_decoder_init()
- *  before decoding again.
+ *  before decoding again.  MD5 checking will be restored to its original
+ *  setting.
+ *
+ *  If the decoder is seekable, or was initialized with
+ *  FLAC__stream_decoder_init_FILE() or FLAC__stream_decoder_init_file(),
+ *  the decoder will also attempt to seek to the beginning of the file.
+ *  If this rewind fails, this function will return \c false.  It follows
+ *  that FLAC__stream_decoder_reset() cannot be used when decoding from
+ *  \c stdin.
+ *
+ *  If the decoder was initialized with FLAC__stream_encoder_init_stream()
+ *  and is not seekable (i.e. no seek callback was provided or the seek
+ *  callback returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED), it
+ *  is the duty of the client to start feeding data from the beginning of
+ *  the stream on the next FLAC__stream_decoder_process() or
+ *  FLAC__stream_decoder_process_interleaved() call.
  *
  * \param  decoder  A decoder instance.
  * \assert
  *    \code decoder != NULL \endcode
  * \retval FLAC__bool
- *    \c true if successful, else \c false if a memory allocation
- *    error occurs.
+ *    \c true if successful, else \c false if a memory allocation occurs
+ *    (in which case the state will be set to
+ *    \c FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR) or a seek error
+ *    occurs (the state will be unchanged).
  */
 FLAC_API FLAC__bool FLAC__stream_decoder_reset(FLAC__StreamDecoder *decoder);
 
@@ -869,6 +1241,24 @@ FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_stream(FLAC__Strea
  */
 FLAC_API FLAC__bool FLAC__stream_decoder_skip_single_frame(FLAC__StreamDecoder *decoder);
 
+/** Flush the input and seek to an absolute sample.
+ *  Decoding will resume at the given sample.  Note that because of
+ *  this, the next write callback may contain a partial block.  The
+ *  client must support seeking the input or this function will fail
+ *  and return \c false.  Furthermore, if the decoder state is
+ *  \c FLAC__STREAM_DECODER_SEEK_ERROR, then the decoder must be flushed
+ *  with FLAC__stream_decoder_flush() or reset with
+ *  FLAC__stream_decoder_reset() before decoding can continue.
+ *
+ * \param  decoder  A decoder instance.
+ * \param  sample   The target sample number to seek to.
+ * \assert
+ *    \code decoder != NULL \endcode
+ * \retval FLAC__bool
+ *    \c true if successful, else \c false.
+ */
+FLAC_API FLAC__bool FLAC__stream_decoder_seek_absolute(FLAC__StreamDecoder *decoder, FLAC__uint64 sample);
+
 /* \} */
 
 #ifdef __cplusplus
index dcf879c..20d7375 100644 (file)
@@ -32,6 +32,7 @@
 #ifndef FLAC__STREAM_ENCODER_H
 #define FLAC__STREAM_ENCODER_H
 
+#include <stdio.h> /* for FILE */
 #include "export.h"
 #include "format.h"
 #include "stream_decoder.h"
@@ -55,29 +56,23 @@ extern "C" {
  *  \ingroup flac
  *
  *  \brief
- *  This module describes the three encoder layers provided by libFLAC.
- *
- * For encoding FLAC streams, libFLAC provides three layers of access.  The
- * lowest layer is non-seekable stream-level encoding, the next is seekable
- * stream-level encoding, and the highest layer is file-level encoding.  The
- * interfaces are described in the \link flac_stream_encoder stream encoder
- * \endlink, \link flac_seekable_stream_encoder seekable stream encoder
- * \endlink, and \link flac_file_encoder file encoder \endlink modules
- * respectively.  Typically you will choose the highest layer that your input
- * source will support.
- * The stream encoder relies on callbacks for writing the data and
- * metadata. The file encoder provides these callbacks internally and you
- * need only supply the filename.
- *
- * The stream encoder relies on callbacks for writing the data and has no
- * provisions for seeking the output.  The seekable stream encoder wraps
- * the stream encoder and also automaticallay handles the writing back of
- * metadata discovered while encoding.  However, you must provide extra
- * callbacks for seek-related operations on your output, like seek and
- * tell.  The file encoder wraps the seekable stream encoder and supplies
- * all of the callbacks internally, simplifying the processing of standard
- * files.  The only callback exposed is for progress reporting, and that
- * is optional.
+ *  This module describes the two encoder layers provided by libFLAC.
+ *
+ * libFLAC provides two ways of encoding FLAC streams.  There is a @@@@@@frame encoder which encodes single frames at a time, and a stream encoder which encodes whole streams.
+ *
+ * @@@@@@TODO frame encoder
+ *
+ * The stream encoder can be used encode complete streams either to the
+ * client via callbacks, or directly to a file, depending on how it is
+ * initialized.  When encoding via callbacks, the client provides a write
+ * callback which will be called whenever FLAC data is ready to be written.
+ * If the client also supplies a seek callback, the encoder will also
+ * automatically handle the writing back of metadata discovered while
+ * encoding, like stream info, seek points offsets, etc.  When encoding to
+ * a file, the client needs only supply a filename or open \c FILE* and an
+ * optional progress callback for periodic notification of progress; the
+ * write and seek callbacks are supplied internally.  For more info see the
+ * \link flac_stream_encoder stream encoder \endlink module.
  */
 
 /** \defgroup flac_stream_encoder FLAC/stream_encoder.h: stream encoder interface
@@ -90,18 +85,21 @@ extern "C" {
  * The basic usage of this encoder is as follows:
  * - The program creates an instance of an encoder using
  *   FLAC__stream_encoder_new().
- * - The program overrides the default settings and sets callbacks using
+ * - The program overrides the default settings using
  *   FLAC__stream_encoder_set_*() functions.
  * - The program initializes the instance to validate the settings and
- *   prepare for encoding using FLAC__stream_encoder_init().
+ *   prepare for encoding using FLAC__stream_encoder_init_stream() or
+ *   FLAC__stream_encoder_init_FILE() or FLAC__stream_encoder_init_file(),
+ *   depending on the nature of the output.
  * - The program calls FLAC__stream_encoder_process() or
  *   FLAC__stream_encoder_process_interleaved() to encode data, which
  *   subsequently calls the callbacks when there is encoder data ready
  *   to be written.
  * - The program finishes the encoding with FLAC__stream_encoder_finish(),
  *   which causes the encoder to encode any data still in its input pipe,
- *   call the metadata callback with the final encoding statistics, and
- *   finally reset the encoder to the uninitialized state.
+ *   update the metadata with the final encoding statistics if output
+ *   seeking is possible, and finally reset the encoder to the
+ *   uninitialized state.
  * - The instance may be used again or deleted with
  *   FLAC__stream_encoder_delete().
  *
@@ -109,8 +107,9 @@ extern "C" {
  * \link flac_stream_decoder stream decoder \endlink, but has fewer
  * callbacks and more options.  Typically the user will create a new
  * instance by calling FLAC__stream_encoder_new(), then set the necessary
- * parameters and callbacks with FLAC__stream_encoder_set_*(), and
- * initialize it by calling FLAC__stream_encoder_init().
+ * parameters with FLAC__stream_encoder_set_*(), and initialize it by
+ * calling FLAC__stream_encoder_init_stream() or
+ * FLAC__stream_encoder_init_file() or FLAC__stream_encoder_init_FILE().
  *
  * Unlike the decoders, the stream encoder has many options that can
  * affect the speed and compression ratio.  When setting these parameters
@@ -118,26 +117,32 @@ extern "C" {
  * <A HREF="../documentation.html#format">user-level documentation</A>
  * or the <A HREF="../format.html">formal description</A>).  The
  * FLAC__stream_encoder_set_*() functions themselves do not validate the
- * values as many are interdependent.  The FLAC__stream_encoder_init()
- * function will do this, so make sure to pay attention to the state
- * returned by FLAC__stream_encoder_init() to make sure that it is
- * FLAC__STREAM_ENCODER_OK.  Any parameters that are not set before
- * FLAC__stream_encoder_init() will take on the defaults from the
- * constructor.
- *
- * The user must provide function pointers for the following callbacks:
- *
- * - Write callback - This function is called by the encoder anytime there
- *   is raw encoded data to write.  It may include metadata mixed with
- *   encoded audio frames and the data is not guaranteed to be aligned on
- *   frame or metadata block boundaries.
- * - Metadata callback - This function is called once at the end of
- *   encoding with the populated STREAMINFO structure.  This is so file
- *   encoders can seek back to the beginning of the file and write the
- *   STREAMINFO block with the correct statistics after encoding (like
- *   minimum/maximum frame size).
- *
- * The call to FLAC__stream_encoder_init() currently will also immediately
+ * values as many are interdependent.  The FLAC__stream_encoder_init_*()
+ * functions will do this, so make sure to pay attention to the state
+ * returned by FLAC__stream_encoder_init_*() to make sure that it is
+ * FLAC__STREAM_ENCODER_INIT_STATUS_OK.  Any parameters that are not set
+ * before FLAC__stream_encoder_init_*() will take on the defaults from
+ * the constructor.
+ *
+ * There are three initialization functions, one for setting up the encoder
+ * to encode FLAC data to the client via callbacks, and two for encoding
+ * directly to a file.
+ *
+ * For encoding via callbacks, use FLAC__stream_encoder_init_stream().
+ * You must also supply a write callback which will be called anytime
+ * there is raw encoded data to write.  If the client can seek the output
+ * it is best to also supply seek and tell callbacks, as this allows the
+ * encoder to go back after encoding is finished to write back
+ * information that was collected while encoding, like seek point offsets,
+ * frame sizes, etc.
+ *
+ * For encoding directly to a file, use FLAC__stream_encoder_init_FILE()
+ * or FLAC__stream_encoder_init_file().  Then you must only supply a
+ * filename or open \c FILE*; the encoder will handle all the callbacks
+ * internally.  You may also supply a progress callback for periodic
+ * notification of the encoding progress.
+ *
+ * The call to FLAC__stream_encoder_init_*() currently will also immediately
  * call the write callback several times, once with the \c fLaC signature,
  * and once for each encoded metadata block.
  *
@@ -177,6 +182,14 @@ extern "C" {
  * for the specification of metadata blocks and their lengths.
  *
  * \note
+ * If you are writing the FLAC data to a file via callbacks, make sure it
+ * is open for update (e.g. mode "w+" for stdio streams).  This is because
+ * after the first encoding pass, the encoder will try to seek back to the
+ * beginning of the stream, to the STREAMINFO block, to write some data
+ * there.  (If using FLAC__stream_encoder_init_file() or
+ * FLAC__stream_encoder_init_FILE(), the file is managed internally.)
+ *
+ * \note
  * The "set" functions may only be called when the encoder is in the
  * state FLAC__STREAM_ENCODER_UNINITIALIZED, i.e. after
  * FLAC__stream_encoder_new() or FLAC__stream_encoder_finish(), but
@@ -185,20 +198,30 @@ extern "C" {
  *
  * \note
  * FLAC__stream_encoder_finish() resets all settings to the constructor
- * defaults, including the callbacks.
+ * defaults.
  *
  * \{
  */
 
 
-/** State values for a FLAC__StreamEncoder
+/** State values for a FLAC__StreamEncoder.
+ *
+ * The encoder's state can be obtained by calling FLAC__stream_encoder_get_state().
  *
- *  The encoder's state can be obtained by calling FLAC__stream_encoder_get_state().
+ * If the encoder gets into any other state besides \c FLAC__STREAM_ENCODER_OK
+ * or \c FLAC__STREAM_ENCODER_UNINITIALIZED, it becomes invalid for encoding and
+ * must be deleted with FLAC__stream_encoder_delete().
  */
 typedef enum {
 
        FLAC__STREAM_ENCODER_OK = 0,
-       /**< The encoder is in the normal OK state. */
+       /**< The encoder is in the normal OK state and samples can be processed. */
+
+       FLAC__STREAM_ENCODER_UNINITIALIZED,
+       /**< The encoder is in the uninitialized state; one of the
+        * FLAC__stream_encoder_init_*() functions must be called before samples
+        * can be processed.
+        */
 
        FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR,
        /**< An error occurred in the underlying verify stream decoder;
@@ -210,49 +233,81 @@ typedef enum {
         * audio signal and the decoded audio signal.
         */
 
-       FLAC__STREAM_ENCODER_INVALID_CALLBACK,
-       /**< The encoder was initialized before setting all the required callbacks. */
+       FLAC__STREAM_ENCODER_CLIENT_ERROR,
+       /**< One of the callbacks returned a fatal error. */
+
+       FLAC__STREAM_ENCODER_IO_ERROR,
+       /**< An I/O error occurred while opening/reading/writing a file.
+        * Check \c errno.
+        */
+
+       FLAC__STREAM_ENCODER_FRAMING_ERROR,
+       /**< An error occurred while writing the stream; usually, the
+        * write_callback returned an error.
+        */
+
+       FLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR
+       /**< Memory allocation failed. */
+
+} FLAC__StreamEncoderState;
+
+/** Maps a FLAC__StreamEncoderState to a C string.
+ *
+ *  Using a FLAC__StreamEncoderState as the index to this array
+ *  will give the string equivalent.  The contents should not be modified.
+ */
+extern FLAC_API const char * const FLAC__StreamEncoderStateString[];
+
+/** Possible return values for the FLAC__stream_encoder_init_*() functions.
+ */
+typedef enum {
+
+       FLAC__STREAM_ENCODER_INIT_STATUS_OK = 0,
+       /**< Initialization was successful. */
 
-       FLAC__STREAM_ENCODER_INVALID_NUMBER_OF_CHANNELS,
+       FLAC__STREAM_ENCODER_INIT_STATUS_ENCODER_ERROR,
+       /**< General failure to set up encoder; call FLAC__stream_encoder_get_state() for cause. */
+
+       FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_CALLBACKS,
+       /**< A required callback was not supplied. */
+
+       FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_NUMBER_OF_CHANNELS,
        /**< The encoder has an invalid setting for number of channels. */
 
-       FLAC__STREAM_ENCODER_INVALID_BITS_PER_SAMPLE,
+       FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BITS_PER_SAMPLE,
        /**< The encoder has an invalid setting for bits-per-sample.
         * FLAC supports 4-32 bps but the reference encoder currently supports
         * only up to 24 bps.
         */
 
-       FLAC__STREAM_ENCODER_INVALID_SAMPLE_RATE,
+       FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_SAMPLE_RATE,
        /**< The encoder has an invalid setting for the input sample rate. */
 
-       FLAC__STREAM_ENCODER_INVALID_BLOCK_SIZE,
+       FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BLOCK_SIZE,
        /**< The encoder has an invalid setting for the block size. */
 
-       FLAC__STREAM_ENCODER_INVALID_MAX_LPC_ORDER,
+       FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_MAX_LPC_ORDER,
        /**< The encoder has an invalid setting for the maximum LPC order. */
 
-       FLAC__STREAM_ENCODER_INVALID_QLP_COEFF_PRECISION,
+       FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_QLP_COEFF_PRECISION,
        /**< The encoder has an invalid setting for the precision of the quantized linear predictor coefficients. */
 
-       FLAC__STREAM_ENCODER_MID_SIDE_CHANNELS_MISMATCH,
+       FLAC__STREAM_ENCODER_INIT_STATUS_MID_SIDE_CHANNELS_MISMATCH,
        /**< Mid/side coding was specified but the number of channels is not equal to 2. */
 
-       FLAC__STREAM_ENCODER_MID_SIDE_SAMPLE_SIZE_MISMATCH,
+       FLAC__STREAM_ENCODER_INIT_STATUS_MID_SIDE_SAMPLE_SIZE_MISMATCH,
        /**< Deprecated. */
 
-       FLAC__STREAM_ENCODER_ILLEGAL_MID_SIDE_FORCE,
+       FLAC__STREAM_ENCODER_INIT_STATUS_ILLEGAL_MID_SIDE_FORCE,
        /**< Loose mid/side coding was specified but mid/side coding was not. */
 
-       FLAC__STREAM_ENCODER_BLOCK_SIZE_TOO_SMALL_FOR_LPC_ORDER,
+       FLAC__STREAM_ENCODER_INIT_STATUS_BLOCK_SIZE_TOO_SMALL_FOR_LPC_ORDER,
        /**< The specified block size is less than the maximum LPC order. */
 
-       FLAC__STREAM_ENCODER_NOT_STREAMABLE,
+       FLAC__STREAM_ENCODER_INIT_STATUS_NOT_STREAMABLE,
        /**< The encoder is bound to the "streamable subset" but other settings violate it. */
 
-       FLAC__STREAM_ENCODER_FRAMING_ERROR,
-       /**< An error occurred while writing the stream; usually, the write_callback returned an error. */
-
-       FLAC__STREAM_ENCODER_INVALID_METADATA,
+       FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_METADATA,
        /**< The metadata input to the encoder is invalid, in one of the following ways:
         * - FLAC__stream_encoder_set_metadata() was called with a null pointer but a block count > 0
         * - One of the metadata blocks contains an undefined type
@@ -261,32 +316,20 @@ typedef enum {
         * - It contains more than one SEEKTABLE block or more than one VORBIS_COMMENT block
         */
 
-       FLAC__STREAM_ENCODER_FATAL_ERROR_WHILE_ENCODING,
-       /**< An error occurred while writing the stream; usually, the write_callback returned an error. */
-
-       FLAC__STREAM_ENCODER_FATAL_ERROR_WHILE_WRITING,
-       /**< The write_callback returned an error. */
-
-       FLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR,
-       /**< Memory allocation failed. */
-
-       FLAC__STREAM_ENCODER_ALREADY_INITIALIZED,
-       /**< FLAC__stream_encoder_init() was called when the encoder was
+       FLAC__STREAM_ENCODER_INIT_STATUS_ALREADY_INITIALIZED
+       /**< FLAC__stream_encoder_init_*() was called when the encoder was
         * already initialized, usually because
         * FLAC__stream_encoder_finish() was not called.
         */
 
-       FLAC__STREAM_ENCODER_UNINITIALIZED
-       /**< The encoder is in the uninitialized state. */
-
-} FLAC__StreamEncoderState;
+} FLAC__StreamEncoderInitStatus;
 
-/** Maps a FLAC__StreamEncoderState to a C string.
+/** Maps a FLAC__StreamEncoderInitStatus to a C string.
  *
- *  Using a FLAC__StreamEncoderState as the index to this array
+ *  Using a FLAC__StreamEncoderInitStatus as the index to this array
  *  will give the string equivalent.  The contents should not be modified.
  */
-extern FLAC_API const char * const FLAC__StreamEncoderStateString[];
+extern FLAC_API const char * const FLAC__StreamEncoderInitStatusString[];
 
 /** Return values for the FLAC__StreamEncoder write callback.
  */
@@ -307,6 +350,51 @@ typedef enum {
  */
 extern FLAC_API const char * const FLAC__StreamEncoderWriteStatusString[];
 
+/** Return values for the FLAC__StreamEncoder seek callback.
+ */
+typedef enum {
+
+       FLAC__STREAM_ENCODER_SEEK_STATUS_OK,
+       /**< The seek was OK and encoding can continue. */
+
+       FLAC__STREAM_ENCODER_SEEK_STATUS_ERROR,
+       /**< An unrecoverable error occurred. */
+
+       FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
+       /**< Client does not support seeking. */
+
+} FLAC__StreamEncoderSeekStatus;
+
+/** Maps a FLAC__StreamEncoderSeekStatus to a C string.
+ *
+ *  Using a FLAC__StreamEncoderSeekStatus as the index to this array
+ *  will give the string equivalent.  The contents should not be modified.
+ */
+extern FLAC_API const char * const FLAC__StreamEncoderSeekStatusString[];
+
+
+/** Return values for the FLAC__StreamEncoder tell callback.
+ */
+typedef enum {
+
+       FLAC__STREAM_ENCODER_TELL_STATUS_OK,
+       /**< The tell was OK and encoding can continue. */
+
+       FLAC__STREAM_ENCODER_TELL_STATUS_ERROR,
+       /**< An unrecoverable error occurred. */
+
+       FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
+       /**< Client does not support seeking. */
+
+} FLAC__StreamEncoderTellStatus;
+
+/** Maps a FLAC__StreamEncoderTellStatus to a C string.
+ *
+ *  Using a FLAC__StreamEncoderTellStatus as the index to this array
+ *  will give the string equivalent.  The contents should not be modified.
+ */
+extern FLAC_API const char * const FLAC__StreamEncoderTellStatusString[];
+
 
 /***********************************************************************
  *
@@ -326,32 +414,126 @@ typedef struct {
 } FLAC__StreamEncoder;
 
 /** Signature for the write callback.
- *  See FLAC__stream_encoder_set_write_callback() for more info.
+ *
+ *  A function pointer matching this signature must be passed to
+ *  FLAC__stream_encoder_init_stream().  The supplied function will be called
+ *  by the encoder anytime there is raw encoded data ready to write.  It may
+ *  include metadata mixed with encoded audio frames and the data is not
+ *  guaranteed to be aligned on frame or metadata block boundaries.
+ *
+ *  The only duty of the callback is to write out the \a bytes worth of data
+ *  in \a buffer to the current position in the output stream.  The arguments
+ *  \a samples and \a current_frame are purely informational.  If \a samples
+ *  is greater than \c 0, then \a current_frame will hold the current frame
+ *  number that is being written; otherwise it indicates that the write
+ *  callback is being called to write metadata.
+ *
+ * \note In general, FLAC__StreamEncoder functions which change the
+ * state should not be called on the \a encoder while in the callback.
  *
  * \param  encoder  The encoder instance calling the callback.
  * \param  buffer   An array of encoded data of length \a bytes.
  * \param  bytes    The byte length of \a buffer.
  * \param  samples  The number of samples encoded by \a buffer.
- *                  \c 0 has a special meaning; see
- *                  FLAC__stream_encoder_set_write_callback().
+ *                  \c 0 has a special meaning; see above.
  * \param  current_frame  The number of the current frame being encoded.
  * \param  client_data  The callee's client data set through
- *                      FLAC__stream_encoder_set_client_data().
+ *                      FLAC__stream_encoder_init_*().
  * \retval FLAC__StreamEncoderWriteStatus
  *    The callee's return status.
  */
 typedef FLAC__StreamEncoderWriteStatus (*FLAC__StreamEncoderWriteCallback)(const FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
 
+/** Signature for the seek callback.
+ *
+ *  A function pointer matching this signature may be passed to
+ *  FLAC__stream_encoder_init_stream().  The supplied function will be called
+ *  when the encoder needs to seek the output stream.  The encoder will pass
+ *  the absolute byte offset to seek to, 0 meaning the beginning of the stream.
+ *
+ * \note In general, FLAC__StreamEncoder functions which change the
+ * state should not be called on the \a encoder while in the callback.
+ *
+ * \param  encoder  The encoder instance calling the callback.
+ * \param  absolute_byte_offset  The offset from the beginning of the stream
+ *                               to seek to.
+ * \param  client_data  The callee's client data set through
+ *                      FLAC__stream_encoder_init_*().
+ * \retval FLAC__StreamEncoderSeekStatus
+ *    The callee's return status.
+ */
+typedef FLAC__StreamEncoderSeekStatus (*FLAC__StreamEncoderSeekCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
+
+/** Signature for the tell callback.
+ *
+ *  A function pointer matching this signature may be passed to
+ *  FLAC__stream_encoder_init_stream().  The supplied function will be called
+ *  when the encoder needs to know the current position of the output stream.
+ *
+ * \warning
+ * The callback must return the true current byte offset of the output to
+ * which the encoder is writing.  If you are buffering the output, make
+ * sure and take this into account.  If you are writing directly to a
+ * FILE* from your write callback, ftell() is sufficient.  If you are
+ * writing directly to a file descriptor from your write callback, you
+ * can use lseek(fd, SEEK_CUR, 0).  The encoder may later seek back to
+ * these points to rewrite metadata after encoding.
+ *
+ * \note In general, FLAC__StreamEncoder functions which change the
+ * state should not be called on the \a encoder while in the callback.
+ *
+ * \param  encoder  The encoder instance calling the callback.
+ * \param  absolute_byte_offset  The address at which to store the current
+ *                               position of the output.
+ * \param  client_data  The callee's client data set through
+ *                      FLAC__stream_encoder_init_*().
+ * \retval FLAC__StreamEncoderTellStatus
+ *    The callee's return status.
+ */
+typedef FLAC__StreamEncoderTellStatus (*FLAC__StreamEncoderTellCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
+
 /** Signature for the metadata callback.
- *  See FLAC__stream_encoder_set_metadata_callback() for more info.
+ *
+ *  A function pointer matching this signature may be passed to
+ *  FLAC__stream_encoder_init_stream().  The supplied function will be called
+ *  once at the end of encoding with the populated STREAMINFO structure.  This
+ *  is so the client can seek back to the beginning of the file and write the
+ *  STREAMINFO block with the correct statistics after encoding (like
+ *  minimum/maximum frame size and total samples).
+ *
+ * \note In general, FLAC__StreamEncoder functions which change the
+ * state should not be called on the \a encoder while in the callback.
  *
  * \param  encoder      The encoder instance calling the callback.
  * \param  metadata     The final populated STREAMINFO block.
  * \param  client_data  The callee's client data set through
- *                      FLAC__stream_encoder_set_client_data().
+ *                      FLAC__stream_encoder_init_*().
  */
 typedef void (*FLAC__StreamEncoderMetadataCallback)(const FLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data);
 
+/** Signature for the progress callback.
+ *
+ *  A function pointer matching this signature may be passed to
+ *  FLAC__stream_encoder_init_file() or FLAC__stream_encoder_init_FILE().
+ *  The supplied function will be called when the encoder has finished
+ *  writing a frame.  The \c total_frames_estimate argument to the
+ *  callback will be based on the value from
+ *  FLAC__file_encoder_set_total_samples_estimate().
+ *
+ * \note In general, FLAC__StreamEncoder functions which change the
+ * state should not be called on the \a encoder while in the callback.
+ *
+ * \param  encoder          The encoder instance calling the callback.
+ * \param  bytes_written    Bytes written so far.
+ * \param  samples_written  Samples written so far.
+ * \param  frames_written   Frames written so far.
+ * \param  total_frames_estimate  The estimate of the total number of
+ *                                frames to be written.
+ * \param  client_data      The callee's client data set through
+ *                          FLAC__stream_encoder_init_*().
+ */
+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);
+
 
 /***********************************************************************
  *
@@ -691,9 +873,10 @@ FLAC_API FLAC__bool FLAC__stream_encoder_set_total_samples_estimate(FLAC__Stream
 /** Set the metadata blocks to be emitted to the stream before encoding.
  *  A value of \c NULL, \c 0 implies no metadata; otherwise, supply an
  *  array of pointers to metadata blocks.  The array is non-const since
- *  the encoder may need to change the \a is_last flag inside them.
- *  Otherwise, the encoder will not modify or free the blocks.  It is up
- *  to the caller to free the metadata blocks after encoding.
+ *  the encoder may need to change the \a is_last flag inside them, and
+ *  in some cases update seek point offsets.  Otherwise, the encoder will
+ *  not modify or free the blocks.  It is up to the caller to free the
+ *  metadata blocks after encoding.
  *
  * \note
  * The encoder stores only the \a metadata pointer; the passed-in array
@@ -706,11 +889,34 @@ FLAC_API FLAC__bool FLAC__stream_encoder_set_total_samples_estimate(FLAC__Stream
  *
  * \note
  * By default the encoder does not create a SEEKTABLE.  If one is supplied
- * in the \a metadata array it will be written verbatim.  However by itself
- * this is not very useful as the user will not know the stream offsets for
- * the seekpoints ahead of time.  You must use the seekable stream encoder
- * to generate a legal seektable
- * (see FLAC__seekable_stream_encoder_set_metadata())
+ * in the \a metadata array, but the client has specified that it does not
+ * support seeking, then the SEEKTABLE will be written verbatim.  However
+ * by itself this is not very useful as the client will not know the stream
+ * offsets for the seekpoints ahead of time.  In order to get a proper
+ * seektable the client must support seeking.  See next note.
+ *
+ * \note
+ * SEEKTABLE blocks are handled specially.  Since you will not know
+ * the values for the seek point stream offsets, you should pass in
+ * a SEEKTABLE 'template', that is, a SEEKTABLE object with the
+ * required sample numbers (or placeholder points), with \c 0 for the
+ * \a frame_samples and \a stream_offset fields for each point.  If the
+ * client has specified that it supports seeking by providing a seek
+ * callback to FLAC__stream_encoder_init_stream() (or by using
+ * FLAC__stream_encoder_init_file() or FLAC__stream_encoder_init_FILE()),
+ * then while it is encoding the encoder will fill the stream offsets in
+ * for you and when encoding is finished, it will seek back and write the
+ * real values into the SEEKTABLE block in the stream.  There are helper
+ * routines for manipulating seektable template blocks; see metadata.h:
+ * FLAC__metadata_object_seektable_template_*().  If the client does
+ * not support seeking, the SEEKTABLE will have inaccurate offsets which
+ * will slow down or remove the ability to seek in the FLAC stream.
+ *
+ * \note
+ * The encoder instance \b will modify the first \c SEEKTABLE block
+ * as it transforms the template to a valid seektable while encoding,
+ * but it is still up to the caller to free all metadata blocks after
+ * encoding.
  *
  * \note
  * A VORBIS_COMMENT block may be supplied.  The vendor string in it
@@ -731,68 +937,6 @@ FLAC_API FLAC__bool FLAC__stream_encoder_set_total_samples_estimate(FLAC__Stream
  */
 FLAC_API FLAC__bool FLAC__stream_encoder_set_metadata(FLAC__StreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
 
-/** Set the write callback.
- *  The supplied function will be called by the encoder anytime there is raw
- *  encoded data ready to write.  It may include metadata mixed with encoded
- *  audio frames and the data is not guaranteed to be aligned on frame or
- *  metadata block boundaries.
- *
- *  The only duty of the callback is to write out the \a bytes worth of data
- *  in \a buffer to the current position in the output stream.  The arguments
- *  \a samples and \a current_frame are purely informational.  If \a samples
- *  is greater than \c 0, then \a current_frame will hold the current frame
- *  number that is being written; otherwise, the write callback is being called
- *  to write metadata.
- *
- * \note
- * The callback is mandatory and must be set before initialization.
- *
- * \default \c NULL
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- *    \code value != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__stream_encoder_set_write_callback(FLAC__StreamEncoder *encoder, FLAC__StreamEncoderWriteCallback value);
-
-/** Set the metadata callback.
- *  The supplied function will be called once at the end of encoding with
- *  the populated STREAMINFO structure.  This is so file encoders can seek
- *  back to the beginning of the file and write the STREAMINFO block with
- *  the correct statistics after encoding (like minimum/maximum frame size
- *  and total samples).
- *
- * \note
- * The callback is mandatory and must be set before initialization.
- *
- * \default \c NULL
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- *    \code value != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__stream_encoder_set_metadata_callback(FLAC__StreamEncoder *encoder, FLAC__StreamEncoderMetadataCallback value);
-
-/** Set the client data to be passed back to callbacks.
- *  This value will be supplied to callbacks in their \a client_data
- *  argument.
- *
- * \default \c NULL
- * \param  encoder  An encoder instance to set.
- * \param  value    See above.
- * \assert
- *    \code encoder != NULL \endcode
- * \retval FLAC__bool
- *    \c false if the encoder is already initialized, else \c true.
- */
-FLAC_API FLAC__bool FLAC__stream_encoder_set_client_data(FLAC__StreamEncoder *encoder, void *value);
-
 /** Get the current encoder state.
  *
  * \param  encoder  An encoder instance to query.
@@ -1021,24 +1165,141 @@ FLAC_API unsigned FLAC__stream_encoder_get_rice_parameter_search_dist(const FLAC
 FLAC_API FLAC__uint64 FLAC__stream_encoder_get_total_samples_estimate(const FLAC__StreamEncoder *encoder);
 
 /** Initialize the encoder instance.
- *  Should be called after FLAC__stream_encoder_new() and
+ *
+ *  This flavor of initialization sets up the encoder to encode to a stream.
+ *  I/O is performed via callbacks to the client.  For encoding to a plain file
+ *  via filename or open \c FILE*, FLAC__stream_encoder_init_file() and
+ *  FLAC__stream_encoder_init_FILE() provide a simpler interface.
+ *
+ *  This function should be called after FLAC__stream_encoder_new() and
  *  FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
- *  or FLAC__stream_encoder_process_interleaved().  Will set and return
- *  the encoder state, which will be FLAC__STREAM_ENCODER_OK if
+ *  or FLAC__stream_encoder_process_interleaved().
  *  initialization succeeded.
  *
- *  The call to FLAC__stream_encoder_init() currently will also immediately
+ *  The call to FLAC__stream_encoder_init_stream() currently will also immediately
  *  call the write callback several times, once with the \c fLaC signature,
  *  and once for each encoded metadata block.
  *
- * \param  encoder  An uninitialized encoder instance.
+ * \param  encoder            An uninitialized encoder instance.
+ * \param  write_callback     See FLAC__StreamEncoderWriteCallback.  This
+ *                            pointer must not be \c NULL.
+ * \param  seek_callback      See FLAC__StreamEncoderSeekCallback.  This
+ *                            pointer may be \c NULL if seeking is not
+ *                            supported.  The encoder uses seeking to go back
+ *                            and write some some stream statistics to the
+ *                            STREAMINFO block; this is recommended but not
+ *                            necessary to create a valid FLAC stream.  If
+ *                            \a seek_callback is not \c NULL then a
+ *                            \a tell_callback must also be supplied.
+ *                            Alternatively, a dummy seek callback that just
+ *                            returns \c FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
+ *                            may also be supplied, all though this is slightly
+ *                            less efficient for the decoder.
+ * \param  tell_callback      See FLAC__StreamEncoderTellCallback.  This
+ *                            pointer may be \c NULL if seeking is not
+ *                            supported.  If \a seek_callback is \c NULL then
+ *                            this argument will be ignored.  If
+ *                            \a seek_callback is not \c NULL then a
+ *                            \a tell_callback must also be supplied.
+ *                            Alternatively, a dummy tell callback that just
+ *                            returns \c FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
+ *                            may also be supplied, all though this is slightly
+ *                            less efficient for the decoder.
+ * \param  metadata_callback  See FLAC__StreamEncoderMetadataCallback.  This
+ *                            pointer may be \c NULL if the callback is not
+ *                            desired.  If the client provides a seek callback,
+ *                            this function is not necessary as the encoder
+ *                            will automatically seek back and update the
+ *                            STREAMINFO block.  It may also be \c NULL if the
+ *                            client does not support seeking, since it will
+ *                            have no way of going back to update the
+ *                            STREAMINFO.  However the client can still supply
+ *                            a callback if it would like to know the details
+ *                            from the STREAMINFO.
+ * \param  client_data        This value will be supplied to callbacks in their
+ *                            \a client_data argument.
  * \assert
  *    \code encoder != NULL \endcode
- * \retval FLAC__StreamEncoderState
- *    \c FLAC__STREAM_ENCODER_OK if initialization was successful; see
- *    FLAC__StreamEncoderState for the meanings of other return values.
+ * \retval FLAC__StreamEncoderInitStatus
+ *    \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
+ *    see FLAC__StreamEncoderInitStatus for the meanings of other return values.
+ */
+FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_stream(FLAC__StreamEncoder *encoder, FLAC__StreamEncoderWriteCallback write_callback, FLAC__StreamEncoderSeekCallback seek_callback, FLAC__StreamEncoderTellCallback tell_callback, FLAC__StreamEncoderMetadataCallback metadata_callback, void *client_data);
+
+/** Initialize the encoder instance.
+ *
+ *  This flavor of initialization sets up the encoder to encode to a plain
+ *  file.  For non-stdio streams, you must use
+ *  FLAC__stream_encoder_init_stream() and provide callbacks for the I/O.
+ *
+ *  This function should be called after FLAC__stream_encoder_new() and
+ *  FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
+ *  or FLAC__stream_encoder_process_interleaved().
+ *  initialization succeeded.
+ *
+ *  The call to FLAC__stream_encoder_init_stream() currently will also immediately
+ *  call the write callback several times, once with the \c fLaC signature,
+ *  and once for each encoded metadata block.
+ *
+ * \param  encoder            An uninitialized encoder instance.
+ * \param  file               An open file.  The file should have been opened
+ *                            with mode \c "w+b" and rewound.  The file
+ *                            becomes owned by the encoder and should not be
+ *                            manipulated by the client while encoding.
+ *                            Unless \a file is \c stdout, it will be closed
+ *                            when FLAC__stream_encoder_finish() is called.
+ *                            Note however that a proper SEEKTABLE cannot be
+ *                            created when encoding to \c stdout since it is
+ *                            not seekable.
+ * \param  progress_callback  See FLAC__StreamEncoderProgressCallback.  This
+ *                            pointer may be \c NULL if the callback is not
+ *                            desired.
+ * \param  client_data        This value will be supplied to callbacks in their
+ *                            \a client_data argument.
+ * \assert
+ *    \code encoder != NULL \endcode
+ *    \code file != NULL \endcode
+ * \retval FLAC__StreamEncoderInitStatus
+ *    \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
+ *    see FLAC__StreamEncoderInitStatus for the meanings of other return values.
+ */
+FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_FILE(FLAC__StreamEncoder *encoder, FILE *file, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
+
+/** Initialize the encoder instance.
+ *
+ *  This flavor of initialization sets up the encoder to encode to a plain
+ *  file.  If POSIX fopen() semantics are not sufficient (for example,
+ *  with Unicode filenames on Windows), you must use
+ *  FLAC__stream_encodeR_init_FILE(), or FLAC__stream_encoder_init_stream()
+ *  and provide callbacks for the I/O.
+ *
+ *  This function should be called after FLAC__stream_encoder_new() and
+ *  FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
+ *  or FLAC__stream_encoder_process_interleaved().
+ *  initialization succeeded.
+ *
+ *  The call to FLAC__stream_encoder_init_stream() currently will also immediately
+ *  call the write callback several times, once with the \c fLaC signature,
+ *  and once for each encoded metadata block.
+ *
+ * \param  encoder            An uninitialized encoder instance.
+ * \param  filename           The name of the file to encode to.  The file will
+ *                            be opened with fopen().  Use \c NULL to encode to
+ *                            \c stdout.  Note however that a proper SEEKTABLE
+ *                            cannot be created when encoding to \c stdout since
+ *                            it is not seekable.
+ * \param  progress_callback  See FLAC__StreamEncoderProgressCallback.  This
+ *                            pointer may be \c NULL if the callback is not
+ *                            desired.
+ * \param  client_data        This value will be supplied to callbacks in their
+ *                            \a client_data argument.
+ * \assert
+ *    \code encoder != NULL \endcode
+ * \retval FLAC__StreamEncoderInitStatus
+ *    \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
+ *    see FLAC__StreamEncoderInitStatus for the meanings of other return values.
  */
-FLAC_API FLAC__StreamEncoderState FLAC__stream_encoder_init(FLAC__StreamEncoder *encoder);
+FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_file(FLAC__StreamEncoder *encoder, const char *filename, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
 
 /** Finish the encoding process.
  *  Flushes the encoding buffer, releases resources, resets the encoder
index d776741..31b7e5f 100644 (file)
@@ -19,4 +19,4 @@ if FLaC__HAS_OGG
 OGGFLAC_DIRS = OggFLAC OggFLAC++
 endif
 
-SUBDIRS = FLAC FLAC++ $(OGGFLAC_DIRS) share
+SUBDIRS = FLAC FLAC++ $(OGGFLAC_DIRS) share test_libs_common
index 0be7bbd..94c6ae5 100644 (file)
@@ -34,8 +34,6 @@
 
 #include "export.h"
 
-#include "OggFLAC/file_decoder.h"
-#include "OggFLAC/seekable_stream_decoder.h"
 #include "OggFLAC/stream_decoder.h"
 // we only need this for the state abstraction really...
 #include "FLAC++/decoder.h"
  *  \ingroup oggflacpp
  *
  *  \brief
- *  This module describes the three decoder layers provided by libOggFLAC++.
+ *  This module describes the decoder layers provided by libOggFLAC++.
  *
  * The libOggFLAC++ decoder classes are object wrappers around their
- * counterparts in libOggFLAC.  All three decoding layers available in
+ * counterparts in libOggFLAC.  All decoding layers available in
  * libOggFLAC are also provided here.  The interface is very similar;
  * make sure to read the \link oggflac_decoder libOggFLAC decoder module \endlink.
  *
- * The only real difference here is that instead of passing in C function
- * pointers for callbacks, you inherit from the decoder class and provide
- * implementations for the callbacks in the derived class; because of this
- * there is no need for a 'client_data' property.
+ * There are only two significant differences here.  First, instead of
+ * passing in C function pointers for callbacks, you inherit from the
+ * decoder class and provide implementations for the callbacks in your
+ * derived class; because of this there is no need for a 'client_data'
+ * property.
+ *
+ * Second, there are two stream decoder classes.  OggFLAC::Decoder::Stream
+ * is used for the same cases that OggFLAC__stream_decoder_init_stream() is
+ * used, and OggFLAC::Decoder::File is used for the same cases that
+ * OggFLAC__stream_decoder_init_FILE() and OggFLAC__stream_decoder_init_file()
+ * are used.
  */
 
 namespace OggFLAC {
        namespace Decoder {
 
-               // ============================================================
-               //
-               //  Equivalent: OggFLAC__StreamDecoder
-               //
-               // ============================================================
-
                /** \defgroup oggflacpp_stream_decoder OggFLAC++/decoder.h: stream decoder class
                 *  \ingroup oggflacpp_decoder
                 *
                 *  \brief
                 *  This class wraps the ::OggFLAC__StreamDecoder.
                 *
-                * See the \link oggflac_stream_decoder libOggFLAC stream decoder module \endlink.
+                * See the \link oggflac_stream_decoder libOggFLAC stream decoder module \endlink
+                * for basic usage.
                 *
                 * \{
                 */
 
-               /** This class wraps the ::OggFLAC__StreamDecoder.
+               /** This class wraps the ::OggFLAC__StreamDecoder.  If you are
+                *  decoding from a file, OggFLAC::Decoder::File may be more
+                *  convenient.
+                *
+                * The usage of this class is similar to OggFLAC__StreamDecoder,
+                * except instead of providing callbacks to
+                * OggFLAC__stream_decoder_init_stream(), you will inherit from this
+                * class and override the virtual callback functions with your
+                * own implementations, then call Stream::init().  The rest of
+                * the calls work the same as in the C layer.
+                *
+                * Only the read, write, and error callbacks are mandatory.  The
+                * others are optional; this class provides default
+                * implementations that do nothing.  In order for seeking to work
+                * you must overide seek_callback(), tell_callback(),
+                * length_callback(), and eof_callback().
                 */
                class OggFLACPP_API Stream {
                public:
@@ -105,245 +120,150 @@ namespace OggFLAC {
                        Stream();
                        virtual ~Stream();
 
+                       /** Call after construction to check the that the object was created
+                        *  successfully.  If not, use get_state() to find out why not.
+                        *
+                        * \{
+                        */
                        bool is_valid() const;
                        inline operator bool() const { return is_valid(); }
-
-                       bool set_serial_number(long value);
-                       bool set_metadata_respond(::FLAC__MetadataType type);
-                       bool set_metadata_respond_application(const FLAC__byte id[4]);
-                       bool set_metadata_respond_all();
-                       bool set_metadata_ignore(::FLAC__MetadataType type);
-                       bool set_metadata_ignore_application(const FLAC__byte id[4]);
-                       bool set_metadata_ignore_all();
-
-                       State get_state() const;
-                       FLAC::Decoder::Stream::State get_FLAC_stream_decoder_state() const;
-                       unsigned get_channels() const;
-                       ::FLAC__ChannelAssignment get_channel_assignment() const;
-                       unsigned get_bits_per_sample() const;
-                       unsigned get_sample_rate() const;
-                       unsigned get_blocksize() const;
+                       /* \} */
+
+                       bool set_serial_number(long value);                            ///< See OggFLAC__stream_decoder_set_serial_number()
+                       bool set_md5_checking(bool value);                             ///< See OggFLAC__stream_decoder_set_md5_checking()
+                       bool set_metadata_respond(::FLAC__MetadataType type);          ///< See OggFLAC__stream_decoder_set_metadata_respond()
+                       bool set_metadata_respond_application(const FLAC__byte id[4]); ///< See OggFLAC__stream_decoder_set_metadata_respond_application()
+                       bool set_metadata_respond_all();                               ///< See OggFLAC__stream_decoder_set_metadata_respond_all()
+                       bool set_metadata_ignore(::FLAC__MetadataType type);           ///< See OggFLAC__stream_decoder_set_metadata_ignore()
+                       bool set_metadata_ignore_application(const FLAC__byte id[4]);  ///< See OggFLAC__stream_decoder_set_metadata_ignore_application()
+                       bool set_metadata_ignore_all();                                ///< See OggFLAC__stream_decoder_set_metadata_ignore_all()
+
+                       State get_state() const;                                  ///< See OggFLAC__stream_decoder_get_state()
+                       FLAC::Decoder::Stream::State get_FLAC_stream_decoder_state() const; ///< See OggFLAC__stream_decoder_get_FLAC_stream_decoder_state()
+                       bool get_md5_checking() const;                            ///< See OggFLAC__stream_decoder_get_md5_checking()
+                       FLAC__uint64 get_total_samples() const;                   ///< See OggFLAC__stream_decoder_get_total_samples()
+                       unsigned get_channels() const;                            ///< See OggFLAC__stream_decoder_get_channels()
+                       ::FLAC__ChannelAssignment get_channel_assignment() const; ///< See OggFLAC__stream_decoder_get_channel_assignment()
+                       unsigned get_bits_per_sample() const;                     ///< See OggFLAC__stream_decoder_get_bits_per_sample()
+                       unsigned get_sample_rate() const;                         ///< See OggFLAC__stream_decoder_get_sample_rate()
+                       unsigned get_blocksize() const;                           ///< See OggFLAC__stream_decoder_get_blocksize()
 
                        /** Initialize the instance; as with the C interface,
                         *  init() should be called after construction and 'set'
                         *  calls but before any of the 'process' calls.
+                        *
+                        *  See OggFLAC__stream_decoder_init_stream().
                         */
-                       State init();
+                       ::FLAC__StreamDecoderInitStatus init();
+
+                       void finish(); ///< See OggFLAC__stream_decoder_finish()
 
-                       void finish();
+                       bool flush(); ///< See OggFLAC__stream_decoder_flush()
+                       bool reset(); ///< See OggFLAC__stream_decoder_reset()
 
-                       bool flush();
-                       bool reset();
+                       bool process_single();                ///< See OggFLAC__stream_decoder_process_single()
+                       bool process_until_end_of_metadata(); ///< See OggFLAC__stream_decoder_process_until_end_of_metadata()
+                       bool process_until_end_of_stream();   ///< See OggFLAC__stream_decoder_process_until_end_of_stream()
+                       bool skip_single_frame();             ///< See OggFLAC__stream_decoder_skip_single_frame()
 
-                       bool process_single();
-                       bool process_until_end_of_metadata();
-                       bool process_until_end_of_stream();
+                       bool seek_absolute(FLAC__uint64 sample); ///< See OggFLAC__stream_decoder_seek_absolute()
                protected:
+                       /// see FLAC__StreamDecoderReadCallback
                        virtual ::FLAC__StreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes) = 0;
-                       virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
-                       virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
-                       virtual void error_callback(::FLAC__StreamDecoderErrorStatus status) = 0;
-
-#if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
-                       // lame hack: some MSVC/GCC versions can't see a protected decoder_ from nested State::resolved_as_cstring()
-                       friend State;
-#endif
-                       ::OggFLAC__StreamDecoder *decoder_;
-               private:
-                       static ::FLAC__StreamDecoderReadStatus read_callback_(const ::OggFLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
-                       static ::FLAC__StreamDecoderWriteStatus write_callback_(const ::OggFLAC__StreamDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
-                       static void metadata_callback_(const ::OggFLAC__StreamDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
-                       static void error_callback_(const ::OggFLAC__StreamDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
-
-                       // Private and undefined so you can't use them:
-                       Stream(const Stream &);
-                       void operator=(const Stream &);
-               };
 
-               /* \} */
+                       /// see FLAC__StreamDecoderSeekCallback
+                       virtual ::FLAC__StreamDecoderSeekStatus seek_callback(FLAC__uint64 absolute_byte_offset);
 
-               // ============================================================
-               //
-               //  Equivalent: OggFLAC__SeekableStreamDecoder
-               //
-               // ============================================================
+                       /// see FLAC__StreamDecoderTellCallback
+                       virtual ::FLAC__StreamDecoderTellStatus tell_callback(FLAC__uint64 *absolute_byte_offset);
 
-               /** \defgroup oggflacpp_seekable_stream_decoder OggFLAC++/decoder.h: seekable stream decoder class
-                *  \ingroup oggflacpp_decoder
-                *
-                *  \brief
-                *  This class wraps the ::OggFLAC__SeekableStreamDecoder.
-                *
-                * See the \link oggflac_seekable_stream_decoder libOggFLAC seekable stream decoder module \endlink.
-                *
-                * \{
-                */
+                       /// see FLAC__StreamDecoderLengthCallback
+                       virtual ::FLAC__StreamDecoderLengthStatus length_callback(FLAC__uint64 *stream_length);
 
-               /** This class wraps the ::OggFLAC__SeekableStreamDecoder.
-                */
-               class OggFLACPP_API SeekableStream {
-               public:
-                       class OggFLACPP_API State {
-                       public:
-                               inline State(::OggFLAC__SeekableStreamDecoderState state): state_(state) { }
-                               inline operator ::OggFLAC__SeekableStreamDecoderState() const { return state_; }
-                               inline const char *as_cstring() const { return ::OggFLAC__SeekableStreamDecoderStateString[state_]; }
-                               inline const char *resolved_as_cstring(const SeekableStream &decoder) const { return ::OggFLAC__seekable_stream_decoder_get_resolved_state_string(decoder.decoder_); }
-                       protected:
-                               ::OggFLAC__SeekableStreamDecoderState state_;
-                       };
+                       /// see FLAC__StreamDecoderEofCallback
+                       virtual bool eof_callback();
 
-                       SeekableStream();
-                       virtual ~SeekableStream();
+                       /// see FLAC__StreamDecoderWriteCallback
+                       virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
 
-                       bool is_valid() const;
-                       inline operator bool() const { return is_valid(); }
+                       /// see FLAC__StreamDecoderMetadataCallback
+                       virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata);
 
-                       bool set_serial_number(long value);
-                       bool set_md5_checking(bool value);
-                       bool set_metadata_respond(::FLAC__MetadataType type);
-                       bool set_metadata_respond_application(const FLAC__byte id[4]);
-                       bool set_metadata_respond_all();
-                       bool set_metadata_ignore(::FLAC__MetadataType type);
-                       bool set_metadata_ignore_application(const FLAC__byte id[4]);
-                       bool set_metadata_ignore_all();
-
-                       State get_state() const;
-                       OggFLAC::Decoder::Stream::State get_stream_decoder_state() const;
-                       FLAC::Decoder::Stream::State get_FLAC_stream_decoder_state() const;
-                       bool get_md5_checking() const;
-                       unsigned get_channels() const;
-                       ::FLAC__ChannelAssignment get_channel_assignment() const;
-                       unsigned get_bits_per_sample() const;
-                       unsigned get_sample_rate() const;
-                       unsigned get_blocksize() const;
-
-                       State init();
-
-                       bool finish();
-
-                       bool flush();
-                       bool reset();
-
-                       bool process_single();
-                       bool process_until_end_of_metadata();
-                       bool process_until_end_of_stream();
-
-                       bool seek_absolute(FLAC__uint64 sample);
-               protected:
-                       virtual ::OggFLAC__SeekableStreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes) = 0;
-                       virtual ::OggFLAC__SeekableStreamDecoderSeekStatus seek_callback(FLAC__uint64 absolute_byte_offset) = 0;
-                       virtual ::OggFLAC__SeekableStreamDecoderTellStatus tell_callback(FLAC__uint64 *absolute_byte_offset) = 0;
-                       virtual ::OggFLAC__SeekableStreamDecoderLengthStatus length_callback(FLAC__uint64 *stream_length) = 0;
-                       virtual bool eof_callback() = 0;
-                       virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
-                       virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
+                       /// see FLAC__StreamDecoderErrorCallback
                        virtual void error_callback(::FLAC__StreamDecoderErrorStatus status) = 0;
 
 #if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
                        // lame hack: some MSVC/GCC versions can't see a protected decoder_ from nested State::resolved_as_cstring()
                        friend State;
 #endif
-                       ::OggFLAC__SeekableStreamDecoder *decoder_;
-               private:
-                       static ::OggFLAC__SeekableStreamDecoderReadStatus read_callback_(const ::OggFLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
-                       static ::OggFLAC__SeekableStreamDecoderSeekStatus seek_callback_(const ::OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
-                       static ::OggFLAC__SeekableStreamDecoderTellStatus tell_callback_(const ::OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
-                       static ::OggFLAC__SeekableStreamDecoderLengthStatus length_callback_(const ::OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
-                       static FLAC__bool eof_callback_(const ::OggFLAC__SeekableStreamDecoder *decoder, void *client_data);
-                       static ::FLAC__StreamDecoderWriteStatus write_callback_(const ::OggFLAC__SeekableStreamDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
-                       static void metadata_callback_(const ::OggFLAC__SeekableStreamDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
-                       static void error_callback_(const ::OggFLAC__SeekableStreamDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
+                       ::OggFLAC__StreamDecoder *decoder_;
 
+                       static ::FLAC__StreamDecoderReadStatus read_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
+                       static ::FLAC__StreamDecoderSeekStatus seek_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
+                       static ::FLAC__StreamDecoderTellStatus tell_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
+                       static ::FLAC__StreamDecoderLengthStatus length_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
+                       static FLAC__bool eof_callback_(const ::FLAC__StreamDecoder *decoder, void *client_data);
+                       static ::FLAC__StreamDecoderWriteStatus write_callback_(const ::FLAC__StreamDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
+                       static void metadata_callback_(const ::FLAC__StreamDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
+                       static void error_callback_(const ::FLAC__StreamDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
+               private:
                        // Private and undefined so you can't use them:
-                       SeekableStream(const SeekableStream &);
-                       void operator=(const SeekableStream &);
+                       Stream(const Stream &);
+                       void operator=(const Stream &);
                };
 
                /* \} */
 
-               // ============================================================
-               //
-               //  Equivalent: OggFLAC__FileDecoder
-               //
-               // ============================================================
-
                /** \defgroup oggflacpp_file_decoder OggFLAC++/decoder.h: file decoder class
                 *  \ingroup oggflacpp_decoder
                 *
                 *  \brief
                 *  This class wraps the ::OggFLAC__FileDecoder.
                 *
-                * See the \link oggflac_file_decoder libOggFLAC file decoder module \endlink.
+                * See the \link oggflac_file_decoder libOggFLAC file decoder module \endlink
+                * for basic usage.
                 *
                 * \{
                 */
 
-               /** This class wraps the ::OggFLAC__FileDecoder.
+               /** This class wraps the ::OggFLAC__StreamDecoder.  If you are
+                *  not decoding from a file, you may need to use
+                *  OggFLAC::Decoder::Stream.
+                *
+                * The usage of this class is similar to OggFLAC__StreamDecoder,
+                * except instead of providing callbacks to
+                * OggFLAC__stream_decoder_init_FILE() or
+                * OggFLAC__stream_decoder_init_file(), you will inherit from this
+                * class and override the virtual callback functions with your
+                * own implementations, then call File::init().  The rest of
+                * the calls work the same as in the C layer.
+                *
+                * Only the write, and error callbacks from OggFLAC::Decoder::Stream
+                * are mandatory.  The others are optional; this class provides
+                * full working implementations for all other callbacks and
+                * supports seeking.
                 */
-               class OggFLACPP_API File {
+               class OggFLACPP_API File: public Stream {
                public:
-                       class OggFLACPP_API State {
-                       public:
-                               inline State(::OggFLAC__FileDecoderState state): state_(state) { }
-                               inline operator ::OggFLAC__FileDecoderState() const { return state_; }
-                               inline const char *as_cstring() const { return ::OggFLAC__FileDecoderStateString[state_]; }
-                               inline const char *resolved_as_cstring(const File &decoder) const { return ::OggFLAC__file_decoder_get_resolved_state_string(decoder.decoder_); }
-                       protected:
-                               ::OggFLAC__FileDecoderState state_;
-                       };
-
                        File();
                        virtual ~File();
 
-                       bool is_valid() const;
-                       inline operator bool() const { return is_valid(); }
-
-                       bool set_serial_number(long value);
-                       bool set_md5_checking(bool value);
-                       bool set_filename(const char *value); //!< 'value' may not be \c NULL; use "-" for stdin
-                       bool set_metadata_respond(::FLAC__MetadataType type);
-                       bool set_metadata_respond_application(const FLAC__byte id[4]);
-                       bool set_metadata_respond_all();
-                       bool set_metadata_ignore(::FLAC__MetadataType type);
-                       bool set_metadata_ignore_application(const FLAC__byte id[4]);
-                       bool set_metadata_ignore_all();
-
-                       State get_state() const;
-                       OggFLAC::Decoder::SeekableStream::State get_seekable_stream_decoder_state() const;
-                       OggFLAC::Decoder::Stream::State get_stream_decoder_state() const;
-                       FLAC::Decoder::Stream::State get_FLAC_stream_decoder_state() const;
-                       bool get_md5_checking() const;
-                       unsigned get_channels() const;
-                       ::FLAC__ChannelAssignment get_channel_assignment() const;
-                       unsigned get_bits_per_sample() const;
-                       unsigned get_sample_rate() const;
-                       unsigned get_blocksize() const;
-
-                       State init();
-
-                       bool finish();
-
-                       bool process_single();
-                       bool process_until_end_of_metadata();
-                       bool process_until_end_of_file();
-
-                       bool seek_absolute(FLAC__uint64 sample);
+                       /** Initialize the instance; as with the C interface,
+                        *  init() should be called after construction and 'set'
+                        *  calls but before any of the 'process' calls.
+                        *
+                        *  See OggFLAC__stream_decoder_init_FILE() and
+                        *  OggFLAC__stream_decoder_init_file().
+                        *  \{
+                        */
+                       ::FLAC__StreamDecoderInitStatus init(FILE *file);
+                       ::FLAC__StreamDecoderInitStatus init(const char *filename);
+                       ::FLAC__StreamDecoderInitStatus init(const std::string &filename);
+                       /*  \} */
                protected:
-                       virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
-                       virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
-                       virtual void error_callback(::FLAC__StreamDecoderErrorStatus status) = 0;
-
-#if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
-                       // lame hack: some MSVC/GCC versions can't see a protected decoder_ from nested State::resolved_as_cstring()
-                       friend State;
-#endif
-                       ::OggFLAC__FileDecoder *decoder_;
+                       // this is a dummy implementation to satisfy the pure virtual in Stream that is actually supplied internally by the C layer
+                       virtual ::FLAC__StreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes);
                private:
-                       static ::FLAC__StreamDecoderWriteStatus write_callback_(const ::OggFLAC__FileDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
-                       static void metadata_callback_(const ::OggFLAC__FileDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
-                       static void error_callback_(const ::OggFLAC__FileDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
-
                        // Private and undefined so you can't use them:
                        File(const File &);
                        void operator=(const File &);
index 0c63937..5231ceb 100644 (file)
@@ -34,8 +34,6 @@
 
 #include "export.h"
 
-#include "OggFLAC/file_encoder.h"
-#include "OggFLAC/seekable_stream_encoder.h"
 #include "OggFLAC/stream_encoder.h"
 #include "decoder.h"
 // we only need these for the state abstractions really...
  *  \ingroup oggflacpp
  *
  *  \brief
- *  This module describes the three encoder layers provided by libOggFLAC++.
+ *  This module describes the encoder layers provided by libOggFLAC++.
  *
  * The libOggFLAC++ encoder classes are object wrappers around their
- * counterparts in libOggFLAC.  All three encoding layers available in
+ * counterparts in libOggFLAC.  All decoding layers available in
  * libOggFLAC are also provided here.  The interface is very similar;
  * make sure to read the \link oggflac_encoder libOggFLAC encoder module \endlink.
  *
- * The only real difference here is that instead of passing in C function
- * pointers for callbacks, you inherit from the encoder class and provide
- * implementations for the callbacks in the derived class; because of this
- * there is no need for a 'client_data' property.
+ * There are only two significant differences here.  First, instead of
+ * passing in C function pointers for callbacks, you inherit from the
+ * encoder class and provide implementations for the callbacks in your
+ * derived class; because of this there is no need for a 'client_data'
+ * property.
+ *
+ * Second, there are two stream encoder classes.  OggFLAC::Encoder::Stream
+ * is used for the same cases that OggFLAC__stream_encoder_init_stream() is
+ * used, and OggFLAC::Encoder::File is used for the same cases that
+ * OggFLAC__stream_encoder_init_FILE() and OggFLAC__stream_encoder_init_file()
+ * are used.
  */
 
 namespace OggFLAC {
        namespace Encoder {
 
-               // ============================================================
-               //
-               //  Equivalent: OggFLAC__StreamEncoder
-               //
-               // ============================================================
-
                /** \defgroup oggflacpp_stream_encoder OggFLAC++/encoder.h: stream encoder class
                 *  \ingroup oggflacpp_encoder
                 *
                 *  \brief
                 *  This class wraps the ::OggFLAC__StreamEncoder.
                 *
-                * See the \link oggflac_stream_encoder libOggFLAC stream encoder module \endlink.
+                * See the \link oggflac_stream_encoder libOggFLAC stream encoder module \endlink
+                * for basic usage.
                 *
                 * \{
                 */
 
-               /** This class wraps the ::OggFLAC__StreamEncoder.
+               /** This class wraps the ::OggFLAC__StreamEncoder.  If you are
+                *  encoding to a file, OggFLAC::Encoder::File may be more
+                *  convenient.
+                *
+                * The usage of this class is similar to OggFLAC__StreamEncoder,
+                * except instead of providing callbacks to