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.

Data Structures

Functions for reading from streams

Detailed Description

Typedef Documentation

◆ op_read_func

◆ op_seek_func

◆ op_tell_func

◆ op_close_func

Function Documentation

◆ op_fopen()

◆ op_fdopen()

◆ op_freopen()

◆ op_mem_stream_create()

◆ op_url_stream_vcreate()

◆ op_url_stream_create()