doc/vorbisfile/ov_test_callbacks.html

   1 <html>
   2
   3 <head>
   4 <title>Vorbisfile - function - ov_test_callbacks</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.3.2 - 20101101</p></td>
  13 </tr>
  14 </table>
  15
  16 <h1>ov_test_callbacks</h1>
  17
  18 <p><i>declared in "vorbis/vorbisfile.h";</i></p>
  19
  20 <p>This is an alternative function used to open and test an OggVorbis_File
  21 structure when using a data source other than a file,
  22 when its necessary to modify default file access behavior, or to
  23 test for Vorbis content from a <tt>FILE *</tt> pointer under
  24 Windows where <a href="ov_open.html">ov_test()</a> cannot be used.  It
  25 allows the application to specify custom file manipulation routines
  26 and sets up all the related decoding structures.
  27
  28 <p>Once this has been called, the same <tt>OggVorbis_File</tt>
  29 struct should be passed to all the libvorbisfile functions.
  30 <p>
  31 <br><br>
  32 <table border=0 color=black cellspacing=0 cellpadding=7>
  33 <tr bgcolor=#cccccc>
  34         <td>
  35 <pre><b>
  36 int ov_test_callbacks(void *datasource, <a href="OggVorbis_File.html">OggVorbis_File</a> *vf, char *initial, long ibytes, <a href="ov_callbacks.html">ov_callbacks</a> callbacks);
  37 </b></pre>
  38         </td>
  39 </tr>
  40 </table>
  41
  42 <h3>Parameters</h3>
  43 <dl>
  44 <dt><i>f</i></dt>
  45 <dd>File pointer to an already opened file
  46 or pipe (it need not be seekable--though this obviously restricts what
  47 can be done with the bitstream).</dd>
  48 <dt><i>vf</i></dt>
  49 <dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
  50 functions. Once this has been called, the same <tt>OggVorbis_File</tt>
  51 struct should be passed to all the libvorbisfile functions.</dd>
  52 <dt><i>initial</i></dt>
  53 <dd>Typically set to NULL.  This parameter is useful if some data has already been
  54 read from the file and the stream is not seekable. It is used in conjunction with <tt>ibytes</tt>.  In this case, <tt>initial</tt>
  55 should be a pointer to a buffer containing the data read.</dd>
  56 <dt><i>ibytes</i></dt>
  57 <dd>Typically set to 0.  This parameter is useful if some data has already been
  58 read from the file and the stream is not seekable. In this case, <tt>ibytes</tt>
  59 should contain the length (in bytes) of the buffer.  Used together with <tt>initial</tt>.</dd>
  60 <dt><i>callbacks</i></dt>
  61 <dd>A completed <a href="ov_callbacks.html">ov_callbacks</a> struct which indicates desired custom file manipulation routines.  vorbisfile.h defines several preprovided callback sets; see <a href="ov_callbacks.html">ov_callbacks</a> for details.</dd>
  62 </dl>
  63
  64
  65 <h3>Return Values</h3>
  66 <blockquote>
  67 <li>0 for success</li>
  68 <li>less than zero for failure:</li>
  69 <ul>
  70 <li>OV_EREAD - A read from media returned an error.</li>
  71 <li>OV_ENOTVORBIS - Bitstream contains no Vorbis data.</li>
  72 <li>OV_EVERSION - Vorbis version mismatch.</li>
  73 <li>OV_EBADHEADER - Invalid Vorbis bitstream header.</li>
  74 <li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.</li>
  75 </ul>
  76 </blockquote>
  77 <p>
  78
  79 <h3>Notes</h3>
  80 <dl>
  81
  82 <dt><b>[a] Windows and use as an ov_test() substitute</b><p> Windows
  83 applications should not use <a href="ov_test.html">ov_test()</a> due
  84 to the likelihood of <a href="ov_open.html#winfoot">CRT linking
  85 mismatches and runtime protection faults
  86 [ov_open:a]</a>. ov_test_callbacks() is a safe substitute; specifically:
  87
  88 <pre><tt>ov_test_callbacks(f, vf, initial, ibytes, OV_CALLBACKS_DEFAULT);</tt>
  89 </pre>
  90
  91 ... provides exactly the same functionality as <a
  92 href="ov_test.html">ov_test()</a> but will always work correctly under
  93 Windows, regardless of linking setup details.<p>
  94
  95 </dl>
  96
  97 <br><br>
  98 <hr noshade>
  99 <table border=0 width=100%>
 100 <tr valign=top>
 101 <td><p class=tiny>copyright &copy; 2000-2010 Xiph.Org</p></td>
 102 <td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
 103 </tr><tr>
 104 <td><p class=tiny>Vorbisfile documentation</p></td>
 105 <td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td>
 106 </tr>
 107 </table>
 108
 109 </body>
 110
 111 </html>