source/modules/juce_audio_formats/codecs/flac/callback.h

   1 /* libFLAC - Free Lossless Audio Codec library
   2  * Copyright (C) 2004-2009  Josh Coalson
   3  * Copyright (C) 2011-2014  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
  38 // JUCE: removed as JUCE already includes this and including stdlib
  39 // in FlacNamespace will cause problems
  40 //#include <stdlib.h>
  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 CANNOT 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  */
  84
  85 #ifdef __cplusplus
  86 extern "C" {
  87 #endif
  88
  89 /** This is the opaque handle type used by the callbacks.  Typically
  90  *  this is a \c FILE* or address of a file descriptor.
  91  */
  92 typedef void* FLAC__IOHandle;
  93
  94 /** Signature for the read callback.
  95  *  The signature and semantics match POSIX fread() implementations
  96  *  and can generally be used interchangeably.
  97  *
  98  * \param  ptr      The address of the read buffer.
  99  * \param  size     The size of the records to be read.
 100  * \param  nmemb    The number of records to be read.
 101  * \param  handle   The handle to the data source.
 102  * \retval size_t
 103  *    The number of records read.
 104  */
 105 typedef size_t (*FLAC__IOCallback_Read) (void *ptr, size_t size, size_t nmemb, FLAC__IOHandle handle);
 106
 107 /** Signature for the write callback.
 108  *  The signature and semantics match POSIX fwrite() implementations
 109  *  and can generally be used interchangeably.
 110  *
 111  * \param  ptr      The address of the write buffer.
 112  * \param  size     The size of the records to be written.
 113  * \param  nmemb    The number of records to be written.
 114  * \param  handle   The handle to the data source.
 115  * \retval size_t
 116  *    The number of records written.
 117  */
 118 typedef size_t (*FLAC__IOCallback_Write) (const void *ptr, size_t size, size_t nmemb, FLAC__IOHandle handle);
 119
 120 /** Signature for the seek callback.
 121  *  The signature and semantics mostly match POSIX fseek() WITH ONE IMPORTANT
 122  *  EXCEPTION: the offset is a 64-bit type whereas fseek() is generally 'long'
 123  *  and 32-bits wide.
 124  *
 125  * \param  handle   The handle to the data source.
 126  * \param  offset   The new position, relative to \a whence
 127  * \param  whence   \c SEEK_SET, \c SEEK_CUR, or \c SEEK_END
 128  * \retval int
 129  *    \c 0 on success, \c -1 on error.
 130  */
 131 typedef int (*FLAC__IOCallback_Seek) (FLAC__IOHandle handle, FLAC__int64 offset, int whence);
 132
 133 /** Signature for the tell callback.
 134  *  The signature and semantics mostly match POSIX ftell() WITH ONE IMPORTANT
 135  *  EXCEPTION: the offset is a 64-bit type whereas ftell() is generally 'long'
 136  *  and 32-bits wide.
 137  *
 138  * \param  handle   The handle to the data source.
 139  * \retval FLAC__int64
 140  *    The current position on success, \c -1 on error.
 141  */
 142 typedef FLAC__int64 (*FLAC__IOCallback_Tell) (FLAC__IOHandle handle);
 143
 144 /** Signature for the EOF callback.
 145  *  The signature and semantics mostly match POSIX feof() but WATCHOUT:
 146  *  on many systems, feof() is a macro, so in this case a wrapper function
 147  *  must be provided instead.
 148  *
 149  * \param  handle   The handle to the data source.
 150  * \retval int
 151  *    \c 0 if not at end of file, nonzero if at end of file.
 152  */
 153 typedef int (*FLAC__IOCallback_Eof) (FLAC__IOHandle handle);
 154
 155 /** Signature for the close callback.
 156  *  The signature and semantics match POSIX fclose() implementations
 157  *  and can generally be used interchangeably.
 158  *
 159  * \param  handle   The handle to the data source.
 160  * \retval int
 161  *    \c 0 on success, \c EOF on error.
 162  */
 163 typedef int (*FLAC__IOCallback_Close) (FLAC__IOHandle handle);
 164
 165 /** A structure for holding a set of callbacks.
 166  *  Each FLAC interface that requires a FLAC__IOCallbacks structure will
 167  *  describe which of the callbacks are required.  The ones that are not
 168  *  required may be set to NULL.
 169  *
 170  *  If the seek requirement for an interface is optional, you can signify that
 171  *  a data sorce is not seekable by setting the \a seek field to \c NULL.
 172  */
 173 typedef struct {
 174         FLAC__IOCallback_Read read;
 175         FLAC__IOCallback_Write write;
 176         FLAC__IOCallback_Seek seek;
 177         FLAC__IOCallback_Tell tell;
 178         FLAC__IOCallback_Eof eof;
 179         FLAC__IOCallback_Close close;
 180 } FLAC__IOCallbacks;
 181
 182 /* \} */
 183
 184 #ifdef __cplusplus
 185 }
 186 #endif
 187
 188 #endif