include/FLAC/seekable_stream_decoder.h

   1 /* libFLAC - Free Lossless Audio Codec library
   2  * Copyright (C) 2000,2001,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 FLAC__SEEKABLE_STREAM_DECODER_H
  21 #define FLAC__SEEKABLE_STREAM_DECODER_H
  22
  23 #include "stream_decoder.h"
  24
  25 typedef enum {
  26     FLAC__SEEKABLE_STREAM_DECODER_OK = 0,
  27         FLAC__SEEKABLE_STREAM_DECODER_SEEKING,
  28         FLAC__SEEKABLE_STREAM_DECODER_END_OF_STREAM,
  29         FLAC__SEEKABLE_STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
  30         FLAC__SEEKABLE_STREAM_DECODER_STREAM_ERROR,
  31         FLAC__SEEKABLE_STREAM_DECODER_READ_ERROR,
  32         FLAC__SEEKABLE_STREAM_DECODER_SEEK_ERROR,
  33     FLAC__SEEKABLE_STREAM_DECODER_ALREADY_INITIALIZED,
  34     FLAC__SEEKABLE_STREAM_DECODER_INVALID_CALLBACK,
  35     FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED
  36 } FLAC__SeekableStreamDecoderState;
  37 extern const char *FLAC__SeekableStreamDecoderStateString[];
  38
  39 typedef enum {
  40         FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_OK,
  41         FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_ERROR
  42 } FLAC__SeekableStreamDecoderReadStatus;
  43 extern const char *FLAC__SeekableStreamDecoderReadStatusString[];
  44
  45 typedef enum {
  46         FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_OK,
  47         FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_ERROR
  48 } FLAC__SeekableStreamDecoderSeekStatus;
  49 extern const char *FLAC__SeekableStreamDecoderSeekStatusString[];
  50
  51 typedef enum {
  52         FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_OK,
  53         FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_ERROR
  54 } FLAC__SeekableStreamDecoderTellStatus;
  55 extern const char *FLAC__SeekableStreamDecoderTellStatusString[];
  56
  57 typedef enum {
  58         FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_OK,
  59         FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_ERROR
  60 } FLAC__SeekableStreamDecoderLengthStatus;
  61 extern const char *FLAC__SeekableStreamDecoderLengthStatusString[];
  62
  63 /***********************************************************************
  64  *
  65  * class FLAC__SeekableStreamDecoder : public FLAC__StreamDecoder
  66  *
  67  ***********************************************************************/
  68
  69 struct FLAC__SeekableStreamDecoderProtected;
  70 struct FLAC__SeekableStreamDecoderPrivate;
  71 typedef struct {
  72         struct FLAC__SeekableStreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
  73         struct FLAC__SeekableStreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
  74 } FLAC__SeekableStreamDecoder;
  75
  76 /***********************************************************************
  77  *
  78  * Class constructor/destructor
  79  *
  80  ***********************************************************************/
  81
  82 /*
  83  * Any parameters that are not set before FLAC__seekable_stream_decoder_init()
  84  * will take on the defaults from the constructor, shown below.
  85  * For more on what the parameters mean, see the documentation.
  86  *
  87  * FLAC__bool  md5_checking                   (DEFAULT: false) MD5 checking will be turned off if a seek is requested
  88  *           (*read_callback)()               (DEFAULT: NULL ) The callbacks are the only values that MUST be set before FLAC__seekable_stream_decoder_init()
  89  *           (*seek_callback)()               (DEFAULT: NULL )
  90  *           (*tell_callback)()               (DEFAULT: NULL )
  91  *           (*length_callback)()             (DEFAULT: NULL )
  92  *           (*eof_callback)()                (DEFAULT: NULL )
  93  *           (*write_callback)()              (DEFAULT: NULL )
  94  *           (*metadata_callback)()           (DEFAULT: NULL )
  95  *           (*error_callback)()              (DEFAULT: NULL )
  96  * void*       client_data                    (DEFAULT: NULL ) passed back through the callbacks
  97  */
  98 FLAC__SeekableStreamDecoder *FLAC__seekable_stream_decoder_new();
  99 void FLAC__seekable_stream_decoder_delete(FLAC__SeekableStreamDecoder *);
 100
 101 /***********************************************************************
 102  *
 103  * Public class method prototypes
 104  *
 105  ***********************************************************************/
 106
 107 /*
 108  * Various "set" methods.  These may only be called when the decoder
 109  * is in the state FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED, i.e. after
 110  * FLAC__seekable_stream_decoder_new() or FLAC__seekable_stream_decoder_finish(),
 111  * but before FLAC__seekable_stream_decoder_init().  If this is the case they
 112  * will return true, otherwise false.
 113  *
 114  * NOTE that these functions do not validate the values as many are
 115  * interdependent.  The FLAC__seekable_stream_decoder_init() function will
 116  * do this, so make sure to pay attention to the state returned by
 117  * FLAC__seekable_stream_decoder_init().
 118  *
 119  * Any parameters that are not set before FLAC__seekable_stream_decoder_init()
 120  * will take on the defaults from the constructor.  NOTE that
 121  * FLAC__seekable_stream_decoder_flush() or FLAC__seekable_stream_decoder_reset()
 122  * do NOT reset the values to the constructor defaults.
 123  */
 124 FLAC__bool FLAC__seekable_stream_decoder_set_md5_checking(const FLAC__SeekableStreamDecoder *decoder, FLAC__bool value);
 125 FLAC__bool FLAC__seekable_stream_decoder_set_read_callback(const FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderReadStatus (*value)(const FLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data));
 126 FLAC__bool FLAC__seekable_stream_decoder_set_seek_callback(const FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderSeekStatus (*value)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data));
 127 FLAC__bool FLAC__seekable_stream_decoder_set_tell_callback(const FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderTellStatus (*value)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data));
 128 FLAC__bool FLAC__seekable_stream_decoder_set_length_callback(const FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderLengthStatus (*value)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data));
 129 FLAC__bool FLAC__seekable_stream_decoder_set_eof_callback(const FLAC__SeekableStreamDecoder *decoder, FLAC__bool (*value)(const FLAC__SeekableStreamDecoder *decoder, void *client_data));
 130 FLAC__bool FLAC__seekable_stream_decoder_set_write_callback(const FLAC__SeekableStreamDecoder *decoder, FLAC__StreamDecoderWriteStatus (*value)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 *buffer[], void *client_data));
 131 FLAC__bool FLAC__seekable_stream_decoder_set_metadata_callback(const FLAC__SeekableStreamDecoder *decoder, void (*value)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__StreamMetaData *metadata, void *client_data));
 132 FLAC__bool FLAC__seekable_stream_decoder_set_error_callback(const FLAC__SeekableStreamDecoder *decoder, void (*value)(const FLAC__SeekableStreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data));
 133 FLAC__bool FLAC__seekable_stream_decoder_set_client_data(const FLAC__SeekableStreamDecoder *decoder, void *value);
 134
 135 /*
 136  * Various "get" methods
 137  */
 138 FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_get_state(const FLAC__SeekableStreamDecoder *decoder);
 139 FLAC__bool FLAC__seekable_stream_decoder_get_md5_checking(const FLAC__SeekableStreamDecoder *decoder);
 140
 141 /*
 142  * Initialize the instance; should be called after construction and
 143  * 'set' calls but before any of the 'process' or 'seek' calls.  Will
 144  * set and return the decoder state, which will be FLAC__SEEKABLE_STREAM_DECODER_OK
 145  * if initialization succeeded.
 146  */
 147 FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_init(FLAC__SeekableStreamDecoder *decoder);
 148
 149 /*
 150  * Flush the decoding buffer, release resources, and return the decoder
 151  * state to FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED.  Only returns false if
 152  * md5_checking is set AND the stored MD5 sum is non-zero AND the stored
 153  * MD5 sum and computed MD5 sum do not match.
 154  */
 155 FLAC__bool FLAC__seekable_stream_decoder_finish(FLAC__SeekableStreamDecoder *decoder);
 156
 157 /*
 158  * Methods for decoding the data
 159  */
 160 FLAC__bool FLAC__seekable_stream_decoder_process_whole_stream(FLAC__SeekableStreamDecoder *decoder);
 161 FLAC__bool FLAC__seekable_stream_decoder_process_metadata(FLAC__SeekableStreamDecoder *decoder);
 162 FLAC__bool FLAC__seekable_stream_decoder_process_one_frame(FLAC__SeekableStreamDecoder *decoder);
 163 FLAC__bool FLAC__seekable_stream_decoder_process_remaining_frames(FLAC__SeekableStreamDecoder *decoder);
 164
 165 FLAC__bool FLAC__seekable_stream_decoder_seek_absolute(FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 sample);
 166
 167 #endif