merge down from merged-API-layer branch: cvs -q up -dP -j API_LAYER_MERGING_BASELINE -j API_LAYER_MERGING_BRANCH

2 files changed, 268 insertions, 446 deletions

diff --git a/include/FLAC++/decoder.h b/include/FLAC++/decoder.h
index aba733f6..5143311e 100644
--- a/include/FLAC++/decoder.h
+++ b/include/FLAC++/decoder.h
@@ -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"
 
 
@@ -53,40 +52,57 @@
  *  \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 &);
diff --git a/include/FLAC++/encoder.h b/include/FLAC++/encoder.h
index 88768ae6..4e310119 100644
--- a/include/FLAC++/encoder.h
+++ b/include/FLAC++/encoder.h
@@ -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"
@@ -55,40 +53,58 @@
  *  \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 &);