ov_open is one of three initialization functions used to initialize
Chris@1: an OggVorbis_File structure and prepare a bitstream for playback.
Chris@1:
Chris@1:
WARNING for Windows developers: Do not use ov_open() in
Chris@1: Windows applications; Windows linking places restrictions on
Chris@1: passing FILE * handles successfully, and ov_open() runs
Chris@1: afoul of these restrictions [a]. See the ov_open_callbacks() page for
Chris@1: details on using ov_open_callbacks() instead.
Chris@1:
Chris@1:
The first argument must be a file pointer to an already opened file
Chris@1: or pipe (it need not be seekable--though this obviously restricts what
Chris@1: can be done with the bitstream). vf should be a pointer to the
Chris@1: OggVorbis_File structure -- this is used for ALL the externally visible libvorbisfile
Chris@1: functions. Once this has been called, the same OggVorbis_File
Chris@1: struct should be passed to all the libvorbisfile functions.
Chris@1:
Chris@1: The vf structure initialized using ov_fopen() must eventually
Chris@1: be cleaned using ov_clear(). Once a
Chris@1: FILE * handle is passed to ov_open() successfully, the
Chris@1: application MUST NOT fclose() or in any other way manipulate
Chris@1: that file handle. Vorbisfile will close the file in ov_clear(). If the application must be able
Chris@1: to close the FILE * handle itself, see ov_open_callbacks() with the use of
Chris@1: OV_CALLBACKS_NOCLOSE.
Chris@1:
Chris@1:
It is often useful to call ov_open() simply to determine
Chris@1: whether a given file is a Vorbis bitstream. If the ov_open()
Chris@1: call fails, then the file is not recognizable as Vorbis. If the call
Chris@1: succeeds but the initialized vf structure will not be used,
Chris@1: the application is responsible for calling ov_clear() to clear the decoder's buffers and
Chris@1: close the file.
Chris@1:
Chris@1: If [and only if] an ov_open() call fails, the application
Chris@1: must explicitly fclose() the FILE * pointer itself.
Chris@1:
Chris@1:
Chris@1:
Chris@1:
Chris@1:
Chris@1:
Chris@1:
Chris@1: int ov_open(FILE *f,OggVorbis_File *vf,char *initial,long ibytes);
Chris@1:
Chris@1:
Chris@1:
Chris@1:
Chris@1:
Chris@1:
Parameters
Chris@1:
Chris@1:
f
Chris@1:
File pointer to an already opened file
Chris@1: or pipe (it need not be seekable--though this obviously restricts what
Chris@1: can be done with the bitstream).
Chris@1:
vf
Chris@1:
A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
Chris@1: functions. Once this has been called, the same OggVorbis_File
Chris@1: struct should be passed to all the libvorbisfile functions.
Chris@1:
initial
Chris@1:
Typically set to NULL. This parameter is useful if some data has already been
Chris@1: read from the file and the stream is not seekable. It is used in conjunction with ibytes. In this case, initial
Chris@1: should be a pointer to a buffer containing the data read.
Chris@1:
ibytes
Chris@1:
Typically set to 0. This parameter is useful if some data has already been
Chris@1: read from the file and the stream is not seekable. In this case, ibytes
Chris@1: should contain the length (in bytes) of the buffer. Used together with initial
Chris@1:
Chris@1:
Chris@1:
Chris@1:
Return Values
Chris@1:
Chris@1:
0 indicates success
Chris@1:
Chris@1:
less than zero for failure:
Chris@1:
Chris@1:
OV_EREAD - A read from media returned an error.
Chris@1:
OV_ENOTVORBIS - Bitstream is not Vorbis data.
Chris@1:
OV_EVERSION - Vorbis version mismatch.
Chris@1:
OV_EBADHEADER - Invalid Vorbis bitstream header.
Chris@1:
OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.
Chris@1:
Chris@1:
Chris@1:
Chris@1:
Chris@1:
Chris@1:
Notes
Chris@1:
Chris@1:
Chris@1:
Chris@1:
[a] Windows and ov_open()
Chris@1:
Chris@1:
Under Windows, stdio file access is implemented in each of many
Chris@1: variants of crt.o, several of which are typically installed on any one
Chris@1: Windows machine. If libvorbisfile and the application using
Chris@1: libvorbisfile are not linked against the exact same
Chris@1: version/variant/build of crt.o (and they usually won't be, especially
Chris@1: using a prebuilt libvorbis DLL), FILE * handles cannot be
Chris@1: opened in the application and then passed to vorbisfile to be used
Chris@1: by stdio calls from vorbisfile's different version of CRT. For this
Chris@1: reason, using ov_open() under Windows
Chris@1: without careful, expert linking will typically cause a protection
Chris@1: fault. Windows programmers should use ov_fopen() (which will only use libvorbis's
Chris@1: crt.o) or ov_open_callbacks()
Chris@1: (which will only use the application's crt.o) instead.
Chris@1:
Chris@1: This warning only applies to Windows and only applies to ov_open(). It is perfectly safe to use ov_open() on all other platforms.
If your decoder is threaded, it is recommended that you NOT call
Chris@1: ov_open()
Chris@1: in the main control thread--instead, call ov_open() in your decode/playback
Chris@1: thread. This is important because ov_open() may be a fairly time-consuming
Chris@1: call, given that the full structure of the file is determined at this point,
Chris@1: which may require reading large parts of the file under certain circumstances
Chris@1: (determining all the logical bitstreams in one physical bitstream, for
Chris@1: example). See Thread Safety for other information on using libvorbisfile with threads.
Chris@1:
Chris@1:
Chris@1:
[c] Mixed media streams
Chris@1:
Chris@1: As of Vorbisfile release 1.2.0, Vorbisfile is able to access the
Chris@1: Vorbis content in mixed-media Ogg streams, not just Vorbis-only
Chris@1: streams. For example, Vorbisfile may be used to open and access the
Chris@1: audio from an Ogg stream consisting of Theora video and Vorbis audio.
Chris@1: Vorbisfile 1.2.0 decodes the first logical audio stream of each
Chris@1: physical stream section.
Chris@1:
Chris@1:
[d] Faster testing for Vorbis files
Chris@1:
ov_test() and ov_test_callbacks() provide less
Chris@1: computationally expensive ways to test a file for Vorbisness, but
Chris@1: require more setup code.