Diff of /doc/vorbisfile/ov_open_callbacks.html [ed1f1f] .. [d865bb]  Maximize  Restore

Switch to unified view

a/doc/vorbisfile/ov_open_callbacks.html b/doc/vorbisfile/ov_open_callbacks.html
...
...
7
7
8
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
8
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
9
<table border=0 width=100%>
9
<table border=0 width=100%>
10
<tr>
10
<tr>
11
<td><p class=tiny>Vorbisfile documentation</p></td>
11
<td><p class=tiny>Vorbisfile documentation</p></td>
12
<td align=right><p class=tiny>vorbisfile version 1.68 - 20030307</p></td>
12
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
13
</tr>
13
</tr>
14
</table>
14
</table>
15
15
16
<h1>ov_open_callbacks</h1>
16
<h1>ov_open_callbacks</h1>
17
17
18
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
18
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
19
19
20
<p>This is an alternative function used to open and initialize an OggVorbis_File
20
<p>This is an alternative function used to open and initialize an
21
structure when using a data source other than a file.   It allows you to specify custom file manipulation routines and sets up all the related decoding structure.
21
OggVorbis_File structure when using a data source other than a file,
22
<p>Once this has been called, the same <tt>OggVorbis_File</tt>
22
when its necessary to modify default file access behavior, or to
23
struct should be passed to all the libvorbisfile functions.
23
initialize a Vorbis decode from a <tt>FILE *</tt> pointer under
24
<p>
24
Windows where <a href="ov_open.html">ov_open()</a> cannot be used.  It
25
It is often useful to call <tt>ov_open_callbacks()</tt>
25
allows the application to specify custom file manipulation routines
26
simply to determine whether a given stream is a vorbis bitstream. If the
26
and sets up all the related decoding structures.
27
<tt>ov_open_callbacks()</tt>
28
call fails, then the data is not recognizable as such. When you use <tt>ov_open_callbacks()
29
</tt>for
30
this, you should close or otherwise deallocate your <tt>datasource</tt> if, and only if, the
31
<tt>ov_open_callbacks()</tt>
32
call fails. If it succeeds, you must call <a href=ov_clear.html>ov_clear()</a> to clear
33
the decoder's buffers and call your close callback.<p>
34
27
35
See also <a href="callbacks.html">Callbacks and Non-stdio I/O</a> for information on designing and specifying the required callback functions.<p>
28
<p>Once ov_open_callbacks() has been called, the same
29
<tt>OggVorbis_File</tt> struct should be passed to all the
30
libvorbisfile functions.  Unlike <a
31
href="ov_fopen.html">ov_fopen()</a> and <a
32
href="ov_open.html">ov_open()</a>, ov_open_callbacks() may be used to
33
instruct vorbisfile to either automatically close or not to close the
34
file/data access handle in <a href="ov_clear.html">ov_clear()</a>.
35
Automatic closure is disabled by passing NULL as the close callback,
36
or using one of the predefined callback sets that specify a NULL close
37
callback.  The application is responsible for closing a file when a
38
call to ov_open_callbacks() is unsuccessful.<p>
39
40
See also <a href="callbacks.html">Callbacks and Non-stdio I/O</a> for
41
information on designing and specifying custom callback functions.<p>
36
42
37
<br><br>
43
<br><br>
38
<table border=0 color=black cellspacing=0 cellpadding=7>
44
<table border=0 color=black cellspacing=0 cellpadding=7>
39
<tr bgcolor=#cccccc>
45
<tr bgcolor=#cccccc>
40
    <td>
46
    <td>
