seekable_stream_decoder.h (36903B)
1 /* libFLAC - Free Lossless Audio Codec library 2 * Copyright (C) 2000,2001,2002,2003,2004,2005 Josh Coalson 3 * 4 * Redistribution and use in source and binary forms, with or without 5 * modification, are permitted provided that the following conditions 6 * are met: 7 * 8 * - Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * 11 * - Redistributions in binary form must reproduce the above copyright 12 * notice, this list of conditions and the following disclaimer in the 13 * documentation and/or other materials provided with the distribution. 14 * 15 * - Neither the name of the Xiph.org Foundation nor the names of its 16 * contributors may be used to endorse or promote products derived from 17 * this software without specific prior written permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 22 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR 23 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 24 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 25 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 26 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 27 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 28 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 29 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 */ 31 32 #ifndef FLAC__SEEKABLE_STREAM_DECODER_H 33 #define FLAC__SEEKABLE_STREAM_DECODER_H 34 35 #include "export.h" 36 #include "stream_decoder.h" 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 43 /** \file include/FLAC/seekable_stream_decoder.h 44 * 45 * \brief 46 * This module contains the functions which implement the seekable stream 47 * decoder. 48 * 49 * See the detailed documentation in the 50 * \link flac_seekable_stream_decoder seekable stream decoder \endlink module. 51 */ 52 53 /** \defgroup flac_seekable_stream_decoder FLAC/seekable_stream_decoder.h: seekable stream decoder interface 54 * \ingroup flac_decoder 55 * 56 * \brief 57 * This module contains the functions which implement the seekable stream 58 * decoder. 59 * 60 * The basic usage of this decoder is as follows: 61 * - The program creates an instance of a decoder using 62 * FLAC__seekable_stream_decoder_new(). 63 * - The program overrides the default settings and sets callbacks for 64 * reading, writing, seeking, error reporting, and metadata reporting 65 * using FLAC__seekable_stream_decoder_set_*() functions. 66 * - The program initializes the instance to validate the settings and 67 * prepare for decoding using FLAC__seekable_stream_decoder_init(). 68 * - The program calls the FLAC__seekable_stream_decoder_process_*() 69 * functions to decode data, which subsequently calls the callbacks. 70 * - The program finishes the decoding with 71 * FLAC__seekable_stream_decoder_finish(), which flushes the input and 72 * output and resets the decoder to the uninitialized state. 73 * - The instance may be used again or deleted with 74 * FLAC__seekable_stream_decoder_delete(). 75 * 76 * The seekable stream decoder is a wrapper around the 77 * \link flac_stream_decoder stream decoder \endlink which also provides 78 * seeking capability. In addition to the Read/Write/Metadata/Error 79 * callbacks of the stream decoder, the user must also provide the following: 80 * 81 * - Seek callback - This function will be called when the decoder wants to 82 * seek to an absolute position in the stream. 83 * - Tell callback - This function will be called when the decoder wants to 84 * know the current absolute position of the stream. 85 * - Length callback - This function will be called when the decoder wants 86 * to know length of the stream. The seeking algorithm currently requires 87 * that the overall stream length be known. 88 * - EOF callback - This function will be called when the decoder wants to 89 * know if it is at the end of the stream. This could be synthesized from 90 * the tell and length callbacks but it may be more expensive that way, so 91 * there is a separate callback for it. 92 * 93 * Seeking is exposed through the 94 * FLAC__seekable_stream_decoder_seek_absolute() method. At any point after 95 * the seekable stream decoder has been initialized, the user can call this 96 * function to seek to an exact sample within the stream. Subsequently, the 97 * first time the write callback is called it will be passed a (possibly 98 * partial) block starting at that sample. 99 * 100 * The seekable stream decoder also provides MD5 signature checking. If 101 * this is turned on before initialization, 102 * FLAC__seekable_stream_decoder_finish() will report when the decoded MD5 103 * signature does not match the one stored in the STREAMINFO block. MD5 104 * checking is automatically turned off (until the next 105 * FLAC__seekable_stream_decoder_reset()) if there is no signature in the 106 * STREAMINFO block or when a seek is attempted. 107 * 108 * Make sure to read the detailed description of the 109 * \link flac_stream_decoder stream decoder module \endlink since the 110 * seekable stream decoder inherits much of its behavior. 111 * 112 * \note 113 * The "set" functions may only be called when the decoder is in the 114 * state FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED, i.e. after 115 * FLAC__seekable_stream_decoder_new() or 116 * FLAC__seekable_stream_decoder_finish(), but before 117 * FLAC__seekable_stream_decoder_init(). If this is the case they will 118 * return \c true, otherwise \c false. 119 * 120 * \note 121 * FLAC__stream_decoder_finish() resets all settings to the constructor 122 * defaults, including the callbacks. 123 * 124 * \{ 125 */ 126 127 128 /** State values for a FLAC__SeekableStreamDecoder 129 * 130 * The decoder's state can be obtained by calling FLAC__seekable_stream_decoder_get_state(). 131 */ 132 typedef enum { 133 134 FLAC__SEEKABLE_STREAM_DECODER_OK = 0, 135 /**< The decoder is in the normal OK state. */ 136 137 FLAC__SEEKABLE_STREAM_DECODER_SEEKING, 138 /**< The decoder is in the process of seeking. */ 139 140 FLAC__SEEKABLE_STREAM_DECODER_END_OF_STREAM, 141 /**< The decoder has reached the end of the stream. */ 142 143 FLAC__SEEKABLE_STREAM_DECODER_MEMORY_ALLOCATION_ERROR, 144 /**< An error occurred allocating memory. */ 145 146 FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR, 147 /**< An error occurred in the underlying stream decoder. */ 148 149 FLAC__SEEKABLE_STREAM_DECODER_READ_ERROR, 150 /**< The read callback returned an error. */ 151 152 FLAC__SEEKABLE_STREAM_DECODER_SEEK_ERROR, 153 /**< An error occurred while seeking or the seek or tell 154 * callback returned an error. 155 */ 156 157 FLAC__SEEKABLE_STREAM_DECODER_ALREADY_INITIALIZED, 158 /**< FLAC__seekable_stream_decoder_init() was called when the 159 * decoder was already initialized, usually because 160 * FLAC__seekable_stream_decoder_finish() was not called. 161 */ 162 163 FLAC__SEEKABLE_STREAM_DECODER_INVALID_CALLBACK, 164 /**< FLAC__seekable_stream_decoder_init() was called without all 165 * callbacks being set. 166 */ 167 168 FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED 169 /**< The decoder is in the uninitialized state. */ 170 171 } FLAC__SeekableStreamDecoderState; 172 173 /** Maps a FLAC__SeekableStreamDecoderState to a C string. 174 * 175 * Using a FLAC__SeekableStreamDecoderState as the index to this array 176 * will give the string equivalent. The contents should not be modified. 177 */ 178 extern FLAC_API const char * const FLAC__SeekableStreamDecoderStateString[]; 179 180 181 /** Return values for the FLAC__SeekableStreamDecoder read callback. 182 */ 183 typedef enum { 184 185 FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_OK, 186 /**< The read was OK and decoding can continue. */ 187 188 FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_ERROR 189 /**< An unrecoverable error occurred. The decoder will return from the process call. */ 190 191 } FLAC__SeekableStreamDecoderReadStatus; 192 193 /** Maps a FLAC__SeekableStreamDecoderReadStatus to a C string. 194 * 195 * Using a FLAC__SeekableStreamDecoderReadStatus as the index to this array 196 * will give the string equivalent. The contents should not be modified. 197 */ 198 extern FLAC_API const char * const FLAC__SeekableStreamDecoderReadStatusString[]; 199 200 201 /** Return values for the FLAC__SeekableStreamDecoder seek callback. 202 */ 203 typedef enum { 204 205 FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_OK, 206 /**< The seek was OK and decoding can continue. */ 207 208 FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_ERROR 209 /**< An unrecoverable error occurred. The decoder will return from the process call. */ 210 211 } FLAC__SeekableStreamDecoderSeekStatus; 212 213 /** Maps a FLAC__SeekableStreamDecoderSeekStatus to a C string. 214 * 215 * Using a FLAC__SeekableStreamDecoderSeekStatus as the index to this array 216 * will give the string equivalent. The contents should not be modified. 217 */ 218 extern FLAC_API const char * const FLAC__SeekableStreamDecoderSeekStatusString[]; 219 220 221 /** Return values for the FLAC__SeekableStreamDecoder tell callback. 222 */ 223 typedef enum { 224 225 FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_OK, 226 /**< The tell was OK and decoding can continue. */ 227 228 FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_ERROR 229 /**< An unrecoverable error occurred. The decoder will return from the process call. */ 230 231 } FLAC__SeekableStreamDecoderTellStatus; 232 233 /** Maps a FLAC__SeekableStreamDecoderTellStatus to a C string. 234 * 235 * Using a FLAC__SeekableStreamDecoderTellStatus as the index to this array 236 * will give the string equivalent. The contents should not be modified. 237 */ 238 extern FLAC_API const char * const FLAC__SeekableStreamDecoderTellStatusString[]; 239 240 241 /** Return values for the FLAC__SeekableStreamDecoder length callback. 242 */ 243 typedef enum { 244 245 FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_OK, 246 /**< The length call was OK and decoding can continue. */ 247 248 FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_ERROR 249 /**< An unrecoverable error occurred. The decoder will return from the process call. */ 250 251 } FLAC__SeekableStreamDecoderLengthStatus; 252 253 /** Maps a FLAC__SeekableStreamDecoderLengthStatus to a C string. 254 * 255 * Using a FLAC__SeekableStreamDecoderLengthStatus as the index to this array 256 * will give the string equivalent. The contents should not be modified. 257 */ 258 extern FLAC_API const char * const FLAC__SeekableStreamDecoderLengthStatusString[]; 259 260 261 /*********************************************************************** 262 * 263 * class FLAC__SeekableStreamDecoder : public FLAC__StreamDecoder 264 * 265 ***********************************************************************/ 266 267 struct FLAC__SeekableStreamDecoderProtected; 268 struct FLAC__SeekableStreamDecoderPrivate; 269 /** The opaque structure definition for the seekable stream decoder type. 270 * See the 271 * \link flac_seekable_stream_decoder seekable stream decoder module \endlink 272 * for a detailed description. 273 */ 274 typedef struct { 275 struct FLAC__SeekableStreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */ 276 struct FLAC__SeekableStreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */ 277 } FLAC__SeekableStreamDecoder; 278 279 /** Signature for the read callback. 280 * See FLAC__seekable_stream_decoder_set_read_callback() 281 * and FLAC__StreamDecoderReadCallback for more info. 282 * 283 * \param decoder The decoder instance calling the callback. 284 * \param buffer A pointer to a location for the callee to store 285 * data to be decoded. 286 * \param bytes A pointer to the size of the buffer. 287 * \param client_data The callee's client data set through 288 * FLAC__seekable_stream_decoder_set_client_data(). 289 * \retval FLAC__SeekableStreamDecoderReadStatus 290 * The callee's return status. 291 */ 292 typedef FLAC__SeekableStreamDecoderReadStatus (*FLAC__SeekableStreamDecoderReadCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data); 293 294 /** Signature for the seek callback. 295 * See FLAC__seekable_stream_decoder_set_seek_callback() for more info. 296 * 297 * \param decoder The decoder instance calling the callback. 298 * \param absolute_byte_offset The offset from the beginning of the stream 299 * to seek to. 300 * \param client_data The callee's client data set through 301 * FLAC__seekable_stream_decoder_set_client_data(). 302 * \retval FLAC__SeekableStreamDecoderSeekStatus 303 * The callee's return status. 304 */ 305 typedef FLAC__SeekableStreamDecoderSeekStatus (*FLAC__SeekableStreamDecoderSeekCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data); 306 307 /** Signature for the tell callback. 308 * See FLAC__seekable_stream_decoder_set_tell_callback() for more info. 309 * 310 * \param decoder The decoder instance calling the callback. 311 * \param absolute_byte_offset A pointer to storage for the current offset 312 * from the beginning of the stream. 313 * \param client_data The callee's client data set through 314 * FLAC__seekable_stream_decoder_set_client_data(). 315 * \retval FLAC__SeekableStreamDecoderTellStatus 316 * The callee's return status. 317 */ 318 typedef FLAC__SeekableStreamDecoderTellStatus (*FLAC__SeekableStreamDecoderTellCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data); 319 320 /** Signature for the length callback. 321 * See FLAC__seekable_stream_decoder_set_length_callback() for more info. 322 * 323 * \param decoder The decoder instance calling the callback. 324 * \param stream_length A pointer to storage for the length of the stream 325 * in bytes. 326 * \param client_data The callee's client data set through 327 * FLAC__seekable_stream_decoder_set_client_data(). 328 * \retval FLAC__SeekableStreamDecoderLengthStatus 329 * The callee's return status. 330 */ 331 typedef FLAC__SeekableStreamDecoderLengthStatus (*FLAC__SeekableStreamDecoderLengthCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data); 332 333 /** Signature for the EOF callback. 334 * See FLAC__seekable_stream_decoder_set_eof_callback() for more info. 335 * 336 * \param decoder The decoder instance calling the callback. 337 * \param client_data The callee's client data set through 338 * FLAC__seekable_stream_decoder_set_client_data(). 339 * \retval FLAC__bool 340 * \c true if the currently at the end of the stream, else \c false. 341 */ 342 typedef FLAC__bool (*FLAC__SeekableStreamDecoderEofCallback)(const FLAC__SeekableStreamDecoder *decoder, void *client_data); 343 344 /** Signature for the write callback. 345 * See FLAC__seekable_stream_decoder_set_write_callback() 346 * and FLAC__StreamDecoderWriteCallback for more info. 347 * 348 * \param decoder The decoder instance calling the callback. 349 * \param frame The description of the decoded frame. 350 * \param buffer An array of pointers to decoded channels of data. 351 * \param client_data The callee's client data set through 352 * FLAC__seekable_stream_decoder_set_client_data(). 353 * \retval FLAC__StreamDecoderWriteStatus 354 * The callee's return status. 355 */ 356 typedef FLAC__StreamDecoderWriteStatus (*FLAC__SeekableStreamDecoderWriteCallback)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data); 357 358 /** Signature for the metadata callback. 359 * See FLAC__seekable_stream_decoder_set_metadata_callback() 360 * and FLAC__StreamDecoderMetadataCallback for more info. 361 * 362 * \param decoder The decoder instance calling the callback. 363 * \param metadata The decoded metadata block. 364 * \param client_data The callee's client data set through 365 * FLAC__seekable_stream_decoder_set_client_data(). 366 */ 367 typedef void (*FLAC__SeekableStreamDecoderMetadataCallback)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data); 368 369 /** Signature for the error callback. 370 * See FLAC__seekable_stream_decoder_set_error_callback() 371 * and FLAC__StreamDecoderErrorCallback for more info. 372 * 373 * \param decoder The decoder instance calling the callback. 374 * \param status The error encountered by the decoder. 375 * \param client_data The callee's client data set through 376 * FLAC__seekable_stream_decoder_set_client_data(). 377 */ 378 typedef void (*FLAC__SeekableStreamDecoderErrorCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data); 379 380 381 /*********************************************************************** 382 * 383 * Class constructor/destructor 384 * 385 ***********************************************************************/ 386 387 /** Create a new seekable stream decoder instance. The instance is created 388 * with default settings; see the individual 389 * FLAC__seekable_stream_decoder_set_*() functions for each setting's 390 * default. 391 * 392 * \retval FLAC__SeekableStreamDecoder* 393 * \c NULL if there was an error allocating memory, else the new instance. 394 */ 395 FLAC_API FLAC__SeekableStreamDecoder *FLAC__seekable_stream_decoder_new(); 396 397 /** Free a decoder instance. Deletes the object pointed to by \a decoder. 398 * 399 * \param decoder A pointer to an existing decoder. 400 * \assert 401 * \code decoder != NULL \endcode 402 */ 403 FLAC_API void FLAC__seekable_stream_decoder_delete(FLAC__SeekableStreamDecoder *decoder); 404 405 406 /*********************************************************************** 407 * 408 * Public class method prototypes 409 * 410 ***********************************************************************/ 411 412 /** Set the "MD5 signature checking" flag. If \c true, the decoder will 413 * compute the MD5 signature of the unencoded audio data while decoding 414 * and compare it to the signature from the STREAMINFO block, if it 415 * exists, during FLAC__seekable_stream_decoder_finish(). 416 * 417 * MD5 signature checking will be turned off (until the next 418 * FLAC__seekable_stream_decoder_reset()) if there is no signature in 419 * the STREAMINFO block or when a seek is attempted. 420 * 421 * \default \c false 422 * \param decoder A decoder instance to set. 423 * \param value Flag value (see above). 424 * \assert 425 * \code decoder != NULL \endcode 426 * \retval FLAC__bool 427 * \c false if the decoder is already initialized, else \c true. 428 */ 429 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_md5_checking(FLAC__SeekableStreamDecoder *decoder, FLAC__bool value); 430 431 /** Set the read callback. 432 * This is inherited from FLAC__StreamDecoder; see 433 * FLAC__stream_decoder_set_read_callback(). 434 * 435 * \note 436 * The callback is mandatory and must be set before initialization. 437 * 438 * \default \c NULL 439 * \param decoder A decoder instance to set. 440 * \param value See above. 441 * \assert 442 * \code decoder != NULL \endcode 443 * \code value != NULL \endcode 444 * \retval FLAC__bool 445 * \c false if the decoder is already initialized, else \c true. 446 */ 447 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_read_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderReadCallback value); 448 449 /** Set the seek callback. 450 * The supplied function will be called when the decoder needs to seek 451 * the input stream. The decoder will pass the absolute byte offset 452 * to seek to, 0 meaning the beginning of the stream. 453 * 454 * \note 455 * The callback is mandatory and must be set before initialization. 456 * 457 * \default \c NULL 458 * \param decoder A decoder instance to set. 459 * \param value See above. 460 * \assert 461 * \code decoder != NULL \endcode 462 * \code value != NULL \endcode 463 * \retval FLAC__bool 464 * \c false if the decoder is already initialized, else \c true. 465 */ 466 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_seek_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderSeekCallback value); 467 468 /** Set the tell callback. 469 * The supplied function will be called when the decoder wants to know 470 * the current position of the stream. The callback should return the 471 * byte offset from the beginning of the stream. 472 * 473 * \note 474 * The callback is mandatory and must be set before initialization. 475 * 476 * \default \c NULL 477 * \param decoder A decoder instance to set. 478 * \param value See above. 479 * \assert 480 * \code decoder != NULL \endcode 481 * \code value != NULL \endcode 482 * \retval FLAC__bool 483 * \c false if the decoder is already initialized, else \c true. 484 */ 485 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_tell_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderTellCallback value); 486 487 /** Set the length callback. 488 * The supplied function will be called when the decoder wants to know 489 * the total length of the stream in bytes. 490 * 491 * \note 492 * The callback is mandatory and must be set before initialization. 493 * 494 * \default \c NULL 495 * \param decoder A decoder instance to set. 496 * \param value See above. 497 * \assert 498 * \code decoder != NULL \endcode 499 * \code value != NULL \endcode 500 * \retval FLAC__bool 501 * \c false if the decoder is already initialized, else \c true. 502 */ 503 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_length_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderLengthCallback value); 504 505 /** Set the eof callback. 506 * The supplied function will be called when the decoder needs to know 507 * if the end of the stream has been reached. 508 * 509 * \note 510 * The callback is mandatory and must be set before initialization. 511 * 512 * \default \c NULL 513 * \param decoder A decoder instance to set. 514 * \param value See above. 515 * \assert 516 * \code decoder != NULL \endcode 517 * \code value != NULL \endcode 518 * \retval FLAC__bool 519 * \c false if the decoder is already initialized, else \c true. 520 */ 521 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_eof_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderEofCallback value); 522 523 /** Set the write callback. 524 * This is inherited from FLAC__StreamDecoder; see 525 * FLAC__stream_decoder_set_write_callback(). 526 * 527 * \note 528 * The callback is mandatory and must be set before initialization. 529 * 530 * \default \c NULL 531 * \param decoder A decoder instance to set. 532 * \param value See above. 533 * \assert 534 * \code decoder != NULL \endcode 535 * \code value != NULL \endcode 536 * \retval FLAC__bool 537 * \c false if the decoder is already initialized, else \c true. 538 */ 539 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_write_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderWriteCallback value); 540 541 /** Set the metadata callback. 542 * This is inherited from FLAC__StreamDecoder; see 543 * FLAC__stream_decoder_set_metadata_callback(). 544 * 545 * \note 546 * The callback is mandatory and must be set before initialization. 547 * 548 * \default \c NULL 549 * \param decoder A decoder instance to set. 550 * \param value See above. 551 * \assert 552 * \code decoder != NULL \endcode 553 * \code value != NULL \endcode 554 * \retval FLAC__bool 555 * \c false if the decoder is already initialized, else \c true. 556 */ 557 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderMetadataCallback value); 558 559 /** Set the error callback. 560 * This is inherited from FLAC__StreamDecoder; see 561 * FLAC__stream_decoder_set_error_callback(). 562 * 563 * \note 564 * The callback is mandatory and must be set before initialization. 565 * 566 * \default \c NULL 567 * \param decoder A decoder instance to set. 568 * \param value See above. 569 * \assert 570 * \code decoder != NULL \endcode 571 * \code value != NULL \endcode 572 * \retval FLAC__bool 573 * \c false if the decoder is already initialized, else \c true. 574 */ 575 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_error_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderErrorCallback value); 576 577 /** Set the client data to be passed back to callbacks. 578 * This value will be supplied to callbacks in their \a client_data 579 * argument. 580 * 581 * \default \c NULL 582 * \param decoder A decoder instance to set. 583 * \param value See above. 584 * \assert 585 * \code decoder != NULL \endcode 586 * \retval FLAC__bool 587 * \c false if the decoder is already initialized, else \c true. 588 */ 589 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_client_data(FLAC__SeekableStreamDecoder *decoder, void *value); 590 591 /** This is inherited from FLAC__StreamDecoder; see 592 * FLAC__stream_decoder_set_metadata_respond(). 593 * 594 * \default By default, only the \c STREAMINFO block is returned via the 595 * metadata callback. 596 * \param decoder A decoder instance to set. 597 * \param type See above. 598 * \assert 599 * \code decoder != NULL \endcode 600 * \a type is valid 601 * \retval FLAC__bool 602 * \c false if the decoder is already initialized, else \c true. 603 */ 604 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond(FLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type); 605 606 /** This is inherited from FLAC__StreamDecoder; see 607 * FLAC__stream_decoder_set_metadata_respond_application(). 608 * 609 * \default By default, only the \c STREAMINFO block is returned via the 610 * metadata callback. 611 * \param decoder A decoder instance to set. 612 * \param id See above. 613 * \assert 614 * \code decoder != NULL \endcode 615 * \code id != NULL \endcode 616 * \retval FLAC__bool 617 * \c false if the decoder is already initialized, else \c true. 618 */ 619 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond_application(FLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]); 620 621 /** This is inherited from FLAC__StreamDecoder; see 622 * FLAC__stream_decoder_set_metadata_respond_all(). 623 * 624 * \default By default, only the \c STREAMINFO block is returned via the 625 * metadata callback. 626 * \param decoder A decoder instance to set. 627 * \assert 628 * \code decoder != NULL \endcode 629 * \retval FLAC__bool 630 * \c false if the decoder is already initialized, else \c true. 631 */ 632 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond_all(FLAC__SeekableStreamDecoder *decoder); 633 634 /** This is inherited from FLAC__StreamDecoder; see 635 * FLAC__stream_decoder_set_metadata_ignore(). 636 * 637 * \default By default, only the \c STREAMINFO block is returned via the 638 * metadata callback. 639 * \param decoder A decoder instance to set. 640 * \param type See above. 641 * \assert 642 * \code decoder != NULL \endcode 643 * \a type is valid 644 * \retval FLAC__bool 645 * \c false if the decoder is already initialized, else \c true. 646 */ 647 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore(FLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type); 648 649 /** This is inherited from FLAC__StreamDecoder; see 650 * FLAC__stream_decoder_set_metadata_ignore_application(). 651 * 652 * \default By default, only the \c STREAMINFO block is returned via the 653 * metadata callback. 654 * \param decoder A decoder instance to set. 655 * \param id See above. 656 * \assert 657 * \code decoder != NULL \endcode 658 * \code id != NULL \endcode 659 * \retval FLAC__bool 660 * \c false if the decoder is already initialized, else \c true. 661 */ 662 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore_application(FLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]); 663 664 /** This is inherited from FLAC__StreamDecoder; see 665 * FLAC__stream_decoder_set_metadata_ignore_all(). 666 * 667 * \default By default, only the \c STREAMINFO block is returned via the 668 * metadata callback. 669 * \param decoder A decoder instance to set. 670 * \assert 671 * \code decoder != NULL \endcode 672 * \retval FLAC__bool 673 * \c false if the decoder is already initialized, else \c true. 674 */ 675 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore_all(FLAC__SeekableStreamDecoder *decoder); 676 677 /** Get the current decoder state. 678 * 679 * \param decoder A decoder instance to query. 680 * \assert 681 * \code decoder != NULL \endcode 682 * \retval FLAC__SeekableStreamDecoderState 683 * The current decoder state. 684 */ 685 FLAC_API FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_get_state(const FLAC__SeekableStreamDecoder *decoder); 686 687 /** Get the state of the underlying stream decoder. 688 * Useful when the seekable stream decoder state is 689 * \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR. 690 * 691 * \param decoder A decoder instance to query. 692 * \assert 693 * \code decoder != NULL \endcode 694 * \retval FLAC__StreamDecoderState 695 * The stream decoder state. 696 */ 697 FLAC_API FLAC__StreamDecoderState FLAC__seekable_stream_decoder_get_stream_decoder_state(const FLAC__SeekableStreamDecoder *decoder); 698 699 /** Get the current decoder state as a C string. 700 * This version automatically resolves 701 * \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR by getting the 702 * stream decoder's state. 703 * 704 * \param decoder A decoder instance to query. 705 * \assert 706 * \code decoder != NULL \endcode 707 * \retval const char * 708 * The decoder state as a C string. Do not modify the contents. 709 */ 710 FLAC_API const char *FLAC__seekable_stream_decoder_get_resolved_state_string(const FLAC__SeekableStreamDecoder *decoder); 711 712 /** Get the "MD5 signature checking" flag. 713 * This is the value of the setting, not whether or not the decoder is 714 * currently checking the MD5 (remember, it can be turned off automatically 715 * by a seek). When the decoder is reset the flag will be restored to the 716 * value returned by this function. 717 * 718 * \param decoder A decoder instance to query. 719 * \assert 720 * \code decoder != NULL \endcode 721 * \retval FLAC__bool 722 * See above. 723 */ 724 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_get_md5_checking(const FLAC__SeekableStreamDecoder *decoder); 725 726 /** This is inherited from FLAC__StreamDecoder; see 727 * FLAC__stream_decoder_get_channels(). 728 * 729 * \param decoder A decoder instance to query. 730 * \assert 731 * \code decoder != NULL \endcode 732 * \retval unsigned 733 * See above. 734 */ 735 FLAC_API unsigned FLAC__seekable_stream_decoder_get_channels(const FLAC__SeekableStreamDecoder *decoder); 736 737 /** This is inherited from FLAC__StreamDecoder; see 738 * FLAC__stream_decoder_get_channel_assignment(). 739 * 740 * \param decoder A decoder instance to query. 741 * \assert 742 * \code decoder != NULL \endcode 743 * \retval FLAC__ChannelAssignment 744 * See above. 745 */ 746 FLAC_API FLAC__ChannelAssignment FLAC__seekable_stream_decoder_get_channel_assignment(const FLAC__SeekableStreamDecoder *decoder); 747 748 /** This is inherited from FLAC__StreamDecoder; see 749 * FLAC__stream_decoder_get_bits_per_sample(). 750 * 751 * \param decoder A decoder instance to query. 752 * \assert 753 * \code decoder != NULL \endcode 754 * \retval unsigned 755 * See above. 756 */ 757 FLAC_API unsigned FLAC__seekable_stream_decoder_get_bits_per_sample(const FLAC__SeekableStreamDecoder *decoder); 758 759 /** This is inherited from FLAC__StreamDecoder; see 760 * FLAC__stream_decoder_get_sample_rate(). 761 * 762 * \param decoder A decoder instance to query. 763 * \assert 764 * \code decoder != NULL \endcode 765 * \retval unsigned 766 * See above. 767 */ 768 FLAC_API unsigned FLAC__seekable_stream_decoder_get_sample_rate(const FLAC__SeekableStreamDecoder *decoder); 769 770 /** This is inherited from FLAC__StreamDecoder; see 771 * FLAC__stream_decoder_get_blocksize(). 772 * 773 * \param decoder A decoder instance to query. 774 * \assert 775 * \code decoder != NULL \endcode 776 * \retval unsigned 777 * See above. 778 */ 779 FLAC_API unsigned FLAC__seekable_stream_decoder_get_blocksize(const FLAC__SeekableStreamDecoder *decoder); 780 781 /** Returns the decoder's current read position within the stream. 782 * The position is the byte offset from the start of the stream. 783 * Bytes before this position have been fully decoded. Note that 784 * there may still be undecoded bytes in the decoder's read FIFO. 785 * The returned position is correct even after a seek. 786 * 787 * \param decoder A decoder instance to query. 788 * \param position Address at which to return the desired position. 789 * \assert 790 * \code decoder != NULL \endcode 791 * \code position != NULL \endcode 792 * \retval FLAC__bool 793 * \c true if successful, \c false if there was an error from 794 * the 'tell' callback. 795 */ 796 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_get_decode_position(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *position); 797 798 /** Initialize the decoder instance. 799 * Should be called after FLAC__seekable_stream_decoder_new() and 800 * FLAC__seekable_stream_decoder_set_*() but before any of the 801 * FLAC__seekable_stream_decoder_process_*() functions. Will set and return 802 * the decoder state, which will be FLAC__SEEKABLE_STREAM_DECODER_OK 803 * if initialization succeeded. 804 * 805 * \param decoder An uninitialized decoder instance. 806 * \assert 807 * \code decoder != NULL \endcode 808 * \retval FLAC__SeekableStreamDecoderState 809 * \c FLAC__SEEKABLE_STREAM_DECODER_OK if initialization was 810 * successful; see FLAC__SeekableStreamDecoderState for the meanings 811 * of other return values. 812 */ 813 FLAC_API FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_init(FLAC__SeekableStreamDecoder *decoder); 814 815 /** Finish the decoding process. 816 * Flushes the decoding buffer, releases resources, resets the decoder 817 * settings to their defaults, and returns the decoder state to 818 * FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED. 819 * 820 * In the event of a prematurely-terminated decode, it is not strictly 821 * necessary to call this immediately before 822 * FLAC__seekable_stream_decoder_delete() but it is good practice to match 823 * every FLAC__seekable_stream_decoder_init() with a 824 * FLAC__seekable_stream_decoder_finish(). 825 * 826 * \param decoder An uninitialized decoder instance. 827 * \assert 828 * \code decoder != NULL \endcode 829 * \retval FLAC__bool 830 * \c false if MD5 checking is on AND a STREAMINFO block was available 831 * AND the MD5 signature in the STREAMINFO block was non-zero AND the 832 * signature does not match the one computed by the decoder; else 833 * \c true. 834 */ 835 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_finish(FLAC__SeekableStreamDecoder *decoder); 836 837 /** Flush the stream input. 838 * The decoder's input buffer will be cleared and the state set to 839 * \c FLAC__SEEKABLE_STREAM_DECODER_OK. This will also turn off MD5 840 * checking. 841 * 842 * \param decoder A decoder instance. 843 * \assert 844 * \code decoder != NULL \endcode 845 * \retval FLAC__bool 846 * \c true if successful, else \c false if a memory allocation 847 * or stream decoder error occurs. 848 */ 849 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_flush(FLAC__SeekableStreamDecoder *decoder); 850 851 /** Reset the decoding process. 852 * The decoder's input buffer will be cleared and the state set to 853 * \c FLAC__SEEKABLE_STREAM_DECODER_OK. This is similar to 854 * FLAC__seekable_stream_decoder_finish() except that the settings are 855 * preserved; there is no need to call FLAC__seekable_stream_decoder_init() 856 * before decoding again. MD5 checking will be restored to its original 857 * setting. 858 * 859 * \param decoder A decoder instance. 860 * \assert 861 * \code decoder != NULL \endcode 862 * \retval FLAC__bool 863 * \c true if successful, else \c false if a memory allocation 864 * or stream decoder error occurs. 865 */ 866 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_reset(FLAC__SeekableStreamDecoder *decoder); 867 868 /** This is inherited from FLAC__StreamDecoder; see 869 * FLAC__stream_decoder_process_single(). 870 * 871 * \param decoder A decoder instance. 872 * \assert 873 * \code decoder != NULL \endcode 874 * \retval FLAC__bool 875 * See above. 876 */ 877 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_single(FLAC__SeekableStreamDecoder *decoder); 878 879 /** This is inherited from FLAC__StreamDecoder; see 880 * FLAC__stream_decoder_process_until_end_of_metadata(). 881 * 882 * \param decoder A decoder instance. 883 * \assert 884 * \code decoder != NULL \endcode 885 * \retval FLAC__bool 886 * See above. 887 */ 888 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_metadata(FLAC__SeekableStreamDecoder *decoder); 889 890 /** This is inherited from FLAC__StreamDecoder; see 891 * FLAC__stream_decoder_process_until_end_of_stream(). 892 * 893 * \param decoder A decoder instance. 894 * \assert 895 * \code decoder != NULL \endcode 896 * \retval FLAC__bool 897 * See above. 898 */ 899 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_stream(FLAC__SeekableStreamDecoder *decoder); 900 901 /** This is inherited from FLAC__StreamDecoder; see 902 * FLAC__stream_decoder_skip_single_frame(). 903 * 904 * \param decoder A decoder instance. 905 * \assert 906 * \code decoder != NULL \endcode 907 * \retval FLAC__bool 908 * See above. 909 */ 910 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_skip_single_frame(FLAC__SeekableStreamDecoder *decoder); 911 912 /** Flush the input and seek to an absolute sample. 913 * Decoding will resume at the given sample. Note that because of 914 * this, the next write callback may contain a partial block. 915 * 916 * \param decoder A decoder instance. 917 * \param sample The target sample number to seek to. 918 * \assert 919 * \code decoder != NULL \endcode 920 * \retval FLAC__bool 921 * \c true if successful, else \c false. 922 */ 923 FLAC_API FLAC__bool FLAC__seekable_stream_decoder_seek_absolute(FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 sample); 924 925 /* \} */ 926 927 #ifdef __cplusplus 928 } 929 #endif 930 931 #endif