Audio plugin host https://kx.studio/carla
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

callback.h 7.3KB

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