1 /* libFLAC++ - Free Lossless Audio Codec library
2 * Copyright (C) 2002,2003,2004,2005,2006 Josh Coalson
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
8 * - Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
11 * - Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
15 * - Neither the name of the Xiph.org Foundation nor the names of its
16 * contributors may be used to endorse or promote products derived from
17 * this software without specific prior written permission.
19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR
23 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
24 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
25 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
26 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
27 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
28 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
29 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 #ifndef FLACPP__DECODER_H
33 #define FLACPP__DECODER_H
38 #include "FLAC/stream_decoder.h"
41 /** \file include/FLAC++/decoder.h
44 * This module contains the classes which implement the various
47 * See the detailed documentation in the
48 * \link flacpp_decoder decoder \endlink module.
51 /** \defgroup flacpp_decoder FLAC++/decoder.h: decoder classes
55 * This module describes the decoder layers provided by libFLAC++.
57 * The libFLAC++ decoder classes are object wrappers around their
58 * counterparts in libFLAC. All decoding layers available in
59 * libFLAC are also provided here. The interface is very similar;
60 * make sure to read the \link flac_decoder libFLAC decoder module \endlink.
62 * There are only two significant differences here. First, instead of
63 * passing in C function pointers for callbacks, you inherit from the
64 * decoder class and provide implementations for the callbacks in your
65 * derived class; because of this there is no need for a 'client_data'
68 * Second, there are two stream decoder classes. FLAC::Decoder::Stream
69 * is used for the same cases that FLAC__stream_decoder_init_stream() is
70 * used, and FLAC::Decoder::File is used for the same cases that
71 * FLAC__stream_decoder_init_FILE() and FLAC__stream_decoder_init_file()
78 /** \defgroup flacpp_stream_decoder FLAC++/decoder.h: stream decoder class
79 * \ingroup flacpp_decoder
82 * This class wraps the ::FLAC__StreamDecoder.
84 * See the \link flac_stream_decoder libFLAC stream decoder module \endlink
90 /** This class wraps the ::FLAC__StreamDecoder. If you are
91 * decoding from a file, FLAC::Decoder::File may be more
94 * The usage of this class is similar to FLAC__StreamDecoder,
95 * except instead of providing callbacks to
96 * FLAC__stream_decoder_init_stream(), you will inherit from this
97 * class and override the virtual callback functions with your
98 * own implementations, then call Stream::init(). The rest of
99 * the calls work the same as in the C layer.
101 * Only the read, write, and error callbacks are mandatory. The
102 * others are optional; this class provides default
103 * implementations that do nothing. In order for seeking to work
104 * you must overide seek_callback(), tell_callback(),
105 * length_callback(), and eof_callback().
107 class FLACPP_API Stream {
109 /** This class is a wrapper around FLAC__StreamDecoderState.
111 class FLACPP_API State {
113 inline State(::FLAC__StreamDecoderState state): state_(state) { }
114 inline operator ::FLAC__StreamDecoderState() const { return state_; }
115 inline const char *as_cstring() const { return ::FLAC__StreamDecoderStateString[state_]; }
116 inline const char *resolved_as_cstring(const Stream &decoder) const { return ::FLAC__stream_decoder_get_resolved_state_string(decoder.decoder_); }
118 ::FLAC__StreamDecoderState state_;
125 /** Call after construction to check the that the object was created
126 * successfully. If not, use get_state() to find out why not.
128 virtual bool is_valid() const;
129 inline operator bool() const { return is_valid(); }
132 virtual bool set_md5_checking(bool value); ///< See FLAC__stream_decoder_set_md5_checking()
133 virtual bool set_metadata_respond(::FLAC__MetadataType type); ///< See FLAC__stream_decoder_set_metadata_respond()
134 virtual bool set_metadata_respond_application(const FLAC__byte id[4]); ///< See FLAC__stream_decoder_set_metadata_respond_application()
135 virtual bool set_metadata_respond_all(); ///< See FLAC__stream_decoder_set_metadata_respond_all()
136 virtual bool set_metadata_ignore(::FLAC__MetadataType type); ///< See FLAC__stream_decoder_set_metadata_ignore()
137 virtual bool set_metadata_ignore_application(const FLAC__byte id[4]); ///< See FLAC__stream_decoder_set_metadata_ignore_application()
138 virtual bool set_metadata_ignore_all(); ///< See FLAC__stream_decoder_set_metadata_ignore_all()
140 /* get_state() is not virtual since we want subclasses to be able to return their own state */
141 State get_state() const; ///< See FLAC__stream_decoder_get_state()
142 virtual bool get_md5_checking() const; ///< See FLAC__stream_decoder_get_md5_checking()
143 virtual FLAC__uint64 get_total_samples() const; ///< See FLAC__stream_decoder_get_total_samples()
144 virtual unsigned get_channels() const; ///< See FLAC__stream_decoder_get_channels()
145 virtual ::FLAC__ChannelAssignment get_channel_assignment() const; ///< See FLAC__stream_decoder_get_channel_assignment()
146 virtual unsigned get_bits_per_sample() const; ///< See FLAC__stream_decoder_get_bits_per_sample()
147 virtual unsigned get_sample_rate() const; ///< See FLAC__stream_decoder_get_sample_rate()
148 virtual unsigned get_blocksize() const; ///< See FLAC__stream_decoder_get_blocksize()
150 /** Initialize the instance; as with the C interface,
151 * init() should be called after construction and 'set'
152 * calls but before any of the 'process' calls.
154 * See FLAC__stream_decoder_init_stream().
156 virtual ::FLAC__StreamDecoderInitStatus init();
158 virtual void finish(); ///< See FLAC__stream_decoder_finish()
160 virtual bool flush(); ///< See FLAC__stream_decoder_flush()
161 virtual bool reset(); ///< See FLAC__stream_decoder_reset()
163 virtual bool process_single(); ///< See FLAC__stream_decoder_process_single()
164 virtual bool process_until_end_of_metadata(); ///< See FLAC__stream_decoder_process_until_end_of_metadata()
165 virtual bool process_until_end_of_stream(); ///< See FLAC__stream_decoder_process_until_end_of_stream()
166 virtual bool skip_single_frame(); ///< See FLAC__stream_decoder_skip_single_frame()
168 virtual bool seek_absolute(FLAC__uint64 sample); ///< See FLAC__stream_decoder_seek_absolute()
170 /// see FLAC__StreamDecoderReadCallback
171 virtual ::FLAC__StreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes) = 0;
173 /// see FLAC__StreamDecoderSeekCallback
174 virtual ::FLAC__StreamDecoderSeekStatus seek_callback(FLAC__uint64 absolute_byte_offset);
176 /// see FLAC__StreamDecoderTellCallback
177 virtual ::FLAC__StreamDecoderTellStatus tell_callback(FLAC__uint64 *absolute_byte_offset);
179 /// see FLAC__StreamDecoderLengthCallback
180 virtual ::FLAC__StreamDecoderLengthStatus length_callback(FLAC__uint64 *stream_length);
182 /// see FLAC__StreamDecoderEofCallback
183 virtual bool eof_callback();
185 /// see FLAC__StreamDecoderWriteCallback
186 virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
188 /// see FLAC__StreamDecoderMetadataCallback
189 virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata);
191 /// see FLAC__StreamDecoderErrorCallback
192 virtual void error_callback(::FLAC__StreamDecoderErrorStatus status) = 0;
194 #if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
195 // lame hack: some MSVC/GCC versions can't see a protected decoder_ from nested State::resolved_as_cstring()
198 // hackery solely for the use of libOggFLAC++
199 Stream(::FLAC__StreamDecoder *);
201 ::FLAC__StreamDecoder *decoder_;
203 static ::FLAC__StreamDecoderReadStatus read_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
204 static ::FLAC__StreamDecoderSeekStatus seek_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
205 static ::FLAC__StreamDecoderTellStatus tell_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
206 static ::FLAC__StreamDecoderLengthStatus length_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
207 static FLAC__bool eof_callback_(const ::FLAC__StreamDecoder *decoder, void *client_data);
208 static ::FLAC__StreamDecoderWriteStatus write_callback_(const ::FLAC__StreamDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
209 static void metadata_callback_(const ::FLAC__StreamDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
210 static void error_callback_(const ::FLAC__StreamDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
212 // Private and undefined so you can't use them:
213 Stream(const Stream &);
214 void operator=(const Stream &);
219 /** \defgroup flacpp_file_decoder FLAC++/decoder.h: file decoder class
220 * \ingroup flacpp_decoder
223 * This class wraps the ::FLAC__StreamDecoder.
225 * See the \link flac_stream_decoder libFLAC stream decoder module \endlink
231 /** This class wraps the ::FLAC__StreamDecoder. If you are
232 * not decoding from a file, you may need to use
233 * FLAC::Decoder::Stream.
235 * The usage of this class is similar to FLAC__StreamDecoder,
236 * except instead of providing callbacks to
237 * FLAC__stream_decoder_init_FILE() or
238 * FLAC__stream_decoder_init_file(), you will inherit from this
239 * class and override the virtual callback functions with your
240 * own implementations, then call File::init(). The rest of
241 * the calls work the same as in the C layer.
243 * Only the write, and error callbacks from FLAC::Decoder::Stream
244 * are mandatory. The others are optional; this class provides
245 * full working implementations for all other callbacks and
248 class FLACPP_API File: public Stream {
254 /** Initialize the instance; as with the C interface,
255 * init() should be called after construction and 'set'
256 * calls but before any of the 'process' calls.
258 * See FLAC__stream_decoder_init_FILE() and
259 * FLAC__stream_decoder_init_file().
261 ::FLAC__StreamDecoderInitStatus init(FILE *file);
262 ::FLAC__StreamDecoderInitStatus init(const char *filename);
263 ::FLAC__StreamDecoderInitStatus init(const std::string &filename);
266 // this is a dummy implementation to satisfy the pure virtual in Stream that is actually supplied internally by the C layer
267 virtual ::FLAC__StreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes);
269 // Private and undefined so you can't use them:
271 void operator=(const File &);