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