opusfile.h 85.2 KB
 Timothy B. Terriberry committed Sep 16, 2012 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 /******************************************************************** * * * THIS FILE IS PART OF THE libopusfile SOFTWARE CODEC SOURCE CODE. * * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS * * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE * * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING. * * * * THE libopusfile SOURCE CODE IS (C) COPYRIGHT 1994-2012 * * by the Xiph.Org Foundation and contributors http://www.xiph.org/ * * * ******************************************************************** function: stdio-based convenience library for opening/seeking/decoding last mod: $Id: vorbisfile.h 17182 2010-04-29 03:48:32Z xiphmont$ ********************************************************************/  Timothy B. Terriberry committed Sep 17, 2012 17 18 #if !defined(_opusfile_h) # define _opusfile_h (1)  Timothy B. Terriberry committed Oct 20, 2012 19 # include  Timothy B. Terriberry committed Sep 16, 2012 20   Timothy B. Terriberry committed Sep 23, 2012 21 22 23 24 25 26 27 28 29 30 31 32 33 34 /**\mainpage \section Introduction This is the documentation for the libopusfile C API. The libopusfile package provides a convenient high-level API for decoding and basic manipulation of all Ogg Opus audio streams. libopusfile is implemented as a layer on top of Xiph.Org's reference libogg and libopus libraries.  Timothy B. Terriberry committed Nov 11, 2012 35  libopusfile provides several sets of built-in routines for  Timothy B. Terriberry committed Sep 23, 2012 36 37 38 39  file/stream access, and may also use custom stream I/O routines provided by the embedded environment. There are built-in I/O routines provided for ANSI-compliant stdio (FILE *), memory buffers, and URLs  Timothy B. Terriberry committed Oct 20, 2012 40  (including URLs, plus optionally and URLs).  Timothy B. Terriberry committed Sep 23, 2012 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55  \section Organization The main API is divided into several sections: - \ref stream_open_close - \ref stream_info - \ref stream_decoding - \ref stream_seeking Several additional sections are not tied to the main API. - \ref stream_callbacks - \ref header_info - \ref error_codes*/  Timothy B. Terriberry committed Sep 16, 2012 56 57 58 59 60 61 # if defined(__cplusplus) extern "C" { # endif # include # include  Ralph Giles committed Sep 16, 2012 62 # include  Timothy B. Terriberry committed Sep 16, 2012 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93  /*Enable special features for gcc and gcc-compatible compilers.*/ # if !defined(OP_GNUC_PREREQ) # if defined(__GNUC__)&&defined(__GNUC_MINOR__) # define OP_GNUC_PREREQ(_maj,_min) \ ((__GNUC__<<16)+__GNUC_MINOR__>=((_maj)<<16)+(_min)) # else # define OP_GNUC_PREREQ(_maj,_min) 0 # endif # endif # if OP_GNUC_PREREQ(4,0) # pragma GCC visibility push(default) # endif typedef struct OpusHead OpusHead; typedef struct OpusTags OpusTags; typedef struct OggOpusFile OggOpusFile; /*Warning attributes for libopusfile functions.*/ # if OP_GNUC_PREREQ(3,4) # define OP_WARN_UNUSED_RESULT __attribute__((__warn_unused_result__)) # else # define OP_WARN_UNUSED_RESULT # endif # if OP_GNUC_PREREQ(3,4) # define OP_ARG_NONNULL(_x) __attribute__((__nonnull__(_x))) # else # define OP_ARG_NONNULL(_x) # endif  Timothy B. Terriberry committed Sep 22, 2012 94 95 96 97 98 99 100 101 102 /**\defgroup error_codes Error Codes*/ /*@{*/ /**\name List of possible error codes Many of the functions in this library return a negative error code when a function fails. This list provides a brief explanation of the common errors. See each individual function for more details on what a specific error code means in that context.*/ /*@{*/  Timothy B. Terriberry committed Sep 24, 2012 103   Timothy B. Terriberry committed Sep 16, 2012 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 /**A request did not succeed.*/ #define OP_FALSE (-1) /*Currently not used externally.*/ #define OP_EOF (-2) /**There was a hole in the page sequence numbers (e.g., a page was corrupt or missing).*/ #define OP_HOLE (-3) /**An underlying read, seek, or tell operation failed when it should have succeeded.*/ #define OP_EREAD (-128) /**A NULL pointer was passed where one was unexpected, or an internal memory allocation failed, or an internal library error was encountered.*/ #define OP_EFAULT (-129) /**The stream used a feature that is not implemented, such as an unsupported channel family.*/ #define OP_EIMPL (-130) /**One or more parameters to a function were invalid.*/ #define OP_EINVAL (-131)  Timothy B. Terriberry committed Sep 23, 2012 123 /**A purported Ogg Opus stream did not begin with an Ogg page, a purported  Timothy B. Terriberry committed Sep 16, 2012 124  header packet did not start with one of the required strings, "OpusHead" or  Timothy B. Terriberry committed Sep 23, 2012 125 126  "OpusTags", or a link in a chained file was encountered that did not contain any logical Opus streams.*/  Timothy B. Terriberry committed Sep 16, 2012 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 #define OP_ENOTFORMAT (-132) /**A required header packet was not properly formatted, contained illegal values, or was missing altogether.*/ #define OP_EBADHEADER (-133) /**The ID header contained an unrecognized version number.*/ #define OP_EVERSION (-134) /*Currently not used at all.*/ #define OP_ENOTAUDIO (-135) /**An audio packet failed to decode properly. This is usually caused by a multistream Ogg packet where the durations of the individual Opus packets contained in it are not all the same.*/ #define OP_EBADPACKET (-136) /**We failed to find data we had seen before, or the bitstream structure was sufficiently malformed that seeking to the target destination was impossible.*/ #define OP_EBADLINK (-137) /**An operation that requires seeking was requested on an unseekable stream.*/ #define OP_ENOSEEK (-138) /**The first or last granule position of a link failed basic validity checks.*/ #define OP_EBADTIMESTAMP (-139)  Timothy B. Terriberry committed Sep 24, 2012 147   Timothy B. Terriberry committed Sep 22, 2012 148 149 150 151 152 /*@}*/ /*@}*/ /**\defgroup header_info Header Information*/ /*@{*/  Timothy B. Terriberry committed Sep 16, 2012 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232  /**The maximum number of channels in an Ogg Opus stream.*/ #define OPUS_CHANNEL_COUNT_MAX (255) /**Ogg Opus bitstream information. This contains the basic playback parameters for a stream, and corresponds to the initial ID header packet of an Ogg Opus stream.*/ struct OpusHead{ /**The Ogg Opus format version, in the range 0...255. The top 4 bits represent a "major" version, and the bottom four bits represent backwards-compatible "minor" revisions. The current specification describes version 1. This library will recognize versions up through 15 as backwards compatible with the current specification. An earlier draft of the specification described a version 0, but the only difference between version 1 and version 0 is that version 0 did not specify the semantics for handling the version field.*/ int version; /**The number of channels, in the range 1...255.*/ int channel_count; /**The number of samples that should be discarded from the beginning of the stream.*/ unsigned pre_skip; /**The sampling rate of the original input. All Opus audio is coded at 48 kHz, and should also be decoded at 48 kHz for playback (unless the target hardware does not support this sampling rate). However, this field may be used to resample the audio back to the original sampling rate, for example, when saving the output to a file.*/ opus_uint32 input_sample_rate; /**The gain to apply to the decoded output, in dB, as a Q8 value in the range -32768...32767. The decoder will automatically scale the output by pow(10,output_gain/(20.0*256)).*/ int output_gain; /**The channel mapping family, in the range 0...255. Channel mapping family 0 covers mono or stereo in a single stream. Channel mapping family 1 covers 1 to 8 channels in one or more streams, using the Vorbis speaker assignments. Channel mapping family 255 covers 1 to 255 channels in one or more streams, but without any defined speaker assignment.*/ int mapping_family; /**The number of Opus streams in each Ogg packet, in the range 1...255.*/ int stream_count; /**The number of coupled Opus streams in each Ogg packet, in the range 0...127. This must satisfy 0 <= coupled_count <= stream_count and coupled_count + stream_count <= 255. The coupled streams appear first, before all uncoupled streams, in an Ogg Opus packet.*/ int coupled_count; /**The mapping from coded stream channels to output channels. Let index=mapping[k] be the value for channel k. If index<2*coupled_count, then it refers to the left channel from stream (index/2) if even, and the right channel from stream (index/2) if odd. Otherwise, it refers to the output of the uncoupled stream (index-coupled_count).*/ unsigned char mapping[OPUS_CHANNEL_COUNT_MAX]; }; /**The metadata from an Ogg Opus stream. This structure holds the in-stream metadata corresponding to the 'comment' header packet of an Ogg Opus stream. The comment header is meant to be used much like someone jotting a quick note on the label of a CD. It should be a short, to the point text note that can be more than a couple words, but not more than a short paragraph. The metadata is stored as a series of (tag, value) pairs, in length-encoded string vectors, using the same format as Vorbis (without the final "framing bit"), Theora, and Speex, except for the packet header. The first occurrence of the '=' character delimits the tag and value. A particular tag may occur more than once, and order is significant. The character set encoding for the strings is always UTF-8, but the tag names are limited to ASCII, and treated as case-insensitive. See the Vorbis comment header specification for details.  Timothy B. Terriberry committed Oct 20, 2012 233  In filling in this structure, libopusfile will null-terminate the  Timothy B. Terriberry committed Sep 16, 2012 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256  #user_comments strings for safety. However, the bitstream format itself treats them as 8-bit clean vectors, possibly containing NUL characters, so the #comment_lengths array should be treated as their authoritative length. This structure is binary and source-compatible with a vorbis_comment, and pointers to it may be freely cast to vorbis_comment pointers, and vice versa. It is provided as a separate type to avoid introducing a compile-time dependency on the libvorbis headers.*/ struct OpusTags{ /**The array of comment string vectors.*/ char **user_comments; /**An array of the corresponding length of each vector, in bytes.*/ int *comment_lengths; /**The total number of comment streams.*/ int comments; /**The null-terminated vendor string. This identifies the software used to encode the stream.*/ char *vendor; }; /**\name Functions for manipulating header data  Timothy B. Terriberry committed Sep 23, 2012 257   Timothy B. Terriberry committed Sep 16, 2012 258  These functions manipulate the #OpusHead and #OpusTags structures,  Timothy B. Terriberry committed Sep 23, 2012 259 260 261 262  which describe the audio parameters and tag-value metadata, respectively. These can be used to query the headers returned by libopusfile, or to parse Opus headers from sources other than an Ogg Opus stream, provided they use the same format.*/  Timothy B. Terriberry committed Sep 16, 2012 263 /*@{*/  Timothy B. Terriberry committed Sep 17, 2012 264   Timothy B. Terriberry committed Sep 16, 2012 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 /**Parses the contents of the ID header packet of an Ogg Opus stream. \param[out] _head Returns the contents of the parsed packet. The contents of this structure are untouched on error. This may be NULL to merely test the header for validity. \param[in] _data The contents of the ID header packet. \param _len The number of bytes of data in the ID header packet. \return 0 on success or a negative value on error. \retval #OP_ENOTFORMAT If the data does not start with the "OpusHead" string. \retval #OP_EVERSION If the version field signaled a version this library does not know how to parse. \retval #OP_EIMPL If the channel mapping family was 255, which general purpose players should not attempt to play. \retval #OP_EBADHEADER If the contents of the packet otherwise violate the Ogg Opus specification:
