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.2.0 - 20070723</p></td> 13</tr> 14</table> 15 16<h1>Callbacks and non-stdio I/O</h1> 17 18Although stdio is convenient and nearly universally implemented as per 19ANSI C, it is not suited to all or even most potential uses of Vorbis. 20For additional flexibility, embedded applications may provide their 21own I/O functions for use with Vorbisfile when stdio is unavailable or not 22suitable. One common example is decoding a Vorbis stream from a 23memory buffer.<p> 24 25Use custom I/O functions by populating an <a 26href="ov_callbacks.html">ov_callbacks</a> structure and calling <a 27href="ov_open_callbacks.html">ov_open_callbacks()</a> or <a 28href="ov_test_callbacks.html">ov_test_callbacks()</a> rather than the 29typical <a href="ov_open.html">ov_open()</a> or <a 30href="ov_test.html">ov_test()</a>. Past the open call, use of 31libvorbisfile is identical to using it with stdio. 32 33<h2>Read function</h2> 34 35The read-like function provided in the <tt>read_func</tt> field is 36used to fetch the requested amount of data. It expects the fetch 37operation to function similar to file-access, that is, a multiple read 38operations will retrieve contiguous sequential pieces of data, 39advancing a position cursor after each read.<p> 40 41The 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 51The seek-like function provided in the <tt>seek_func</tt> field is 52used to request non-sequential data access by libvorbisfile, moving 53the access cursor to the requested position. The seek function is 54optional; if callbacks are only to handle non-seeking (streaming) data 55or the application wishes to force streaming behavior, 56<tt>seek_func</tt> and <tt>tell_func</tt> should be set to NULL. If 57the seek function is non-NULL, libvorbisfile mandates the following 58behavior: 59 60<ul> 61<li>The seek function must always return -1 (failure) if the given 62data abstraction is not seekable. It may choose to always return -1 63if the application desires libvorbisfile to treat the Vorbis data 64strictly as a stream (which makes for a less expensive open 65operation).<p> 66 67<li>If the seek function initially indicates seekability, it must 68always succeed upon being given a valid seek request.<p> 69 70<li>The seek function must implement all of SEEK_SET, SEEK_CUR and 71SEEK_END. The implementation of SEEK_END should set the access cursor 72one past the last byte of accessible data, as would stdio 73<tt>fseek()</tt><p> 74</ul> 75 76<h2>Close function</h2> 77 78The close function should deallocate any access state used by the 79passed in instance of the data access abstraction and invalidate the 80instance handle. The close function is assumed to succeed; its return 81code is not checked.<p> 82 83The <tt>close_func</tt> may be set to NULL to indicate that libvorbis 84should not attempt to close the file/data handle in <a 85href="ov_clear.html">ov_clear</a> but allow the application to handle 86file/data access cleanup itself. For example, by passing the normal 87stdio calls as callback functions, but passing a <tt>close_func</tt> 88that is NULL or does nothing (as in the case of OV_CALLBACKS_NOCLOSE), an 89application may call <a href="ov_clear.html">ov_clear()</a> and then 90later <tt>fclose()</tt> the file originally passed to libvorbisfile. 91 92<h2>Tell function</h2> 93 94The tell function is intended to mimic the 95behavior of <tt>ftell()</tt> and must return the byte position of the 96next data byte that would be read. If the data access cursor is at 97the end of the 'file' (pointing to one past the last byte of data, as 98it would be after calling <tt>fseek(file,SEEK_END,0)</tt>), the tell 99function must return the data position (and thus the total file size), 100not an error.<p> 101 102The tell function need not be provided if the data IO abstraction is 103not seekable, or the application wishes to force streaming 104behavior. In this case, the <tt>tell_func</tt> and <tt>seek_func</tt> 105fields 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 © 2007 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.2.0 - 20070723</p></td> 116</tr> 117</table> 118 119</body> 120 121</html> 122