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