[pcsx_rearmed.git] / deps / flac-1.3.2 / include / FLAC / callback.h

/* libFLAC - Free Lossless Audio Codec library
 * Copyright (C) 2004-2009  Josh Coalson
 * Copyright (C) 2011-2016  Xiph.Org Foundation
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * - Redistributions of source code must retain the above copyright
 * notice, this list of conditions and the following disclaimer.
 *
 * - Redistributions in binary form must reproduce the above copyright
 * notice, this list of conditions and the following disclaimer in the
 * documentation and/or other materials provided with the distribution.
 *
 * - Neither the name of the Xiph.org Foundation nor the names of its
 * contributors may be used to endorse or promote products derived from
 * this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef FLAC__CALLBACK_H
#define FLAC__CALLBACK_H

#include "ordinals.h"
#include <stdlib.h> /* for size_t */

/** \file include/FLAC/callback.h
 *
 *  \brief
 *  This module defines the structures for describing I/O callbacks
 *  to the other FLAC interfaces.
 *
 *  See the detailed documentation for callbacks in the
 *  \link flac_callbacks callbacks \endlink module.
 */

/** \defgroup flac_callbacks FLAC/callback.h: I/O callback structures
 *  \ingroup flac
 *
 *  \brief
 *  This module defines the structures for describing I/O callbacks
 *  to the other FLAC interfaces.
 *
 *  The purpose of the I/O callback functions is to create a common way
 *  for the metadata interfaces to handle I/O.
 *
 *  Originally the metadata interfaces required filenames as the way of
 *  specifying FLAC files to operate on.  This is problematic in some
 *  environments so there is an additional option to specify a set of
 *  callbacks for doing I/O on the FLAC file, instead of the filename.
 *
 *  In addition to the callbacks, a FLAC__IOHandle type is defined as an
 *  opaque structure for a data source.
 *
 *  The callback function prototypes are similar (but not identical) to the
 *  stdio functions fread, fwrite, fseek, ftell, feof, and fclose.  If you use
 *  stdio streams to implement the callbacks, you can pass fread, fwrite, and
 *  fclose anywhere a FLAC__IOCallback_Read, FLAC__IOCallback_Write, or
 *  FLAC__IOCallback_Close is required, and a FILE* anywhere a FLAC__IOHandle
 *  is required.  \warning You generally CANNOT directly use fseek or ftell
 *  for FLAC__IOCallback_Seek or FLAC__IOCallback_Tell since on most systems
 *  these use 32-bit offsets and FLAC requires 64-bit offsets to deal with
 *  large files.  You will have to find an equivalent function (e.g. ftello),
 *  or write a wrapper.  The same is true for feof() since this is usually
 *  implemented as a macro, not as a function whose address can be taken.
 *
 * \{
 */

#ifdef __cplusplus
extern "C" {
#endif

/** This is the opaque handle type used by the callbacks.  Typically
 *  this is a \c FILE* or address of a file descriptor.
 */
typedef void* FLAC__IOHandle;

/** Signature for the read callback.
 *  The signature and semantics match POSIX fread() implementations
 *  and can generally be used interchangeably.
 *
 * \param  ptr      The address of the read buffer.
 * \param  size     The size of the records to be read.
 * \param  nmemb    The number of records to be read.
 * \param  handle   The handle to the data source.
 * \retval size_t
 *    The number of records read.
 */
typedef size_t (*FLAC__IOCallback_Read) (void *ptr, size_t size, size_t nmemb, FLAC__IOHandle handle);

/** Signature for the write callback.
 *  The signature and semantics match POSIX fwrite() implementations
 *  and can generally be used interchangeably.
 *
 * \param  ptr      The address of the write buffer.
 * \param  size     The size of the records to be written.
 * \param  nmemb    The number of records to be written.
 * \param  handle   The handle to the data source.
 * \retval size_t
 *    The number of records written.
 */
typedef size_t (*FLAC__IOCallback_Write) (const void *ptr, size_t size, size_t nmemb, FLAC__IOHandle handle);

/** Signature for the seek callback.
 *  The signature and semantics mostly match POSIX fseek() WITH ONE IMPORTANT
 *  EXCEPTION: the offset is a 64-bit type whereas fseek() is generally 'long'
 *  and 32-bits wide.
 *
 * \param  handle   The handle to the data source.
 * \param  offset   The new position, relative to \a whence
 * \param  whence   \c SEEK_SET, \c SEEK_CUR, or \c SEEK_END
 * \retval int
 *    \c 0 on success, \c -1 on error.
 */
typedef int (*FLAC__IOCallback_Seek) (FLAC__IOHandle handle, FLAC__int64 offset, int whence);

/** Signature for the tell callback.
 *  The signature and semantics mostly match POSIX ftell() WITH ONE IMPORTANT
 *  EXCEPTION: the offset is a 64-bit type whereas ftell() is generally 'long'
 *  and 32-bits wide.
 *
 * \param  handle   The handle to the data source.
 * \retval FLAC__int64
 *    The current position on success, \c -1 on error.
 */
typedef FLAC__int64 (*FLAC__IOCallback_Tell) (FLAC__IOHandle handle);

/** Signature for the EOF callback.
 *  The signature and semantics mostly match POSIX feof() but WATCHOUT:
 *  on many systems, feof() is a macro, so in this case a wrapper function
 *  must be provided instead.
 *
 * \param  handle   The handle to the data source.
 * \retval int
 *    \c 0 if not at end of file, nonzero if at end of file.
 */
typedef int (*FLAC__IOCallback_Eof) (FLAC__IOHandle handle);

/** Signature for the close callback.
 *  The signature and semantics match POSIX fclose() implementations
 *  and can generally be used interchangeably.
 *
 * \param  handle   The handle to the data source.
 * \retval int
 *    \c 0 on success, \c EOF on error.
 */
typedef int (*FLAC__IOCallback_Close) (FLAC__IOHandle handle);

/** A structure for holding a set of callbacks.
 *  Each FLAC interface that requires a FLAC__IOCallbacks structure will
 *  describe which of the callbacks are required.  The ones that are not
 *  required may be set to NULL.
 *
 *  If the seek requirement for an interface is optional, you can signify that
 *  a data sorce is not seekable by setting the \a seek field to \c NULL.
 */
typedef struct {
	FLAC__IOCallback_Read read;
	FLAC__IOCallback_Write write;
	FLAC__IOCallback_Seek seek;
	FLAC__IOCallback_Tell tell;
	FLAC__IOCallback_Eof eof;
	FLAC__IOCallback_Close close;
} FLAC__IOCallbacks;

/* \} */

#ifdef __cplusplus
}
#endif

