OggVorbis_File

declared in "vorbis/vorbisfile.h"

The OggVorbis_File structure defines an Ogg Vorbis file.

This structure is used in all libvorbisfile routines. Before it can be used, it must be initialized by ov_open(), ov_fopen(), or ov_open_callbacks(). Important Note: The use of ov_open() is discouraged under Windows due to a peculiarity of Windows linking convention; use ov_fopen() or ov_open_callbacks() instead. This caution only applies to Windows; use of ov_open() is appropriate for all other platforms. See the ov_open() page for more information.

After use, the OggVorbis_File structure must be deallocated with a call to ov_clear().

Note that once a file handle is passed to a successful ov_open() call, the handle is owned by libvorbisfile and will be closed by libvorbisfile later during the call to ov_clear(). The handle should not be used or closed outside of the libvorbisfile API. Similarly, files opened by ov_fopen() will also be closed internally by vorbisfile in ov_clear().

ov_open_callbacks() allows the application to choose whether libvorbisfile will or will not close the handle in ov_clear(); see the ov_open_callbacks() page for more information.

If a call to ov_open() or ov_open_callbacks() fails, libvorbisfile does not assume ownership of the handle and the application is expected to close it if necessary. A failed ov_fopen() call will internally close the file handle if the open process fails.

typedef struct { void *datasource; /* Pointer to a FILE *, etc. */ int seekable; ogg_int64_t offset; ogg_int64_t end; ogg_sync_state oy; /* If the FILE handle isn't seekable (eg, a pipe), only the current stream appears */ int links; ogg_int64_t *offsets; ogg_int64_t *dataoffsets; long *serialnos; ogg_int64_t *pcmlengths; vorbis_info *vi; vorbis_comment *vc; /* Decoding working state local storage */ ogg_int64_t pcm_offset; int ready_state; long current_serialno; int current_link; ogg_int64_t bittrack; ogg_int64_t samptrack; ogg_stream_state os; /* take physical pages, weld into a logical stream of packets */ vorbis_dsp_state vd; /* central working state for the packet->PCM decoder */ vorbis_block vb; /* local working space for packet->PCM decode */ ov_callbacks callbacks; } OggVorbis_File;

Relevant Struct Members

datasource

Pointer to file or other ogg source. When using stdio based file/stream access, this field contains a FILE pointer. When using custom IO via callbacks, libvorbisfile treats this void pointer as a black box only to be passed to the callback routines provided by the application.

seekable

Read-only int indicating whether file is seekable. E.g., a physical file is seekable, a pipe isn't.

links

Read-only int indicating the number of logical bitstreams within the physical bitstream.

ov_callbacks

Collection of file manipulation routines to be used on this data source. When using stdio/FILE access via ov_open(), the callbacks will be filled in with stdio calls or wrappers to stdio calls.