1<html>
2
3<head>
4<title>Vorbisfile - function - ov_fopen</title>
5<link rel=stylesheet href="style.css" type="text/css">
6</head>
7
8<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
9<table border=0 width=100%>
10<tr>
11<td><p class=tiny>Vorbisfile documentation</p></td>
12<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
13</tr>
14</table>
15
16<h1>ov_fopen</h1>
17
18<p><i>declared in "vorbis/vorbisfile.h";</i></p>
19
20<p>This is the simplest function used to open and initialize an OggVorbis_File
21structure. It sets up all the related decoding structure.
22<p>The first argument is a file path suitable
23for passing to fopen(). <tt>vf</tt> should be a pointer to an empty
24OggVorbis_File structure -- this is used for ALL the externally visible
25libvorbisfile functions. Once this has been called, the same <a
26href="OggVorbis_File.html">OggVorbis_File</a> struct should be passed
27to all the libvorbisfile functions.
28<p>The <tt>vf</tt> structure initialized using ov_fopen() must
29eventually be cleaned using <a href="ov_clear.html">ov_clear()</a>.
30
31<p>
32It is often useful to call <tt>ov_fopen()</tt> simply to determine
33whether a given file is a Vorbis bitstream. If the <tt>ov_fopen()</tt>
34call fails, then the file is either inaccessable (errno is set) or not
35recognizable as Vorbis (errno unchanged).  If the call succeeds but
36the initialized <tt>vf</tt> structure will not be used, the
37application is responsible for calling <a
38href="ov_clear.html">ov_clear()</a> to clear the decoder's buffers and
39close the file.<p>
40
41<br><br>
42<table border=0 color=black cellspacing=0 cellpadding=7>
43<tr bgcolor=#cccccc>
44	<td>
45<pre><b>
46int ov_fopen(char *path,<a href="OggVorbis_File.html">OggVorbis_File</a> *vf);
47</b></pre>
48	</td>
49</tr>
50</table>
51
52<h3>Parameters</h3>
53<dl>
54<dt><i>path</i></dt>
55<dd>Null terminated string containing a file path suitable for passing to <tt>fopen()</tt>.
56</dd>
57<dt><i>vf</i></dt>
58<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
59functions. Once this has been called, the same <tt>OggVorbis_File</tt>
60struct should be passed to all the libvorbisfile functions.</dd>
61</dl>
62
63
64<h3>Return Values</h3>
65<blockquote>
66<li>0 indicates success</li>
67
68<li>less than zero for failure:</li>
69<ul>
70<li>OV_EREAD - A read from media returned an error.</li>
71<li>OV_ENOTVORBIS - Bitstream does not contain any Vorbis data.</li>
72<li>OV_EVERSION - Vorbis version mismatch.</li>
73<li>OV_EBADHEADER - Invalid Vorbis bitstream header.</li>
74<li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.</li>
75</ul>
76</blockquote>
77<p>
78
79<h3>Notes</h3>
80<dl>
81
82<dt><b>[a] Threaded decode</b><p>
83<dd>If your decoder is threaded, it is recommended that you NOT call
84<tt>ov_open_callbacks()</tt>
85in the main control thread--instead, call <tt>ov_open_callbacks()</tt> in your decode/playback
86thread. This is important because <tt>ov_open_callbacks()</tt> may be a fairly time-consuming
87call, given that the full structure of the file is determined at this point,
88which may require reading large parts of the file under certain circumstances
89(determining all the logical bitstreams in one physical bitstream, for
90example).  See <a href="threads.html">Thread Safety</a> for other information on using libvorbisfile with threads.
91<p>
92
93<dt><b>[b] Mixed media streams</b><p>
94<dd>
95As of Vorbisfile release 1.2.0, Vorbisfile is able to access the
96Vorbis content in mixed-media Ogg streams, not just Vorbis-only
97streams.  For example, Vorbisfile may be used to open and access the
98audio from an Ogg stream consisting of Theora video and Vorbis audio.
99Vorbisfile 1.2.0 decodes the first logical audio stream of each
100physical stream section.<p>
101
102<dt><b>[c] Faster testing for Vorbis files</b><p>
103<dd><a href="ov_test.html">ov_test()</a> and <a
104href="ov_test_callbacks.html">ov_test_callbacks()</a> provide less
105computationally expensive ways to test a file for Vorbisness, but
106require more setup code.<p>
107
108</dl>
109
110<br><br>
111<hr noshade>
112<table border=0 width=100%>
113<tr valign=top>
114<td><p class=tiny>copyright &copy; 2007 Xiph.org</p></td>
115<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
116</tr><tr>
117<td><p class=tiny>Vorbisfile documentation</p></td>
118<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
119</tr>
120</table>
121
122</body>
123
124</html>
125