opusfile  0.7
Stand-alone decoder library for .opus files.
Data Structures
Abstract Stream Reading Interface

Data Structures

struct  OpusFileCallbacks
 The callbacks used to access non-FILE stream resources. More...
 

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 standard FILE pointers, complete streams stored in a single block of memory, or URLs.

typedef int(* op_read_func) (void *_stream, unsigned char *_ptr, int _nbytes)
 Reads up to _nbytes bytes of data from _stream. More...
 
typedef int(* op_seek_func) (void *_stream, opus_int64 _offset, int _whence)
 Sets the position indicator for _stream. More...
 
typedef opus_int64(* op_tell_func) (void *_stream)
 Obtains the current value of the position indicator for _stream. More...
 
typedef int(* op_close_func) (void *_stream)
 Closes the underlying stream. More...
 
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)
 Opens a stream with fopen() and fills in a set of callbacks that can be used to access it. More...
 
OP_WARN_UNUSED_RESULT void * op_fdopen (OpusFileCallbacks *_cb, int _fd, const char *_mode) OP_ARG_NONNULL(1) OP_ARG_NONNULL(3)
 Opens a stream with fdopen() and fills in a set of callbacks that can be used to access it. More...
 
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)
 Opens a stream with freopen() and fills in a set of callbacks that can be used to access it. More...
 
OP_WARN_UNUSED_RESULT void * op_mem_stream_create (OpusFileCallbacks *_cb, const unsigned char *_data, size_t _size) OP_ARG_NONNULL(1)
 Creates a stream that reads from the given block of memory. More...
 
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)
 Creates a stream that reads from the given URL. More...
 
OP_WARN_UNUSED_RESULT void * op_url_stream_create (OpusFileCallbacks *_cb, const char *_url,...) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2)
 Creates a stream that reads from the given URL. More...
 

Detailed Description

Typedef Documentation

typedef int(* op_read_func) (void *_stream, unsigned char *_ptr, int _nbytes)

Reads up to _nbytes bytes of data from _stream.

Parameters
_streamThe stream to read from.
[out]_ptrThe buffer to store the data in.
_nbytesThe maximum number of bytes to read. This function may return fewer, though it will not return zero unless it reaches end-of-file.
Returns
The number of bytes successfully read, or a negative value on error.
typedef int(* op_seek_func) (void *_stream, opus_int64 _offset, int _whence)

Sets the position indicator for _stream.

The new position, measured in bytes, is obtained by adding _offset bytes to the position specified by _whence. If _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.

Return values
0Success.
-1Seeking is not supported or an error occurred. errno need not be set.
typedef opus_int64(* op_tell_func) (void *_stream)

Obtains the current value of the position indicator for _stream.

Returns
The current position indicator.
typedef int(* op_close_func) (void *_stream)

Closes the underlying stream.

Return values
0Success.
EOFAn error occurred. errno need not be set.

Function Documentation

OP_WARN_UNUSED_RESULT void* op_fopen ( OpusFileCallbacks _cb,
const char *  _path,
const char *  _mode 
)

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.

Parameters
[out]_cbThe callbacks to use for this file. If there is an error opening the file, nothing will be filled in here.
_pathThe path to the file to open. On Windows, this string must be UTF-8 (to allow access to files whose names cannot be represented in the current MBCS code page). All other systems use the native character encoding.
_modeThe mode to open the file in.
Returns
A stream handle to use with the callbacks, or NULL on error.
OP_WARN_UNUSED_RESULT void* op_fdopen ( OpusFileCallbacks _cb,
int  _fd,
const char *  _mode 
)

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.

Parameters
[out]_cbThe callbacks to use for this file. If there is an error opening the file, nothing will be filled in here.
_fdThe file descriptor to open.
_modeThe mode to open the file in.
Returns
A stream handle to use with the callbacks, or NULL on error.
OP_WARN_UNUSED_RESULT void* op_freopen ( OpusFileCallbacks _cb,
const char *  _path,
const char *  _mode,
void *  _stream 
)

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.

Parameters
[out]_cbThe callbacks to use for this file. If there is an error opening the file, nothing will be filled in here.
_pathThe path to the file to open. On Windows, this string must be UTF-8 (to allow access to files whose names cannot be represented in the current MBCS code page). All other systems use the native character encoding.
_modeThe mode to open the file in.
_streamA stream previously returned by op_fopen(), op_fdopen(), or op_freopen().
Returns
A stream handle to use with the callbacks, or NULL on error.
OP_WARN_UNUSED_RESULT void* op_mem_stream_create ( OpusFileCallbacks _cb,
const unsigned char *  _data,
size_t  _size 
)

Creates a stream that reads from the given block of memory.

This block of memory must contain the complete stream to decode. This is useful for caching small streams (e.g., sound effects) in RAM.

Parameters
[out]_cbThe callbacks to use for this stream. If there is an error creating the stream, nothing will be filled in here.
_dataThe block of memory to read from.
_sizeThe size of the block of memory.
Returns
A stream handle to use with the callbacks, or NULL on error.
OP_WARN_UNUSED_RESULT void* op_url_stream_vcreate ( OpusFileCallbacks _cb,
const char *  _url,
va_list  _ap 
)

Creates a stream that reads from the given URL.

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 _ap is undefined after the call.

Note
If you use this function, you must link against libopusurl.
Parameters
[out]_cbThe callbacks to use for this stream. If there is an error creating the stream, nothing will be filled in here.
_urlThe URL to read from. Currently only the <file:>, <http:>, and <https:> schemes are supported. Both <http:> and <https:> may be disabled at compile time, in which case opening such URLs will always fail. Currently this only supports URIs. IRIs should be converted to UTF-8 and URL-escaped, with internationalized domain names encoded in punycode, before passing them to this function.
[in,out]_apA list of the optional flags to use. This is a variable-length list of options terminated with NULL.
Returns
A stream handle to use with the callbacks, or NULL on error.
OP_WARN_UNUSED_RESULT void* op_url_stream_create ( OpusFileCallbacks _cb,
const char *  _url,
  ... 
)

Creates a stream that reads from the given URL.

Note
If you use this function, you must link against libopusurl.
Parameters
[out]_cbThe callbacks to use for this stream. If there is an error creating the stream, nothing will be filled in here.
_urlThe URL to read from. Currently only the <file:>, <http:>, and <https:> schemes are supported. Both <http:> and <https:> may be disabled at compile time, in which case opening such URLs will always fail. Currently this only supports URIs. IRIs should be converted to UTF-8 and URL-escaped, with internationalized domain names encoded in punycode, before passing them to this function.
...The optional flags to use. This is a variable-length list of options terminated with NULL.
Returns
A stream handle to use with the callbacks, or NULL on error.