Fix an uninitialized value in the http reader.
[opusfile.git] / include / opusfile.h
1 /********************************************************************
2  *                                                                  *
3  * THIS FILE IS PART OF THE libopusfile SOFTWARE CODEC SOURCE CODE. *
4  * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS     *
5  * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE *
6  * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING.       *
7  *                                                                  *
8  * THE libopusfile SOURCE CODE IS (C) COPYRIGHT 1994-2012           *
9  * by the Xiph.Org Foundation and contributors http://www.xiph.org/ *
10  *                                                                  *
11  ********************************************************************
12
13  function: stdio-based convenience library for opening/seeking/decoding
14  last mod: $Id: vorbisfile.h 17182 2010-04-29 03:48:32Z xiphmont $
15
16  ********************************************************************/
17 #if !defined(_opusfile_h)
18 # define _opusfile_h (1)
19
20 # if defined(__cplusplus)
21 extern "C" {
22 # endif
23
24 # include <stdio.h>
25 # include <ogg/ogg.h>
26 # include <opus_multistream.h>
27
28 /*Enable special features for gcc and gcc-compatible compilers.*/
29 # if !defined(OP_GNUC_PREREQ)
30 #  if defined(__GNUC__)&&defined(__GNUC_MINOR__)
31 #   define OP_GNUC_PREREQ(_maj,_min) \
32  ((__GNUC__<<16)+__GNUC_MINOR__>=((_maj)<<16)+(_min))
33 #  else
34 #   define OP_GNUC_PREREQ(_maj,_min) 0
35 #  endif
36 # endif
37
38 # if OP_GNUC_PREREQ(4,0)
39 #  pragma GCC visibility push(default)
40 # endif
41
42 typedef struct OpusHead    OpusHead;
43 typedef struct OpusTags    OpusTags;
44 typedef struct OggOpusFile OggOpusFile;
45
46 /*Warning attributes for libopusfile functions.*/
47 # if OP_GNUC_PREREQ(3,4)
48 #  define OP_WARN_UNUSED_RESULT __attribute__((__warn_unused_result__))
49 # else
50 #  define OP_WARN_UNUSED_RESULT
51 # endif
52 # if OP_GNUC_PREREQ(3,4)
53 #  define OP_ARG_NONNULL(_x) __attribute__((__nonnull__(_x)))
54 # else
55 #  define OP_ARG_NONNULL(_x)
56 # endif
57
58 /**\defgroup error_codes Error Codes*/
59 /*@{*/
60 /**\name List of possible error codes
61    Many of the functions in this library return a negative error code when a
62     function fails.
63    This list provides a brief explanation of the common errors.
64    See each individual function for more details on what a specific error code
65     means in that context.*/
66 /*@{*/
67 /**A request did not succeed.*/
68 #define OP_FALSE         (-1)
69 /*Currently not used externally.*/
70 #define OP_EOF           (-2)
71 /**There was a hole in the page sequence numbers (e.g., a page was corrupt or
72     missing).*/
73 #define OP_HOLE          (-3)
74 /**An underlying read, seek, or tell operation failed when it should have
75     succeeded.*/
76 #define OP_EREAD         (-128)
77 /**A <code>NULL</code> pointer was passed where one was unexpected, or an
78     internal memory allocation failed, or an internal library error was
79     encountered.*/
80 #define OP_EFAULT        (-129)
81 /**The stream used a feature that is not implemented, such as an unsupported
82     channel family.*/
83 #define OP_EIMPL         (-130)
84 /**One or more parameters to a function were invalid.*/
85 #define OP_EINVAL        (-131)
86 /**A purported Ogg Opus stream did not begin with an Ogg page, or a purported
87     header packet did not start with one of the required strings, "OpusHead" or
88     "OpusTags".*/
89 #define OP_ENOTFORMAT    (-132)
90 /**A required header packet was not properly formatted, contained illegal
91     values, or was missing altogether.*/
92 #define OP_EBADHEADER    (-133)
93 /**The ID header contained an unrecognized version number.*/
94 #define OP_EVERSION      (-134)
95 /*Currently not used at all.*/
96 #define OP_ENOTAUDIO     (-135)
97 /**An audio packet failed to decode properly.
98    This is usually caused by a multistream Ogg packet where the durations of
99     the individual Opus packets contained in it are not all the same.*/
100 #define OP_EBADPACKET    (-136)
101 /**We failed to find data we had seen before, or the bitstream structure was
102     sufficiently malformed that seeking to the target destination was
103     impossible.*/
104 #define OP_EBADLINK      (-137)
105 /**An operation that requires seeking was requested on an unseekable stream.*/
106 #define OP_ENOSEEK       (-138)
107 /**The first or last granule position of a link failed basic validity checks.*/
108 #define OP_EBADTIMESTAMP (-139)
109 /*@}*/
110 /*@}*/
111
112 /**\defgroup header_info Header Information*/
113 /*@{*/
114
115 /**The maximum number of channels in an Ogg Opus stream.*/
116 #define OPUS_CHANNEL_COUNT_MAX (255)
117
118 /**Ogg Opus bitstream information.
119    This contains the basic playback parameters for a stream, and corresponds to
120     the initial ID header packet of an Ogg Opus stream.*/
121 struct OpusHead{
122   /**The Ogg Opus format version, in the range 0...255.
123      The top 4 bits represent a "major" version, and the bottom four bits
124       represent backwards-compatible "minor" revisions.
125      The current specification describes version 1.
126      This library will recognize versions up through 15 as backwards compatible
127       with the current specification.
128      An earlier draft of the specification described a version 0, but the only
129       difference between version 1 and version 0 is that version 0 did
130       not specify the semantics for handling the version field.*/
131   int           version;
132   /**The number of channels, in the range 1...255.*/
133   int           channel_count;
134   /**The number of samples that should be discarded from the beginning of the
135       stream.*/
136   unsigned      pre_skip;
137   /**The sampling rate of the original input.
138      All Opus audio is coded at 48 kHz, and should also be decoded at 48 kHz
139       for playback (unless the target hardware does not support this sampling
140       rate).
141      However, this field may be used to resample the audio back to the original
142       sampling rate, for example, when saving the output to a file.*/
143   opus_uint32   input_sample_rate;
144   /**The gain to apply to the decoded output, in dB, as a Q8 value in the range
145       -32768...32767.
146      The decoder will automatically scale the output by
147       pow(10,output_gain/(20.0*256)).*/
148   int           output_gain;
149   /**The channel mapping family, in the range 0...255.
150      Channel mapping family 0 covers mono or stereo in a single stream.
151      Channel mapping family 1 covers 1 to 8 channels in one or more streams,
152       using the Vorbis speaker assignments.
153      Channel mapping family 255 covers 1 to 255 channels in one or more
154       streams, but without any defined speaker assignment.*/
155   int           mapping_family;
156   /**The number of Opus streams in each Ogg packet, in the range 1...255.*/
157   int           stream_count;
158   /**The number of coupled Opus streams in each Ogg packet, in the range
159       0...127.
160      This must satisfy <code>0 <= coupled_count <= stream_count</code> and
161       <code>coupled_count + stream_count <= 255</code>.
162      The coupled streams appear first, before all uncoupled streams, in an Ogg
163       Opus packet.*/
164   int           coupled_count;
165   /**The mapping from coded stream channels to output channels.
166      Let <code>index=mapping[k]</code> be the value for channel <code>k</code>.
167      If <code>index<2*coupled_count</code>, then it refers to the left channel
168       from stream <code>(index/2)</code> if even, and the right channel from
169       stream <code>(index/2)</code> if odd.
170      Otherwise, it refers to the output of the uncoupled stream
171       <code>(index-coupled_count)</code>.*/
172   unsigned char mapping[OPUS_CHANNEL_COUNT_MAX];
173 };
174
175 /**The metadata from an Ogg Opus stream.
176
177    This structure holds the in-stream metadata corresponding to the 'comment'
178     header packet of an Ogg Opus stream.
179    The comment header is meant to be used much like someone jotting a quick
180     note on the label of a CD.
181    It should be a short, to the point text note that can be more than a couple
182     words, but not more than a short paragraph.
183
184    The metadata is stored as a series of (tag, value) pairs, in length-encoded
185     string vectors, using the same format as Vorbis (without the final "framing
186     bit"), Theora, and Speex, except for the packet header.
187    The first occurrence of the '=' character delimits the tag and value.
188    A particular tag may occur more than once, and order is significant.
189    The character set encoding for the strings is always UTF-8, but the tag
190     names are limited to ASCII, and treated as case-insensitive.
191    See <a href="http://www.xiph.org/vorbis/doc/v-comment.html">the Vorbis
192     comment header specification</a> for details.
193
194    In filling in this structure, \a libopsfile will null-terminate the
195     #user_comments strings for safety.
196    However, the bitstream format itself treats them as 8-bit clean vectors,
197     possibly containing NUL characters, so the #comment_lengths array should be
198     treated as their authoritative length.
199
200    This structure is binary and source-compatible with a
201     <code>vorbis_comment</code>, and pointers to it may be freely cast to
202     <code>vorbis_comment</code> pointers, and vice versa.
203    It is provided as a separate type to avoid introducing a compile-time
204     dependency on the libvorbis headers.*/
205 struct OpusTags{
206   /**The array of comment string vectors.*/
207   char **user_comments;
208   /**An array of the corresponding length of each vector, in bytes.*/
209   int   *comment_lengths;
210   /**The total number of comment streams.*/
211   int    comments;
212   /**The null-terminated vendor string.
213      This identifies the software used to encode the stream.*/
214   char  *vendor;
215 };
216
217 /**\name Functions for manipulating header data
218    These functions manipulate the #OpusHead and #OpusTags structures,
219     which describe the audio parameters and tag-value metadata, respectively.*/
220 /*@{*/
221
222 /**Parses the contents of the ID header packet of an Ogg Opus stream.
223    \param[out] _head Returns the contents of the parsed packet.
224                      The contents of this structure are untouched on error.
225                      This may be <code>NULL</code> to merely test the header
226                       for validity.
227    \param[in]  _data The contents of the ID header packet.
228    \param      _len  The number of bytes of data in the ID header packet.
229    \return 0 on success or a negative value on error.
230    \retval #OP_ENOTFORMAT If the data does not start with the "OpusHead"
231                            string.
232    \retval #OP_EVERSION   If the version field signaled a version this library
233                            does not know how to parse.
234    \retval #OP_EIMPL      If the channel mapping family was 255, which general
235                            purpose players should not attempt to play.
236    \retval #OP_EBADHEADER If the contents of the packet otherwise violate the
237                            Ogg Opus specification:
238                           <ul>
239                            <li>Insufficient data,</li>
240                            <li>Too much data for the known minor versions,</li>
241                            <li>An unrecognized channel mapping family,</li>
242                            <li>Zero channels or too many channels,</li>
243                            <li>Zero coded streams,</li>
244                            <li>Too many coupled streams, or</li>
245                            <li>An invalid channel mapping index.</li>
246                           </ul>*/
247 OP_WARN_UNUSED_RESULT int opus_head_parse(OpusHead *_head,
248  const unsigned char *_data,size_t _len) OP_ARG_NONNULL(2);
249
250 /**Converts a granule position to a sample offset for a given Ogg Opus stream.
251    The sample offset is simply <code>_gp-_head->pre_skip</code>.
252    Granule position values smaller than OpusHead#pre_skip correspond to audio
253     that should never be played, and thus have no associated sample offset.
254    This function returns -1 for such values.
255    This function also correctly handles extremely large granule positions,
256     which may have wrapped around to a negative number when stored in a signed
257     ogg_int64_t value.
258    \param _head The #OpusHead information from the ID header of the stream.
259    \param _gp   The granule position to convert.
260    \return The sample offset associated with the given granule position
261             (counting at a 48 kHz sampling rate), or the special value -1 on
262             error (i.e., the granule position was smaller than the pre-skip
263             amount).*/
264 ogg_int64_t opus_granule_sample(const OpusHead *_head,ogg_int64_t _gp)
265  OP_ARG_NONNULL(1);
266
267 /**Parses the contents of the 'comment' header packet of an Ogg Opus stream.
268    \param[out] _tags An uninitialized #OpusTags structure.
269                      This returns the contents of the parsed packet.
270                      The contents of this structure are untouched on error.
271                      This may be <code>NULL</code> to merely test the header
272                       for validity.
273    \param[in]  _data The contents of the 'comment' header packet.
274    \param      _len  The number of bytes of data in the 'info' header packet.
275    \retval 0             Success.
276    \retval #OP_ENOTFORMAT If the data does not start with the "OpusTags"
277                            string.
278    \retval #OP_EBADHEADER If the contents of the packet otherwise violate the
279                            Ogg Opus specification.
280    \retval #OP_EFAULT     If there wasn't enough memory to store the tags.*/
281 OP_WARN_UNUSED_RESULT int opus_tags_parse(OpusTags *_tags,
282  const unsigned char *_data,size_t _len) OP_ARG_NONNULL(2);
283
284 /**Initializes an #OpusTags structure.
285    This should be called on a freshly allocated #OpusTags structure before
286     attempting to use it.
287    \param _tags The #OpusTags structure to initialize.*/
288 void opus_tags_init(OpusTags *_tags) OP_ARG_NONNULL(1);
289
290 /**Add a (tag, value) pair to an initialized #OpusTags structure.
291    \note Neither opus_tags_add() nor opus_tags_add_comment() support values
292     containing embedded NULs, although the bitstream format does support them.
293    To add such tags, you will need to manipulate the #OpusTags structure
294     directly.
295    \param _tags    The #OpusTags structure to add the (tag, value) pair to.
296    \param _tag     A NUL-terminated, case-insensitive, ASCII string containing
297                     the tag to add (without an '=' character).
298    \param _comment A NUL-terminated UTF-8 containing the corresponding value.
299    \return 0 on success, or a negative value on failure.
300    \retval OP_EFAULT An internal memory allocation failed.*/
301 int opus_tags_add(OpusTags *_tags,const char *_tag,const char *_value)
302  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2) OP_ARG_NONNULL(3);
303
304 /**Add a comment to an initialized #OpusTags structure.
305    \note Neither opus_tags_add_comment() nor opus_tags_add() support comments
306     containing embedded NULs, although the bitstream format does support them.
307    To add such tags, you will need to manipulate the #OpusTags structure
308     directly.
309    \param _tags    The #OpusTags structure to add the comment to.
310    \param _comment A NUL-terminated UTF-8 string containing the comment in
311                     "TAG=value" form.
312    \return 0 on success, or a negative value on failure.
313    \retval OP_EFAULT An internal memory allocation failed.*/
314 int opus_tags_add_comment(OpusTags *_tags,const char *_comment)
315  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
316
317 /**Look up a comment value by its tag.
318    \param _tags  An initialized #OpusTags structure.
319    \param _tag   The tag to look up.
320    \param _count The instance of the tag.
321                  The same tag can appear multiple times, each with a distinct
322                   value, so an index is required to retrieve them all.
323                  The order in which these values appear is significant and
324                   should be preserved.
325                  Use opus_tags_query_count() to get the legal range for the
326                   \a _count parameter.
327    \return A pointer to the queried tag's value.
328            This points directly to data in the #OpusTags structure.
329            It should not be modified or freed by the application, and
330             modifications to the structure may invalidate the pointer.
331    \retval <code>NULL</code> if no matching tag is found.*/
332 const char *opus_tags_query(const OpusTags *_tags,const char *_tag,int _count)
333  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
334
335 /**Look up the number of instances of a tag.
336    Call this first when querying for a specific tag and then iterate over the
337     number of instances with separate calls to opus_tags_query() to retrieve
338     all the values for that tag in order.
339    \param _tags An initialized #OpusTags structure.
340    \param _tag  The tag to look up.
341    \return The number of instances of this particular tag.*/
342 int opus_tags_query_count(const OpusTags *_tags,const char *_tag)
343  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
344
345 /**Clears the #OpusTags structure.
346    This should be called on an #OpusTags structure after it is no longer
347     needed.
348    It will free all memory used by the structure members.
349    \param _tags The #OpusTags structure to clear.*/
350 void opus_tags_clear(OpusTags *_tags) OP_ARG_NONNULL(1);
351
352 /*@}*/
353
354 /*@}*/
355
356 /**\defgroup url_flags URL Reading Flags*/
357 /*@{*/
358 /**\name Flags for op_url_create_with_proxy() and associated functions.
359    These may be expanded in the future.*/
360 /*@{*/
361
362 /**Skip the certificate check when connecting via TLS/SSL (https).*/
363 #define OP_SSL_SKIP_CERTIFICATE_CHECK (1)
364
365 /*@}*/
366 /*@}*/
367
368 /*\defgroup file_callbacks Abstract Stream Reading Functions*/
369 /*@{*/
370
371 /**\name Functions for reading from streams
372    These functions define the interface used to read from and seek in a stream
373     of data.
374    A stream does not need to implement seeking, but the decoder will not be
375     able to seek if it does not do so.
376    These functions also include some convenience routines for working with
377     standard FILE pointers or complete streams stored in a single block of
378     memory.*/
379 /*@{*/
380
381 typedef struct OpusFileCallbacks OpusFileCallbacks;
382
383 /**Reads \a _nmemb elements of data, each \a _size bytes long, from
384     \a _stream.
385    \return The number of items successfully read (i.e., not the number of
386             characters).
387            Unlike normal <code>fread()</code>, this function is allowed to
388             return fewer bytes than requested (e.g., if reading more would
389             block), as long as <em>some</em> data is returned when no error
390             occurs and EOF has not been reached.
391            If an error occurs, or the end-of-file is reached, the return
392             value is zero.*/
393 typedef size_t (*op_read_func)(void *_ptr,size_t _size,size_t _nmemb,
394  void *_stream);
395
396 /**Sets the position indicator for \a _stream.
397    The new position, measured in bytes, is obtained by adding \a _offset
398     bytes to the position specified by \a _whence.
399    If \a _whence is set to <code>SEEK_SET</code>, <code>SEEK_CUR</code>, or
400     <code>SEEK_END</code>, the offset is relative to the start of the stream,
401     the current position indicator, or end-of-file, respectively.
402    \retval 0  Success.
403    \retval -1 Seeking is not supported or an error occurred.
404               <code>errno</code> need not be set.*/
405 typedef int (*op_seek_func)(void *_stream,opus_int64 _offset,int _whence);
406
407 /**Obtains the current value of the position indicator for \a _stream.
408    \return The current position indicator.*/
409 typedef opus_int64 (*op_tell_func)(void *_stream);
410
411 /**Closes the underlying stream.
412    \retval 0   Success.
413    \retval EOF An error occurred.
414                <code>errno</code> need not be set.*/
415 typedef int (*op_close_func)(void *_stream);
416
417 /**The callbacks used to access non-FILE stream resources.
418    The function prototypes are basically the same as for the stdio functions
419     <code>fread()</code>, <code>fseek()</code>, <code>ftell()</code>, and
420     <code>fclose()</code>.
421    The differences are that the <code>FILE *</code> arguments have been
422     replaced with a <code>void *</code>, which is to be used as a pointer to
423     whatever internal data these functions might need, that #seek_func and
424     #tell_func take and return 64-bit offsets, and that #seek_func *must*
425     return -1 if the stream is unseekable.*/
426 struct OpusFileCallbacks{
427   /**Used to read data from the stream.
428      This must not be <code>NULL</code>.*/
429   op_read_func  read;
430   /**Used to seek in the stream.
431      This may be <code>NULL</code> if seeking is not implemented.*/
432   op_seek_func  seek;
433   /**Used to return the current read position in the stream.
434      This may be <code>NULL</code> if seeking is not implemented.*/
435   op_tell_func  tell;
436   /**Used to close the stream when the decoder is freed.
437      This may be <code>NULL</code> to leave the stream open.*/
438   op_close_func close;
439 };
440
441 /**Opens a stream with <code>fopen()</code> and fills in a set of callbacks
442     that can be used to access it.
443    This is useful to avoid writing your own portable 64-bit seeking wrappers,
444     and also avoids cross-module linking issues on Windows, where a
445     <code>FILE *</code> must be accessed by routines defined in the same module
446     that opened it.
447    \param[out] _cb   The callbacks to use for this file.
448                      If there is an error opening the file, nothing will be
449                       filled in here.
450    \param      _path The path to the file to open.
451    \param      _mode The mode to open the file in.
452    \return A stream handle to use with the callbacks, or <code>NULL</code> on
453             error.*/
454 OP_WARN_UNUSED_RESULT void *op_fopen(OpusFileCallbacks *_cb,
455  const char *_path,const char *_mode) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2)
456  OP_ARG_NONNULL(3);
457
458 /**Opens a stream with <code>fdopen()</code> and fills in a set of callbacks
459     that can be used to access it.
460    This is useful to avoid writing your own portable 64-bit seeking wrappers,
461     and also avoids cross-module linking issues on Windows, where a
462     <code>FILE *</code> must be accessed by routines defined in the same module
463     that opened it.
464    \param[out] _cb   The callbacks to use for this file.
465                      If there is an error opening the file, nothing will be
466                       filled in here.
467    \param      _fd   The file descriptor to open.
468    \param      _mode The mode to open the file in.
469    \return A stream handle to use with the callbacks, or <code>NULL</code> on
470             error.*/
471 OP_WARN_UNUSED_RESULT void *op_fdopen(OpusFileCallbacks *_cb,
472  int _fd,const char *_mode) OP_ARG_NONNULL(1) OP_ARG_NONNULL(3);
473
474 /**Opens a stream with <code>freopen()</code> and fills in a set of callbacks
475     that can be used to access it.
476    This is useful to avoid writing your own portable 64-bit seeking wrappers,
477     and also avoids cross-module linking issues on Windows, where a
478     <code>FILE *</code> must be accessed by routines defined in the same module
479     that opened it.
480    \param[out] _cb     The callbacks to use for this file.
481                        If there is an error opening the file, nothing will be
482                         filled in here.
483    \param      _path   The path to the file to open.
484    \param      _mode   The mode to open the file in.
485    \param      _stream A stream previously returned by op_fopen(), op_fdopen(),
486                         or op_freopen().
487    \return A stream handle to use with the callbacks, or <code>NULL</code> on
488             error.*/
489 OP_WARN_UNUSED_RESULT void *op_freopen(OpusFileCallbacks *_cb,
490  const char *_path,const char *_mode,void *_stream) OP_ARG_NONNULL(1)
491  OP_ARG_NONNULL(2) OP_ARG_NONNULL(3) OP_ARG_NONNULL(4);
492
493 /**Creates a stream that reads from the given block of memory.
494    This block of memory must contain the complete stream to decode.
495    This is useful for caching small streams (e.g., sound effects) in RAM.
496    \param[out] _cb   The callbacks to use for this stream.
497                      If there is an error creating the stream, nothing will be
498                       filled in here.
499    \param      _data The block of memory to read from.
500    \param      _size The size of the block of memory.
501    \return A stream handle to use with the callbacks, or <code>NULL</code> on
502             error.*/
503 OP_WARN_UNUSED_RESULT void *op_mem_stream_create(OpusFileCallbacks *_cb,
504  const unsigned char *_data,size_t _size) OP_ARG_NONNULL(1);
505
506 /**Creates a stream that reads from the given URL.
507    This is equivalent to calling op_url_stream_create_with_proxy() with
508     <code>NULL</code> for \a _proxy_host.
509    \param[out] _cb    The callbacks to use for this stream.
510                       If there is an error creating the stream, nothing will be
511                        filled in here.
512    \param      _url   The URL to read from.
513                       Currently only the "file:", "http:", and "https:" schemes
514                        are supported.
515                       Both "http:" and "https:" may be disabled at compile
516                        time, in which case opening such URLs will fail.
517    \param      _flags The <a href="#url_flags">optional flags</a> to use.
518    \return A stream handle to use with the callbacks, or <code>NULL</code> on
519             error.*/
520 OP_WARN_UNUSED_RESULT void *op_url_stream_create(OpusFileCallbacks *_cb,
521  const char *_url,int _flags) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
522
523 /**Creates a stream that reads from the given URL using the specified proxy.
524    \param[out] _cb         The callbacks to use for this stream.
525                            If there is an error creating the stream, nothing
526                             will be filled in here.
527    \param      _url        The URL to read from.
528                            Currently only the "file:", "http:", and "https:"
529                             schemes are supported.
530                            Both "http:" and "https:" may be disabled at compile
531                             time, in which case opening such URLs will fail.
532    \param      _flags      The <a href="#url_flags">optional flags</a> to use.
533    \param      _proxy_host The host of the proxy to connect to.
534                            This may be <code>NULL</code> if you do not wish to
535                             use a proxy.
536                            The proxy information is ignored if \a _url is a
537                             <file:> URL.
538    \param      _proxy_port The port of the proxy to connect to.
539                            This is ignored if \a _proxy_host is
540                             <code>NULL</code>.
541    \param      _proxy_user The username to use with the specified proxy.
542                            This may be <code>NULL</code> if no authorization is
543                             required.
544                            This is ignored if \a _proxy_host is
545                             <code>NULL</code>.
546    \param      _proxy_pass The password to use with the specified proxy.
547                            This may be <code>NULL</code> if no authorization is
548                             required.
549                            This is ignored if either \a _proxy_host or
550                             \a _proxy_user are <code>NULL</code>.
551    \return A stream handle to use with the callbacks, or <code>NULL</code> on
552             error.*/
553 OP_WARN_UNUSED_RESULT void *op_url_stream_create_with_proxy(
554  OpusFileCallbacks *_cb,const char *_url,int _flags,
555   const char *_proxy_host,unsigned _proxy_port,
556   const char *_proxy_user,const char *_proxy_pass) OP_ARG_NONNULL(1)
557   OP_ARG_NONNULL(2);
558
559 /*@}*/
560
561 /*@}*/
562
563 /**Test to see if this is an Opus stream.
564    For good results, you will need at least 57 bytes (for a pure Opus-only
565     stream).
566    Something more like 512 bytes will give more reliable results for
567     multiplexed streams.
568    This function is meant to be a quick-rejection filter.
569    Its purpose is not to guarantee that a stream is a valid Opus stream, but to
570     ensure that looks enough like Opus that it isn't going to be recognized as
571     some other format (except possibly an Opus stream that is also multiplexed
572     with other codecs, such as video).
573    If you need something that gives a much better guarantee that this stream
574     can be opened successfully, use op_test_callbacks() or one of the
575     associated convenience functions.
576    \param[out] _head     The parsed ID header contents.
577                          You may pass <code>NULL</code> if you do not need
578                           this information.
579                          If the function fails, the contents of this structure
580                           remain untouched.
581    \param _initial_data  An initial buffer of data from the start of the
582                           stream.
583    \param _initial_bytes The number of bytes in \a _initial_data.
584    \return 0 if the data appears to be Opus, or a negative value on error.
585    \retval #OP_FALSE      There was not enough data to tell if this was an Opus
586                            stream or not.
587    \retval #OP_EFAULT     An internal memory allocation failed.
588    \retval #OP_EIMPL      The stream used a feature that is not implemented,
589                            such as an unsupported channel family.
590    \retval #OP_ENOTFORMAT If the data did not contain a recognizable ID
591                            header for an Opus stream.
592    \retval #OP_EVERSION   If the version field signaled a version this library
593                            does not know how to parse.
594    \retval #OP_EBADHEADER A required header packet was not properly formatted,
595                            contained illegal values, or was missing
596                            altogether.*/
597 int op_test(OpusHead *_head,
598  const unsigned char *_initial_data,size_t _initial_bytes);
599
600 /**Open a stream from the given file path.
601    \param      _path  The path to the file to open.
602    \param[out] _error Returns 0 on success, or a failure code on error.
603                       You may pass in <code>NULL</code> if you don't want the
604                        failure code.
605                       The failure code will be #OP_EFAULT if the file could not
606                        be opened, or one of the other failure codes from
607                        op_open_callbacks() otherwise.
608    \return An #OggOpusFile pointer on success, or <code>NULL</code> on error.*/
609 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_file(const char *_path,int *_error)
610  OP_ARG_NONNULL(1);
611
612 /**Open a stream from a memory buffer.
613    \param      _data  The memory buffer to open.
614    \param      _size  The number of bytes in the buffer.
615    \param[out] _error Returns 0 on success, or a failure code on error.
616                       You may pass in <code>NULL</code> if you don't want the
617                        failure code.
618                       See op_open_callbacks() for a full list of failure codes.
619    \return An #OggOpusFile pointer on success, or <code>NULL</code> on error.*/
620 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_memory(const unsigned char *_data,
621  size_t _size,int *_error);
622
623 /**Open a stream from a URL.
624    \param      _url   The URL to open.
625                       Currently only the <file:>, <http:>, and <https:> schemes
626                        are supported.
627                       Both "http:" and "https:" may be disabled at compile
628                        time, in which case opening such URLs will fail.
629    \param      _flags The <a href="#url_flags">optional flags</a> to use.
630    \param[out] _error Returns 0 on success, or a failure code on error.
631                       You may pass in <code>NULL</code> if you don't want the
632                        failure code.
633                       See op_open_callbacks() for a full list of failure codes.
634    \return An #OggOpusFile pointer on success, or <code>NULL</code> on error.*/
635 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_url(const char *_url,
636  int _flags,int *_error) OP_ARG_NONNULL(1);
637
638 /**Open a stream from a URL using the specified proxy.
639    \param      _url        The URL to open.
640                            Currently only the <file:>, <http:>, and <https:>
641                             schemes are supported.
642                            Both "http:" and "https:" may be disabled at compile
643                             time, in which case opening such URLs will fail.
644    \param      _flags      The <a href="#url_flags">optional flags</a> to use.
645    \param      _proxy_host The host of the proxy to connect to.
646                            This may be <code>NULL</code> if you do not wish to
647                             use a proxy.
648                            The proxy information is ignored if \a _url is a
649                             <file:> URL.
650    \param      _proxy_port The port of the proxy to connect to.
651                            This is ignored if \a _proxy_host is
652                             <code>NULL</code>.
653    \param      _proxy_user The username to use with the specified proxy.
654                            This may be <code>NULL</code> if no authorization is
655                             required.
656                            This is ignored if \a _proxy_host is
657                             <code>NULL</code>.
658    \param      _proxy_pass The password to use with the specified proxy.
659                            This may be <code>NULL</code> if no authorization is
660                             required.
661                            This is ignored if either \a _proxy_host or
662                             \a _proxy_user are <code>NULL</code>.
663    \param[out] _error      Returns 0 on success, or a failure code on error.
664                            You may pass in <code>NULL</code> if you don't want
665                             the failure code.
666                            See op_open_callbacks() for a full list of failure
667                             codes.
668    \return An #OggOpusFile pointer on success, or <code>NULL</code> on error.*/
669 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_url_with_proxy(const char *_url,
670  int _flags,const char *_proxy_host,unsigned _proxy_port,
671  const char *_proxy_user,const char *_proxy_pass,int *_error)
672  OP_ARG_NONNULL(1);
673
674 /**Open a stream using the given set of callbacks to access it.
675    \param _source        The stream to read from (e.g., a <code>FILE *</code>).
676    \param _cb            The callbacks with which to access the stream.
677                          <code><a href="#op_read_func">read()</a></code> must
678                           be implemented.
679                          <code><a href="#op_seek_func">seek()</a></code> and
680                           <code><a href="#op_tell_func">tell()</a></code> may
681                           be <code>NULL</code>, or may always return -1 to
682                           indicate a source is unseekable, but if
683                           <code><a href="#op_seek_func">seek()</a></code> is
684                           implemented and succeeds on a particular source, then
685                           <code><a href="#op_tell_func">tell()</a></code> must
686                           also.
687                          <code><a href="#op_close_func">close()</a></code> may
688                           be <code>NULL</code>, but if it is not, it will be
689                           called when the #OggOpusFile is destroyed by
690                           op_free().
691                          It will not be called if op_open_callbacks() fails
692                           with an error.
693    \param _initial_data  An initial buffer of data from the start of the
694                           stream.
695                          Applications can read some number of bytes from the
696                           start of the stream to help identify this as an Opus
697                           stream, and then provide them here to allow the
698                           stream to be opened, even if it is unseekable.
699    \param _initial_bytes The number of bytes in \a _initial_data.
700                          If the stream is seekable, its current position (as
701                           reported by
702                           <code><a href="#opus_tell_func">tell()</a></code>
703                           at the start of this function) must be equal to
704                           \a _initial_bytes.
705                          Otherwise, seeking to absolute positions will
706                           generate inconsistent results.
707    \param[out] _error    Returns 0 on success, or a failure code on error.
708                          You may pass in <code>NULL</code> if you don't want
709                           the failure code.
710                          The failure code will be one of
711                          <dl>
712                            <dt>#OP_EREAD</dt>
713                            <dd>An underlying read, seek, or tell operation
714                             failed when it should have succeeded, or we failed
715                             to find data in the stream we had seen before.</dd>
716                            <dt>#OP_EFAULT</dt>
717                            <dd>There was a memory allocation failure, or an
718                             internal library error.</dd>
719                            <dt>#OP_EIMPL</dt>
720                            <dd>The stream used a feature that is not
721                             implemented, such as an unsupported channel
722                             family.</dd>
723                            <dt>#OP_EINVAL</dt>
724                            <dd><code><a href="#op_seek_func">seek()</a></code>
725                             was implemented and succeeded on this source, but
726                             <code><a href="#op_tell_func">tell()</a></code>
727                             did not, or the starting position indicator was
728                             not equal to \a _initial_bytes.</dd>
729                            <dt>#OP_ENOTFORMAT</dt>
730                            <dd>The stream contained a link that did not have
731                             any logical Opus streams in it.</dd>
732                            <dt>#OP_EBADHEADER</dt>
733                            <dd>A required header packet was not properly
734                             formatted, contained illegal values, or was missing
735                             altogether.</dd>
736                            <dt>#OP_EVERSION</dt>
737                            <dd>An ID header contained an unrecognized version
738                             number.</dd>
739                            <dt>#OP_EBADLINK</dt>
740                            <dd>We failed to find data we had seen before after
741                             seeking.</dd>
742                            <dt>#OP_EBADTIMESTAMP</dt>
743                            <dd>The first or last timestamp in a link failed
744                             basic validity checks.</dd>
745                          </dl>
746    \return A freshly opened #OggOpusFile, or <code>NULL</code> on error.*/
747 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_callbacks(void *_source,
748  const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
749  size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
750
751 /**Release all memory used by an #OggOpusFile.*/
752 void op_free(OggOpusFile *_of);
753
754 /**Partially open a stream from the given file path.
755    \see op_test_callbacks
756    \param      _path  The path to the file to open.
757    \param[out] _error Returns 0 on success, or a failure code on error.
758                       You may pass in <code>NULL</code> if you don't want the
759                        failure code.
760                       The failure code will be #OP_EFAULT if the file could not
761                        be opened, or one of the other failure codes from
762                        op_open_callbacks() otherwise.
763    \return An #OggOpusFile pointer on success, or <code>NULL</code> on error.*/
764 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_file(const char *_path,int *_error)
765  OP_ARG_NONNULL(1);
766
767 /**Partially open a stream from a memory buffer.
768    \see op_test_callbacks
769    \param      _data  The memory buffer to open.
770    \param      _size  The number of bytes in the buffer.
771    \param[out] _error Returns 0 on success, or a failure code on error.
772                       You may pass in <code>NULL</code> if you don't want the
773                        failure code.
774                       See op_open_callbacks() for a full list of failure codes.
775    \return An #OggOpusFile pointer on success, or <code>NULL</code> on error.*/
776 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_memory(const unsigned char *_data,
777  size_t _size,int *_error);
778
779 /**Partially open a stream from a URL.
780    \see op_test_callbacks
781    \param      _url   The URL to open.
782                       Currently only the <file:>, <http:>, and <https:> schemes
783                        are supported.
784                       Both "http:" and "https:" may be disabled at compile
785                        time, in which case opening such URLs will fail.
786    \param      _flags The <a href="#url_flags">optional flags</a> to use.
787    \param[out] _error Returns 0 on success, or a failure code on error.
788                       You may pass in <code>NULL</code> if you don't want the
789                        failure code.
790                       See op_open_callbacks() for a full list of failure codes.
791    \return An #OggOpusFile pointer on success, or <code>NULL</code> on error.*/
792 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_url(const char *_url,int _flags,
793  int *_error) OP_ARG_NONNULL(1);
794
795 /**Partially open a stream from a URL using the specified proxy.
796    \see op_test_callbacks
797    \param      _url        The URL to open.
798                            Currently only the <file:>, <http:>, and <https:>
799                             schemes are supported.
800                            Both "http:" and "https:" may be disabled at compile
801                             time, in which case opening such URLs will fail.
802    \param      _flags      The <a href="#url_flags">optional flags</a> to use.
803    \param      _proxy_host The host of the proxy to connect to.
804                            This may be <code>NULL</code> if you do not wish to
805                             use a proxy.
806                            The proxy information is ignored if \a _url is a
807                             <file:> URL.
808    \param      _proxy_port The port of the proxy to connect to.
809                            This is ignored if \a _proxy_host is
810                             <code>NULL</code>.
811    \param      _proxy_user The username to use with the specified proxy.
812                            This may be <code>NULL</code> if no authorization is
813                             required.
814                            This is ignored if \a _proxy_host is
815                             <code>NULL</code>.
816    \param      _proxy_pass The password to use with the specified proxy.
817                            This may be <code>NULL</code> if no authorization is
818                             required.
819                            This is ignored if either \a _proxy_host or
820                             \a _proxy_user are <code>NULL</code>.
821    \param[out] _error      Returns 0 on success, or a failure code on error.
822                            You may pass in <code>NULL</code> if you don't want
823                             the failure code.
824                            See op_open_callbacks() for a full list of failure
825                             codes.
826    \return An #OggOpusFile pointer on success, or <code>NULL</code> on error.*/
827 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_url_with_proxy(const char *_url,
828  int _flags,const char *_proxy_host,unsigned _proxy_port,
829  const char *_proxy_user,const char *_proxy_pass,int *_error)
830  OP_ARG_NONNULL(1);
831
832 /**Partially open a stream using the given set of callbacks to access it.
833    This tests for Opusness and loads the headers for the first link.
834    It does not seek (although it tests for seekability).
835    Use op_test_open() to finish opening the stream, or op_free() to dispose of
836     it.
837    \param _source        The stream to read from (e.g., a <code>FILE *</code>).
838    \param _cb            The callbacks with which to access the stream.
839                          <code><a href="#op_read_func">read()</a></code> must
840                           be implemented.
841                          <code><a href="#op_seek_func">seek()</a></code> and
842                           <code><a href="#op_tell_func">tell()</a></code> may
843                           be <code>NULL</code>, or may always return -1 to
844                           indicate a source is unseekable, but if
845                           <code><a href="#op_seek_func">seek()</a></code> is
846                           implemented and succeeds on a particular source, then
847                           <code><a href="#op_tell_func">tell()</a></code> must
848                           also.
849                          <code><a href="#op_close_func">close()</a></code> may
850                           be <code>NULL</code>, but if it is not, it will be
851                           called when the #OggOpusFile is destroyed by
852                           op_free().
853                          It will not be called if op_open_callbacks() fails
854                           with an error.
855    \param _initial_data  An initial buffer of data from the start of the
856                           stream.
857                          Applications can read some number of bytes from the
858                           start of the stream to help identify this as an Opus
859                           stream, and then provide them here to allow the
860                           stream to be tested more thoroughly, even if it is
861                           unseekable.
862    \param _initial_bytes The number of bytes in \a _initial_data.
863                          If the stream is seekable, its current position (as
864                           reported by
865                           <code><a href="#opus_tell_func">tell()</a></code>
866                           at the start of this function) must be equal to
867                           \a _initial_bytes.
868                          Otherwise, seeking to absolute positions will
869                           generate inconsistent results.
870    \param[out] _error    Returns 0 on success, or a failure code on error.
871                          You may pass in <code>NULL</code> if you don't want
872                           the failure code.
873                          See op_open_callbacks() for a full list of failure
874                           codes.
875    \return A freshly opened #OggOpusFile, or <code>NULL</code> on error.*/
876 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_callbacks(void *_source,
877  const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
878  size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
879
880 /**Finish opening a stream partially opened with op_test_callbacks() or one of
881     the associated convenience functions.
882    If this function fails, you are still responsible for freeing the
883     #OggOpusFile with op_free().
884    \return 0 on success, or a negative value on error.
885    \retval #OP_EREAD         An underlying read, seek, or tell operation failed
886                               when it should have succeeded.
887    \retval #OP_EFAULT        There was a memory allocation failure, or an
888                               internal library error.
889    \retval #OP_EIMPL         The stream used a feature that is not implemented,
890                               such as an unsupported channel family.
891    \retval #OP_EINVAL        The stream was not partially opened with
892                               op_test_callbacks() or one of the associated
893                               convenience functions.
894    \retval #OP_ENOTFORMAT    The stream contained a link that did not have any
895                               logical Opus streams in it.
896    \retval #OP_EBADHEADER    A required header packet was not properly
897                               formatted, contained illegal values, or was
898                               missing altogether.
899    \retval #OP_EVERSION      An ID header contained an unrecognized version
900                               number.
901    \retval #OP_EBADLINK      We failed to find data we had seen before after
902                               seeking.
903    \retval #OP_EBADTIMESTAMP The first or last timestamp in a link failed basic
904                               validity checks.*/
905 int op_test_open(OggOpusFile *_of) OP_ARG_NONNULL(1);
906
907 /**Returns the number of links in this chained stream.
908    \return For seekable sources, this returns the total number of links in the
909             whole stream.
910            For unseekable sources, this always returns 1.*/
911 int op_link_count(OggOpusFile *_of) OP_ARG_NONNULL(1);
912
913 /**Returns whether or not the data source being read is seekable.
914    This is true if
915    a) The seek and tell callbacks are both non-<code>NULL</code>,
916    b) The seek callback was successfully executed at least once, and
917    c) The tell callback was successfully able to report the position indicator
918     afterwards.
919    \return A non-zero value if seekable, and 0 if unseekable.*/
920 int op_seekable(OggOpusFile *_of) OP_ARG_NONNULL(1);
921
922 /**Get the serial number of the given link in a (possibly-chained) Ogg Opus
923     stream.
924    \param _li The index of the link whose serial number should be retrieved.
925               Use a negative number to get the serial number of the current
926                link.
927    \return The serial number of the given link.
928            If \a _li is greater than the total number of links, this returns
929             the serial number of the last link.
930            If the source is not seekable, this always returns the serial number
931             of the current link.*/
932 opus_uint32 op_serialno(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
933
934 /**Get the channel count of the given link in a (possibly-chained Ogg Opus
935     stream.
936    This is equivalent to <code>op_head(_of,_li)->channel_count</code>, but
937     is provided for convenience.
938    \param _li The index of the link whose channel count should be retrieved.
939               Use a negative number to get the channel count of the current
940                link.
941    \return The channel count of the given link.
942            If \a _li is greater than the total number of links, this returns
943             the channel count of the last link.
944            If the source is not seekable, this always returns the channel count
945             of the current link.*/
946 int op_channel_count(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
947
948 /**Get the total (compressed) size of the stream, or of an individual link in
949     a (possibly-chained) Ogg Opus stream, including all headers and Ogg muxing
950     overhead.
951    \param _li The index of the link whose compressed size should be computed.
952               Use a negative number to get the compressed size of the entire
953                stream.
954    \return The compressed size of the entire stream if \a _li is negative, the
955             compressed size of link \a _li if it is non-negative, or a negative
956             value on error.
957    \retval #OP_EINVAL The source is not seekable (so we can't know the length),
958                        \a _li wasn't less than the total number of links in
959                        the stream, or the stream was only partially open.*/
960 opus_int64 op_raw_total(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
961
962 /**Get the total PCM length (number of samples at 48 kHz) of the stream, or of
963     an individual link in a (possibly-chained) Ogg Opus stream.
964    Users looking for <code>op_time_total()</code> should use op_pcm_total()
965     instead.
966    Because timestamps in Opus are fixed at 48 kHz, there is no need for a
967     separate function to convert this to seconds (and leaving it out avoids
968     introducing floating point to the API, for those that wish to avoid it).
969    \param _li The index of the link whose PCM length should be computed.
970               Use a negative number to get the PCM length of the entire stream.
971    \return The PCM length of the entire stream if \a _li is negative, the PCM
972             length of link \a _li if it is non-negative, or a negative value on
973             error.
974    \retval #OP_EINVAL The source is not seekable (so we can't know the length),
975                        \a _li wasn't less than the total number of links in
976                        the stream, or the stream was only partially open.*/
977 ogg_int64_t op_pcm_total(OggOpusFile *_of,int i) OP_ARG_NONNULL(1);
978
979 /**Get the ID header information for the given link in a (possibly chained) Ogg
980     Opus stream.
981    \param _li The index of the link whose ID header information should be
982                retrieved.
983               Use a negative number to get the ID header information of the
984                current link.
985               For an unseekable stream, \a _li is ignored, and the ID header
986                information for the current link is always returned, if
987                available.
988    \return The contents of the ID header for the given link, or
989             <code>NULL</code> if either \a _li is larger than the number of
990             links or the current link was requested, but the stream was only
991             partially open.*/
992 const OpusHead *op_head(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
993
994 /**Get the comment header information for the given link in a (possibly
995     chained) Ogg Opus stream.
996    \param _li The index of the link whose comment header information should be
997                retrieved.
998               Use a negative number to get the comment header information of
999                the current link.
1000               For an unseekable stream, \a _li is ignored, and the comment
1001                header information for the current link is always returned, if
1002                available.
1003    \return The contents of the comment header for the given link, or
1004             <code>NULL</code> if either \a _li is larger than the number of
1005             links or the current link was requested, but the stream was only
1006             partially open.*/
1007 const OpusTags *op_tags(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1008
1009 /**Retrieve the index of the current link.
1010    This is the link that produced the data most recently read by
1011     op_read_float() or its associated functions, or, after a seek, the link
1012     that the seek target landed in.
1013    Reading more data may advance the link index (even on the first read after a
1014     seek).
1015    \return The index of the current link on success, or a negative value on
1016             failture.
1017            For seekable streams, this is a number between 0 and the value
1018             returned by op_link_count().
1019            For unseekable streams, this value starts at 0 and increments by one
1020             each time a new link is encountered (even though op_link_count()
1021             always returns 1).
1022    \retval #OP_EINVAL The stream was not fully open.*/
1023 int op_current_link(OggOpusFile *_of) OP_ARG_NONNULL(1);
1024
1025 /**Computes the bitrate for a given link in a (possibly chained) Ogg Opus
1026     stream.
1027    The stream must be seekable to compute the bitrate.
1028    For unseekable streams, use op_bitrate_instant() to get periodic estimates.
1029    \param _li The index of the link whose bitrate should be computed.
1030               USe a negative number to get the bitrate of the whole stream.
1031    \return The bitrate on success, or a negative value on error.
1032    \retval #OP_EINVAL The stream was not fully open, the stream was not
1033                        seekable, or \a _li was larger than the number of
1034                        links.*/
1035 opus_int32 op_bitrate(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1036
1037 /**Compute the instantaneous bitrate, measured as the ratio of bits to playable
1038     samples decoed since a) the last call to op_bitrate_instant(), b) the last
1039     seek, or c) the start of playback, whichever was most recent.
1040    This will spike somewhat after a seek or at the start/end of a chain
1041     boundary, as pre-skip, pre-roll, and end-trimming causes samples to be
1042     decoded but not played.
1043    \return The bitrate, in bits per second, or a negative value on error.
1044    \retval #OP_EFALSE No data has been decoded since any of the events
1045                        described above.
1046    \retval #OP_EINVAL The stream was not fully open.*/
1047 opus_int32 op_bitrate_instant(OggOpusFile *_of) OP_ARG_NONNULL(1);
1048
1049 /**Seek to a byte offset relative to the <b>compressed</b> data.
1050    This also scans packets to update the PCM cursor.
1051    It will cross a logical bitstream boundary, but only if it can't get any
1052     packets out of the tail of the link to which it seeks.
1053    \param _byte_offset The byte position to seek to.
1054    \return 0 on success, or a negative error code on failure.
1055    \retval #OP_EREAD    The seek failed.
1056    \retval #OP_EINVAL   The stream was not fully open, or the target was
1057                          outside the valid range for the stream.
1058    \retval #OP_ENOSEEK  This stream is not seekable.
1059    \retval #OP_EBADLINK Failed to initialize a decoder for a stream for an
1060                          unknown reason.*/
1061 int op_raw_seek(OggOpusFile *_of,opus_int64 _byte_offset) OP_ARG_NONNULL(1);
1062
1063 /**Seek to a page preceding the specified PCM offset, such that decoding will
1064     quickly arrive at the requested position.
1065    This is faster than sample-granularity seeking because it doesn't do the
1066     last bit of decode to find a specific sample.
1067    \param _pcm_offset The PCM offset to seek to.
1068                       This is in samples at 48 kHz relative to the start of the
1069                        stream.
1070    \return 0 on success, or a negative value on error.
1071    \retval #OP_EREAD   The seek failed.
1072    \retval #OP_EINVAL  The stream was not fully open, or the target was outside
1073                         the valid range for the stream.
1074    \retval #OP_ENOSEEK This stream is not seekable.*/
1075 int op_pcm_seek_page(OggOpusFile *_of,ogg_int64_t _pcm_offset)
1076  OP_ARG_NONNULL(1);
1077
1078 /**Seek to the specified PCM offset, such that decoding will begin at exactly
1079     the requested position.
1080    \param _pcm_offset The PCM offset to seek to.
1081                       This is in samples at 48 kHz relative to the start of the
1082                        stream.
1083    \return 0 on success, or a negative value on error.
1084    \retval #OP_EREAD   The seek failed.
1085    \retval #OP_EINVAL  The stream was not fully open, or the target was outside
1086                         the valid range for the stream.
1087    \retval #OP_ENOSEEK This stream is not seekable.*/
1088 int op_pcm_seek(OggOpusFile *_of,ogg_int64_t _pcm_offset) OP_ARG_NONNULL(1);
1089
1090 /**Obtain the current value of the position indicator for \a _of.
1091    \return The byte position that is currently being read from.*/
1092 opus_int64 op_raw_tell(OggOpusFile *_of) OP_ARG_NONNULL(1);
1093
1094 /**Obtain the PCM offset of the next sample to be read.
1095    If the stream is not properly timestamped, this might not increment by the
1096     proper amount between reads, or even return monotonically increasing
1097     values.
1098    \return The PCM offset of the next sample to be read.*/
1099 ogg_int64_t op_pcm_tell(OggOpusFile *_of) OP_ARG_NONNULL(1);
1100
1101 /**Reads more samples from the stream.
1102    \param[out] _pcm      A buffer in which to store the output PCM samples, as
1103                           signed native-endian 16-bit values with a nominal
1104                           range of <code>[-32768,32767)</code>.
1105                          Multiple channels are interleaved using the
1106                           <a href="http://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-800004.3.9">Vorbis
1107                           channel ordering</a>.
1108                          This must have room for at least \a _buf_size values.
1109    \param      _buf_size The number of values that can be stored in \a _pcm.
1110                          It is reccommended that this be large enough for at
1111                           least 120 ms of data at 48 kHz per channel (5760
1112                           values per channel).
1113                          Smaller buffers will simply return less data, possibly
1114                           consuming more memory to buffer the data internally.
1115    \param[out] _li       The index of the link this data was decoded from.
1116                          You may pass <code>NULL</code> if you do not need this
1117                           information.
1118                          If this function fails (returning a negative value),
1119                           this parameter is left unset.
1120    \return The number of samples read per channel on success, or a negative
1121             value on failure.
1122            The channel count can be retrieved on success by calling
1123             <code>op_head(_of,*_li)</code>.
1124            The number of samples returned may be 0 if the buffer was too small
1125             to store even a single sample for all channels, or if end-of-file
1126             was reached.
1127            The list of possible failure codes follows.
1128            Most of them can only be returned by unseekable, chained streams
1129             that encounter a new link.
1130    \retval #OP_EFAULT        An internal memory allocation failed.
1131    \retval #OP_EIMPL         An unseekable stream encountered a new link that
1132                               used a feature that is not implemented, such as
1133                               an unsupported channel family.
1134    \retval #OP_EINVAL        The stream was not fully open.
1135    \retval #OP_ENOTFORMAT    An unseekable stream encountered a new link that
1136                               contained a link that did not have any logical
1137                               Opus streams in it.
1138    \retval #OP_EBADHEADER    An unseekable stream encountered a new link with a
1139                               required header packet that was not properly
1140                               formatted, contained illegal values, or was
1141                               missing altogether.
1142    \retval #OP_EVERSION      An unseekable stream encountered a new link with
1143                               an ID header that contained an unrecognized
1144                               version number.
1145    \retval #OP_EBADPACKET    Failed to properly decode the next packet.
1146    \retval #OP_EBADTIMESTAMP An unseekable stream encountered a new link with
1147                               a starting timestamp that failed basic validity
1148                               checks.*/
1149 OP_WARN_UNUSED_RESULT int op_read(OggOpusFile *_of,
1150  opus_int16 *_pcm,int _buf_size,int *_li) OP_ARG_NONNULL(1);
1151
1152 /**Reads more samples from the stream.
1153    \param[out] _pcm      A buffer in which to store the output PCM samples as
1154                           signed floats with a nominal range of
1155                           <code>[-1.0,1.0]</code>.
1156                          Multiple channels are interleaved using the
1157                           <a href="http://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-800004.3.9">Vorbis
1158                           channel ordering</a>.
1159                          This must have room for at least \a _buf_size floats.
1160    \param      _buf_size The number of floats that can be stored in \a _pcm.
1161                          It is reccommended that this be large enough for at
1162                           least 120 ms of data at 48 kHz per channel (5760
1163                           samples per channel).
1164                          Smaller buffers will simply return less data, possibly
1165                           consuming more memory to buffer the data internally.
1166    \param[out] _li       The index of the link this data was decoded from.
1167                          You may pass <code>NULL</code> if you do not need this
1168                           information.
1169                          If this function fails (returning a negative value),
1170                           this parameter is left unset.
1171    \return The number of samples read per channel on success, or a negative
1172             value on failure.
1173            The channel count can be retrieved on success by calling
1174             <code>op_head(_of,*_li)</code>.
1175            The number of samples returned may be 0 if the buffer was too small
1176             to store even a single sample for all channels, or if end-of-file
1177             was reached.
1178            The list of possible failure codes follows.
1179            Most of them can only be returned by unseekable, chained streams
1180             that encounter a new link.
1181    \retval #OP_EFAULT        An internal memory allocation failed.
1182    \retval #OP_EIMPL         An unseekable stream encountered a new link that
1183                               used a feature that is not implemented, such as
1184                               an unsupported channel family.
1185    \retval #OP_EINVAL        The stream was not fully open.
1186    \retval #OP_ENOTFORMAT    An unseekable stream encountered a new link that
1187                               contained a link that did not have any logical
1188                               Opus streams in it.
1189    \retval #OP_EBADHEADER    An unseekable stream encountered a new link with a
1190                               required header packet that was not properly
1191                               formatted, contained illegal values, or was
1192                               missing altogether.
1193    \retval #OP_EVERSION      An unseekable stream encountered a new link with
1194                               an ID header that contained an unrecognized
1195                               version number.
1196    \retval #OP_EBADPACKET    Failed to properly decode the next packet.
1197    \retval #OP_EBADTIMESTAMP An unseekable stream encountered a new link with
1198                               a starting timestamp that failed basic validity
1199                               checks.*/
1200 OP_WARN_UNUSED_RESULT int op_read_float(OggOpusFile *_of,
1201  float *_pcm,int _buf_size,int *_li) OP_ARG_NONNULL(1);
1202
1203 /**Reads more samples from the stream and downmixes to stereo, if necessary.
1204    This function is intended for simple players that want a uniform output
1205     format, even if the channel count changes between links in a chained
1206     stream.
1207    \param[out] _pcm      A buffer in which to store the output PCM samples, as
1208                           signed native-endian 16-bit values with a nominal
1209                           range of <code>[-32768,32767)</code>.
1210                          The left and right channels are interleaved in the
1211                           buffer.
1212                          This must have room for at least \a _buf_size values.
1213    \param      _buf_size The number of values that can be stored in \a _pcm.
1214                          It is reccommended that this be large enough for at
1215                           least 120 ms of data at 48 kHz per channel (11520
1216                           values total).
1217                          Smaller buffers will simply return less data, possibly
1218                           consuming more memory to buffer the data internally.
1219    \return The number of samples read per channel on success, or a negative
1220             value on failure.
1221            The number of samples returned may be 0 if the buffer was too small
1222             to store even a single sample for both channels, or if end-of-file
1223             was reached.
1224            The list of possible failure codes follows.
1225            Most of them can only be returned by unseekable, chained streams
1226             that encounter a new link.
1227    \retval #OP_EFAULT        An internal memory allocation failed.
1228    \retval #OP_EIMPL         An unseekable stream encountered a new link that
1229                               used a feature that is not implemented, such as
1230                               an unsupported channel family.
1231    \retval #OP_EINVAL        The stream was not fully open.
1232    \retval #OP_ENOTFORMAT    An unseekable stream encountered a new link that
1233                               contained a link that did not have any logical
1234                               Opus streams in it.
1235    \retval #OP_EBADHEADER    An unseekable stream encountered a new link with a
1236                               required header packet that was not properly
1237                               formatted, contained illegal values, or was
1238                               missing altogether.
1239    \retval #OP_EVERSION      An unseekable stream encountered a new link with
1240                               an ID header that contained an unrecognized
1241                               version number.
1242    \retval #OP_EBADPACKET    Failed to properly decode the next packet.
1243    \retval #OP_EBADTIMESTAMP An unseekable stream encountered a new link with
1244                               a starting timestamp that failed basic validity
1245                               checks.*/
1246 OP_WARN_UNUSED_RESULT int op_read_stereo(OggOpusFile *_of,
1247  opus_int16 *_pcm,int _buf_size) OP_ARG_NONNULL(1);
1248
1249 /**Reads more samples from the stream and downmixes to stereo, if necessary.
1250    This function is intended for simple players that want a uniform output
1251     format, even if the channel count changes between links in a chained
1252     stream.
1253    \param[out] _pcm      A buffer in which to store the output PCM samples, as
1254                           signed floats with a nominal range of
1255                           <code>[-1.0,1.0]</code>.
1256                          The left and right channels are interleaved in the
1257                           buffer.
1258                          This must have room for at least \a _buf_size values.
1259    \param      _buf_size The number of values that can be stored in \a _pcm.
1260                          It is reccommended that this be large enough for at
1261                           least 120 ms of data at 48 kHz per channel (11520
1262                           values total).
1263                          Smaller buffers will simply return less data, possibly
1264                           consuming more memory to buffer the data internally.
1265    \return The number of samples read per channel on success, or a negative
1266             value on failure.
1267            The number of samples returned may be 0 if the buffer was too small
1268             to store even a single sample for both channels, or if end-of-file
1269             was reached.
1270            The list of possible failure codes follows.
1271            Most of them can only be returned by unseekable, chained streams
1272             that encounter a new link.
1273    \retval #OP_EFAULT        An internal memory allocation failed.
1274    \retval #OP_EIMPL         An unseekable stream encountered a new link that
1275                               used a feature that is not implemented, such as
1276                               an unsupported channel family.
1277    \retval #OP_EINVAL        The stream was not fully open.
1278    \retval #OP_ENOTFORMAT    An unseekable stream encountered a new link that
1279                               contained a link that did not have any logical
1280                               Opus streams in it.
1281    \retval #OP_EBADHEADER    An unseekable stream encountered a new link with a
1282                               required header packet that was not properly
1283                               formatted, contained illegal values, or was
1284                               missing altogether.
1285    \retval #OP_EVERSION      An unseekable stream encountered a new link with
1286                               an ID header that contained an unrecognized
1287                               version number.
1288    \retval #OP_EBADPACKET    Failed to properly decode the next packet.
1289    \retval #OP_EBADTIMESTAMP An unseekable stream encountered a new link with
1290                               a starting timestamp that failed basic validity
1291                               checks.*/
1292 OP_WARN_UNUSED_RESULT int op_read_float_stereo(OggOpusFile *_of,
1293  float *_pcm,int _buf_size) OP_ARG_NONNULL(1);
1294
1295 # if OP_GNUC_PREREQ(4,0)
1296 #  pragma GCC visibility pop
1297 # endif
1298
1299 # if defined(__cplusplus)
1300 }
1301 # endif
1302
1303 #endif