cannam@86: The ov_callbacks structure contains file manipulation function prototypes necessary for opening, closing, seeking, and location.
cannam@86:
cannam@86:
cannam@86: The ov_callbacks structure does not need to be user-defined if you are
cannam@86: working with stdio-based file manipulation; the ov_fopen() and ov_open() calls internally provide default callbacks for
cannam@86: stdio. ov_callbacks are defined and passed to ov_open_callbacks() when
cannam@86: implementing non-stdio based stream manipulation (such as playback
cannam@86: from a memory buffer) or when ov_open()-style initialization from a FILE * is required under Windows [a].
cannam@86:
cannam@86:
cannam@86:
cannam@86:
cannam@86:
cannam@86:
typedef struct {
cannam@86: size_t (*read_func) (void *ptr, size_t size, size_t nmemb, void *datasource);
cannam@86: int (*seek_func) (void *datasource, ogg_int64_t offset, int whence);
cannam@86: int (*close_func) (void *datasource);
cannam@86: long (*tell_func) (void *datasource);
cannam@86: } ov_callbacks;
cannam@86:
cannam@86:
cannam@86:
cannam@86:
cannam@86:
Relevant Struct Members
cannam@86:
cannam@86:
read_func
cannam@86:
Pointer to custom data reading function.
cannam@86:
seek_func
cannam@86:
Pointer to custom data seeking function. If the data source is not seekable (or the application wants the data source to be treated as unseekable at all times), the provided seek callback should always return -1 (failure) or the seek_func and tell_func fields should be set to NULL.
cannam@86:
close_func
cannam@86:
Pointer to custom data source closure function. Set to NULL if libvorbisfile should not attempt to automatically close the file/data handle.
cannam@86:
tell_func
cannam@86:
Pointer to custom data location function. If the data source is not seekable (or the application wants the data source to be treated as unseekable at all times), the provided tell callback should always return -1 (failure) or the seek_func and tell_func fields should be set to NULL.
cannam@86:
cannam@86:
cannam@86:
cannam@86:
cannam@86:
Predefined callbacks
cannam@86: The header vorbis/vorbisfile.h provides several predefined static ov_callbacks structures that may be passed to ov_open_callbacks():
cannam@86:
cannam@86:
OV_CALLBACKS_DEFAULT
cannam@86:
cannam@86: These callbacks provide the same behavior as used internally by ov_fopen() and ov_open().
cannam@86:
cannam@86:
OV_CALLBACKS_NOCLOSE
cannam@86:
cannam@86: The same as OV_CALLBACKS_DEFAULT, but with the
cannam@86: close_func field set to NULL. The most typical use would be
cannam@86: to use ov_open_callbacks() to
cannam@86: provide the same behavior as ov_open(), but
cannam@86: not close the file/data handle in ov_clear().
cannam@86:
cannam@86:
OV_CALLBACKS_STREAMONLY
cannam@86:
cannam@86: A set of callbacks that set seek_func and tell_func
cannam@86: to NULL, thus forcing strict streaming-only behavior regardless of
cannam@86: whether or not the input is actually seekable.
cannam@86:
cannam@86:
OV_CALLBACKS_STREAMONLY_NOCLOSE
cannam@86:
cannam@86: The same as OV_CALLBACKS_STREAMONLY, but with
cannam@86: close_func also set to null, preventing libvorbisfile from
cannam@86: attempting to close the file/data handle in ov_clear().
cannam@86:
cannam@86:
cannam@86:
cannam@86:
cannam@86:
Examples and usage
cannam@86:
cannam@86: See the callbacks and non-stdio I/O document for more
cannam@86: detailed information on required behavior of the various callback
cannam@86: functions.