1c74663799493f2b1e6123c18def94295d0afab7Kenny Root/* libFLAC - Free Lossless Audio Codec library 2c74663799493f2b1e6123c18def94295d0afab7Kenny Root * Copyright (C) 2004,2005,2006,2007 Josh Coalson 3c74663799493f2b1e6123c18def94295d0afab7Kenny Root * 4c74663799493f2b1e6123c18def94295d0afab7Kenny Root * Redistribution and use in source and binary forms, with or without 5c74663799493f2b1e6123c18def94295d0afab7Kenny Root * modification, are permitted provided that the following conditions 6c74663799493f2b1e6123c18def94295d0afab7Kenny Root * are met: 7c74663799493f2b1e6123c18def94295d0afab7Kenny Root * 8c74663799493f2b1e6123c18def94295d0afab7Kenny Root * - Redistributions of source code must retain the above copyright 9c74663799493f2b1e6123c18def94295d0afab7Kenny Root * notice, this list of conditions and the following disclaimer. 10c74663799493f2b1e6123c18def94295d0afab7Kenny Root * 11c74663799493f2b1e6123c18def94295d0afab7Kenny Root * - Redistributions in binary form must reproduce the above copyright 12c74663799493f2b1e6123c18def94295d0afab7Kenny Root * notice, this list of conditions and the following disclaimer in the 13c74663799493f2b1e6123c18def94295d0afab7Kenny Root * documentation and/or other materials provided with the distribution. 14c74663799493f2b1e6123c18def94295d0afab7Kenny Root * 15c74663799493f2b1e6123c18def94295d0afab7Kenny Root * - Neither the name of the Xiph.org Foundation nor the names of its 16c74663799493f2b1e6123c18def94295d0afab7Kenny Root * contributors may be used to endorse or promote products derived from 17c74663799493f2b1e6123c18def94295d0afab7Kenny Root * this software without specific prior written permission. 18c74663799493f2b1e6123c18def94295d0afab7Kenny Root * 19c74663799493f2b1e6123c18def94295d0afab7Kenny Root * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20c74663799493f2b1e6123c18def94295d0afab7Kenny Root * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21c74663799493f2b1e6123c18def94295d0afab7Kenny Root * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 22c74663799493f2b1e6123c18def94295d0afab7Kenny Root * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR 23c74663799493f2b1e6123c18def94295d0afab7Kenny Root * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 24c74663799493f2b1e6123c18def94295d0afab7Kenny Root * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 25c74663799493f2b1e6123c18def94295d0afab7Kenny Root * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 26c74663799493f2b1e6123c18def94295d0afab7Kenny Root * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 27c74663799493f2b1e6123c18def94295d0afab7Kenny Root * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 28c74663799493f2b1e6123c18def94295d0afab7Kenny Root * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 29c74663799493f2b1e6123c18def94295d0afab7Kenny Root * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30c74663799493f2b1e6123c18def94295d0afab7Kenny Root */ 31c74663799493f2b1e6123c18def94295d0afab7Kenny Root 32c74663799493f2b1e6123c18def94295d0afab7Kenny Root#ifndef FLAC__CALLBACK_H 33c74663799493f2b1e6123c18def94295d0afab7Kenny Root#define FLAC__CALLBACK_H 34c74663799493f2b1e6123c18def94295d0afab7Kenny Root 35c74663799493f2b1e6123c18def94295d0afab7Kenny Root#include "ordinals.h" 36c74663799493f2b1e6123c18def94295d0afab7Kenny Root#include <stdlib.h> /* for size_t */ 37c74663799493f2b1e6123c18def94295d0afab7Kenny Root 38c74663799493f2b1e6123c18def94295d0afab7Kenny Root/** \file include/FLAC/callback.h 39c74663799493f2b1e6123c18def94295d0afab7Kenny Root * 40c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \brief 41c74663799493f2b1e6123c18def94295d0afab7Kenny Root * This module defines the structures for describing I/O callbacks 42c74663799493f2b1e6123c18def94295d0afab7Kenny Root * to the other FLAC interfaces. 43c74663799493f2b1e6123c18def94295d0afab7Kenny Root * 44c74663799493f2b1e6123c18def94295d0afab7Kenny Root * See the detailed documentation for callbacks in the 45c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \link flac_callbacks callbacks \endlink module. 46c74663799493f2b1e6123c18def94295d0afab7Kenny Root */ 47c74663799493f2b1e6123c18def94295d0afab7Kenny Root 48c74663799493f2b1e6123c18def94295d0afab7Kenny Root/** \defgroup flac_callbacks FLAC/callback.h: I/O callback structures 49c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \ingroup flac 50c74663799493f2b1e6123c18def94295d0afab7Kenny Root * 51c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \brief 52c74663799493f2b1e6123c18def94295d0afab7Kenny Root * This module defines the structures for describing I/O callbacks 53c74663799493f2b1e6123c18def94295d0afab7Kenny Root * to the other FLAC interfaces. 54c74663799493f2b1e6123c18def94295d0afab7Kenny Root * 55c74663799493f2b1e6123c18def94295d0afab7Kenny Root * The purpose of the I/O callback functions is to create a common way 56c74663799493f2b1e6123c18def94295d0afab7Kenny Root * for the metadata interfaces to handle I/O. 57c74663799493f2b1e6123c18def94295d0afab7Kenny Root * 58c74663799493f2b1e6123c18def94295d0afab7Kenny Root * Originally the metadata interfaces required filenames as the way of 59c74663799493f2b1e6123c18def94295d0afab7Kenny Root * specifying FLAC files to operate on. This is problematic in some 60c74663799493f2b1e6123c18def94295d0afab7Kenny Root * environments so there is an additional option to specify a set of 61c74663799493f2b1e6123c18def94295d0afab7Kenny Root * callbacks for doing I/O on the FLAC file, instead of the filename. 62c74663799493f2b1e6123c18def94295d0afab7Kenny Root * 63c74663799493f2b1e6123c18def94295d0afab7Kenny Root * In addition to the callbacks, a FLAC__IOHandle type is defined as an 64c74663799493f2b1e6123c18def94295d0afab7Kenny Root * opaque structure for a data source. 65c74663799493f2b1e6123c18def94295d0afab7Kenny Root * 66c74663799493f2b1e6123c18def94295d0afab7Kenny Root * The callback function prototypes are similar (but not identical) to the 67c74663799493f2b1e6123c18def94295d0afab7Kenny Root * stdio functions fread, fwrite, fseek, ftell, feof, and fclose. If you use 68c74663799493f2b1e6123c18def94295d0afab7Kenny Root * stdio streams to implement the callbacks, you can pass fread, fwrite, and 69c74663799493f2b1e6123c18def94295d0afab7Kenny Root * fclose anywhere a FLAC__IOCallback_Read, FLAC__IOCallback_Write, or 70c74663799493f2b1e6123c18def94295d0afab7Kenny Root * FLAC__IOCallback_Close is required, and a FILE* anywhere a FLAC__IOHandle 71c74663799493f2b1e6123c18def94295d0afab7Kenny Root * is required. \warning You generally CANNOT directly use fseek or ftell 72c74663799493f2b1e6123c18def94295d0afab7Kenny Root * for FLAC__IOCallback_Seek or FLAC__IOCallback_Tell since on most systems 73c74663799493f2b1e6123c18def94295d0afab7Kenny Root * these use 32-bit offsets and FLAC requires 64-bit offsets to deal with 74c74663799493f2b1e6123c18def94295d0afab7Kenny Root * large files. You will have to find an equivalent function (e.g. ftello), 75c74663799493f2b1e6123c18def94295d0afab7Kenny Root * or write a wrapper. The same is true for feof() since this is usually 76c74663799493f2b1e6123c18def94295d0afab7Kenny Root * implemented as a macro, not as a function whose address can be taken. 77c74663799493f2b1e6123c18def94295d0afab7Kenny Root * 78c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \{ 79c74663799493f2b1e6123c18def94295d0afab7Kenny Root */ 80c74663799493f2b1e6123c18def94295d0afab7Kenny Root 81c74663799493f2b1e6123c18def94295d0afab7Kenny Root#ifdef __cplusplus 82c74663799493f2b1e6123c18def94295d0afab7Kenny Rootextern "C" { 83c74663799493f2b1e6123c18def94295d0afab7Kenny Root#endif 84c74663799493f2b1e6123c18def94295d0afab7Kenny Root 85c74663799493f2b1e6123c18def94295d0afab7Kenny Root/** This is the opaque handle type used by the callbacks. Typically 86c74663799493f2b1e6123c18def94295d0afab7Kenny Root * this is a \c FILE* or address of a file descriptor. 87c74663799493f2b1e6123c18def94295d0afab7Kenny Root */ 88c74663799493f2b1e6123c18def94295d0afab7Kenny Roottypedef void* FLAC__IOHandle; 89c74663799493f2b1e6123c18def94295d0afab7Kenny Root 90c74663799493f2b1e6123c18def94295d0afab7Kenny Root/** Signature for the read callback. 91c74663799493f2b1e6123c18def94295d0afab7Kenny Root * The signature and semantics match POSIX fread() implementations 92c74663799493f2b1e6123c18def94295d0afab7Kenny Root * and can generally be used interchangeably. 93c74663799493f2b1e6123c18def94295d0afab7Kenny Root * 94c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \param ptr The address of the read buffer. 95c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \param size The size of the records to be read. 96c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \param nmemb The number of records to be read. 97c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \param handle The handle to the data source. 98c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \retval size_t 99c74663799493f2b1e6123c18def94295d0afab7Kenny Root * The number of records read. 100c74663799493f2b1e6123c18def94295d0afab7Kenny Root */ 101c74663799493f2b1e6123c18def94295d0afab7Kenny Roottypedef size_t (*FLAC__IOCallback_Read) (void *ptr, size_t size, size_t nmemb, FLAC__IOHandle handle); 102c74663799493f2b1e6123c18def94295d0afab7Kenny Root 103c74663799493f2b1e6123c18def94295d0afab7Kenny Root/** Signature for the write callback. 104c74663799493f2b1e6123c18def94295d0afab7Kenny Root * The signature and semantics match POSIX fwrite() implementations 105c74663799493f2b1e6123c18def94295d0afab7Kenny Root * and can generally be used interchangeably. 106c74663799493f2b1e6123c18def94295d0afab7Kenny Root * 107c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \param ptr The address of the write buffer. 108c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \param size The size of the records to be written. 109c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \param nmemb The number of records to be written. 110c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \param handle The handle to the data source. 111c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \retval size_t 112c74663799493f2b1e6123c18def94295d0afab7Kenny Root * The number of records written. 113c74663799493f2b1e6123c18def94295d0afab7Kenny Root */ 114c74663799493f2b1e6123c18def94295d0afab7Kenny Roottypedef size_t (*FLAC__IOCallback_Write) (const void *ptr, size_t size, size_t nmemb, FLAC__IOHandle handle); 115c74663799493f2b1e6123c18def94295d0afab7Kenny Root 116c74663799493f2b1e6123c18def94295d0afab7Kenny Root/** Signature for the seek callback. 117c74663799493f2b1e6123c18def94295d0afab7Kenny Root * The signature and semantics mostly match POSIX fseek() WITH ONE IMPORTANT 118c74663799493f2b1e6123c18def94295d0afab7Kenny Root * EXCEPTION: the offset is a 64-bit type whereas fseek() is generally 'long' 119c74663799493f2b1e6123c18def94295d0afab7Kenny Root * and 32-bits wide. 120c74663799493f2b1e6123c18def94295d0afab7Kenny Root * 121c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \param handle The handle to the data source. 122c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \param offset The new position, relative to \a whence 123c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \param whence \c SEEK_SET, \c SEEK_CUR, or \c SEEK_END 124c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \retval int 125c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \c 0 on success, \c -1 on error. 126c74663799493f2b1e6123c18def94295d0afab7Kenny Root */ 127c74663799493f2b1e6123c18def94295d0afab7Kenny Roottypedef int (*FLAC__IOCallback_Seek) (FLAC__IOHandle handle, FLAC__int64 offset, int whence); 128c74663799493f2b1e6123c18def94295d0afab7Kenny Root 129c74663799493f2b1e6123c18def94295d0afab7Kenny Root/** Signature for the tell callback. 130c74663799493f2b1e6123c18def94295d0afab7Kenny Root * The signature and semantics mostly match POSIX ftell() WITH ONE IMPORTANT 131c74663799493f2b1e6123c18def94295d0afab7Kenny Root * EXCEPTION: the offset is a 64-bit type whereas ftell() is generally 'long' 132c74663799493f2b1e6123c18def94295d0afab7Kenny Root * and 32-bits wide. 133c74663799493f2b1e6123c18def94295d0afab7Kenny Root * 134c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \param handle The handle to the data source. 135c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \retval FLAC__int64 136c74663799493f2b1e6123c18def94295d0afab7Kenny Root * The current position on success, \c -1 on error. 137c74663799493f2b1e6123c18def94295d0afab7Kenny Root */ 138c74663799493f2b1e6123c18def94295d0afab7Kenny Roottypedef FLAC__int64 (*FLAC__IOCallback_Tell) (FLAC__IOHandle handle); 139c74663799493f2b1e6123c18def94295d0afab7Kenny Root 140c74663799493f2b1e6123c18def94295d0afab7Kenny Root/** Signature for the EOF callback. 141c74663799493f2b1e6123c18def94295d0afab7Kenny Root * The signature and semantics mostly match POSIX feof() but WATCHOUT: 142c74663799493f2b1e6123c18def94295d0afab7Kenny Root * on many systems, feof() is a macro, so in this case a wrapper function 143c74663799493f2b1e6123c18def94295d0afab7Kenny Root * must be provided instead. 144c74663799493f2b1e6123c18def94295d0afab7Kenny Root * 145c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \param handle The handle to the data source. 146c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \retval int 147c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \c 0 if not at end of file, nonzero if at end of file. 148c74663799493f2b1e6123c18def94295d0afab7Kenny Root */ 149c74663799493f2b1e6123c18def94295d0afab7Kenny Roottypedef int (*FLAC__IOCallback_Eof) (FLAC__IOHandle handle); 150c74663799493f2b1e6123c18def94295d0afab7Kenny Root 151c74663799493f2b1e6123c18def94295d0afab7Kenny Root/** Signature for the close callback. 152c74663799493f2b1e6123c18def94295d0afab7Kenny Root * The signature and semantics match POSIX fclose() implementations 153c74663799493f2b1e6123c18def94295d0afab7Kenny Root * and can generally be used interchangeably. 154c74663799493f2b1e6123c18def94295d0afab7Kenny Root * 155c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \param handle The handle to the data source. 156c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \retval int 157c74663799493f2b1e6123c18def94295d0afab7Kenny Root * \c 0 on success, \c EOF on error. 158c74663799493f2b1e6123c18def94295d0afab7Kenny Root */ 159c74663799493f2b1e6123c18def94295d0afab7Kenny Roottypedef int (*FLAC__IOCallback_Close) (FLAC__IOHandle handle); 160c74663799493f2b1e6123c18def94295d0afab7Kenny Root 161c74663799493f2b1e6123c18def94295d0afab7Kenny Root/** A structure for holding a set of callbacks. 162c74663799493f2b1e6123c18def94295d0afab7Kenny Root * Each FLAC interface that requires a FLAC__IOCallbacks structure will 163c74663799493f2b1e6123c18def94295d0afab7Kenny Root * describe which of the callbacks are required. The ones that are not 164c74663799493f2b1e6123c18def94295d0afab7Kenny Root * required may be set to NULL. 165c74663799493f2b1e6123c18def94295d0afab7Kenny Root * 166c74663799493f2b1e6123c18def94295d0afab7Kenny Root * If the seek requirement for an interface is optional, you can signify that 167c74663799493f2b1e6123c18def94295d0afab7Kenny Root * a data sorce is not seekable by setting the \a seek field to \c NULL. 168c74663799493f2b1e6123c18def94295d0afab7Kenny Root */ 169c74663799493f2b1e6123c18def94295d0afab7Kenny Roottypedef struct { 170c74663799493f2b1e6123c18def94295d0afab7Kenny Root FLAC__IOCallback_Read read; 171c74663799493f2b1e6123c18def94295d0afab7Kenny Root FLAC__IOCallback_Write write; 172c74663799493f2b1e6123c18def94295d0afab7Kenny Root FLAC__IOCallback_Seek seek; 173c74663799493f2b1e6123c18def94295d0afab7Kenny Root FLAC__IOCallback_Tell tell; 174c74663799493f2b1e6123c18def94295d0afab7Kenny Root FLAC__IOCallback_Eof eof; 175c74663799493f2b1e6123c18def94295d0afab7Kenny Root FLAC__IOCallback_Close close; 176c74663799493f2b1e6123c18def94295d0afab7Kenny Root} FLAC__IOCallbacks; 177c74663799493f2b1e6123c18def94295d0afab7Kenny Root 178c74663799493f2b1e6123c18def94295d0afab7Kenny Root/* \} */ 179c74663799493f2b1e6123c18def94295d0afab7Kenny Root 180c74663799493f2b1e6123c18def94295d0afab7Kenny Root#ifdef __cplusplus 181c74663799493f2b1e6123c18def94295d0afab7Kenny Root} 182c74663799493f2b1e6123c18def94295d0afab7Kenny Root#endif 183c74663799493f2b1e6123c18def94295d0afab7Kenny Root 184c74663799493f2b1e6123c18def94295d0afab7Kenny Root#endif 185