callback.h - vx32 - Local 9vx git repository for patches.
(HTM) git clone git://r-36.net/vx32
(DIR) Log
(DIR) Files
(DIR) Refs
---
callback.h (7057B)
---
1 /* libFLAC - Free Lossless Audio Codec library
2 * Copyright (C) 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__CALLBACK_H
33 #define FLAC__CALLBACK_H
34
35 #include "ordinals.h"
36 #include <stdlib.h> /* for size_t */
37
38 /** \file include/FLAC/callback.h
39 *
40 * \brief
41 * This module defines the structures for describing I/O callbacks
42 * to the other FLAC interfaces.
43 *
44 * See the detailed documentation for callbacks in the
45 * \link flac_callbacks callbacks \endlink module.
46 */
47
48 /** \defgroup flac_callbacks FLAC/callback.h: I/O callback structures
49 * \ingroup flac
50 *
51 * \brief
52 * This module defines the structures for describing I/O callbacks
53 * to the other FLAC interfaces.
54 *
55 * The purpose of the I/O callback functions is to create a common way
56 * for the metadata interfaces to handle I/O.
57 *
58 * Originally the metadata interfaces required filenames as the way of
59 * specifying FLAC files to operate on. This is problematic in some
60 * environments so there is an additional option to specify a set of
61 * callbacks for doing I/O on the FLAC file, instead of the filename.
62 *
63 * In addition to the callbacks, a FLAC__IOHandle type is defined as an
64 * opaque structure for a data source.
65 *
66 * The callback function prototypes are similar (but not identical) to the
67 * stdio functions fread, fwrite, fseek, ftell, feof, and fclose. If you use
68 * stdio streams to implement the callbacks, you can pass fread, fwrite, and
69 * fclose anywhere a FLAC__IOCallback_Read, FLAC__IOCallback_Write, or
70 * FLAC__IOCallback_Close is required, and a FILE* anywhere a FLAC__IOHandle
71 * is required. \warning You generally can NOT directly use fseek or ftell
72 * for FLAC__IOCallback_Seek or FLAC__IOCallback_Tell since on most systems
73 * these use 32-bit offsets and FLAC requires 64-bit offsets to deal with
74 * large files. You will have to find an equivalent function (e.g. ftello),
75 * or write a wrapper. The same is true for feof() since this is usually
76 * implemented as a macro, not as a function whose address can be taken.
77 *
78 * \{
79 */
80
81 #ifdef __cplusplus
82 extern "C" {
83 #endif
84
85 typedef void* FLAC__IOHandle;
86
87 /** Signature for the read callback.
88 * The signature and semantics match POSIX fread() implementations
89 * and can generally be used interchangeably.
90 *
91 * \param ptr The address of the read buffer.
92 * \param size The size of the records to be read.
93 * \param nmemb The number of records to be read.
94 * \param handle The handle to the data source.
95 * \retval size_t
96 * The number of records read.
97 */
98 typedef size_t (*FLAC__IOCallback_Read) (void *ptr, size_t size, size_t nmemb, FLAC__IOHandle handle);
99
100 /** Signature for the write callback.
101 * The signature and semantics match POSIX fwrite() implementations
102 * and can generally be used interchangeably.
103 *
104 * \param ptr The address of the write buffer.
105 * \param size The size of the records to be written.
106 * \param nmemb The number of records to be written.
107 * \param handle The handle to the data source.
108 * \retval size_t
109 * The number of records written.
110 */
111 typedef size_t (*FLAC__IOCallback_Write) (const void *ptr, size_t size, size_t nmemb, FLAC__IOHandle handle);
112
113 /** Signature for the seek callback.
114 * The signature and semantics mostly match POSIX fseek() WITH ONE IMPORTANT
115 * EXCEPTION: the offset is a 64-bit type whereas fseek() is generally 'long'
116 * and 32-bits wide.
117 *
118 * \param handle The handle to the data source.
119 * \param offset The new position, relative to \a whence
120 * \param whence \c SEEK_SET, \c SEEK_CUR, or \c SEEK_END
121 * \retval int
122 * \c 0 on success, \c -1 on error.
123 */
124 typedef int (*FLAC__IOCallback_Seek) (FLAC__IOHandle handle, FLAC__int64 offset, int whence);
125
126 /** Signature for the tell callback.
127 * The signature and semantics mostly match POSIX ftell() WITH ONE IMPORTANT
128 * EXCEPTION: the offset is a 64-bit type whereas ftell() is generally 'long'
129 * and 32-bits wide.
130 *
131 * \param handle The handle to the data source.
132 * \retval FLAC__int64
133 * The current position on success, \c -1 on error.
134 */
135 typedef FLAC__int64 (*FLAC__IOCallback_Tell) (FLAC__IOHandle handle);
136
137 /** Signature for the EOF callback.
138 * The signature and semantics mostly match POSIX feof() but WATCHOUT:
139 * on many systems, feof() is a macro, so in this case a wrapper function
140 * must be provided instead.
141 *
142 * \param handle The handle to the data source.
143 * \retval int
144 * \c 0 if not at end of file, nonzero if at end of file.
145 */
146 typedef int (*FLAC__IOCallback_Eof) (FLAC__IOHandle handle);
147
148 /** Signature for the close callback.
149 * The signature and semantics match POSIX fclose() implementations
150 * and can generally be used interchangeably.
151 *
152 * \param handle The handle to the data source.
153 * \retval int
154 * \c 0 on success, \c EOF on error.
155 */
156 typedef int (*FLAC__IOCallback_Close) (FLAC__IOHandle handle);
157
158 /** A structure for holding a set of callbacks.
159 * Each FLAC interface that requires a FLAC__IOCallbacks structure will
160 * describe which of the callbacks are required. The ones that are not
161 * required may be set to NULL.
162 *
163 * If the seek requirement for an interface is optional, you can signify that
164 * a data sorce is not seekable by setting the \a seek field to \c NULL.
165 */
166 typedef struct {
167 FLAC__IOCallback_Read read;
168 FLAC__IOCallback_Write write;
169 FLAC__IOCallback_Seek seek;
170 FLAC__IOCallback_Tell tell;
171 FLAC__IOCallback_Eof eof;
172 FLAC__IOCallback_Close close;
173 } FLAC__IOCallbacks;
174
175 /* \} */
176
177 #ifdef __cplusplus
178 }
179 #endif
180
181 #endif