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                                 const char *resolved_as_cstring(const Stream &) const;
  85                         protected:
  86                                 ::FLAC__StreamDecoderState state_;
  87                         };
  88
  89                         Stream();
  90                         virtual ~Stream();
  91
  92                         bool is_valid() const;
  93                         inline operator bool() const { return is_valid(); }
  94
  95                         bool set_metadata_respond(::FLAC__MetadataType type);
  96                         bool set_metadata_respond_application(const FLAC__byte id[4]);
  97                         bool set_metadata_respond_all();
  98                         bool set_metadata_ignore(::FLAC__MetadataType type);
  99                         bool set_metadata_ignore_application(const FLAC__byte id[4]);
 100                         bool set_metadata_ignore_all();
 101
 102                         State get_state() const;
 103                         unsigned get_channels() const;
 104                         ::FLAC__ChannelAssignment get_channel_assignment() const;
 105                         unsigned get_bits_per_sample() const;
 106                         unsigned get_sample_rate() const;
 107                         unsigned get_blocksize() const;
 108
 109                         /** Initialize the instance; as with the C interface,
 110                          *  init() should be called after construction and 'set'
 111                          *  calls but before any of the 'process' calls.
 112                          */
 113                         State init();
 114
 115                         void finish();
 116
 117                         bool flush();
 118                         bool reset();
 119
 120                         bool process_single();
 121                         bool process_until_end_of_metadata();
 122                         bool process_until_end_of_stream();
 123                 protected:
 124                         virtual ::FLAC__StreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes) = 0;
 125                         virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
 126                         virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
 127                         virtual void error_callback(::FLAC__StreamDecoderErrorStatus status) = 0;
 128
 129                         ::FLAC__StreamDecoder *decoder_;
 130                 private:
 131                         static ::FLAC__StreamDecoderReadStatus read_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
 132                         static ::FLAC__StreamDecoderWriteStatus write_callback_(const ::FLAC__StreamDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
 133                         static void metadata_callback_(const ::FLAC__StreamDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
 134                         static void error_callback_(const ::FLAC__StreamDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
 135
 136                         // Private and undefined so you can't use them:
 137                         Stream(const Stream &);
 138                         void operator=(const Stream &);
 139                 };
 140
 141                 /* \} */
 142
 143
 144                 // ============================================================
 145                 //
 146                 //  Equivalent: FLAC__SeekableStreamDecoder
 147                 //
 148                 // ============================================================
 149
 150                 /** \defgroup flacpp_seekable_stream_decoder FLAC++/decoder.h: seekable stream decoder class
 151                  *  \ingroup flacpp_decoder
 152                  *
 153                  *  \brief
 154                  *  This class wraps the ::FLAC__SeekableStreamDecoder.
 155                  *
 156                  * See the \link flac_seekable_stream_decoder libFLAC seekable stream decoder module \endlink.
 157                  *
 158                  * \{
 159                  */
 160
 161                 /** This class wraps the ::FLAC__SeekableStreamDecoder.
 162                  */
 163                 class SeekableStream {
 164                 public:
 165                         class State {
 166                         public:
 167                                 inline State(::FLAC__SeekableStreamDecoderState state): state_(state) { }
 168                                 inline operator ::FLAC__SeekableStreamDecoderState() const { return state_; }
 169                                 inline const char *as_cstring() const { return ::FLAC__SeekableStreamDecoderStateString[state_]; }
 170                                 const char *resolved_as_cstring(const SeekableStream &) const;
 171                         protected:
 172                                 ::FLAC__SeekableStreamDecoderState state_;
 173                         };
 174
 175                         SeekableStream();
 176                         virtual ~SeekableStream();
 177
 178                         bool is_valid() const;
 179                         inline operator bool() const { return is_valid(); }
 180
 181                         bool set_md5_checking(bool value);
 182                         bool set_metadata_respond(::FLAC__MetadataType type);
 183                         bool set_metadata_respond_application(const FLAC__byte id[4]);
 184                         bool set_metadata_respond_all();
 185                         bool set_metadata_ignore(::FLAC__MetadataType type);
 186                         bool set_metadata_ignore_application(const FLAC__byte id[4]);
 187                         bool set_metadata_ignore_all();
 188
 189                         State get_state() const;
 190                         Stream::State get_stream_decoder_state() const;
 191                         bool get_md5_checking() const;
 192                         unsigned get_channels() const;
 193                         ::FLAC__ChannelAssignment get_channel_assignment() const;
 194                         unsigned get_bits_per_sample() const;
 195                         unsigned get_sample_rate() const;
 196                         unsigned get_blocksize() const;
 197
 198                         State init();
 199
 200                         bool finish();
 201
 202                         bool flush();
 203                         bool reset();
 204
 205                         bool process_single();
 206                         bool process_until_end_of_metadata();
 207                         bool process_until_end_of_stream();
 208
 209                         bool seek_absolute(FLAC__uint64 sample);
 210                 protected:
 211                         virtual ::FLAC__SeekableStreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes) = 0;
 212                         virtual ::FLAC__SeekableStreamDecoderSeekStatus seek_callback(FLAC__uint64 absolute_byte_offset) = 0;
 213                         virtual ::FLAC__SeekableStreamDecoderTellStatus tell_callback(FLAC__uint64 *absolute_byte_offset) = 0;
 214                         virtual ::FLAC__SeekableStreamDecoderLengthStatus length_callback(FLAC__uint64 *stream_length) = 0;
 215                         virtual bool eof_callback() = 0;
 216                         virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
 217                         virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
 218                         virtual void error_callback(::FLAC__StreamDecoderErrorStatus status) = 0;
 219
 220                         ::FLAC__SeekableStreamDecoder *decoder_;
 221                 private:
 222                         static ::FLAC__SeekableStreamDecoderReadStatus read_callback_(const ::FLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
 223                         static ::FLAC__SeekableStreamDecoderSeekStatus seek_callback_(const ::FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
 224                         static ::FLAC__SeekableStreamDecoderTellStatus tell_callback_(const ::FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
 225                         static ::FLAC__SeekableStreamDecoderLengthStatus length_callback_(const ::FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
 226                         static FLAC__bool eof_callback_(const ::FLAC__SeekableStreamDecoder *decoder, void *client_data);
 227                         static ::FLAC__StreamDecoderWriteStatus write_callback_(const ::FLAC__SeekableStreamDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
 228                         static void metadata_callback_(const ::FLAC__SeekableStreamDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
 229                         static void error_callback_(const ::FLAC__SeekableStreamDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
 230
 231                         // Private and undefined so you can't use them:
 232                         SeekableStream(const SeekableStream &);
 233                         void operator=(const SeekableStream &);
 234                 };
 235
 236                 /* \} */
 237
 238
 239                 // ============================================================
 240                 //
 241                 //  Equivalent: FLAC__FileDecoder
 242                 //
 243                 // ============================================================
 244
 245                 /** \defgroup flacpp_file_decoder FLAC++/decoder.h: file decoder class
 246                  *  \ingroup flacpp_decoder
 247                  *
 248                  *  \brief
 249                  *  This class wraps the ::FLAC__FileDecoder.
 250                  *
 251                  * See the \link flac_file_decoder libFLAC file decoder module \endlink.
 252                  *
 253                  * \{
 254                  */
 255
 256                 /** This class wraps the ::FLAC__FileDecoder.
 257                  */
 258                 class File {
 259                 public:
 260                         class State {
 261                         public:
 262                                 inline State(::FLAC__FileDecoderState state): state_(state) { }
 263                                 inline operator ::FLAC__FileDecoderState() const { return state_; }
 264                                 inline const char *as_cstring() const { return ::FLAC__FileDecoderStateString[state_]; }
 265                                 const char *resolved_as_cstring(const File &) const;
 266                         protected:
 267                                 ::FLAC__FileDecoderState state_;
 268                         };
 269
 270                         File();
 271                         virtual ~File();
 272
 273                         bool is_valid() const;
 274                         inline operator bool() const { return is_valid(); }
 275
 276                         bool set_md5_checking(bool value);
 277                         bool set_filename(const char *value); //!< 'value' may not be \c NULL; use "-" for stdin
 278                         bool set_metadata_respond(::FLAC__MetadataType type);
 279                         bool set_metadata_respond_application(const FLAC__byte id[4]);
 280                         bool set_metadata_respond_all();
 281                         bool set_metadata_ignore(::FLAC__MetadataType type);
 282                         bool set_metadata_ignore_application(const FLAC__byte id[4]);
 283                         bool set_metadata_ignore_all();
 284
 285                         State get_state() const;
 286                         SeekableStream::State get_seekable_stream_decoder_state() const;
 287                         Stream::State get_stream_decoder_state() const;
 288                         bool get_md5_checking() const;
 289                         unsigned get_channels() const;
 290                         ::FLAC__ChannelAssignment get_channel_assignment() const;
 291                         unsigned get_bits_per_sample() const;
 292                         unsigned get_sample_rate() const;
 293                         unsigned get_blocksize() const;
 294
 295                         State init();
 296
 297                         bool finish();
 298
 299                         bool process_single();
 300                         bool process_until_end_of_metadata();
 301                         bool process_until_end_of_file();
 302
 303                         bool seek_absolute(FLAC__uint64 sample);
 304                 protected:
 305                         virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
 306                         virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
 307                         virtual void error_callback(::FLAC__StreamDecoderErrorStatus status) = 0;
 308
 309                         ::FLAC__FileDecoder *decoder_;
 310                 private:
 311                         static ::FLAC__StreamDecoderWriteStatus write_callback_(const ::FLAC__FileDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
 312                         static void metadata_callback_(const ::FLAC__FileDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
 313                         static void error_callback_(const ::FLAC__FileDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
 314
 315                         // Private and undefined so you can't use them:
 316                         File(const File &);
 317                         void operator=(const File &);
 318                 };
 319
 320                 /* \} */
 321
 322         };
 323 };
 324
 325 #endif