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