#endif
Commit	Line	Data
ce188d4d	1	/* libFLAC - Free Lossless Audio Codec library
	2	* Copyright (C) 2004-2009 Josh Coalson
	3	* Copyright (C) 2011-2016 Xiph.Org Foundation
	4	*
	5	* Redistribution and use in source and binary forms, with or without
	6	* modification, are permitted provided that the following conditions
	7	* are met:
	8	*
	9	* - Redistributions of source code must retain the above copyright
	10	* notice, this list of conditions and the following disclaimer.
	11	*
	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.
	15	*
	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.
	19	*
	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.
	31	*/
	32
	33	#ifndef FLAC__CALLBACK_H
	34	#define FLAC__CALLBACK_H
	35
	36	#include "ordinals.h"
	37	#include <stdlib.h> /* for size_t */
	38
	39	/** \file include/FLAC/callback.h
	40	*
	41	* \brief
	42	* This module defines the structures for describing I/O callbacks
	43	* to the other FLAC interfaces.
	44	*
	45	* See the detailed documentation for callbacks in the
	46	* \link flac_callbacks callbacks \endlink module.
	47	*/
	48
	49	/** \defgroup flac_callbacks FLAC/callback.h: I/O callback structures
	50	* \ingroup flac
	51	*
	52	* \brief
	53	* This module defines the structures for describing I/O callbacks
	54	* to the other FLAC interfaces.
	55	*
	56	* The purpose of the I/O callback functions is to create a common way
	57	* for the metadata interfaces to handle I/O.
	58	*
	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.
	63	*
	64	* In addition to the callbacks, a FLAC__IOHandle type is defined as an
65	* opaque structure for a data source.
66	*
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.
78	*
79	* \{
80	*/
81
82	#ifdef __cplusplus
83	extern "C" {
84	#endif
85
86	/** This is the opaque handle type used by the callbacks. Typically
87	* this is a \c FILE* or address of a file descriptor.
88	*/
89	typedef void* FLAC__IOHandle;
90
91	/** Signature for the read callback.
92	* The signature and semantics match POSIX fread() implementations
93	* and can generally be used interchangeably.
94	*
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.
99	* \retval size_t
100	* The number of records read.
101	*/
102	typedef size_t (FLAC__IOCallback_Read) (void ptr, size_t size, size_t nmemb, FLAC__IOHandle handle);
103
104	/** Signature for the write callback.
105	* The signature and semantics match POSIX fwrite() implementations
106	* and can generally be used interchangeably.
107	*
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.
112	* \retval size_t
113	* The number of records written.
114	*/
115	typedef size_t (FLAC__IOCallback_Write) (const void ptr, size_t size, size_t nmemb, FLAC__IOHandle handle);
116
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'
120	* and 32-bits wide.
121	*
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
125	* \retval int
126	* \c 0 on success, \c -1 on error.
127	*/
128	typedef int (*FLAC__IOCallback_Seek) (FLAC__IOHandle handle, FLAC__int64 offset, int whence);
129
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'
133	* and 32-bits wide.
134	*
135	* \param handle The handle to the data source.
136	* \retval FLAC__int64
137	* The current position on success, \c -1 on error.
138	*/
139	typedef FLAC__int64 (*FLAC__IOCallback_Tell) (FLAC__IOHandle handle);
140
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.
145	*
146	* \param handle The handle to the data source.
147	* \retval int
148	* \c 0 if not at end of file, nonzero if at end of file.
149	*/
150	typedef int (*FLAC__IOCallback_Eof) (FLAC__IOHandle handle);
151
152	/** Signature for the close callback.
153	* The signature and semantics match POSIX fclose() implementations
154	* and can generally be used interchangeably.
155	*
156	* \param handle The handle to the data source.
157	* \retval int
158	* \c 0 on success, \c EOF on error.
159	*/
160	typedef int (*FLAC__IOCallback_Close) (FLAC__IOHandle handle);
161
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.
166	*
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.
169	*/
170	typedef struct {
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;
177	} FLAC__IOCallbacks;
178
179	/* \} */
180
181	#ifdef __cplusplus
182	}
183	#endif
184
185	#endif