Tremor/doc/callbacks.html - platform/external/tremor - Git at Google

 <html>

 <head>
 <title>Tremor - Callbacks and non-stdio I/O</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>

 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
 <td><p class=tiny>Tremor documentation</p></td>
 <td align=right><p class=tiny>Tremor version 1.0 - 20020403</p></td>
 </tr>
 </table>

 <h1>Callbacks and non-stdio I/O</h1>

 Although stdio is convenient and nearly universally implemented as per
 ANSI C, it is not suited to all or even most potential uses of Vorbis.
 For additional flexibility, embedded applications may provide their
 own I/O functions for use with Tremor when stdio is unavailable or not
 suitable.  One common example is decoding a Vorbis stream from a
 memory buffer.<p>

 Use custom I/O functions by populating an <a
 href="ov_callbacks.html">ov_callbacks</a> structure and calling <a
 href="ov_open_callbacks.html">ov_open_callbacks()</a> or <a
 href="ov_test_callbacks.html">ov_test_callbacks()</a> rather than the
 typical <a href="ov_open.html">ov_open()</a> or <a
 href="ov_test.html">ov_test()</a>.  Past the open call, use of
 libvorbisidec is identical to using it with stdio.

 <h2>Read function</h2>

 The read-like function provided in the <tt>read_func</tt> field is
 used to fetch the requested amount of data.  It expects the fetch
 operation to function similar to file-access, that is, a multiple read
 operations will retrieve contiguous sequential pieces of data,
 advancing a position cursor after each read.<p>

 The following behaviors are also expected:<p>
 <ul>
 <li>a return of '0' indicates end-of-data (if the by-thread errno is unset)
 <li>short reads mean nothing special (short reads are not treated as error conditions)
 <li>a return of zero with the by-thread errno set to nonzero indicates a read error
 </ul>
 <p>

 <h2>Seek function</h2>

 The seek-like function provided in the <tt>seek_func</tt> field is
 used to request non-sequential data access by libvorbisidec, moving
 the access cursor to the requested position.<p>

 libvorbisidec expects the following behavior:
 <ul>
 <li>The seek function must always return -1 (failure) if the given
 data abstraction is not seekable.  It may choose to always return -1
 if the application desires libvorbisidec to treat the Vorbis data
 strictly as a stream (which makes for a less expensive open
 operation).<p>

 <li>If the seek function initially indicates seekability, it must
 always succeed upon being given a valid seek request.<p>

 <li>The seek function must implement all of SEEK_SET, SEEK_CUR and
 SEEK_END.  The implementation of SEEK_END should set the access cursor
 one past the last byte of accessible data, as would stdio
 <tt>fseek()</tt><p>
 </ul>

 <h2>Close function</h2>

 The close function should deallocate any access state used by the
 passed in instance of the data access abstraction and invalidate the
 instance handle.  The close function is assumed to succeed.<p>

 One common use of callbacks and the close function is to change the
 behavior of libvorbisidec with respect to file closure for applications
 that <em>must</em> <tt>fclose</tt> data files themselves. By passing
 the normal stdio calls as callback functions, but passing a
 <tt>close_func</tt> that does nothing, an application may call <a
 href="ov_clear.html">ov_clear()</a> and then <tt>fclose()</tt> the
 file originally passed to libvorbisidec.

 <h2>Tell function</h2>

 The tell function is intended to mimic the
 behavior of <tt>ftell()</tt> and must return the byte position of the
 next data byte that would be read.  If the data access cursor is at
 the end of the 'file' (pointing to one past the last byte of data, as
 it would be after calling <tt>fseek(file,SEEK_END,0)</tt>), the tell
 function must return the data position (and thus the total file size),
 not an error.<p>

 The tell function need not be provided if the data IO abstraction is
 not seekable.<p.

 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
 <td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
 <td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
 </tr><tr>
 <td><p class=tiny>Tremor documentation</p></td>
 <td align=right><p class=tiny>Tremor version 1.0 - 20020403</p></td>
 </tr>
 </table>

 </body>

 </html>
	<html>

	<head>
	<title>Tremor - Callbacks and non-stdio I/O</title>
	<link rel=stylesheet href="style.css" type="text/css">
	</head>

	<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
	<table border=0 width=100%>
	<tr>
	<td><p class=tiny>Tremor documentation</p></td>
	<td align=right><p class=tiny>Tremor version 1.0 - 20020403</p></td>
	</tr>
	</table>

	<h1>Callbacks and non-stdio I/O</h1>

	Although stdio is convenient and nearly universally implemented as per
	ANSI C, it is not suited to all or even most potential uses of Vorbis.
	For additional flexibility, embedded applications may provide their
	own I/O functions for use with Tremor when stdio is unavailable or not
	suitable. One common example is decoding a Vorbis stream from a
	memory buffer.<p>

	Use custom I/O functions by populating an <a
	href="ov_callbacks.html">ov_callbacks</a> structure and calling <a
	href="ov_open_callbacks.html">ov_open_callbacks()</a> or <a
	href="ov_test_callbacks.html">ov_test_callbacks()</a> rather than the
	typical <a href="ov_open.html">ov_open()</a> or <a
	href="ov_test.html">ov_test()</a>. Past the open call, use of
	libvorbisidec is identical to using it with stdio.

	<h2>Read function</h2>

	The read-like function provided in the <tt>read_func</tt> field is
	used to fetch the requested amount of data. It expects the fetch
	operation to function similar to file-access, that is, a multiple read
	operations will retrieve contiguous sequential pieces of data,
	advancing a position cursor after each read.<p>

	The following behaviors are also expected:<p>
	<ul>
	<li>a return of '0' indicates end-of-data (if the by-thread errno is unset)
	<li>short reads mean nothing special (short reads are not treated as error conditions)
	<li>a return of zero with the by-thread errno set to nonzero indicates a read error
	</ul>
	<p>

	<h2>Seek function</h2>

	The seek-like function provided in the <tt>seek_func</tt> field is
	used to request non-sequential data access by libvorbisidec, moving
	the access cursor to the requested position.<p>

	libvorbisidec expects the following behavior:
	<ul>
	<li>The seek function must always return -1 (failure) if the given
	data abstraction is not seekable. It may choose to always return -1
	if the application desires libvorbisidec to treat the Vorbis data
	strictly as a stream (which makes for a less expensive open
	operation).<p>

	<li>If the seek function initially indicates seekability, it must
	always succeed upon being given a valid seek request.<p>

	<li>The seek function must implement all of SEEK_SET, SEEK_CUR and
	SEEK_END. The implementation of SEEK_END should set the access cursor
	one past the last byte of accessible data, as would stdio
	<tt>fseek()</tt><p>
	</ul>

	<h2>Close function</h2>

	The close function should deallocate any access state used by the
	passed in instance of the data access abstraction and invalidate the
	instance handle. The close function is assumed to succeed.<p>

	One common use of callbacks and the close function is to change the
	behavior of libvorbisidec with respect to file closure for applications
	that <em>must</em> <tt>fclose</tt> data files themselves. By passing
	the normal stdio calls as callback functions, but passing a
	<tt>close_func</tt> that does nothing, an application may call <a
	href="ov_clear.html">ov_clear()</a> and then <tt>fclose()</tt> the
	file originally passed to libvorbisidec.

	<h2>Tell function</h2>

	The tell function is intended to mimic the
	behavior of <tt>ftell()</tt> and must return the byte position of the
	next data byte that would be read. If the data access cursor is at
	the end of the 'file' (pointing to one past the last byte of data, as
	it would be after calling <tt>fseek(file,SEEK_END,0)</tt>), the tell
	function must return the data position (and thus the total file size),
	not an error.<p>

	The tell function need not be provided if the data IO abstraction is
	not seekable.<p.

	<br><br>
	<hr noshade>
	<table border=0 width=100%>
	<tr valign=top>
	<td><p class=tiny>copyright © 2002 Xiph.org</p></td>
	<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
	</tr><tr>
	<td><p class=tiny>Tremor documentation</p></td>
	<td align=right><p class=tiny>Tremor version 1.0 - 20020403</p></td>
	</tr>
	</table>

	</body>

	</html>