/* libFLAC - Free Lossless Audio Codec library * Copyright (C) 2004-2009 Josh Coalson * Copyright (C) 2011-2022 Xiph.Org Foundation * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * - Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * - Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * - Neither the name of the Xiph.org Foundation nor the names of its * contributors may be used to endorse or promote products derived from * this software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ #ifndef FLAC__CALLBACK_H #define FLAC__CALLBACK_H #include "ordinals.h" #include <stdlib.h> /* for size_t */ /** \file include/FLAC/callback.h * * \brief * This module defines the structures for describing I/O callbacks * to the other FLAC interfaces. * * See the detailed documentation for callbacks in the * \link flac_callbacks callbacks \endlink module. */ /** \defgroup flac_callbacks FLAC/callback.h: I/O callback structures * \ingroup flac * * \brief * This module defines the structures for describing I/O callbacks * to the other FLAC interfaces. * * The purpose of the I/O callback functions is to create a common way * for the metadata interfaces to handle I/O. * * Originally the metadata interfaces required filenames as the way of * specifying FLAC files to operate on. This is problematic in some * environments so there is an additional option to specify a set of * callbacks for doing I/O on the FLAC file, instead of the filename. * * In addition to the callbacks, a FLAC__IOHandle type is defined as an * opaque structure for a data source. * * The callback function prototypes are similar (but not identical) to the * stdio functions fread, fwrite, fseek, ftell, feof, and fclose. If you use * stdio streams to implement the callbacks, you can pass fread, fwrite, and * fclose anywhere a FLAC__IOCallback_Read, FLAC__IOCallback_Write, or * FLAC__IOCallback_Close is required, and a FILE* anywhere a FLAC__IOHandle * is required. \warning You generally CANNOT directly use fseek or ftell * for FLAC__IOCallback_Seek or FLAC__IOCallback_Tell since on most systems * these use 32-bit offsets and FLAC requires 64-bit offsets to deal with * large files. You will have to find an equivalent function (e.g. ftello), * or write a wrapper. The same is true for feof() since this is usually * implemented as a macro, not as a function whose address can be taken. * * \{ */ #ifdef __cplusplus extern "C" { #endif /** This is the opaque handle type used by the callbacks. Typically * this is a \c FILE* or address of a file descriptor. */ FLAC__IOHandle; /** Signature for the read callback. * The signature and semantics match POSIX fread() implementations * and can generally be used interchangeably. * * \param ptr The address of the read buffer. * \param size The size of the records to be read. * \param nmemb The number of records to be read. * \param handle The handle to the data source. * \retval size_t * The number of records read. */ FLAC__IOCallback_Read; /** Signature for the write callback. * The signature and semantics match POSIX fwrite() implementations * and can generally be used interchangeably. * * \param ptr The address of the write buffer. * \param size The size of the records to be written. * \param nmemb The number of records to be written. * \param handle The handle to the data source. * \retval size_t * The number of records written. */ FLAC__IOCallback_Write; /** Signature for the seek callback. * The signature and semantics mostly match POSIX fseek() WITH ONE IMPORTANT * EXCEPTION: the offset is a 64-bit type whereas fseek() is generally 'long' * and 32-bits wide. * * \param handle The handle to the data source. * \param offset The new position, relative to \a whence * \param whence \c SEEK_SET, \c SEEK_CUR, or \c SEEK_END * \retval int * \c 0 on success, \c -1 on error. */ FLAC__IOCallback_Seek; /** Signature for the tell callback. * The signature and semantics mostly match POSIX ftell() WITH ONE IMPORTANT * EXCEPTION: the offset is a 64-bit type whereas ftell() is generally 'long' * and 32-bits wide. * * \param handle The handle to the data source. * \retval FLAC__int64 * The current position on success, \c -1 on error. */ FLAC__IOCallback_Tell; /** Signature for the EOF callback. * The signature and semantics mostly match POSIX feof() but WATCHOUT: * on many systems, feof() is a macro, so in this case a wrapper function * must be provided instead. * * \param handle The handle to the data source. * \retval int * \c 0 if not at end of file, nonzero if at end of file. */ FLAC__IOCallback_Eof; /** Signature for the close callback. * The signature and semantics match POSIX fclose() implementations * and can generally be used interchangeably. * * \param handle The handle to the data source. * \retval int * \c 0 on success, \c EOF on error. */ FLAC__IOCallback_Close; /** A structure for holding a set of callbacks. * Each FLAC interface that requires a FLAC__IOCallbacks structure will * describe which of the callbacks are required. The ones that are not * required may be set to NULL. * * If the seek requirement for an interface is optional, you can signify that * a data source is not seekable by setting the \a seek field to \c NULL. */ FLAC__IOCallbacks; /* \} */ #ifdef __cplusplus } #endif #endif
Codebase Browser
chromium