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