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