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