1 <html> 2 3 <head> 4 <title>Vorbisfile - datatype - OggVorbis_File</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>OggVorbis_File</h1> 17 18 <p><i>declared in "vorbis/vorbisfile.h"</i></p> 19 20 <p> 21 The OggVorbis_File structure defines an Ogg Vorbis file. 22 <p> 23 24 This structure is used in all libvorbisfile routines. Before it can 25 be used, it must be initialized by <a 26 href="ov_open.html">ov_open()</a>, <a 27 href="ov_fopen.html">ov_fopen()</a>, or <a 28 href="ov_open_callbacks.html">ov_open_callbacks()</a>. <em>Important 29 Note:</em> The use of <a href="ov_open.html">ov_open()</a> is 30 discouraged under Windows due to a peculiarity of Windows linking 31 convention; use <a href="ov_fopen.html">ov_fopen()</a> or <a 32 href="ov_open_callbacks.html">ov_open_callbacks()</a> instead. This 33 caution only applies to Windows; use of <a 34 href="ov_open.html">ov_open()</a> is appropriate for all other 35 platforms. See the <a href="ov_open.html">ov_open()</a> page for more 36 information. 37 38 <p> 39 After use, the OggVorbis_File structure must be deallocated with a 40 call to <a href="ov_clear.html">ov_clear()</a>. 41 42 <p> 43 Note that once a file handle is passed to a successful <a 44 href="ov_open.html">ov_open()</a> call, the handle is owned by 45 libvorbisfile and will be closed by libvorbisfile later during the 46 call to <a href="ov_clear.html">ov_clear()</a>. The handle should not 47 be used or closed outside of the libvorbisfile API. Similarly, files 48 opened by <a href="ov_fopen.html">ov_fopen()</a> will also be closed 49 internally by vorbisfile in <a href="ov_clear.html">ov_clear()</a>.<p> 50 51 <a href="ov_open_callbacks.html">ov_open_callbacks()</a> allows the 52 application to choose whether libvorbisfile will or will not close the 53 handle in <a href="ov_clear.html">ov_clear()</a>; see the <a 54 href="ov_open_callbacks.html">ov_open_callbacks()</a> page for more information.<p> 55 56 If a call to <a href="ov_open.html">ov_open()</a> or <a 57 href="ov_open_callbacks.html">ov_open_callbacks()</a> <b>fails</b>, 58 libvorbisfile does <b>not</b> assume ownership of the handle and the 59 application is expected to close it if necessary. A failed <a 60 href="ov_fopen.html">ov_fopen()</a> call will internally close the 61 file handle if the open process fails.<p> 62 63 <br><br> 64 <table border=0 width=100% color=black cellspacing=0 cellpadding=7> 65 <tr bgcolor=#cccccc> 66 <td> 67 <pre><b>typedef struct { 68 void *datasource; /* Pointer to a FILE *, etc. */ 69 int seekable; 70 ogg_int64_t offset; 71 ogg_int64_t end; 72 ogg_sync_state oy; 73 74 /* If the FILE handle isn't seekable (eg, a pipe), only the current 75 stream appears */ 76 int links; 77 ogg_int64_t *offsets; 78 ogg_int64_t *dataoffsets; 79 long *serialnos; 80 ogg_int64_t *pcmlengths; 81 vorbis_info *vi; 82 vorbis_comment *vc; 83 84 /* Decoding working state local storage */ 85 ogg_int64_t pcm_offset; 86 int ready_state; 87 long current_serialno; 88 int current_link; 89 90 ogg_int64_t bittrack; 91 ogg_int64_t samptrack; 92 93 ogg_stream_state os; /* take physical pages, weld into a logical 94 stream of packets */ 95 vorbis_dsp_state vd; /* central working state for the packet->PCM decoder */ 96 vorbis_block vb; /* local working space for packet->PCM decode */ 97 98 <a href="ov_callbacks.html">ov_callbacks</a> callbacks; 99 100 } OggVorbis_File;</b></pre> 101 </td> 102 </tr> 103 </table> 104 105 <h3>Relevant Struct Members</h3> 106 <dl> 107 <dt><i>datasource</i></dt> 108 109 <dd>Pointer to file or other ogg source. When using stdio based 110 file/stream access, this field contains a <tt>FILE</tt> pointer. When using 111 custom IO via callbacks, libvorbisfile treats this void pointer as a 112 black box only to be passed to the callback routines provided by the 113 application.</dd> 114 115 <dt><i>seekable</i></dt> 116 <dd>Read-only int indicating whether file is seekable. E.g., a physical file is seekable, a pipe isn't.</dd> 117 <dt><i>links</i></dt> 118 <dd>Read-only int indicating the number of logical bitstreams within the physical bitstream.</dd> 119 <dt><i>ov_callbacks</i></dt> 120 <dd>Collection of file manipulation routines to be used on this data source. When using stdio/FILE access via <a href="ov_open.html">ov_open()</a>, the callbacks will be filled in with stdio calls or wrappers to stdio calls.</dd> 121 </dl> 122 123 <br><br> 124 <hr noshade> 125 <table border=0 width=100%> 126 <tr valign=top> 127 <td><p class=tiny>copyright © 2007 Xiph.org</p></td> 128 <td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> 129 </tr><tr> 130 <td><p class=tiny>Vorbisfile documentation</p></td> 131 <td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td> 132 </tr> 133 </table> 134 135 </body> 136 137 </html> 138
