00001 <html>
00002
00003 <head>
00004 <title>Vorbisfile - Callbacks and non-stdio I/O</title>
00005 <link rel=stylesheet href="style.css" type="text/css">
00006 </head>
00007
00008 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
00009 <table border=0 width=100%>
00010 <tr>
00011 <td><p class=tiny>Vorbisfile documentation</p></td>
00012 <td align=right><p class=tiny>vorbisfile version 1.68 - 20030307</p></td>
00013 </tr>
00014 </table>
00015
00016 <h1>Callbacks and non-stdio I/O</h1>
00017
00018 Although stdio is convenient and nearly universally implemented as per
00019 ANSI C, it is not suited to all or even most potential uses of Vorbis.
00020 For additional flexibility, embedded applications may provide their
00021 own I/O functions for use with Vorbisfile when stdio is unavailable or not
00022 suitable. One common example is decoding a Vorbis stream from a
00023 memory buffer.<p>
00024
00025 Use custom I/O functions by populating an <a
00026 href="ov_callbacks.html">ov_callbacks</a> structure and calling <a
00027 href="ov_open_callbacks.html">ov_open_callbacks()</a> or <a
00028 href="ov_test_callbacks.html">ov_test_callbacks()</a> rather than the
00029 typical <a href="ov_open.html">ov_open()</a> or <a
00030 href="ov_test.html">ov_test()</a>. Past the open call, use of
00031 libvorbisfile is identical to using it with stdio.
00032
00033 <h2>Read function</h2>
00034
00035 The read-like function provided in the <tt>read_func</tt> field is
00036 used to fetch the requested amount of data. It expects the fetch
00037 operation to function similar to file-access, that is, a multiple read
00038 operations will retrieve contiguous sequential pieces of data,
00039 advancing a position cursor after each read.<p>
00040
00041 The following behaviors are also expected:<p>
00042 <ul>
00043 <li>a return of '0' indicates end-of-data (if the by-thread errno is unset)
00044 <li>short reads mean nothing special (short reads are not treated as error conditions)
00045 <li>a return of zero with the by-thread errno set to nonzero indicates a read error
00046 </ul>
00047 <p>
00048
00049 <h2>Seek function</h2>
00050
00051 The seek-like function provided in the <tt>seek_func</tt> field is
00052 used to request non-sequential data access by libvorbisfile, moving
00053 the access cursor to the requested position.<p>
00054
00055 libvorbisfile expects the following behavior:
00056 <ul>
00057 <li>The seek function must always return -1 (failure) if the given
00058 data abstraction is not seekable. It may choose to always return -1
00059 if the application desires libvorbisfile to treat the Vorbis data
00060 strictly as a stream (which makes for a less expensive open
00061 operation).<p>
00062
00063 <li>If the seek function initially indicates seekability, it must
00064 always succeed upon being given a valid seek request.<p>
00065
00066 <li>The seek function must implement all of SEEK_SET, SEEK_CUR and
00067 SEEK_END. The implementation of SEEK_END should set the access cursor
00068 one past the last byte of accessible data, as would stdio
00069 <tt>fseek()</tt><p>
00070 </ul>
00071
00072 <h2>Close function</h2>
00073
00074 The close function should deallocate any access state used by the
00075 passed in instance of the data access abstraction and invalidate the
00076 instance handle. The close function is assumed to succeed.<p>
00077
00078 One common use of callbacks and the close function is to change the
00079 behavior of libvorbisfile with respect to file closure for applications
00080 that <em>must</em> <tt>fclose</tt> data files themselves. By passing
00081 the normal stdio calls as callback functions, but passing a
00082 <tt>close_func</tt> that does nothing, an application may call <a
00083 href="ov_clear.html">ov_clear()</a> and then <tt>fclose()</tt> the
00084 file originally passed to libvorbisfile.
00085
00086 <h2>Tell function</h2>
00087
00088 The tell function is intended to mimic the
00089 behavior of <tt>ftell()</tt> and must return the byte position of the
00090 next data byte that would be read. If the data access cursor is at
00091 the end of the 'file' (pointing to one past the last byte of data, as
00092 it would be after calling <tt>fseek(file,SEEK_END,0)</tt>), the tell
00093 function must return the data position (and thus the total file size),
00094 not an error.<p>
00095
00096 The tell function need not be provided if the data IO abstraction is
00097 not seekable.<p>
00098
00099 <br><br>
00100 <hr noshade>
00101 <table border=0 width=100%>
00102 <tr valign=top>
00103 <td><p class=tiny>copyright © 2003 Xiph.org</p></td>
00104 <td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
00105 </tr><tr>
00106 <td><p class=tiny>Vorbisfile documentation</p></td>
00107 <td align=right><p class=tiny>vorbisfile version 1.68 - 20030307</p></td>
00108 </tr>
00109 </table>
00110
00111 </body>
00112
00113 </html>
