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