Patch for trac #1965; clarify in comments and docs that a failed call

[platform/upstream/libvorbis.git] / doc / vorbisfile / ov_test.html

diff --git a/doc/vorbisfile/ov_test.html b/doc/vorbisfile/ov_test.html
index 9aa72d1..cb11d01 100644 (file)
--- a/doc/vorbisfile/ov_test.html
+++ b/doc/vorbisfile/ov_test.html
@@ -9,7 +9,7 @@
 <table border=0 width=100%>
 <tr>
 <td><p class=tiny>Vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.68 - 20030307</p></td>
+<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td>
 </tr>
 </table>
 
@@ -19,9 +19,22 @@
 
 <p>
 This partially opens a vorbis file to test for Vorbis-ness.  It loads
-the headers for the first chain, and tests for seekability (but does not seek).
-Use <a href="ov_test_open.html">ov_test_open()</a> to finish opening the file
-or <a href="ov_clear.html">ov_clear</a> to close/free it.
+the headers for the first chain and tests for seekability (but does
+not seek).  Use <a href="ov_test_open.html">ov_test_open()</a> to
+finish opening the file or <a href="ov_clear.html">ov_clear</a> to
+close/free it.  Note that vorbisfile does <b>not</b> take ownership of
+the file if the call fails; the calling applicaiton is responsible for
+closing the file if this call returns an error.
+<p>
+
+<p><em><b> WARNING for Windows developers: </b> Do not use ov_test()
+in Windows applications; Windows linking places restrictions on
+passing <tt>FILE *</tt> handles successfully, and ov_test() runs afoul
+of these restrictions <a href="#winfoot">[a]</a> in exactly the same
+way as <a href="ov_open.html">ov_open()</a>.  See the <a
+href="ov_test_callbacks.html">ov_test_callbacks() page </a> for
+details on using <a
+href="ov_test_callbacks.html">ov_test_callbacks()</a> instead. </em>
 <p>
 
 <table border=0 color=black cellspacing=0 cellpadding=7>
@@ -62,7 +75,7 @@ should contain the length (in bytes) of the buffer.  Used together with <tt>init
 <li>less than zero for failure:</li>
 <ul>
 <li>OV_EREAD - A read from media returned an error.</li>
-<li>OV_ENOTVORBIS - Bitstream is not Vorbis data.</li>
+<li>OV_ENOTVORBIS - Bitstream contains no Vorbis data.</li>
 <li>OV_EVERSION - Vorbis version mismatch.</li>
 <li>OV_EBADHEADER - Invalid Vorbis bitstream header.</li>
 <li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.</li>
@@ -70,17 +83,19 @@ should contain the length (in bytes) of the buffer.  Used together with <tt>init
 </blockquote>
 <p>
 
+<h3>Notes</h3>
 
+All the <a href="ov_open.html#notes">notes from ov_open()</a> apply to ov_test().
 
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2003 Xiph.org</p></td>
+<td><p class=tiny>copyright &copy; 2000-2010 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>Vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.68 - 20030307</p></td>
+<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td>
 </tr>
 </table>