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_single();
 127                         bool process_until_end_of_metadata();
 128                         bool process_until_end_of_stream();
 129                 protected:
 130                         virtual ::FLAC__StreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes) = 0;
 131                         virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
 132                         virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
 133                         virtual void error_callback(::FLAC__StreamDecoderErrorStatus status) = 0;
 134
 135                         ::FLAC__StreamDecoder *decoder_;
 136                 private:
 137                         static ::FLAC__StreamDecoderReadStatus read_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
 138                         static ::FLAC__StreamDecoderWriteStatus write_callback_(const ::FLAC__StreamDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
 139                         static void metadata_callback_(const ::FLAC__StreamDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
 140                         static void error_callback_(const ::FLAC__StreamDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
 141
 142                         // Private and undefined so you can't use them:
 143                         Stream(const Stream &);
 144                         void operator=(const Stream &);
 145                 };
 146
 147                 /* \} */
 148
 149
 150                 // ============================================================
 151                 //
 152                 //  Equivalent: FLAC__SeekableStreamDecoder
 153                 //
 154                 // ============================================================
 155
 156                 /** \defgroup flacpp_seekable_stream_decoder FLAC++/decoder.h: seekable stream decoder class
 157                  *  \ingroup flacpp_decoder
 158                  *
 159                  *  \brief
 160                  *  Brief XXX.
 161                  *
 162                  * Detailed seekable stream decoder XXX.
 163                  * \{
 164                  */
 165
 166                 /** seekable stream decoder XXX.
 167                  */
 168                 class SeekableStream {
 169                 public:
 170                         class State {
 171                         public:
 172                                 inline State(::FLAC__SeekableStreamDecoderState state): state_(state) { }
 173                                 inline operator ::FLAC__SeekableStreamDecoderState() const { return state_; }
 174                                 inline const char *as_cstring() const { return ::FLAC__SeekableStreamDecoderStateString[state_]; }
 175                         protected:
 176                                 ::FLAC__SeekableStreamDecoderState state_;
 177                         };
 178
 179                         SeekableStream();
 180                         virtual ~SeekableStream();
 181
 182                         bool is_valid() const;
 183                         inline operator bool() const { return is_valid(); }
 184
 185                         bool set_md5_checking(bool value);
 186                         bool set_metadata_respond(::FLAC__MetadataType type);
 187                         bool set_metadata_respond_application(const FLAC__byte id[4]);
 188                         bool set_metadata_respond_all();
 189                         bool set_metadata_ignore(::FLAC__MetadataType type);
 190                         bool set_metadata_ignore_application(const FLAC__byte id[4]);
 191                         bool set_metadata_ignore_all();
 192
 193                         State get_state() const;
 194                         Stream::State get_stream_decoder_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_single();
 210                         bool process_until_end_of_metadata();
 211                         bool process_until_end_of_stream();
 212
 213                         bool seek_absolute(FLAC__uint64 sample);
 214                 protected:
 215                         virtual ::FLAC__SeekableStreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes) = 0;
 216                         virtual ::FLAC__SeekableStreamDecoderSeekStatus seek_callback(FLAC__uint64 absolute_byte_offset) = 0;
 217                         virtual ::FLAC__SeekableStreamDecoderTellStatus tell_callback(FLAC__uint64 *absolute_byte_offset) = 0;
 218                         virtual ::FLAC__SeekableStreamDecoderLengthStatus length_callback(FLAC__uint64 *stream_length) = 0;
 219                         virtual bool eof_callback() = 0;
 220                         virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
 221                         virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
 222                         virtual void error_callback(::FLAC__StreamDecoderErrorStatus status) = 0;
 223
 224                         ::FLAC__SeekableStreamDecoder *decoder_;
 225                 private:
 226                         static FLAC__SeekableStreamDecoderReadStatus read_callback_(const ::FLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
 227                         static FLAC__SeekableStreamDecoderSeekStatus seek_callback_(const ::FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
 228                         static FLAC__SeekableStreamDecoderTellStatus tell_callback_(const ::FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
 229                         static FLAC__SeekableStreamDecoderLengthStatus length_callback_(const ::FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
 230                         static FLAC__bool eof_callback_(const ::FLAC__SeekableStreamDecoder *decoder, void *client_data);
 231                         static FLAC__StreamDecoderWriteStatus write_callback_(const ::FLAC__SeekableStreamDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
 232                         static void metadata_callback_(const ::FLAC__SeekableStreamDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
 233                         static void error_callback_(const ::FLAC__SeekableStreamDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
 234
 235                         // Private and undefined so you can't use them:
 236                         SeekableStream(const SeekableStream &);
 237                         void operator=(const SeekableStream &);
 238                 };
 239
 240                 /* \} */
 241
 242
 243                 // ============================================================
 244                 //
 245                 //  Equivalent: FLAC__FileDecoder
 246                 //
 247                 // ============================================================
 248
 249                 /** \defgroup flacpp_file_decoder FLAC++/decoder.h: file decoder class
 250                  *  \ingroup flacpp_decoder
 251                  *
 252                  *  \brief
 253                  *  Brief XXX.
 254                  *
 255                  * Detailed file decoder XXX.
 256                  * \{
 257                  */
 258
 259                 /** file decoder XXX.
 260                  */
 261                 class File {
 262                 public:
 263                         class State {
 264                         public:
 265                                 inline State(::FLAC__FileDecoderState state): state_(state) { }
 266                                 inline operator ::FLAC__FileDecoderState() const { return state_; }
 267                                 inline const char *as_cstring() const { return ::FLAC__FileDecoderStateString[state_]; }
 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 0; 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