Vorbisfile documentation | vorbisfile version 1.2.0 - 20070723

# 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 © 2007 Xiph.org | Ogg Vorbis
Vorbisfile documentation | vorbisfile version 1.2.0 - 20070723