file_decoder.h (24554B)
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__FILE_DECODER_H 33 #define FLAC__FILE_DECODER_H 34 35 #include "export.h" 36 #include "seekable_stream_decoder.h" 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 43 /** \file include/FLAC/file_decoder.h 44 * 45 * \brief 46 * This module contains the functions which implement the file 47 * decoder. 48 * 49 * See the detailed documentation in the 50 * \link flac_file_decoder file decoder \endlink module. 51 */ 52 53 /** \defgroup flac_file_decoder FLAC/file_decoder.h: file decoder interface 54 * \ingroup flac_decoder 55 * 56 * \brief 57 * This module contains the functions which implement the file 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__file_decoder_new(). 63 * - The program overrides the default settings and sets callbacks for 64 * writing, error reporting, and metadata reporting using 65 * FLAC__file_decoder_set_*() functions. 66 * - The program initializes the instance to validate the settings and 67 * prepare for decoding using FLAC__file_decoder_init(). 68 * - The program calls the FLAC__file_decoder_process_*() functions 69 * to decode data, which subsequently calls the callbacks. 70 * - The program finishes the decoding with FLAC__file_decoder_finish(), 71 * which flushes the input and output and resets the decoder to the 72 * uninitialized state. 73 * - The instance may be used again or deleted with 74 * FLAC__file_decoder_delete(). 75 * 76 * The file decoder is a trivial wrapper around the 77 * \link flac_seekable_stream_decoder seekable stream decoder \endlink 78 * meant to simplfy the process of decoding from a standard file. The 79 * file decoder supplies all but the Write/Metadata/Error callbacks. 80 * The user needs only to provide the path to the file and the file 81 * decoder handles the rest. 82 * 83 * Like the seekable stream decoder, seeking is exposed through the 84 * FLAC__file_decoder_seek_absolute() method. At any point after the file 85 * decoder has been initialized, the user can call this function to seek to 86 * an exact sample within the file. Subsequently, the first time the write 87 * callback is called it will be passed a (possibly partial) block starting 88 * at that sample. 89 * 90 * The file decoder also inherits MD5 signature checking from the seekable 91 * stream decoder. If this is turned on before initialization, 92 * FLAC__file_decoder_finish() will report when the decoded MD5 signature 93 * does not match the one stored in the STREAMINFO block. MD5 checking is 94 * automatically turned off if there is no signature in the STREAMINFO 95 * block or when a seek is attempted. 96 * 97 * Make sure to read the detailed descriptions of the 98 * \link flac_seekable_stream_decoder seekable stream decoder module \endlink 99 * and \link flac_stream_decoder stream decoder module \endlink 100 * since the file decoder inherits much of its behavior from them. 101 * 102 * \note 103 * The "set" functions may only be called when the decoder is in the 104 * state FLAC__FILE_DECODER_UNINITIALIZED, i.e. after 105 * FLAC__file_decoder_new() or FLAC__file_decoder_finish(), but 106 * before FLAC__file_decoder_init(). If this is the case they will 107 * return \c true, otherwise \c false. 108 * 109 * \note 110 * FLAC__file_decoder_finish() resets all settings to the constructor 111 * defaults, including the callbacks. 112 * 113 * \{ 114 */ 115 116 117 /** State values for a FLAC__FileDecoder 118 * 119 * The decoder's state can be obtained by calling FLAC__file_decoder_get_state(). 120 */ 121 typedef enum { 122 123 FLAC__FILE_DECODER_OK = 0, 124 /**< The decoder is in the normal OK state. */ 125 126 FLAC__FILE_DECODER_END_OF_FILE, 127 /**< The decoder has reached the end of the file. */ 128 129 FLAC__FILE_DECODER_ERROR_OPENING_FILE, 130 /**< An error occurred opening the input file. */ 131 132 FLAC__FILE_DECODER_MEMORY_ALLOCATION_ERROR, 133 /**< An error occurred allocating memory. */ 134 135 FLAC__FILE_DECODER_SEEK_ERROR, 136 /**< An error occurred while seeking. */ 137 138 FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR, 139 /**< An error occurred in the underlying seekable stream decoder. */ 140 141 FLAC__FILE_DECODER_ALREADY_INITIALIZED, 142 /**< FLAC__file_decoder_init() was called when the decoder was already 143 * initialized, usually because FLAC__file_decoder_finish() was not 144 * called. 145 */ 146 147 FLAC__FILE_DECODER_INVALID_CALLBACK, 148 /**< FLAC__file_decoder_init() was called without all callbacks 149 * being set. 150 */ 151 152 FLAC__FILE_DECODER_UNINITIALIZED 153 /**< The decoder is in the uninitialized state. */ 154 155 } FLAC__FileDecoderState; 156 157 /** Maps a FLAC__FileDecoderState to a C string. 158 * 159 * Using a FLAC__FileDecoderState as the index to this array 160 * will give the string equivalent. The contents should not be modified. 161 */ 162 extern FLAC_API const char * const FLAC__FileDecoderStateString[]; 163 164 165 /*********************************************************************** 166 * 167 * class FLAC__FileDecoder : public FLAC__StreamDecoder 168 * 169 ***********************************************************************/ 170 171 struct FLAC__FileDecoderProtected; 172 struct FLAC__FileDecoderPrivate; 173 /** The opaque structure definition for the file decoder type. See the 174 * \link flac_file_decoder file decoder module \endlink for a detailed 175 * description. 176 */ 177 typedef struct { 178 struct FLAC__FileDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */ 179 struct FLAC__FileDecoderPrivate *private_; /* avoid the C++ keyword 'private' */ 180 } FLAC__FileDecoder; 181 182 /** Signature for the write callback. 183 * See FLAC__file_decoder_set_write_callback() 184 * and FLAC__SeekableStreamDecoderWriteCallback for more info. 185 * 186 * \param decoder The decoder instance calling the callback. 187 * \param frame The description of the decoded frame. 188 * \param buffer An array of pointers to decoded channels of data. 189 * \param client_data The callee's client data set through 190 * FLAC__file_decoder_set_client_data(). 191 * \retval FLAC__StreamDecoderWriteStatus 192 * The callee's return status. 193 */ 194 typedef FLAC__StreamDecoderWriteStatus (*FLAC__FileDecoderWriteCallback)(const FLAC__FileDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data); 195 196 /** Signature for the metadata callback. 197 * See FLAC__file_decoder_set_metadata_callback() 198 * and FLAC__SeekableStreamDecoderMetadataCallback for more info. 199 * 200 * \param decoder The decoder instance calling the callback. 201 * \param metadata The decoded metadata block. 202 * \param client_data The callee's client data set through 203 * FLAC__file_decoder_set_client_data(). 204 */ 205 typedef void (*FLAC__FileDecoderMetadataCallback)(const FLAC__FileDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data); 206 207 /** Signature for the error callback. 208 * See FLAC__file_decoder_set_error_callback() 209 * and FLAC__SeekableStreamDecoderErrorCallback for more info. 210 * 211 * \param decoder The decoder instance calling the callback. 212 * \param status The error encountered by the decoder. 213 * \param client_data The callee's client data set through 214 * FLAC__file_decoder_set_client_data(). 215 */ 216 typedef void (*FLAC__FileDecoderErrorCallback)(const FLAC__FileDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data); 217 218 219 /*********************************************************************** 220 * 221 * Class constructor/destructor 222 * 223 ***********************************************************************/ 224 225 /** Create a new file decoder instance. The instance is created with 226 * default settings; see the individual FLAC__file_decoder_set_*() 227 * functions for each setting's default. 228 * 229 * \retval FLAC__FileDecoder* 230 * \c NULL if there was an error allocating memory, else the new instance. 231 */ 232 FLAC_API FLAC__FileDecoder *FLAC__file_decoder_new(); 233 234 /** Free a decoder instance. Deletes the object pointed to by \a decoder. 235 * 236 * \param decoder A pointer to an existing decoder. 237 * \assert 238 * \code decoder != NULL \endcode 239 */ 240 FLAC_API void FLAC__file_decoder_delete(FLAC__FileDecoder *decoder); 241 242 243 /*********************************************************************** 244 * 245 * Public class method prototypes 246 * 247 ***********************************************************************/ 248 249 /** Set the "MD5 signature checking" flag. 250 * This is inherited from FLAC__SeekableStreamDecoder; see 251 * FLAC__seekable_stream_decoder_set_md5_checking(). 252 * 253 * \default \c false 254 * \param decoder A decoder instance to set. 255 * \param value See above. 256 * \assert 257 * \code decoder != NULL \endcode 258 * \retval FLAC__bool 259 * \c false if the decoder is already initialized, else \c true. 260 */ 261 FLAC_API FLAC__bool FLAC__file_decoder_set_md5_checking(FLAC__FileDecoder *decoder, FLAC__bool value); 262 263 /** Set the input file name to decode. 264 * 265 * \default \c "-" 266 * \param decoder A decoder instance to set. 267 * \param value The input file name, or "-" for \c stdin. 268 * \assert 269 * \code decoder != NULL \endcode 270 * \code value != NULL \endcode 271 * \retval FLAC__bool 272 * \c false if the decoder is already initialized, or there was a memory 273 * allocation error, else \c true. 274 */ 275 FLAC_API FLAC__bool FLAC__file_decoder_set_filename(FLAC__FileDecoder *decoder, const char *value); 276 277 /** Set the write callback. 278 * This is inherited from FLAC__SeekableStreamDecoder; see 279 * FLAC__seekable_stream_decoder_set_write_callback(). 280 * 281 * \note 282 * The callback is mandatory and must be set before initialization. 283 * 284 * \default \c NULL 285 * \param decoder A decoder instance to set. 286 * \param value See above. 287 * \assert 288 * \code decoder != NULL \endcode 289 * \code value != NULL \endcode 290 * \retval FLAC__bool 291 * \c false if the decoder is already initialized, else \c true. 292 */ 293 FLAC_API FLAC__bool FLAC__file_decoder_set_write_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderWriteCallback value); 294 295 /** Set the metadata callback. 296 * This is inherited from FLAC__SeekableStreamDecoder; see 297 * FLAC__seekable_stream_decoder_set_metadata_callback(). 298 * 299 * \note 300 * The callback is mandatory and must be set before initialization. 301 * 302 * \default \c NULL 303 * \param decoder A decoder instance to set. 304 * \param value See above. 305 * \assert 306 * \code decoder != NULL \endcode 307 * \code value != NULL \endcode 308 * \retval FLAC__bool 309 * \c false if the decoder is already initialized, else \c true. 310 */ 311 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderMetadataCallback value); 312 313 /** Set the error callback. 314 * This is inherited from FLAC__SeekableStreamDecoder; see 315 * FLAC__seekable_stream_decoder_set_error_callback(). 316 * 317 * \note 318 * The callback is mandatory and must be set before initialization. 319 * 320 * \default \c NULL 321 * \param decoder A decoder instance to set. 322 * \param value See above. 323 * \assert 324 * \code decoder != NULL \endcode 325 * \code value != NULL \endcode 326 * \retval FLAC__bool 327 * \c false if the decoder is already initialized, else \c true. 328 */ 329 FLAC_API FLAC__bool FLAC__file_decoder_set_error_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderErrorCallback value); 330 331 /** Set the client data to be passed back to callbacks. 332 * This value will be supplied to callbacks in their \a client_data 333 * argument. 334 * 335 * \default \c NULL 336 * \param decoder A decoder instance to set. 337 * \param value See above. 338 * \assert 339 * \code decoder != NULL \endcode 340 * \retval FLAC__bool 341 * \c false if the decoder is already initialized, else \c true. 342 */ 343 FLAC_API FLAC__bool FLAC__file_decoder_set_client_data(FLAC__FileDecoder *decoder, void *value); 344 345 /** This is inherited from FLAC__SeekableStreamDecoder; see 346 * FLAC__seekable_stream_decoder_set_metadata_respond(). 347 * 348 * \default By default, only the \c STREAMINFO block is returned via the 349 * metadata callback. 350 * \param decoder A decoder instance to set. 351 * \param type See above. 352 * \assert 353 * \code decoder != NULL \endcode 354 * \a type is valid 355 * \retval FLAC__bool 356 * \c false if the decoder is already initialized, else \c true. 357 */ 358 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond(FLAC__FileDecoder *decoder, FLAC__MetadataType type); 359 360 /** This is inherited from FLAC__SeekableStreamDecoder; see 361 * FLAC__seekable_stream_decoder_set_metadata_respond_application(). 362 * 363 * \default By default, only the \c STREAMINFO block is returned via the 364 * metadata callback. 365 * \param decoder A decoder instance to set. 366 * \param id See above. 367 * \assert 368 * \code decoder != NULL \endcode 369 * \code id != NULL \endcode 370 * \retval FLAC__bool 371 * \c false if the decoder is already initialized, else \c true. 372 */ 373 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond_application(FLAC__FileDecoder *decoder, const FLAC__byte id[4]); 374 375 /** This is inherited from FLAC__SeekableStreamDecoder; see 376 * FLAC__seekable_stream_decoder_set_metadata_respond_all(). 377 * 378 * \default By default, only the \c STREAMINFO block is returned via the 379 * metadata callback. 380 * \param decoder A decoder instance to set. 381 * \assert 382 * \code decoder != NULL \endcode 383 * \retval FLAC__bool 384 * \c false if the decoder is already initialized, else \c true. 385 */ 386 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond_all(FLAC__FileDecoder *decoder); 387 388 /** This is inherited from FLAC__SeekableStreamDecoder; see 389 * FLAC__seekable_stream_decoder_set_metadata_ignore(). 390 * 391 * \default By default, only the \c STREAMINFO block is returned via the 392 * metadata callback. 393 * \param decoder A decoder instance to set. 394 * \param type See above. 395 * \assert 396 * \code decoder != NULL \endcode 397 * \a type is valid 398 * \retval FLAC__bool 399 * \c false if the decoder is already initialized, else \c true. 400 */ 401 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore(FLAC__FileDecoder *decoder, FLAC__MetadataType type); 402 403 /** This is inherited from FLAC__SeekableStreamDecoder; see 404 * FLAC__seekable_stream_decoder_set_metadata_ignore_application(). 405 * 406 * \default By default, only the \c STREAMINFO block is returned via the 407 * metadata callback. 408 * \param decoder A decoder instance to set. 409 * \param id See above. 410 * \assert 411 * \code decoder != NULL \endcode 412 * \code id != NULL \endcode 413 * \retval FLAC__bool 414 * \c false if the decoder is already initialized, else \c true. 415 */ 416 FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore_application(FLAC__FileDecoder *decoder, const FLAC__byte id[4]); 417 418 /** This is inherited from FLAC__SeekableStreamDecoder; see 419 * FLAC__seekable_stream_decoder_set_metadata_ignore_all(). 420 * 421 * \default By default, only the \c STREAMINFO block is returned via the 422 * metadata callback. 423 * \param decoder A decoder instance to set. 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__file_decoder_set_metadata_ignore_all(FLAC__FileDecoder *decoder); 430 431 /** Get the current decoder state. 432 * 433 * \param decoder A decoder instance to query. 434 * \assert 435 * \code decoder != NULL \endcode 436 * \retval FLAC__FileDecoderState 437 * The current decoder state. 438 */ 439 FLAC_API FLAC__FileDecoderState FLAC__file_decoder_get_state(const FLAC__FileDecoder *decoder); 440 441 /** Get the state of the underlying seekable stream decoder. 442 * Useful when the file decoder state is 443 * \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR. 444 * 445 * \param decoder A decoder instance to query. 446 * \assert 447 * \code decoder != NULL \endcode 448 * \retval FLAC__SeekableStreamDecoderState 449 * The seekable stream decoder state. 450 */ 451 FLAC_API FLAC__SeekableStreamDecoderState FLAC__file_decoder_get_seekable_stream_decoder_state(const FLAC__FileDecoder *decoder); 452 453 /** Get the state of the underlying stream decoder. 454 * Useful when the file decoder state is 455 * \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR and the seekable stream 456 * decoder state is \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR. 457 * 458 * \param decoder A decoder instance to query. 459 * \assert 460 * \code decoder != NULL \endcode 461 * \retval FLAC__StreamDecoderState 462 * The seekable stream decoder state. 463 */ 464 FLAC_API FLAC__StreamDecoderState FLAC__file_decoder_get_stream_decoder_state(const FLAC__FileDecoder *decoder); 465 466 /** Get the current decoder state as a C string. 467 * This version automatically resolves 468 * \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR by getting the 469 * seekable stream decoder's state. 470 * 471 * \param decoder A decoder instance to query. 472 * \assert 473 * \code decoder != NULL \endcode 474 * \retval const char * 475 * The decoder state as a C string. Do not modify the contents. 476 */ 477 FLAC_API const char *FLAC__file_decoder_get_resolved_state_string(const FLAC__FileDecoder *decoder); 478 479 /** Get the "MD5 signature checking" flag. 480 * This is inherited from FLAC__SeekableStreamDecoder; see 481 * FLAC__seekable_stream_decoder_get_md5_checking(). 482 * 483 * \param decoder A decoder instance to query. 484 * \assert 485 * \code decoder != NULL \endcode 486 * \retval FLAC__bool 487 * See above. 488 */ 489 FLAC_API FLAC__bool FLAC__file_decoder_get_md5_checking(const FLAC__FileDecoder *decoder); 490 491 /** This is inherited from FLAC__SeekableStreamDecoder; see 492 * FLAC__seekable_stream_decoder_get_channels(). 493 * 494 * \param decoder A decoder instance to query. 495 * \assert 496 * \code decoder != NULL \endcode 497 * \retval unsigned 498 * See above. 499 */ 500 FLAC_API unsigned FLAC__file_decoder_get_channels(const FLAC__FileDecoder *decoder); 501 502 /** This is inherited from FLAC__SeekableStreamDecoder; see 503 * FLAC__seekable_stream_decoder_get_channel_assignment(). 504 * 505 * \param decoder A decoder instance to query. 506 * \assert 507 * \code decoder != NULL \endcode 508 * \retval FLAC__ChannelAssignment 509 * See above. 510 */ 511 FLAC_API FLAC__ChannelAssignment FLAC__file_decoder_get_channel_assignment(const FLAC__FileDecoder *decoder); 512 513 /** This is inherited from FLAC__SeekableStreamDecoder; see 514 * FLAC__seekable_stream_decoder_get_bits_per_sample(). 515 * 516 * \param decoder A decoder instance to query. 517 * \assert 518 * \code decoder != NULL \endcode 519 * \retval unsigned 520 * See above. 521 */ 522 FLAC_API unsigned FLAC__file_decoder_get_bits_per_sample(const FLAC__FileDecoder *decoder); 523 524 /** This is inherited from FLAC__SeekableStreamDecoder; see 525 * FLAC__seekable_stream_decoder_get_sample_rate(). 526 * 527 * \param decoder A decoder instance to query. 528 * \assert 529 * \code decoder != NULL \endcode 530 * \retval unsigned 531 * See above. 532 */ 533 FLAC_API unsigned FLAC__file_decoder_get_sample_rate(const FLAC__FileDecoder *decoder); 534 535 /** This is inherited from FLAC__SeekableStreamDecoder; see 536 * FLAC__seekable_stream_decoder_get_blocksize(). 537 * 538 * \param decoder A decoder instance to query. 539 * \assert 540 * \code decoder != NULL \endcode 541 * \retval unsigned 542 * See above. 543 */ 544 FLAC_API unsigned FLAC__file_decoder_get_blocksize(const FLAC__FileDecoder *decoder); 545 546 /** This is inherited from FLAC__SeekableStreamDecoder; see 547 * FLAC__seekable_stream_decoder_get_decode_position(). 548 * 549 * \param decoder A decoder instance to query. 550 * \param position Address at which to return the desired position. 551 * \assert 552 * \code decoder != NULL \endcode 553 * \code position != NULL \endcode 554 * \retval FLAC__bool 555 * \c true if successful, \c false if there was an error from 556 * the 'tell' callback. 557 */ 558 FLAC_API FLAC__bool FLAC__file_decoder_get_decode_position(const FLAC__FileDecoder *decoder, FLAC__uint64 *position); 559 560 /** Initialize the decoder instance. 561 * Should be called after FLAC__file_decoder_new() and 562 * FLAC__file_decoder_set_*() but before any of the 563 * FLAC__file_decoder_process_*() functions. Will set and return 564 * the decoder state, which will be FLAC__FILE_DECODER_OK if 565 * initialization succeeded. 566 * 567 * \param decoder An uninitialized decoder instance. 568 * \assert 569 * \code decoder != NULL \endcode 570 * \retval FLAC__FileDecoderState 571 * \c FLAC__FILE_DECODER_OK if initialization was successful; see 572 * FLAC__FileDecoderState for the meanings of other return values. 573 */ 574 FLAC_API FLAC__FileDecoderState FLAC__file_decoder_init(FLAC__FileDecoder *decoder); 575 576 /** Finish the decoding process. 577 * Flushes the decoding buffer, releases resources, resets the decoder 578 * settings to their defaults, and returns the decoder state to 579 * FLAC__FILE_DECODER_UNINITIALIZED. 580 * 581 * In the event of a prematurely-terminated decode, it is not strictly 582 * necessary to call this immediately before FLAC__file_decoder_delete() 583 * but it is good practice to match every FLAC__file_decoder_init() with 584 * a FLAC__file_decoder_finish(). 585 * 586 * \param decoder An uninitialized decoder instance. 587 * \assert 588 * \code decoder != NULL \endcode 589 * \retval FLAC__bool 590 * \c false if MD5 checking is on AND a STREAMINFO block was available 591 * AND the MD5 signature in the STREAMINFO block was non-zero AND the 592 * signature does not match the one computed by the decoder; else 593 * \c true. 594 */ 595 FLAC_API FLAC__bool FLAC__file_decoder_finish(FLAC__FileDecoder *decoder); 596 597 /** This is inherited from FLAC__SeekableStreamDecoder; see 598 * FLAC__seekable_stream_decoder_process_single(). 599 * 600 * \param decoder A decoder instance. 601 * \assert 602 * \code decoder != NULL \endcode 603 * \retval FLAC__bool 604 * See above. 605 */ 606 FLAC_API FLAC__bool FLAC__file_decoder_process_single(FLAC__FileDecoder *decoder); 607 608 /** This is inherited from FLAC__SeekableStreamDecoder; see 609 * FLAC__seekable_stream_decoder_process_until_end_of_metadata(). 610 * 611 * \param decoder A decoder instance. 612 * \assert 613 * \code decoder != NULL \endcode 614 * \retval FLAC__bool 615 * See above. 616 */ 617 FLAC_API FLAC__bool FLAC__file_decoder_process_until_end_of_metadata(FLAC__FileDecoder *decoder); 618 619 /** This is inherited from FLAC__SeekableStreamDecoder; see 620 * FLAC__seekable_stream_decoder_process_until_end_of_stream(). 621 * 622 * \param decoder A decoder instance. 623 * \assert 624 * \code decoder != NULL \endcode 625 * \retval FLAC__bool 626 * See above. 627 */ 628 FLAC_API FLAC__bool FLAC__file_decoder_process_until_end_of_file(FLAC__FileDecoder *decoder); 629 630 /** This is inherited from FLAC__SeekableStreamDecoder; see 631 * FLAC__seekable_stream_decoder_skip_single_frame(). 632 * 633 * \param decoder A decoder instance. 634 * \assert 635 * \code decoder != NULL \endcode 636 * \retval FLAC__bool 637 * See above. 638 */ 639 FLAC_API FLAC__bool FLAC__file_decoder_skip_single_frame(FLAC__FileDecoder *decoder); 640 641 /** Flush the input and seek to an absolute sample. 642 * This is inherited from FLAC__SeekableStreamDecoder; see 643 * FLAC__seekable_stream_decoder_seek_absolute(). 644 * 645 * \param decoder A decoder instance. 646 * \param sample The target sample number to seek to. 647 * \assert 648 * \code decoder != NULL \endcode 649 * \retval FLAC__bool 650 * \c true if successful, else \c false. 651 */ 652 FLAC_API FLAC__bool FLAC__file_decoder_seek_absolute(FLAC__FileDecoder *decoder, FLAC__uint64 sample); 653 654 /* \} */ 655 656 #ifdef __cplusplus 657 } 658 #endif 659 660 #endif