...
...
60
<dt><i>ibytes</i></dt>
66
<dt><i>ibytes</i></dt>
61
<dd>Typically set to 0.  This parameter is useful if some data has already been
67
<dd>Typically set to 0.  This parameter is useful if some data has already been
62
read from the stream and the stream is not seekable. In this case, <tt>ibytes</tt>
68
read from the stream and the stream is not seekable. In this case, <tt>ibytes</tt>
63
should contain the length (in bytes) of the buffer.  Used together with <tt>initial</tt>.</dd>
69
should contain the length (in bytes) of the buffer.  Used together with <tt>initial</tt>.</dd>
64
<dt><i>callbacks</i></dt>
70
<dt><i>callbacks</i></dt>
65
<dd>A completed <a href="ov_callbacks.html">ov_callbacks</a> struct which indicates desired custom file manipulation routines.</dd>
71
<dd>A completed <a href="ov_callbacks.html">ov_callbacks</a> struct which indicates desired custom file manipulation routines.  vorbisfile.h defines several preprovided callback sets; see <a href="ov_callbacks.html">ov_callbacks</a> for details.</dd>
66
</dl>
72
</dl>
67
73
68
74
69
<h3>Return Values</h3>
75
<h3>Return Values</h3>
70
<blockquote>
76
<blockquote>
71
<li>0 for success</li>
77
<li>0 for success</li>
72
<li>less than zero for failure:</li>
78
<li>less than zero for failure:</li>
73
<ul>
79
<ul>
74
<li>OV_EREAD - A read from media returned an error.</li>
80
<li>OV_EREAD - A read from media returned an error.</li>
75
<li>OV_ENOTVORBIS - Bitstream is not Vorbis data.</li>
81
<li>OV_ENOTVORBIS - Bitstream does not contain any Vorbis data.</li>
76
<li>OV_EVERSION - Vorbis version mismatch.</li>
82
<li>OV_EVERSION - Vorbis version mismatch.</li>
77
<li>OV_EBADHEADER - Invalid Vorbis bitstream header.</li>
83
<li>OV_EBADHEADER - Invalid Vorbis bitstream header.</li>
78
<li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.</li>
84
<li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.</li>
79
</ul>
85
</ul>
80
</blockquote>
86
</blockquote>
81
<p>
87
<p>
82
88
83
<h3>Notes</h3>
89
<h3>Notes</h3>
90
<dl>
91
92
<dt><b>[a] Windows and use as an ov_open() substitute</b><p> Windows
93
applications should not use <a href="ov_open.html">ov_open()</a> due
94
to the likelihood of <a href="ov_open.html#winfoot">CRT linking
95
mismatches and runtime protection faults
96
[ov_open:a]</a>. ov_open_callbacks() is a safe substitute; specifically:
97
98
<pre><tt>ov_open_callbacks(f, vf, initial, ibytes, OV_CALLBACKS_DEFAULT);</tt>
99
</pre>
100
101
... provides exactly the same functionality as <a
102
href="ov_open.html">ov_open()</a> but will always work correctly under
103
Windows, regardless of linking setup details.<p>
104
105
<dt><b>[b] Threaded decode</b><p>
84
<p>If your decoder is threaded, it is recommended that you NOT call
106
<dd>If your decoder is threaded, it is recommended that you NOT call
85
<tt>ov_open_callbacks()</tt>
107
<tt>ov_open_callbacks()</tt>
86
in the main control thread--instead, call <tt>ov_open_callbacks()</tt> IN your decode/playback
108
in the main control thread--instead, call <tt>ov_open_callbacks()</tt> in your decode/playback
87
thread. This is important because <tt>ov_open_callbacks()</tt> may be a fairly time-consuming
109
thread. This is important because <tt>ov_open_callbacks()</tt> may be a fairly time-consuming
88
call, given that the full structure of the file is determined at this point,
110
call, given that the full structure of the file is determined at this point,
89
which may require reading large parts of the file under certain circumstances
111
which may require reading large parts of the file under certain circumstances
90
(determining all the logical bitstreams in one physical bitstream, for
112
(determining all the logical bitstreams in one physical bitstream, for
91
example).
92
See <a href="threads.html">Thread Safety</a> for other information on using libvorbisfile with threads.
113
example).  See <a href="threads.html">Thread Safety</a> for other information on using libvorbisfile with threads.
114
<p>
115
116
<dt><b>[c] Mixed media streams</b><p>
117
<dd>
118
As of Vorbisfile release 1.2.0, Vorbisfile is able to access the
119
Vorbis content in mixed-media Ogg streams, not just Vorbis-only
120
streams.  For example, Vorbisfile may be used to open and access the
121
audio from an Ogg stream consisting of Theora video and Vorbis audio.
122
Vorbisfile 1.2.0 decodes the first logical audio stream of each
123
physical stream section.<p>
124
125
<dt><b>[d] Faster testing for Vorbis files</b><p>
126
<dd><a href="ov_test.html">ov_test()</a> and <a
127
href="ov_test_callbacks.html">ov_test_callbacks()</a> provide less
128
computationally expensive ways to test a file for Vorbisness, but
129
require more setup code.<p>
130
131
</dl>
93
132
94
<br><br>
133
<br><br>
95
<hr noshade>
134
<hr noshade>
96
<table border=0 width=100%>
135
<table border=0 width=100%>
97
<tr valign=top>
136
<tr valign=top>
98
<td><p class=tiny>copyright &copy; 2003 Xiph.org</p></td>
137
<td><p class=tiny>copyright &copy; 2007 Xiph.org</p></td>
99
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
138
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
100
</tr><tr>
139
</tr><tr>
101
<td><p class=tiny>Vorbisfile documentation</p></td>
140
<td><p class=tiny>Vorbisfile documentation</p></td>
102
<td align=right><p class=tiny>vorbisfile version 1.68 - 20030307</p></td>
141
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
103
</tr>
142
</tr>
104
</table>
143
</table>
105
144
106
</body>
145
</body>
107
146