home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / FLAC / callback.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-09-10  |  7.0 KB  |  185 lines
  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
  185.