opusfile: Abstract Stream Reading Interface

| opusfile 0.10 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

## ◆ op_read_func

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

Reads up to _nbytes bytes of data from _stream.

Parameters

  | _stream | The stream to read from.
  [out] | _ptr | The buffer to store the data in.
  | _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.

Returns
  The number of bytes successfully read, or a negative value on error.

## ◆ op_seek_func

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

  0 | Success.
  -1 | Seeking is not supported or an error occurred. `errno` need not be set.

## ◆ op_tell_func

typedef opus_int64(* op_tell_func) (void *_stream)

Obtains the current value of the position indicator for _stream.

Returns
  The current position indicator.

## ◆ op_close_func

typedef int(* op_close_func) (void *_stream)

Closes the underlying stream.

Return values

  0 | Success.
  EOF | An error occurred. `errno` need not be set.

## Function Documentation

## ◆ op_fopen()

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] | _cb | The callbacks to use for this file. If there is an error opening the file, nothing will be filled in here.
  | _path | The 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.
  | _mode | The mode to open the file in.

Returns
  A stream handle to use with the callbacks, or `NULL` on error.

## ◆ op_fdopen()

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] | _cb | The callbacks to use for this file. If there is an error opening the file, nothing will be filled in here.
  | _fd | The file descriptor to open.
  | _mode | The mode to open the file in.

Returns
  A stream handle to use with the callbacks, or `NULL` on error.

## ◆ op_freopen()

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] | _cb | The callbacks to use for this file. If there is an error opening the file, nothing will be filled in here.
  | _path | The 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.
  | _mode | The mode to open the file in.
  | _stream | A 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_mem_stream_create()

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] | _cb | The callbacks to use for this stream. If there is an error creating the stream, nothing will be filled in here.
  | _data | The block of memory to read from.
  | _size | The size of the block of memory.

Returns
  A stream handle to use with the callbacks, or `NULL` on error.

## ◆ op_url_stream_vcreate()

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] | _cb | The callbacks to use for this stream. If there is an error creating the stream, nothing will be filled in here.
  | _url | The 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] | _ap | A 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_url_stream_create()

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] | _cb | The callbacks to use for this stream. If there is an error creating the stream, nothing will be filled in here.
  | _url | The 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.