• Insufficient data,
• Too much data for the known minor versions,
• An unrecognized channel mapping family,
• Zero channels or too many channels,
• Zero coded streams,
• Too many coupled streams, or
• An invalid channel mapping index.
*/ OP_WARN_UNUSED_RESULT int opus_head_parse(OpusHead *_head, const unsigned char *_data,size_t _len) OP_ARG_NONNULL(2);  Timothy B. Terriberry committed Sep 17, 2012 292   Timothy B. Terriberry committed Sep 16, 2012 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 /**Converts a granule position to a sample offset for a given Ogg Opus stream. The sample offset is simply _gp-_head->pre_skip. Granule position values smaller than OpusHead#pre_skip correspond to audio that should never be played, and thus have no associated sample offset. This function returns -1 for such values. This function also correctly handles extremely large granule positions, which may have wrapped around to a negative number when stored in a signed ogg_int64_t value. \param _head The #OpusHead information from the ID header of the stream. \param _gp The granule position to convert. \return The sample offset associated with the given granule position (counting at a 48 kHz sampling rate), or the special value -1 on error (i.e., the granule position was smaller than the pre-skip amount).*/ ogg_int64_t opus_granule_sample(const OpusHead *_head,ogg_int64_t _gp) OP_ARG_NONNULL(1); /**Parses the contents of the 'comment' header packet of an Ogg Opus stream. \param[out] _tags An uninitialized #OpusTags structure. This returns the contents of the parsed packet. The contents of this structure are untouched on error. This may be NULL to merely test the header for validity. \param[in] _data The contents of the 'comment' header packet. \param _len The number of bytes of data in the 'info' header packet. \retval 0 Success. \retval #OP_ENOTFORMAT If the data does not start with the "OpusTags" string. \retval #OP_EBADHEADER If the contents of the packet otherwise violate the Ogg Opus specification. \retval #OP_EFAULT If there wasn't enough memory to store the tags.*/ OP_WARN_UNUSED_RESULT int opus_tags_parse(OpusTags *_tags, const unsigned char *_data,size_t _len) OP_ARG_NONNULL(2);  Timothy B. Terriberry committed Sep 17, 2012 326   Timothy B. Terriberry committed Sep 16, 2012 327 328 329 330 331 /**Initializes an #OpusTags structure. This should be called on a freshly allocated #OpusTags structure before attempting to use it. \param _tags The #OpusTags structure to initialize.*/ void opus_tags_init(OpusTags *_tags) OP_ARG_NONNULL(1);  Timothy B. Terriberry committed Sep 17, 2012 332   Timothy B. Terriberry committed Sep 16, 2012 333 334 335 336 337 /**Add a (tag, value) pair to an initialized #OpusTags structure. \note Neither opus_tags_add() nor opus_tags_add_comment() support values containing embedded NULs, although the bitstream format does support them. To add such tags, you will need to manipulate the #OpusTags structure directly.  Timothy B. Terriberry committed Sep 23, 2012 338 339 340 341  \param _tags The #OpusTags structure to add the (tag, value) pair to. \param _tag A NUL-terminated, case-insensitive, ASCII string containing the tag to add (without an '=' character). \param _value A NUL-terminated UTF-8 containing the corresponding value.  Timothy B. Terriberry committed Sep 17, 2012 342  \return 0 on success, or a negative value on failure.  Timothy B. Terriberry committed Sep 30, 2012 343  \retval #OP_EFAULT An internal memory allocation failed.*/  Timothy B. Terriberry committed Sep 16, 2012 344 345 int opus_tags_add(OpusTags *_tags,const char *_tag,const char *_value) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2) OP_ARG_NONNULL(3);  Timothy B. Terriberry committed Sep 17, 2012 346   Timothy B. Terriberry committed Sep 16, 2012 347 348 349 350 351 352 353 /**Add a comment to an initialized #OpusTags structure. \note Neither opus_tags_add_comment() nor opus_tags_add() support comments containing embedded NULs, although the bitstream format does support them. To add such tags, you will need to manipulate the #OpusTags structure directly. \param _tags The #OpusTags structure to add the comment to. \param _comment A NUL-terminated UTF-8 string containing the comment in  Timothy B. Terriberry committed Sep 17, 2012 354 355  "TAG=value" form. \return 0 on success, or a negative value on failure.  Timothy B. Terriberry committed Sep 30, 2012 356  \retval #OP_EFAULT An internal memory allocation failed.*/  Timothy B. Terriberry committed Sep 16, 2012 357 358 int opus_tags_add_comment(OpusTags *_tags,const char *_comment) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);  Timothy B. Terriberry committed Sep 17, 2012 359   Timothy B. Terriberry committed Sep 16, 2012 360 361 362 363 364 365 366 367 368 369 370 371 372 373 /**Look up a comment value by its tag. \param _tags An initialized #OpusTags structure. \param _tag The tag to look up. \param _count The instance of the tag. The same tag can appear multiple times, each with a distinct value, so an index is required to retrieve them all. The order in which these values appear is significant and should be preserved. Use opus_tags_query_count() to get the legal range for the \a _count parameter. \return A pointer to the queried tag's value. This points directly to data in the #OpusTags structure. It should not be modified or freed by the application, and modifications to the structure may invalidate the pointer.  Timothy B. Terriberry committed Sep 30, 2012 374  \retval NULL If no matching tag is found.*/  Timothy B. Terriberry committed Sep 16, 2012 375 376 const char *opus_tags_query(const OpusTags *_tags,const char *_tag,int _count) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);  Timothy B. Terriberry committed Sep 17, 2012 377   Timothy B. Terriberry committed Sep 16, 2012 378 379 380 381 382 383 384 385 386 /**Look up the number of instances of a tag. Call this first when querying for a specific tag and then iterate over the number of instances with separate calls to opus_tags_query() to retrieve all the values for that tag in order. \param _tags An initialized #OpusTags structure. \param _tag The tag to look up. \return The number of instances of this particular tag.*/ int opus_tags_query_count(const OpusTags *_tags,const char *_tag) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);  Timothy B. Terriberry committed Sep 17, 2012 387   Timothy B. Terriberry committed Sep 16, 2012 388 389 390 391 392 393 394 395 396 /**Clears the #OpusTags structure. This should be called on an #OpusTags structure after it is no longer needed. It will free all memory used by the structure members. \param _tags The #OpusTags structure to clear.*/ void opus_tags_clear(OpusTags *_tags) OP_ARG_NONNULL(1); /*@}*/  Timothy B. Terriberry committed Sep 22, 2012 397 398 /*@}*/  Timothy B. Terriberry committed Oct 20, 2012 399 /**\defgroup url_options URL Reading Options*/  Timothy B. Terriberry committed Sep 22, 2012 400 /*@{*/  Timothy B. Terriberry committed Oct 20, 2012 401 402 403 404 405 406 407 408 /**\name URL reading options Options for op_url_stream_create() and associated functions. These allow you to provide proxy configuration parameters, skip SSL certificate checks, etc. Options are processed in order, and if the same option is passed multiple times, only the value specified by the last occurrence has an effect (unless otherwise specified). They may be expanded in the future.*/  Timothy B. Terriberry committed Sep 22, 2012 409 410 /*@{*/  Timothy B. Terriberry committed Oct 20, 2012 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 /*These are the raw numbers used to define the request codes. They should not be used directly.*/ #define OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST (6464) #define OP_HTTP_PROXY_HOST_REQUEST (6528) #define OP_HTTP_PROXY_PORT_REQUEST (6592) #define OP_HTTP_PROXY_USER_REQUEST (6656) #define OP_HTTP_PROXY_PASS_REQUEST (6720) #define OP_URL_OPT(_request) ((_request)+(char *)0) /*These macros trigger compilation errors or warnings if the wrong types are provided to one of the URL options.*/ #define OP_CHECK_INT(_x) ((void)((_x)==(opus_int32)0),(opus_int32)(_x)) #define OP_CHECK_CONST_CHAR_PTR(_x) ((_x)+((_x)-(const char *)(_x))) /**Skip the certificate check when connecting via TLS/SSL (https). \param _b opus_int32: Whether or not to skip the certificate check. The check will be skipped if \a _b is non-zero, and will not be skipped if \a _b is zero. \hideinitializer*/ #define OP_SSL_SKIP_CERTIFICATE_CHECK(_b) \ OP_URL_OPT(OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST),OP_CHECK_INT(_b) /**Proxy connections through the given host. If no port is specified via #OP_HTTP_PROXY_PORT, the port number defaults to 8080 (http-alt). All proxy parameters are ignored for non-http and non-https URLs. \param _host const char *: The proxy server hostname. This may be NULL to disable the use of a proxy server. \hideinitializer*/ #define OP_HTTP_PROXY_HOST(_host) \ OP_URL_OPT(OP_HTTP_PROXY_HOST_REQUEST),OP_CHECK_CONST_CHAR_PTR(_host) /**Use the given port when proxying connections. This option only has an effect if #OP_HTTP_PROXY_HOST is specified with a non-NULL \a _host. If this option is not provided, the proxy port number defaults to 8080 (http-alt). All proxy parameters are ignored for non-http and non-https URLs. \param _port opus_int32: The proxy server port. This must be in the range 0...65535 (inclusive), or the URL function this is passed to will fail. \hideinitializer*/ #define OP_HTTP_PROXY_PORT(_port) \ OP_URL_OPT(OP_HTTP_PROXY_PORT_REQUEST),OP_CHECK_INT(_port) /**Use the given user name for authentication when proxying connections. All proxy parameters are ignored for non-http and non-https URLs. \param _user const char *: The proxy server user name. This may be NULL to disable proxy authentication. A non-NULL value only has an effect if #OP_HTTP_PROXY_HOST and #OP_HTTP_PROXY_PASS are also specified with non-NULL arguments. \hideinitializer*/ #define OP_HTTP_PROXY_USER(_user) \ OP_URL_OPT(OP_HTTP_PROXY_USER_REQUEST),OP_CHECK_CONST_CHAR_PTR(_host) /**Use the given password for authentication when proxying connections. All proxy parameters are ignored for non-http and non-https URLs. \param _pass const char *: The proxy server password. This may be NULL to disable proxy authentication. A non-NULL value only has an effect if #OP_HTTP_PROXY_HOST and #OP_HTTP_PROXY_USER are also specified with non-NULL arguments. \hideinitializer*/ #define OP_HTTP_PROXY_PASS(_pass) \ OP_URL_OPT(OP_HTTP_PROXY_PASS_REQUEST),OP_CHECK_CONST_CHAR_PTR(_host)  Timothy B. Terriberry committed Sep 22, 2012 484 485 486 487  /*@}*/ /*@}*/  Timothy B. Terriberry committed Sep 23, 2012 488 /**\defgroup stream_callbacks Abstract Stream Reading Interface*/  Timothy B. Terriberry committed Sep 22, 2012 489 /*@{*/  Timothy B. Terriberry committed Sep 16, 2012 490 491 492 493 494 495 /**\name Functions for reading from streams These functions define the interface used to read from and seek in a stream of data. A stream does not need to implement seeking, but the decoder will not be able to seek if it does not do so. These functions also include some convenience routines for working with  Timothy B. Terriberry committed Sep 23, 2012 496 497  standard FILE pointers, complete streams stored in a single block of memory, or URLs.*/  Timothy B. Terriberry committed Sep 16, 2012 498 499 500 501 /*@{*/ typedef struct OpusFileCallbacks OpusFileCallbacks;  Timothy B. Terriberry committed Oct 20, 2012 502 503 504 505 506 507 508 509 510 /**Reads up to \a _nbytes bytes of data from \a _stream. \param _stream The stream to read from. \param[out] _ptr The buffer to store the data in. \param _nbytes The maximum number of bytes to read. This function may return fewer, though it will not return zero unless it reaches end-of-file. \return The number of bytes successfully read, or a negative value on error.*/ typedef int (*op_read_func)(void *_stream,unsigned char *_ptr,int _nbytes);  Timothy B. Terriberry committed Sep 17, 2012 511   Timothy B. Terriberry committed Sep 16, 2012 512 513 514 515 516 517 518 519 520 521 /**Sets the position indicator for \a _stream. The new position, measured in bytes, is obtained by adding \a _offset bytes to the position specified by \a _whence. If \a _whence is set to SEEK_SET, SEEK_CUR, or SEEK_END, the offset is relative to the start of the stream, the current position indicator, or end-of-file, respectively. \retval 0 Success. \retval -1 Seeking is not supported or an error occurred. errno need not be set.*/ typedef int (*op_seek_func)(void *_stream,opus_int64 _offset,int _whence);  Timothy B. Terriberry committed Sep 17, 2012 522   Timothy B. Terriberry committed Sep 16, 2012 523 524 525 /**Obtains the current value of the position indicator for \a _stream. \return The current position indicator.*/ typedef opus_int64 (*op_tell_func)(void *_stream);  Timothy B. Terriberry committed Sep 17, 2012 526   Timothy B. Terriberry committed Sep 16, 2012 527 528 529 530 531 532 /**Closes the underlying stream. \retval 0 Success. \retval EOF An error occurred. errno need not be set.*/ typedef int (*op_close_func)(void *_stream);  Timothy B. Terriberry committed Sep 23, 2012 533 /**The callbacks used to access non-FILE stream resources.  Timothy B. Terriberry committed Sep 16, 2012 534 535 536 537 538  The function prototypes are basically the same as for the stdio functions fread(), fseek(), ftell(), and fclose(). The differences are that the FILE * arguments have been replaced with a void *, which is to be used as a pointer to  Timothy B. Terriberry committed Sep 30, 2012 539 540 541  whatever internal data these functions might need, that #seek and #tell take and return 64-bit offsets, and that #seek must return -1 if the stream is unseekable.*/  Timothy B. Terriberry committed Sep 16, 2012 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 struct OpusFileCallbacks{ /**Used to read data from the stream. This must not be NULL.*/ op_read_func read; /**Used to seek in the stream. This may be NULL if seeking is not implemented.*/ op_seek_func seek; /**Used to return the current read position in the stream. This may be NULL if seeking is not implemented.*/ op_tell_func tell; /**Used to close the stream when the decoder is freed. This may be NULL to leave the stream open.*/ op_close_func close; }; /**Opens a stream with fopen() and fills in a set of callbacks that can be used to access it. This is useful to avoid writing your own portable 64-bit seeking wrappers, and also avoids cross-module linking issues on Windows, where a FILE * must be accessed by routines defined in the same module that opened it. \param[out] _cb The callbacks to use for this file. If there is an error opening the file, nothing will be filled in here. \param _path The path to the file to open. \param _mode The mode to open the file in.  Timothy B. Terriberry committed Sep 22, 2012 568 569  \return A stream handle to use with the callbacks, or NULL on error.*/  Timothy B. Terriberry committed Sep 16, 2012 570 571 572 OP_WARN_UNUSED_RESULT void *op_fopen(OpusFileCallbacks *_cb, const char *_path,const char *_mode) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2) OP_ARG_NONNULL(3);  Timothy B. Terriberry committed Sep 17, 2012 573   Timothy B. Terriberry committed Sep 16, 2012 574 575 576 577 578 579 580 581 582 583 584 /**Opens a stream with fdopen() and fills in a set of callbacks that can be used to access it. This is useful to avoid writing your own portable 64-bit seeking wrappers, and also avoids cross-module linking issues on Windows, where a FILE * must be accessed by routines defined in the same module that opened it. \param[out] _cb The callbacks to use for this file. If there is an error opening the file, nothing will be filled in here. \param _fd The file descriptor to open. \param _mode The mode to open the file in.  Timothy B. Terriberry committed Sep 22, 2012 585 586  \return A stream handle to use with the callbacks, or NULL on error.*/  Timothy B. Terriberry committed Sep 16, 2012 587 588 OP_WARN_UNUSED_RESULT void *op_fdopen(OpusFileCallbacks *_cb, int _fd,const char *_mode) OP_ARG_NONNULL(1) OP_ARG_NONNULL(3);  Timothy B. Terriberry committed Sep 17, 2012 589   Timothy B. Terriberry committed Sep 16, 2012 590 591 592 593 594 595 596 597 598 599 600 601 602 /**Opens a stream with freopen() and fills in a set of callbacks that can be used to access it. This is useful to avoid writing your own portable 64-bit seeking wrappers, and also avoids cross-module linking issues on Windows, where a FILE * must be accessed by routines defined in the same module that opened it. \param[out] _cb The callbacks to use for this file. If there is an error opening the file, nothing will be filled in here. \param _path The path to the file to open. \param _mode The mode to open the file in. \param _stream A stream previously returned by op_fopen(), op_fdopen(), or op_freopen().  Timothy B. Terriberry committed Sep 22, 2012 603 604  \return A stream handle to use with the callbacks, or NULL on error.*/  Timothy B. Terriberry committed Sep 17, 2012 605 606 607 OP_WARN_UNUSED_RESULT void *op_freopen(OpusFileCallbacks *_cb, const char *_path,const char *_mode,void *_stream) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2) OP_ARG_NONNULL(3) OP_ARG_NONNULL(4);  Timothy B. Terriberry committed Sep 16, 2012 608 609  /**Creates a stream that reads from the given block of memory.  Timothy B. Terriberry committed Sep 17, 2012 610 611  This block of memory must contain the complete stream to decode. This is useful for caching small streams (e.g., sound effects) in RAM.  Timothy B. Terriberry committed Sep 16, 2012 612 613 614 615 616  \param[out] _cb The callbacks to use for this stream. If there is an error creating the stream, nothing will be filled in here. \param _data The block of memory to read from. \param _size The size of the block of memory.  Timothy B. Terriberry committed Sep 22, 2012 617 618  \return A stream handle to use with the callbacks, or NULL on error.*/  Timothy B. Terriberry committed Sep 17, 2012 619 OP_WARN_UNUSED_RESULT void *op_mem_stream_create(OpusFileCallbacks *_cb,  Timothy B. Terriberry committed Sep 22, 2012 620 621 622  const unsigned char *_data,size_t _size) OP_ARG_NONNULL(1); /**Creates a stream that reads from the given URL.  Timothy B. Terriberry committed Oct 20, 2012 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637  This function behaves identically to op_url_stream_create(), except that it takes a va_list instead of a variable number of arguments. It does not call the va_end macro, and because it invokes the va_arg macro, the value of \a _ap is undefined after the call. \param[out] _cb The callbacks to use for this stream. If there is an error creating the stream, nothing will be filled in here. \param _url The URL to read from. Currently only the , , and schemes are supported. Both and may be disabled at compile time, in which case opening such URLs will always fail. \param[in,out] _ap A list of the \ref url_options "optional flags" to use. This is a variable-length list of options terminated with NULL.  Timothy B. Terriberry committed Sep 22, 2012 638 639  \return A stream handle to use with the callbacks, or NULL on error.*/  Timothy B. Terriberry committed Oct 20, 2012 640 641 OP_WARN_UNUSED_RESULT void *op_url_stream_vcreate(OpusFileCallbacks *_cb, const char *_url,va_list _ap) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);  Timothy B. Terriberry committed Sep 22, 2012 642 643  /**Creates a stream that reads from the given URL using the specified proxy.  Timothy B. Terriberry committed Oct 20, 2012 644 645 646 647 648 649 650 651 652 653 654  \param[out] _cb The callbacks to use for this stream. If there is an error creating the stream, nothing will be filled in here. \param _url The URL to read from. Currently only the , , and schemes are supported. Both and may be disabled at compile time, in which case opening such URLs will always fail. \param ... The \ref url_options "optional flags" to use. This is a variable-length list of options terminated with NULL.  Timothy B. Terriberry committed Sep 22, 2012 655 656  \return A stream handle to use with the callbacks, or NULL on error.*/  Timothy B. Terriberry committed Oct 20, 2012 657 658 OP_WARN_UNUSED_RESULT void *op_url_stream_create(OpusFileCallbacks *_cb, const char *_url,...) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);  Timothy B. Terriberry committed Sep 22, 2012 659 660  /*@}*/  Timothy B. Terriberry committed Sep 16, 2012 661 662 /*@}*/  Timothy B. Terriberry committed Sep 23, 2012 663 /**\defgroup stream_open_close Opening and Closing*/  Timothy B. Terriberry committed Sep 23, 2012 664 665 666 667 668 669 670 671 672 /*@{*/ /**\name Functions for opening and closing streams These functions allow you to test a stream to see if it is Opus, open it, and close it. Several flavors are provided for each of the built-in stream types, plus a more general version which takes a set of application-provided callbacks.*/ /*@{*/  Timothy B. Terriberry committed Sep 17, 2012 673 /**Test to see if this is an Opus stream.  Timothy B. Terriberry committed Sep 16, 2012 674  For good results, you will need at least 57 bytes (for a pure Opus-only  Timothy B. Terriberry committed Sep 17, 2012 675  stream).  Timothy B. Terriberry committed Oct 20, 2012 676 677  Something like 512 bytes will give more reliable results for multiplexed streams.  Timothy B. Terriberry committed Sep 16, 2012 678 679  This function is meant to be a quick-rejection filter. Its purpose is not to guarantee that a stream is a valid Opus stream, but to  Timothy B. Terriberry committed Sep 23, 2012 680 681 682  ensure that it looks enough like Opus that it isn't going to be recognized as some other format (except possibly an Opus stream that is also multiplexed with other codecs, such as video).  Timothy B. Terriberry committed Sep 16, 2012 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700  \param[out] _head The parsed ID header contents. You may pass NULL if you do not need this information. If the function fails, the contents of this structure remain untouched. \param _initial_data An initial buffer of data from the start of the stream. \param _initial_bytes The number of bytes in \a _initial_data. \return 0 if the data appears to be Opus, or a negative value on error. \retval #OP_FALSE There was not enough data to tell if this was an Opus stream or not. \retval #OP_EFAULT An internal memory allocation failed. \retval #OP_EIMPL The stream used a feature that is not implemented, such as an unsupported channel family. \retval #OP_ENOTFORMAT If the data did not contain a recognizable ID header for an Opus stream. \retval #OP_EVERSION If the version field signaled a version this library does not know how to parse.  Timothy B. Terriberry committed Oct 20, 2012 701 702  \retval #OP_EBADHEADER The ID header was not properly formatted or contained illegal values.*/  Timothy B. Terriberry committed Sep 16, 2012 703 704 705 706 707 708 int op_test(OpusHead *_head, const unsigned char *_initial_data,size_t _initial_bytes); /**Open a stream from the given file path. \param _path The path to the file to open. \param[out] _error Returns 0 on success, or a failure code on error.  Timothy B. Terriberry committed Sep 22, 2012 709 710  You may pass in NULL if you don't want the failure code.  Timothy B. Terriberry committed Sep 16, 2012 711 712 713  The failure code will be #OP_EFAULT if the file could not be opened, or one of the other failure codes from op_open_callbacks() otherwise.  Timothy B. Terriberry committed Sep 30, 2012 714  \return A freshly opened \c OggOpusFile, or NULL on error.*/  Timothy B. Terriberry committed Sep 17, 2012 715 716 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_file(const char *_path,int *_error) OP_ARG_NONNULL(1);  Timothy B. Terriberry committed Sep 16, 2012 717 718 719 720 721  /**Open a stream from a memory buffer. \param _data The memory buffer to open. \param _size The number of bytes in the buffer. \param[out] _error Returns 0 on success, or a failure code on error.  Timothy B. Terriberry committed Sep 22, 2012 722 723  You may pass in NULL if you don't want the failure code.  Timothy B. Terriberry committed Sep 16, 2012 724  See op_open_callbacks() for a full list of failure codes.  Timothy B. Terriberry committed Sep 30, 2012 725  \return A freshly opened \c OggOpusFile, or NULL on error.*/  Timothy B. Terriberry committed Sep 17, 2012 726 727 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_memory(const unsigned char *_data, size_t _size,int *_error);  Timothy B. Terriberry committed Sep 16, 2012 728   Timothy B. Terriberry committed Sep 22, 2012 729 /**Open a stream from a URL.  Timothy B. Terriberry committed Oct 20, 2012 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748  This function behaves identically to op_open_url(), except that it takes a va_list instead of a variable number of arguments. It does not call the va_end macro, and because it invokes the va_arg macro, the value of \a _ap is undefined after the call. \param _url The URL to open. Currently only the , , and schemes are supported. Both and may be disabled at compile time, in which case opening such URLs will always fail. \param[out] _error Returns 0 on success, or a failure code on error. You may pass in NULL if you don't want the failure code. See op_open_callbacks() for a full list of failure codes. \param[in,out] _ap A list of the \ref url_options "optional flags" to use. This is a variable-length list of options terminated with NULL.  Timothy B. Terriberry committed Sep 30, 2012 749  \return A freshly opened \c OggOpusFile, or NULL on error.*/  Timothy B. Terriberry committed Oct 20, 2012 750 751 OP_WARN_UNUSED_RESULT OggOpusFile *op_vopen_url(const char *_url, int *_error,va_list _ap) OP_ARG_NONNULL(1);  Timothy B. Terriberry committed Sep 22, 2012 752   Timothy B. Terriberry committed Oct 20, 2012 753 /**Open a stream from a URL.  Timothy B. Terriberry committed Oct 12, 2012 754 755  However, this approach will not work for live streams or HTTP/1.0 servers (which do not support Range requets).  Timothy B. Terriberry committed Oct 20, 2012 756 757 758 759 760 761 762 763 764 765 766 767  \param _url The URL to open. Currently only the , , and schemes are supported. Both and may be disabled at compile time, in which case opening such URLs will always fail. \param[out] _error Returns 0 on success, or a failure code on error. You may pass in NULL if you don't want the failure code. See op_open_callbacks() for a full list of failure codes. \param ... The \ref url_options "optional flags" to use. This is a variable-length list of options terminated with NULL.  Timothy B. Terriberry committed Sep 30, 2012 768  \return A freshly opened \c OggOpusFile, or NULL on error.*/  Timothy B. Terriberry committed Oct 20, 2012 769 770 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_url(const char *_url, int *_error,...) OP_ARG_NONNULL(1);  Timothy B. Terriberry committed Sep 22, 2012 771   Timothy B. Terriberry committed Sep 16, 2012 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 /**Open a stream using the given set of callbacks to access it. \param _source The stream to read from (e.g., a FILE *). \param _cb The callbacks with which to access the stream. read() must be implemented. seek() and tell() may be NULL, or may always return -1 to indicate a source is unseekable, but if seek() is implemented and succeeds on a particular source, then tell() must also. close() may be NULL, but if it is not, it will be  Timothy B. Terriberry committed Sep 30, 2012 787  called when the \c OggOpusFile is destroyed by  Timothy B. Terriberry committed Sep 16, 2012 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805  op_free(). It will not be called if op_open_callbacks() fails with an error. \param _initial_data An initial buffer of data from the start of the stream. Applications can read some number of bytes from the start of the stream to help identify this as an Opus stream, and then provide them here to allow the stream to be opened, even if it is unseekable. \param _initial_bytes The number of bytes in \a _initial_data. If the stream is seekable, its current position (as reported by tell() at the start of this function) must be equal to \a _initial_bytes. Otherwise, seeking to absolute positions will generate inconsistent results. \param[out] _error Returns 0 on success, or a failure code on error.  Timothy B. Terriberry committed Sep 22, 2012 806 807  You may pass in NULL if you don't want the failure code.  Timothy B. Terriberry committed Sep 16, 2012 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843  The failure code will be one of
An underlying read, seek, or tell operation failed when it should have succeeded, or we failed to find data in the stream we had seen before.
#OP_EFAULT
There was a memory allocation failure, or an internal library error.
#OP_EIMPL
The stream used a feature that is not implemented, such as an unsupported channel family.
#OP_EINVAL
seek() was implemented and succeeded on this source, but tell() did not, or the starting position indicator was not equal to \a _initial_bytes.
#OP_ENOTFORMAT
The stream contained a link that did not have any logical Opus streams in it.
 Timothy B. Terriberry committed Sep 30, 2012 844  \return A freshly opened \c OggOpusFile, or NULL on error.*/  Timothy B. Terriberry committed Sep 17, 2012 845 846 847 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_callbacks(void *_source, const OpusFileCallbacks *_cb,const unsigned char *_initial_data, size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);  Timothy B. Terriberry committed Sep 16, 2012 848 849  /**Partially open a stream from the given file path.  Timothy B. Terriberry committed Sep 22, 2012 850  \see op_test_callbacks  Timothy B. Terriberry committed Sep 16, 2012 851 852  \param _path The path to the file to open. \param[out] _error Returns 0 on success, or a failure code on error.  Timothy B. Terriberry committed Sep 22, 2012 853 854  You may pass in NULL if you don't want the failure code.  Timothy B. Terriberry committed Sep 16, 2012 855 856 857  The failure code will be #OP_EFAULT if the file could not be opened, or one of the other failure codes from op_open_callbacks() otherwise.  Timothy B. Terriberry committed Sep 30, 2012 858  \return A partially opened \c OggOpusFile, or NULL on error.*/  Timothy B. Terriberry committed Sep 17, 2012 859 860 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_file(const char *_path,int *_error) OP_ARG_NONNULL(1);  Timothy B. Terriberry committed Sep 16, 2012 861 862  /**Partially open a stream from a memory buffer.  Timothy B. Terriberry committed Sep 22, 2012 863  \see op_test_callbacks  Timothy B. Terriberry committed Sep 16, 2012 864 865 866  \param _data The memory buffer to open. \param _size The number of bytes in the buffer. \param[out] _error Returns 0 on success, or a failure code on error.  Timothy B. Terriberry committed Sep 22, 2012 867 868  You may pass in NULL if you don't want the failure code.  Timothy B. Terriberry committed Sep 16, 2012 869  See op_open_callbacks() for a full list of failure codes.  Timothy B. Terriberry committed Sep 30, 2012 870  \return A partially opened \c OggOpusFile, or NULL on error.*/  Timothy B. Terriberry committed Sep 17, 2012 871 872 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_memory(const unsigned char *_data, size_t _size,int *_error);  Timothy B. Terriberry committed Sep 16, 2012 873   Timothy B. Terriberry committed Sep 22, 2012 874 /**Partially open a stream from a URL.  Timothy B. Terriberry committed Oct 20, 2012 875 876 877 878 879  This function behaves identically to op_test_url(), except that it takes a va_list instead of a variable number of arguments. It does not call the va_end macro, and because it invokes the va_arg macro, the value of \a _ap is undefined after the call. \see op_test_url  Timothy B. Terriberry committed Sep 22, 2012 880  \see op_test_callbacks  Timothy B. Terriberry committed Oct 20, 2012 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895  \param _url The URL to open. Currently only the , , and schemes are supported. Both and may be disabled at compile time, in which case opening such URLs will always fail. \param[out] _error Returns 0 on success, or a failure code on error. You may pass in NULL if you don't want the failure code. See op_open_callbacks() for a full list of failure codes. \param[in,out] _ap A list of the \ref url_options "optional flags" to use. This is a variable-length list of options terminated with NULL.  Timothy B. Terriberry committed Sep 30, 2012 896  \return A partially opened \c OggOpusFile, or NULL on error.*/  Timothy B. Terriberry committed Oct 20, 2012 897 898 OP_WARN_UNUSED_RESULT OggOpusFile *op_vtest_url(const char *_url, int *_error,va_list _ap) OP_ARG_NONNULL(1);  Timothy B. Terriberry committed Sep 22, 2012 899   Timothy B. Terriberry committed Oct 20, 2012 900 /**Partially open a stream from a URL.  Timothy B. Terriberry committed Sep 22, 2012 901  \see op_test_callbacks  Timothy B. Terriberry committed Oct 20, 2012 902 903 904 905 906 907 908 909 910 911 912 913 914  \param _url The URL to open. Currently only the , , and schemes are supported. Both and may be disabled at compile time, in which case opening such URLs will always fail. \param[out] _error Returns 0 on success, or a failure code on error. You may pass in NULL if you don't want the failure code. See op_open_callbacks() for a full list of failure codes. \param ... The \ref url_options "optional flags" to use. This is a variable-length list of options terminated with NULL.  Timothy B. Terriberry committed Sep 30, 2012 915  \return A partially opened \c OggOpusFile, or NULL on error.*/  Timothy B. Terriberry committed Oct 20, 2012 916 917 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_url(const char *_url, int *_error,...) OP_ARG_NONNULL(1);  Timothy B. Terriberry committed Sep 22, 2012 918   Timothy B. Terriberry committed Sep 17, 2012 919 /**Partially open a stream using the given set of callbacks to access it.  Timothy B. Terriberry committed Sep 16, 2012 920 921  This tests for Opusness and loads the headers for the first link. It does not seek (although it tests for seekability).  Timothy B. Terriberry committed Oct 20, 2012 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938  You can query a partially open stream for the few pieces of basic information returned by op_serialno(), op_channel_count(), op_head(), and op_tags() (but only for the first link). You may also determine if it is seekable via a call to op_seekable(). You cannot read audio from the stream, seek, get the size or duration, get information from links other than the first one, or even get the total number of links until you finish opening the stream with op_test_open(). If you do not need to do any of these things, you can dispose of it with op_free() instead. This function is provided mostly to simplify porting existing code that used libvorbisfile. For new code, you are likely better off using op_test() instead, which is less resource-intensive, requires less data to succeed, and imposes a hard limit on the amount of data it examines (important for unseekable sources, where all such data must be buffered until you are sure of the stream type).  Timothy B. Terriberry committed Sep 16, 2012 939 940 941 942 943 944 945 946 947 948 949 950 951 952  \param _source The stream to read from (e.g., a FILE *). \param _cb The callbacks with which to access the stream. read() must be implemented. seek() and tell() may be NULL, or may always return -1 to indicate a source is unseekable, but if seek() is implemented and succeeds on a particular source, then tell() must also. close() may be NULL, but if it is not, it will be  Timothy B. Terriberry committed Sep 30, 2012 953  called when the \c OggOpusFile is destroyed by  Timothy B. Terriberry committed Sep 16, 2012 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972  op_free(). It will not be called if op_open_callbacks() fails with an error. \param _initial_data An initial buffer of data from the start of the stream. Applications can read some number of bytes from the start of the stream to help identify this as an Opus stream, and then provide them here to allow the stream to be tested more thoroughly, even if it is unseekable. \param _initial_bytes The number of bytes in \a _initial_data. If the stream is seekable, its current position (as reported by tell() at the start of this function) must be equal to \a _initial_bytes. Otherwise, seeking to absolute positions will generate inconsistent results. \param[out] _error Returns 0 on success, or a failure code on error.  Timothy B. Terriberry committed Sep 22, 2012 973 974  You may pass in NULL if you don't want the failure code.  Timothy B. Terriberry committed Sep 16, 2012 975 976  See op_open_callbacks() for a full list of failure codes.  Timothy B. Terriberry committed Sep 30, 2012 977  \return A partially opened \c OggOpusFile, or NULL on error.*/  Timothy B. Terriberry committed Sep 17, 2012 978 979 980 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_callbacks(void *_source, const OpusFileCallbacks *_cb,const unsigned char *_initial_data, size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);  Timothy B. Terriberry committed Sep 16, 2012 981 982 983 984  /**Finish opening a stream partially opened with op_test_callbacks() or one of the associated convenience functions. If this function fails, you are still responsible for freeing the  Timothy B. Terriberry committed Sep 30, 2012 985 986  \c OggOpusFile with op_free(). \param _of The \c OggOpusFile to finish opening.  Timothy B. Terriberry committed Sep 16, 2012 987 988 989 990 991 992 993 994 995 996 997 998 999 1000  \return 0 on success, or a negative value on error. \retval #OP_EREAD An underlying read, seek, or tell operation failed when it should have succeeded. \retval #OP_EFAULT There was a memory allocation failure, or an internal library error. \retval #OP_EIMPL The stream used a feature that is not implemented, such as an unsupported channel family. \retval #OP_EINVAL The stream was not partially opened with op_test_callbacks() or one of the associated convenience functions. \retval #OP_ENOTFORMAT The stream contained a link that did not have any logical Opus streams in it. \retval #OP_EBADHEADER A required header packet was not properly formatted, contained illegal values, or was