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 struct OpusFileCallbacks	OpusFileCallbacks
typedef int(*	op_read_func )(void *_stream, unsigned char *_ptr, int _nbytes)
	Reads up to _nbytes bytes of data from _stream.
typedef int(*	op_seek_func )(void *_stream, opus_int64 _offset, int _whence)
	Sets the position indicator for _stream.
typedef opus_int64(*	op_tell_func )(void *_stream)
	Obtains the current value of the position indicator for _stream.
typedef int(*	op_close_func )(void *_stream)
	Closes the underlying stream.
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.
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.
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.
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.
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.
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 using the specified proxy.

---

Typedef Documentation

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.

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.

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:

0	Success.
EOF	An 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]	_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.
	_mode	The 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]	_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_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.
	_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_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_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.

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.
[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_WARN_UNUSED_RESULT void* op_url_stream_create	(	OpusFileCallbacks *	_cb,
		const char *	_url,
			...
	)

Creates a stream that reads from the given URL using the specified proxy.

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.
	...	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.