[xiph-cvs] cvs commit: vorbis/doc/vorbisfile ov_callbacks.html

[Michael Smith]

msmith      02/06/08 01:04:06

  Modified:    doc/vorbisfile ov_callbacks.html
  Log:
  Start clearing out my TODO list...
  Document the requirements for the callbacks in ov_callbacks.

Revision  Changes    Path
1.3       +16 -4     vorbis/doc/vorbisfile/ov_callbacks.html

Index: ov_callbacks.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_callbacks.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ov_callbacks.html	2000/11/06 00:06:47	1.2
+++ ov_callbacks.html	2002/06/08 08:04:06	1.3
@@ -23,6 +23,12 @@
 The ov_callbacks structure does not need to be user-defined if you are working with a standard file.  The typical ov_open() call will fill ov_callbacks for you.  However, ov_callbacks should be defined if you are using other data sources.  In this situation, use ov_open_callbacks() instead of ov_open().
 <p>
 
+<p>
+The callbacks are designed following the stdio functions fread, fseek, fclose,
+and ftell. Except where otherwise noted below, they should work the same as
+these functions do.
+</p>
+
 <table border=0 width=100% color=black cellspacing=0 cellpadding=7>
 <tr bgcolor=#cccccc>
         <td>
@@ -39,13 +45,19 @@
 <h3>Relevant Struct Members</h3>
 <dl>
 <dt><i>read_func</i></dt>
-<dd>Pointer to custom data reading function.</dd>
+<dd>Pointer to custom data reading function. Read up to size*nmemb bytes from
+the source into the buffer at ptr. Return the number of bytes read successfully.
+Must return 0 if nothing can be read. Should also set errno if an error occurs,
+in order to distinguish between error and EOF.</dd>
 <dt><i>seek_func</i></dt>
-<dd>Pointer to custom data seeking function.</dd>
+<dd>Pointer to custom data seeking function. If your data source does not support
+seeking, you must</em> return -1. Returns 0 on success. Seeks to a position <em>offset</em> bytes from a position defined by <em>whence</em>. If whence is SEEK_SET, seek relative to the file start. If SEEK_CUR, seek is relative to current file position. If SEEK_END, relative to end of file.</dd>
 <dt><i>close_func</i></dt>
-<dd>Pointer to custom data source closure function.</dd>
+<dd>Pointer to custom data source closure function. This should clear any
+resources used by the data source, such as open files or network sockets. Returns 0.</dd>
 <dt><i>tell_func</i></dt>
-<dd>Pointer to custom data location function.</dd>
+<dd>Pointer to custom data location function. Returns the current offset (from the start) of the data stream. If your source is non-seekable, this need not be
+implemented.</dd>
 </dl>
 
 

<p><p><p>--- >8 ----
List archives:  http://www.xiph.org/archives/
Ogg project homepage: http://www.xiph.org/ogg/
To unsubscribe from this list, send a message to 'cvs-request at xiph.org'
containing only the word 'unsubscribe' in the body.  No subject is needed.
Unsubscribe messages sent to the list will be ignored/filtered.