ao/doc/ao_open_file.html

   1 <html>
   2
   3 <head>
   4 <title>libao - function - ao_open_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>libao documentation</p></td>
  12 <td align=right><p class=tiny>libao version 0.8.5 - 20040312</p></td>
  13 </tr>
  14 </table>
  15
  16 <h1>ao_open_file</h1>
  17
  18 <p><i>declared in "ao/ao.h";</i></p>
  19
  20 <p>Open a file for audio output.  The file format is determined by the
  21 audio driver used.
  22
  23 <br><br>
  24 <table border=0 color=black cellspacing=0 cellpadding=7>
  25 <tr bgcolor=#cccccc>
  26         <td>
  27 <pre><b>
  28 <a href="ao_device.html">ao_device</a>* ao_open_file(int driver_id, const char *filename, int overwrite,
  29                                <a href="ao_sample_format.html">ao_sample_format</a> *format, <a href="ao_option.html">ao_option</a> *options);
  30 </b></pre>
  31         </td>
  32 </tr>
  33 </table>
  34
  35 <h3>Parameters</h3>
  36 <dl>
  37 <dt><i>driver_id</i></dt>
  38 <dd>The ID number of the driver as returned by
  39 <a href="ao_driver_id.html">ao_driver_id()</a>.</dd>
  40 <dt><i>filename</i></dt>
  41 <dd>Name of the file in which to store the audio.  The special filename "-" corresponds to <tt>stdout</tt>.</dd>
  42 <dt><i>overwrite</i></dt>
  43 <dd>If non-zero, the file is automatically overwritten.  If zero, then a
  44 preexisting file will cause the function to report a failure.</dd>
  45 <dt><i>format</i></dt>
  46 <dd>Pointer to a struct describing the sample format.  The caller retains ownership of this structure.</dd>
  47 <dt><i>options</i></dt>
  48 <dd>A linked list of options to be passed to the driver or NULL if no options
  49 are needed.  Unsupported options are ignored.</dd>
  50 </dl>
  51
  52 <h3>Return Values</h3>
  53 <blockquote>
  54 <li>
  55 non-NULL pointer inicates success.  This pointer must be passed in subsequent
  56 calls to <a href="ao_play.html">ao_play()</a> and
  57 <a href="ao_close.html">ao_close()</a>.</li>
  58
  59 <li>NULL indicates failure.  <tt>errno</tt> will contain the specific cause of the failure:</li>
  60 <ul>
  61 <li>AO_ENODRIVER - No driver corresponds to <tt>driver_id</tt>.</li>
  62 <li>AO_ENOTFILE - This driver is not a file output driver.</li>
  63 <li>AO_EBADOPTION - A valid option key has an invalid value.</li>
  64 <li>AO_EOPENFILE - Cannot open the file.</li>
  65 <li>AO_EFILEEXISTS - The file already exists.
  66 (Only if <tt>overwrite == 0</tt>)</li>
  67 <li>AO_EFAIL - Any other cause of failure.</li>
  68 </ul>
  69 </blockquote>
  70 <p>
  71
  72
  73 <h3>Notes</h3>
  74
  75 <p>Live output drivers cannot be used with this function.  Use <a
  76 href="ao_open_live.html">ao_open_live()</a> instead.  Some file
  77 formats (notably .WAV) cannot be correctly written to non-seekable
  78 files (like <tt>stdin</tt>).
  79
  80 <p>When passed to <a href="ao_open_file.html">ao_open_file()</a>, the
  81 <tt>byte_format</tt> member of an ao_sample_format struct does not
  82 specify the byte format that will be used in the file <i>output</i>,
  83 just the input sample format.
  84
  85 <br><br>
  86 <hr noshade>
  87 <table border=0 width=100%>
  88 <tr valign=top>
  89 <td><p class=tiny>copyright &copy; 2001-2003 Stan Seibert</p></td>
  90 <td align=right><p class=tiny><a href="http://www.xiph.org/">xiph.org</a><br><a href="mailto:volsung@xiph.org">volsung@xiph.org</a></p></td>
  91 </tr><tr>
  92 <td><p class=tiny>libao documentation</p></td>
  93 <td align=right><p class=tiny>libao version 0.8.5 - 20040312</p></td>
  94 </tr>
  95 </table>
  96
  97 </body>
  98
  99 </html>