Documentation/media/uapi/v4l/vidioc-g-audioout.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_G_AUDOUT:
   4
   5 **************************************
   6 ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT
   7 **************************************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_G_AUDOUT - VIDIOC_S_AUDOUT - Query or select the current audio output
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. cpp:function:: int ioctl( int fd, int request, struct v4l2_audioout *argp )
  19
  20 .. cpp:function:: int ioctl( int fd, int request, const struct v4l2_audioout *argp )
  21
  22
  23 Arguments
  24 =========
  25
  26 ``fd``
  27     File descriptor returned by :ref:`open() <func-open>`.
  28
  29 ``request``
  30     VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT
  31
  32 ``argp``
  33
  34
  35 Description
  36 ===========
  37
  38 To query the current audio output applications zero out the ``reserved``
  39 array of a struct :ref:`v4l2_audioout <v4l2-audioout>` and call the
  40 ``VIDIOC_G_AUDOUT`` ioctl with a pointer to this structure. Drivers fill
  41 the rest of the structure or return an ``EINVAL`` error code when the device
  42 has no audio inputs, or none which combine with the current video
  43 output.
  44
  45 Audio outputs have no writable properties. Nevertheless, to select the
  46 current audio output applications can initialize the ``index`` field and
  47 ``reserved`` array (which in the future may contain writable properties)
  48 of a :ref:`struct v4l2_audioout <v4l2-audioout>` structure and call the
  49 ``VIDIOC_S_AUDOUT`` ioctl. Drivers switch to the requested output or
  50 return the ``EINVAL`` error code when the index is out of bounds. This is a
  51 write-only ioctl, it does not return the current audio output attributes
  52 as ``VIDIOC_G_AUDOUT`` does.
  53
  54 .. note::
  55
  56    Connectors on a TV card to loop back the received audio signal
  57    to a sound card are not audio outputs in this sense.
  58
  59
  60 .. _v4l2-audioout:
  61
  62 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  63
  64 .. flat-table:: struct v4l2_audioout
  65     :header-rows:  0
  66     :stub-columns: 0
  67     :widths:       1 1 2
  68
  69
  70     -  .. row 1
  71
  72        -  __u32
  73
  74        -  ``index``
  75
  76        -  Identifies the audio output, set by the driver or application.
  77
  78     -  .. row 2
  79
  80        -  __u8
  81
  82        -  ``name``\ [32]
  83
  84        -  Name of the audio output, a NUL-terminated ASCII string, for
  85           example: "Line Out". This information is intended for the user,
  86           preferably the connector label on the device itself.
  87
  88     -  .. row 3
  89
  90        -  __u32
  91
  92        -  ``capability``
  93
  94        -  Audio capability flags, none defined yet. Drivers must set this
  95           field to zero.
  96
  97     -  .. row 4
  98
  99        -  __u32
 100
 101        -  ``mode``
 102
 103        -  Audio mode, none defined yet. Drivers and applications (on
 104           ``VIDIOC_S_AUDOUT``) must set this field to zero.
 105
 106     -  .. row 5
 107
 108        -  __u32
 109
 110        -  ``reserved``\ [2]
 111
 112        -  Reserved for future extensions. Drivers and applications must set
 113           the array to zero.
 114
 115
 116 Return Value
 117 ============
 118
 119 On success 0 is returned, on error -1 and the ``errno`` variable is set
 120 appropriately. The generic error codes are described at the
 121 :ref:`Generic Error Codes <gen-errors>` chapter.
 122
 123 EINVAL
 124     No audio outputs combine with the current video output, or the
 125     number of the selected audio output is out of bounds or it does not
 126     combine.