Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

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.



copyright © 2000-2010 Xiph.Org

Ogg Vorbis

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101