include/FLAC++/decoder.h

   1 /* libFLAC++ - Free Lossless Audio Codec library
   2  * Copyright (C) 2002  Josh Coalson
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA  02111-1307, USA.
  18  */
  19
  20 #ifndef FLACPP__DECODER_H
  21 #define FLACPP__DECODER_H
  22
  23 #include "FLAC/file_decoder.h"
  24 #include "FLAC/seekable_stream_decoder.h"
  25 #include "FLAC/stream_decoder.h"
  26
  27
  28 /** \file include/FLAC++/decoder.h
  29  *
  30  *  \brief
  31  *  This module contains the classes which implement the various
  32  *  decoders.
  33  *
  34  *  See the detailed documentation in the
  35  *  \link flacpp_decoder decoder \endlink module.
  36  */
  37
  38 /** \defgroup flacpp_decoder FLAC++/decoder.h: decoder classes
  39  *  \ingroup flacpp
  40  *
  41  *  \brief
  42  *  This module describes the three decoder layers provided by libFLAC++.
  43  *
  44  * The libFLAC++ decoder classes are object wrappers around their
  45  * counterparts in libFLAC.  All three decoding layers available in
  46  * libFLAC are also provided here.  The interface is very similar;
  47  * make sure to read the \link flac_decoder libFLAC decoder module \endlink.
  48  *
  49  * The only real difference here is that instead of passing in C function
  50  * pointers for callbacks, you inherit from the decoder class and provide
  51  * implementations for the callbacks in the derived class; because of this
  52  * there is no need for a 'client_data' property.
  53  */
  54
  55 namespace FLAC {
  56         namespace Decoder {
  57
  58                 // ============================================================
  59                 //
  60                 //  Equivalent: FLAC__StreamDecoder
  61                 //
  62                 // ============================================================
  63
  64                 /** \defgroup flacpp_stream_decoder FLAC++/decoder.h: stream decoder class
  65                  *  \ingroup flacpp_decoder
  66                  *
  67                  *  \brief
  68                  *  This class wraps the ::FLAC__StreamDecoder.
  69                  *
  70                  * See the \link flac_stream_decoder libFLAC stream decoder module \endlink.
  71                  *
  72                  * \{
  73                  */
  74
  75                 /** This class wraps the ::FLAC__StreamDecoder.
  76                  */
  77                 class Stream {
  78                 public:
  79                         class State {
  80                         public:
  81                                 inline State(::FLAC__StreamDecoderState state): state_(state) { }
  82                                 inline operator ::FLAC__StreamDecoderState() const { return state_; }
  83                                 inline const char *as_cstring() const { return ::FLAC__StreamDecoderStateString[state_]; }
  84                         protected:
  85                                 ::FLAC__StreamDecoderState state_;
  86                         };
  87
  88                         Stream();
  89                         virtual ~Stream();
  90
  91                         bool is_valid() const;
  92                         inline operator bool() const { return is_valid(); }
  93
  94                         bool set_metadata_respond(::FLAC__MetadataType type);
  95                         bool set_metadata_respond_application(const FLAC__byte id[4]);
  96                         bool set_metadata_respond_all();
  97                         bool set_metadata_ignore(::FLAC__MetadataType type);
  98                         bool set_metadata_ignore_application(const FLAC__byte id[4]);
  99                         bool set_metadata_ignore_all();
 100
 101                         State get_state() const;
 102                         unsigned get_channels() const;
 103                         ::FLAC__ChannelAssignment get_channel_assignment() const;
 104                         unsigned get_bits_per_sample() const;
 105                         unsigned get_sample_rate() const;
 106                         unsigned get_blocksize() const;
 107
 108                         /** Initialize the instance; as with the C interface,
 109                          *  init() should be called after construction and 'set'
 110                          *  calls but before any of the 'process' calls.
 111                          */
 112                         State init();
 113
 114                         void finish();
 115
 116                         bool flush();
 117                         bool reset();
 118
 119                         bool process_single();
 120                         bool process_until_end_of_metadata();
 121                         bool process_until_end_of_stream();
 122                 protected:
 123                         virtual ::FLAC__StreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes) = 0;
 124                         virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
 125                         virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
 126                         virtual void error_callback(::FLAC__StreamDecoderErrorStatus status) = 0;
 127
 128                         ::FLAC__StreamDecoder *decoder_;
 129                 private:
 130                         static ::FLAC__StreamDecoderReadStatus read_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
 131                         static ::FLAC__StreamDecoderWriteStatus write_callback_(const ::FLAC__StreamDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
 132                         static void metadata_callback_(const ::FLAC__StreamDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
 133                         static void error_callback_(const ::FLAC__StreamDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
 134
 135                         // Private and undefined so you can't use them:
 136                         Stream(const Stream &);
 137                         void operator=(const Stream &);
 138                 };
 139
 140                 /* \} */
 141
 142
 143                 // ============================================================
 144                 //
 145                 //  Equivalent: FLAC__SeekableStreamDecoder
 146                 //
 147                 // ============================================================
 148
 149                 /** \defgroup flacpp_seekable_stream_decoder FLAC++/decoder.h: seekable stream decoder class
 150                  *  \ingroup flacpp_decoder
 151                  *
 152                  *  \brief
 153                  *  This class wraps the ::FLAC__SeekableStreamDecoder.
 154                  *
 155                  * See the \link flac_seekable_stream_decoder libFLAC seekable stream decoder module \endlink.
 156                  *
 157                  * \{
 158                  */
 159
 160                 /** This class wraps the ::FLAC__SeekableStreamDecoder.
 161                  */
 162                 class SeekableStream {
 163                 public:
 164                         class State {
 165                         public:
 166                                 inline State(::FLAC__SeekableStreamDecoderState state): state_(state) { }
 167                                 inline operator ::FLAC__SeekableStreamDecoderState() const { return state_; }
 168                                 inline const char *as_cstring() const { return ::FLAC__SeekableStreamDecoderStateString[state_]; }
 169                         protected:
 170                                 ::FLAC__SeekableStreamDecoderState state_;
 171                         };
 172
 173                         SeekableStream();
 174                         virtual ~SeekableStream();
 175
 176                         bool is_valid() const;
 177                         inline operator bool() const { return is_valid(); }
 178
 179                         bool set_md5_checking(bool value);
 180                         bool set_metadata_respond(::FLAC__MetadataType type);
 181                         bool set_metadata_respond_application(const FLAC__byte id[4]);
 182                         bool set_metadata_respond_all();
 183                         bool set_metadata_ignore(::FLAC__MetadataType type);
 184                         bool set_metadata_ignore_application(const FLAC__byte id[4]);
 185                         bool set_metadata_ignore_all();
 186
 187                         State get_state() const;
 188                         Stream::State get_stream_decoder_state() const;
 189                         bool get_md5_checking() const;
 190                         unsigned get_channels() const;
 191                         ::FLAC__ChannelAssignment get_channel_assignment() const;
 192                         unsigned get_bits_per_sample() const;
 193                         unsigned get_sample_rate() const;
 194                         unsigned get_blocksize() const;
 195
 196                         State init();
 197
 198                         bool finish();
 199
 200                         bool flush();
 201                         bool reset();
 202
 203                         bool process_single();
 204                         bool process_until_end_of_metadata();
 205                         bool process_until_end_of_stream();
 206
 207                         bool seek_absolute(FLAC__uint64 sample);
 208                 protected:
 209                         virtual ::FLAC__SeekableStreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes) = 0;
 210                         virtual ::FLAC__SeekableStreamDecoderSeekStatus seek_callback(FLAC__uint64 absolute_byte_offset) = 0;
 211                         virtual ::FLAC__SeekableStreamDecoderTellStatus tell_callback(FLAC__uint64 *absolute_byte_offset) = 0;
 212                         virtual ::FLAC__SeekableStreamDecoderLengthStatus length_callback(FLAC__uint64 *stream_length) = 0;
 213                         virtual bool eof_callback() = 0;
 214                         virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
 215                         virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
 216                         virtual void error_callback(::FLAC__StreamDecoderErrorStatus status) = 0;
 217
 218                         ::FLAC__SeekableStreamDecoder *decoder_;
 219                 private:
 220                         static FLAC__SeekableStreamDecoderReadStatus read_callback_(const ::FLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
 221                         static FLAC__SeekableStreamDecoderSeekStatus seek_callback_(const ::FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
 222                         static FLAC__SeekableStreamDecoderTellStatus tell_callback_(const ::FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
 223                         static FLAC__SeekableStreamDecoderLengthStatus length_callback_(const ::FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
 224                         static FLAC__bool eof_callback_(const ::FLAC__SeekableStreamDecoder *decoder, void *client_data);
 225                         static FLAC__StreamDecoderWriteStatus write_callback_(const ::FLAC__SeekableStreamDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
 226                         static void metadata_callback_(const ::FLAC__SeekableStreamDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
 227                         static void error_callback_(const ::FLAC__SeekableStreamDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
 228
 229                         // Private and undefined so you can't use them:
 230                         SeekableStream(const SeekableStream &);
 231                         void operator=(const SeekableStream &);
 232                 };
 233
 234                 /* \} */
 235
 236
 237                 // ============================================================
 238                 //
 239                 //  Equivalent: FLAC__FileDecoder
 240                 //
 241                 // ============================================================
 242
 243                 /** \defgroup flacpp_file_decoder FLAC++/decoder.h: file decoder class
 244                  *  \ingroup flacpp_decoder
 245                  *
 246                  *  \brief
 247                  *  This class wraps the ::FLAC__FileDecoder.
 248                  *
 249                  * See the \link flac_file_decoder libFLAC file decoder module \endlink.
 250                  *
 251                  * \{
 252                  */
 253
 254                 /** This class wraps the ::FLAC__FileDecoder.
 255                  */
 256                 class File {
 257                 public:
 258                         class State {
 259                         public:
 260                                 inline State(::FLAC__FileDecoderState state): state_(state) { }
 261                                 inline operator ::FLAC__FileDecoderState() const { return state_; }
 262                                 inline const char *as_cstring() const { return ::FLAC__FileDecoderStateString[state_]; }
 263                         protected:
 264                                 ::FLAC__FileDecoderState state_;
 265                         };
 266
 267                         File();
 268                         virtual ~File();
 269
 270                         bool is_valid() const;
 271                         inline operator bool() const { return is_valid(); }
 272
 273                         bool set_md5_checking(bool value);
 274                         bool set_filename(const char *value); //!< 'value' may not be \c NULL; use "-" for stdin
 275                         bool set_metadata_respond(::FLAC__MetadataType type);
 276                         bool set_metadata_respond_application(const FLAC__byte id[4]);
 277                         bool set_metadata_respond_all();
 278                         bool set_metadata_ignore(::FLAC__MetadataType type);
 279                         bool set_metadata_ignore_application(const FLAC__byte id[4]);
 280                         bool set_metadata_ignore_all();
 281
 282                         State get_state() const;
 283                         SeekableStream::State get_seekable_stream_decoder_state() const;
 284                         Stream::State get_stream_decoder_state() const;
 285                         bool get_md5_checking() const;
 286                         unsigned get_channels() const;
 287                         ::FLAC__ChannelAssignment get_channel_assignment() const;
 288                         unsigned get_bits_per_sample() const;
 289                         unsigned get_sample_rate() const;
 290                         unsigned get_blocksize() const;
 291
 292                         State init();
 293
 294                         bool finish();
 295
 296                         bool process_single();
 297                         bool process_until_end_of_metadata();
 298                         bool process_until_end_of_file();
 299
 300                         bool seek_absolute(FLAC__uint64 sample);
 301                 protected:
 302                         virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
 303                         virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
 304                         virtual void error_callback(::FLAC__StreamDecoderErrorStatus status) = 0;
 305
 306                         ::FLAC__FileDecoder *decoder_;
 307                 private:
 308                         static ::FLAC__StreamDecoderWriteStatus write_callback_(const ::FLAC__FileDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
 309                         static void metadata_callback_(const ::FLAC__FileDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
 310                         static void error_callback_(const ::FLAC__FileDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
 311
 312                         // Private and undefined so you can't use them:
 313                         File(const File &);
 314                         void operator=(const File &);
 315                 };
 316
 317                 /* \} */
 318
 319         };
 320 };
 321
 322 #endif