Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/libvorbis-1.2.0/doc/vorbisfile/ov_callbacks.html @ 16

Last change on this file since 16 was 16, checked in by landauf, 16 years ago

added libvorbis

File size: 4.3 KB
Line 
1<html>
2
3<head>
4<title>Vorbisfile - datatype - ov_callbacks</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_callbacks</h1>
17
18<p><i>declared in "vorbis/codec.h"</i></p>
19
20<p>
21The ov_callbacks structure contains file manipulation function prototypes necessary for opening, closing, seeking, and location.
22
23<p>
24The ov_callbacks structure does not need to be user-defined if you are
25working with stdio-based file manipulation; the <a
26href="ov_fopen.html">ov_fopen()</a> and <a
27href="ov_open.html">ov_open()</a> calls internally provide default callbacks for
28stdio.  ov_callbacks are defined and passed to <a
29href="ov_open_callbacks.html">ov_open_callbacks()</a> when
30implementing non-stdio based stream manipulation (such as playback
31from a memory buffer) or when <a
32href="ov_open.html#winfoot">ov_open()-style initialization from a <tt>FILE *</tt> is required under Windows [a]</a>.
33<p>
34
35<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
36<tr bgcolor=#cccccc>
37        <td>
38<pre><b>typedef struct {
39  size_t (*read_func)  (void *ptr, size_t size, size_t nmemb, void *datasource);
40  int    (*seek_func)  (void *datasource, ogg_int64_t offset, int whence);
41  int    (*close_func) (void *datasource);
42  long   (*tell_func)  (void *datasource);
43} ov_callbacks;</b></pre>
44        </td>
45</tr>
46</table>
47
48<h3>Relevant Struct Members</h3>
49<dl>
50<dt><i>read_func</i></dt>
51<dd>Pointer to custom data reading function.</dd>
52<dt><i>seek_func</i></dt>
53<dd>Pointer to custom data seeking function. If the data source is not seekable (or the application wants the data source to be treated as unseekable at all times), the provided seek callback should always return -1 (failure) or the <tt>seek_func</tt> and <tt>tell_func</tt> fields should be set to NULL.</dd>
54<dt><i>close_func</i></dt>
55<dd>Pointer to custom data source closure function.  Set to NULL if libvorbisfile should not attempt to automatically close the file/data handle.</dd>
56<dt><i>tell_func</i></dt>
57<dd>Pointer to custom data location function. If the data source is not seekable (or the application wants the data source to be treated as unseekable at all times), the provided tell callback should always return -1 (failure) or the <tt>seek_func</tt> and <tt>tell_func</tt> fields should be set to NULL.</dd>
58</dl>
59
60<p>
61
62<h3>Predefined callbacks</h3>
63The header vorbis/vorbisfile.h provides several predefined static ov_callbacks structures that may be passed to <a
64href="ov_open_callbacks.html">ov_open_callbacks()</a>:
65<dl>
66<dt><tt>OV_CALLBACKS_DEFAULT</tt><dd>
67
68These callbacks provide the same behavior as used internally by <a
69href="ov_fopen.html">ov_fopen()</a> and <a
70href="ov_open.html">ov_open()</a>.
71
72<dt><tt>OV_CALLBACKS_NOCLOSE</tt><dd>
73
74The same as <tt>OV_CALLBACKS_DEFAULT</tt>, but with the
75<tt>close_func</tt> field set to NULL.  The most typical use would be
76to use <a href="ov_open_callbacks.html">ov_open_callbacks()</a> to
77provide the same behavior as <a href="ov_open.html">ov_open()</a>, but
78not close the file/data handle in <a
79href="ov_clear.html">ov_clear()</a>.
80
81<dt><tt>OV_CALLBACKS_STREAMONLY</tt><dd>
82
83A set of callbacks that set <tt>seek_func</tt> and <tt>tell_func</tt>
84to NULL, thus forcing strict streaming-only behavior regardless of
85whether or not the input is actually seekable.
86
87<dt><tt>OV_CALLBACKS_STREAMONLY_NOCLOSE</tt><dd>
88
89The same as <tt>OV_CALLBACKS_STREAMONLY</tt>, but with
90<tt>close_func</tt> also set to null, preventing libvorbisfile from
91attempting to close the file/data handle in <a
92href="ov_clear.html">ov_clear()</a>.
93
94</dl>
95<p>
96
97<h3>Examples and usage</h3>
98
99See <a href="callbacks.html">the callbacks and non-stdio I/O document</a> for more
100detailed information on required behavior of the various callback
101functions.<p>
102
103<br><br>
104<hr noshade>
105<table border=0 width=100%>
106<tr valign=top>
107<td><p class=tiny>copyright &copy; 2007 Xiph.org</p></td>
108<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
109</tr><tr>
110<td><p class=tiny>Vorbisfile documentation</p></td>
111<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
112</tr>
113</table>
114
115</body>
116
117</html>
Note: See TracBrowser for help on using the repository browser.