Documentation/DocBook/v4l/vidioc-g-audioout.xml

   1 <refentry id="vidioc-g-audioout">
   2   <refmeta>
   3     <refentrytitle>ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>VIDIOC_G_AUDOUT</refname>
   9     <refname>VIDIOC_S_AUDOUT</refname>
  10     <refpurpose>Query or select the current audio output</refpurpose>
  11   </refnamediv>
  12
  13   <refsynopsisdiv>
  14     <funcsynopsis>
  15       <funcprototype>
  16         <funcdef>int <function>ioctl</function></funcdef>
  17         <paramdef>int <parameter>fd</parameter></paramdef>
  18         <paramdef>int <parameter>request</parameter></paramdef>
  19         <paramdef>struct v4l2_audioout *<parameter>argp</parameter></paramdef>
  20       </funcprototype>
  21     </funcsynopsis>
  22     <funcsynopsis>
  23       <funcprototype>
  24         <funcdef>int <function>ioctl</function></funcdef>
  25         <paramdef>int <parameter>fd</parameter></paramdef>
  26         <paramdef>int <parameter>request</parameter></paramdef>
  27         <paramdef>const struct v4l2_audioout *<parameter>argp</parameter></paramdef>
  28       </funcprototype>
  29     </funcsynopsis>
  30   </refsynopsisdiv>
  31
  32   <refsect1>
  33     <title>Arguments</title>
  34
  35     <variablelist>
  36       <varlistentry>
  37         <term><parameter>fd</parameter></term>
  38         <listitem>
  39           <para>&fd;</para>
  40         </listitem>
  41       </varlistentry>
  42       <varlistentry>
  43         <term><parameter>request</parameter></term>
  44         <listitem>
  45           <para>VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</para>
  46         </listitem>
  47       </varlistentry>
  48       <varlistentry>
  49         <term><parameter>argp</parameter></term>
  50         <listitem>
  51           <para></para>
  52         </listitem>
  53       </varlistentry>
  54     </variablelist>
  55   </refsect1>
  56
  57   <refsect1>
  58     <title>Description</title>
  59
  60     <para>To query the current audio output applications zero out the
  61 <structfield>reserved</structfield> array of a &v4l2-audioout; and
  62 call the <constant>VIDIOC_G_AUDOUT</constant> ioctl with a pointer
  63 to this structure. Drivers fill the rest of the structure or return an
  64 &EINVAL; when the device has no audio inputs, or none which combine
  65 with the current video output.</para>
  66
  67     <para>Audio outputs have no writable properties. Nevertheless, to
  68 select the current audio output applications can initialize the
  69 <structfield>index</structfield> field and
  70 <structfield>reserved</structfield> array (which in the future may
  71 contain writable properties) of a
  72 <structname>v4l2_audioout</structname> structure and call the
  73 <constant>VIDIOC_S_AUDOUT</constant> ioctl. Drivers switch to the
  74 requested output or return the &EINVAL; when the index is out of
  75 bounds. This is a write-only ioctl, it does not return the current
  76 audio output attributes as <constant>VIDIOC_G_AUDOUT</constant>
  77 does.</para>
  78
  79     <para>Note connectors on a TV card to loop back the received audio
  80 signal to a sound card are not audio outputs in this sense.</para>
  81
  82     <table pgwide="1" frame="none" id="v4l2-audioout">
  83       <title>struct <structname>v4l2_audioout</structname></title>
  84       <tgroup cols="3">
  85         &cs-str;
  86         <tbody valign="top">
  87           <row>
  88             <entry>__u32</entry>
  89             <entry><structfield>index</structfield></entry>
  90             <entry>Identifies the audio output, set by the
  91 driver or application.</entry>
  92           </row>
  93           <row>
  94             <entry>__u8</entry>
  95             <entry><structfield>name</structfield>[32]</entry>
  96             <entry>Name of the audio output, a NUL-terminated ASCII
  97 string, for example: "Line Out". This information is intended for the
  98 user, preferably the connector label on the device itself.</entry>
  99           </row>
 100           <row>
 101             <entry>__u32</entry>
 102             <entry><structfield>capability</structfield></entry>
 103             <entry>Audio capability flags, none defined yet. Drivers
 104 must set this field to zero.</entry>
 105           </row>
 106           <row>
 107             <entry>__u32</entry>
 108             <entry><structfield>mode</structfield></entry>
 109             <entry>Audio mode, none defined yet. Drivers and
 110 applications (on <constant>VIDIOC_S_AUDOUT</constant>) must set this
 111 field to zero.</entry>
 112           </row>
 113           <row>
 114             <entry>__u32</entry>
 115             <entry><structfield>reserved</structfield>[2]</entry>
 116             <entry>Reserved for future extensions. Drivers and
 117 applications must set the array to zero.</entry>
 118           </row>
 119         </tbody>
 120       </tgroup>
 121     </table>
 122   </refsect1>
 123
 124   <refsect1>
 125     &return-value;
 126
 127     <variablelist>
 128       <varlistentry>
 129         <term><errorcode>EINVAL</errorcode></term>
 130         <listitem>
 131           <para>No audio outputs combine with the current video
 132 output, or the number of the selected audio output is out of bounds or
 133 it does not combine, or there are no audio outputs at all and the
 134 ioctl is not supported.</para>
 135         </listitem>
 136       </varlistentry>
 137       <varlistentry>
 138         <term><errorcode>EBUSY</errorcode></term>
 139         <listitem>
 140           <para>I/O is in progress, the output cannot be
 141 switched.</para>
 142         </listitem>
 143       </varlistentry>
 144     </variablelist>
 145   </refsect1>
 146 </refentry>
 147
 148 <!--
 149 Local Variables:
 150 mode: sgml
 151 sgml-parent-document: "v4l2.sgml"
 152 indent-tabs-mode: nil
 153 End:
 154 -->