Mercurial > hg > sv-dependency-builds

comparison src/libvorbis-1.3.3/doc/vorbisfile/callbacks.html @ 1:05aa0afa9217

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Bring in flac, ogg, vorbis
author Chris Cannam
date Tue, 19 Mar 2013 17:37:49 +0000
parents
children
comparison
equal deleted inserted replaced
0:c7265573341e 1:05aa0afa9217
1 <html>
2
3 <head>
4 <title>Vorbisfile - Callbacks and non-stdio I/O</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.3.2 - 20101101</p></td>
13 </tr>
14 </table>
15
16 <h1>Callbacks and non-stdio I/O</h1>
17
18 Although stdio is convenient and nearly universally implemented as per
19 ANSI C, it is not suited to all or even most potential uses of Vorbis.
20 For additional flexibility, embedded applications may provide their
21 own I/O functions for use with Vorbisfile when stdio is unavailable or not
22 suitable. One common example is decoding a Vorbis stream from a
23 memory buffer.<p>
24
25 Use custom I/O functions by populating an <a
26 href="ov_callbacks.html">ov_callbacks</a> structure and calling <a
27 href="ov_open_callbacks.html">ov_open_callbacks()</a> or <a
28 href="ov_test_callbacks.html">ov_test_callbacks()</a> rather than the
29 typical <a href="ov_open.html">ov_open()</a> or <a
30 href="ov_test.html">ov_test()</a>. Past the open call, use of
31 libvorbisfile is identical to using it with stdio.
32
33 <h2>Read function</h2>
34
35 The read-like function provided in the <tt>read_func</tt> field is
36 used to fetch the requested amount of data. It expects the fetch
37 operation to function similar to file-access, that is, a multiple read
38 operations will retrieve contiguous sequential pieces of data,
39 advancing a position cursor after each read.<p>
40
41 The following behaviors are also expected:<p>
42 <ul>
43 <li>a return of '0' indicates end-of-data (if the by-thread errno is unset)
44 <li>short reads mean nothing special (short reads are not treated as error conditions)
45 <li>a return of zero with the by-thread errno set to nonzero indicates a read error
46 </ul>
47 <p>
48
49 <h2>Seek function</h2>
50
51 The seek-like function provided in the <tt>seek_func</tt> field is
52 used to request non-sequential data access by libvorbisfile, moving
53 the access cursor to the requested position. The seek function is
54 optional; if callbacks are only to handle non-seeking (streaming) data
55 or the application wishes to force streaming behavior,
56 <tt>seek_func</tt> and <tt>tell_func</tt> should be set to NULL. If
57 the seek function is non-NULL, libvorbisfile mandates the following
58 behavior:
59
60 <ul>
61 <li>The seek function must always return -1 (failure) if the given
62 data abstraction is not seekable. It may choose to always return -1
63 if the application desires libvorbisfile to treat the Vorbis data
64 strictly as a stream (which makes for a less expensive open
65 operation).<p>
66
67 <li>If the seek function initially indicates seekability, it must
68 always succeed upon being given a valid seek request.<p>
69
70 <li>The seek function must implement all of SEEK_SET, SEEK_CUR and
71 SEEK_END. The implementation of SEEK_END should set the access cursor
72 one past the last byte of accessible data, as would stdio
73 <tt>fseek()</tt><p>
74 </ul>
75
76 <h2>Close function</h2>
77
78 The close function should deallocate any access state used by the
79 passed in instance of the data access abstraction and invalidate the
80 instance handle. The close function is assumed to succeed; its return
81 code is not checked.<p>
82
83 The <tt>close_func</tt> may be set to NULL to indicate that libvorbis
84 should not attempt to close the file/data handle in <a
85 href="ov_clear.html">ov_clear</a> but allow the application to handle
86 file/data access cleanup itself. For example, by passing the normal
87 stdio calls as callback functions, but passing a <tt>close_func</tt>
88 that is NULL or does nothing (as in the case of OV_CALLBACKS_NOCLOSE), an
89 application may call <a href="ov_clear.html">ov_clear()</a> and then
90 later <tt>fclose()</tt> the file originally passed to libvorbisfile.
91
92 <h2>Tell function</h2>
93
94 The tell function is intended to mimic the
95 behavior of <tt>ftell()</tt> and must return the byte position of the
96 next data byte that would be read. If the data access cursor is at
97 the end of the 'file' (pointing to one past the last byte of data, as
98 it would be after calling <tt>fseek(file,SEEK_END,0)</tt>), the tell
99 function must return the data position (and thus the total file size),
100 not an error.<p>
101
102 The tell function need not be provided if the data IO abstraction is
103 not seekable, or the application wishes to force streaming
104 behavior. In this case, the <tt>tell_func</tt> and <tt>seek_func</tt>
105 fields should be set to NULL.<p>
106
107 <br><br>
108 <hr noshade>
109 <table border=0 width=100%>
110 <tr valign=top>
111 <td><p class=tiny>copyright &copy; 2000-2010 Xiph.Org</p></td>
112 <td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
113 </tr><tr>
114 <td><p class=tiny>Vorbisfile documentation</p></td>
115 <td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td>
116 </tr>
117 </table>
118
119 </body>
120
121 </html>