vorbisfile version 1.3.2 - 20101101
Callbacks and non-stdio I/O
Although stdio is convenient and nearly universally implemented as per
ANSI C, it is not suited to all or even most potential uses of Vorbis.
For additional flexibility, embedded applications may provide their
own I/O functions for use with Vorbisfile when stdio is unavailable or not
suitable. One common example is decoding a Vorbis stream from a
Use custom I/O functions by populating an ov_callbacks structure and calling ov_open_callbacks() or ov_test_callbacks() rather than the
typical ov_open() or ov_test(). Past the open call, use of
libvorbisfile is identical to using it with stdio.
The read-like function provided in the read_func field is
used to fetch the requested amount of data. It expects the fetch
operation to function similar to file-access, that is, a multiple read
operations will retrieve contiguous sequential pieces of data,
advancing a position cursor after each read.
The following behaviors are also expected:
- a return of '0' indicates end-of-data (if the by-thread errno is unset)
- short reads mean nothing special (short reads are not treated as error conditions)
- a return of zero with the by-thread errno set to nonzero indicates a read error
The seek-like function provided in the seek_func field is
used to request non-sequential data access by libvorbisfile, moving
the access cursor to the requested position. The seek function is
optional; if callbacks are only to handle non-seeking (streaming) data
or the application wishes to force streaming behavior,
seek_func and tell_func should be set to NULL. If
the seek function is non-NULL, libvorbisfile mandates the following
- The seek function must always return -1 (failure) if the given
data abstraction is not seekable. It may choose to always return -1
if the application desires libvorbisfile to treat the Vorbis data
strictly as a stream (which makes for a less expensive open
- If the seek function initially indicates seekability, it must
always succeed upon being given a valid seek request.
- The seek function must implement all of SEEK_SET, SEEK_CUR and
SEEK_END. The implementation of SEEK_END should set the access cursor
one past the last byte of accessible data, as would stdio
The close function should deallocate any access state used by the
passed in instance of the data access abstraction and invalidate the
instance handle. The close function is assumed to succeed; its return
code is not checked.
The close_func may be set to NULL to indicate that libvorbis
should not attempt to close the file/data handle in ov_clear but allow the application to handle
file/data access cleanup itself. For example, by passing the normal
stdio calls as callback functions, but passing a close_func
that is NULL or does nothing (as in the case of OV_CALLBACKS_NOCLOSE), an
application may call ov_clear() and then
later fclose() the file originally passed to libvorbisfile.
The tell function is intended to mimic the
behavior of ftell() and must return the byte position of the
next data byte that would be read. If the data access cursor is at
the end of the 'file' (pointing to one past the last byte of data, as
it would be after calling fseek(file,SEEK_END,0)), the tell
function must return the data position (and thus the total file size),
not an error.
The tell function need not be provided if the data IO abstraction is
not seekable, or the application wishes to force streaming
behavior. In this case, the tell_func and seek_func
fields should be set to NULL.
copyright © 2000-2010 Xiph.Org
vorbisfile version 1.3.2 - 20101101