Documentation/DocBook/media/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.</para>
 134         </listitem>
 135       </varlistentry>
 136     </variablelist>
 137   </refsect1>
 138 </refentry>