include/FLAC++/decoder.h

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