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