VIDIOC_G_AUDOUT·VIDIOC_S_AUDOUT ioctl

목적, 호출 형식과 인자

`VIDIOC_G_AUDOUT`은 현재 audio output을 조회하고, `VIDIOC_S_AUDOUT`은 현재 audio output을 선택하는 ioctl입니다.

조회 형식은 `int ioctl(int fd, VIDIOC_G_AUDOUT, struct v4l2_audioout *argp)`, 선택 형식은 `int ioctl(int fd, VIDIOC_S_AUDOUT, const struct v4l2_audioout *argp)`입니다.

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_G_AUDOUT:

**************************************
ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT
**************************************

Name
====

VIDIOC_G_AUDOUT - VIDIOC_S_AUDOUT - Query or select the current audio output

Synopsis
========

.. c:macro:: VIDIOC_G_AUDOUT

``int ioctl(int fd, VIDIOC_G_AUDOUT, struct v4l2_audioout *argp)``

.. c:macro:: VIDIOC_S_AUDOUT

``int ioctl(int fd, VIDIOC_S_AUDOUT, const struct v4l2_audioout *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_audioout`.

현재 출력 조회와 선택

현재 audio output을 조회할 때 응용 프로그램은 `v4l2_audioout.reserved` 배열을 0으로 만들고 `VIDIOC_G_AUDOUT`을 호출합니다. 드라이버가 나머지 구조체를 채웁니다.

로컬 원문은 조회 실패 조건을 장치에 `audio inputs`가 없거나 현재 video output과 조합되는 항목이 없는 경우라고 표현합니다. 명령과 구조체 문맥은 audio output을 다루지만, 이 원문 표현은 임의로 바꾸지 않고 그대로 주의 대상으로 남깁니다.

audio output에는 현재 정의된 writable 속성이 없습니다. 그래도 `index`와 미래 writable 속성용 `reserved`를 초기화해 `VIDIOC_S_AUDOUT`을 호출하면 현재 audio output을 선택할 수 있습니다.

요청 index가 범위를 벗어나면 드라이버는 `EINVAL`을 반환합니다. `VIDIOC_S_AUDOUT`도 write-only이므로 `VIDIOC_G_AUDOUT`처럼 현재 출력 속성을 반환하지 않습니다.

TV 카드에서 수신한 audio 신호를 sound card로 되돌려 보내는 loop-back connector는 이 API의 audio output이 아닙니다.

Description
===========

To query the current audio output applications zero out the ``reserved``
array of a struct :c:type:`v4l2_audioout` and call the
``VIDIOC_G_AUDOUT`` ioctl with a pointer to this structure. Drivers fill
the rest of the structure or return an ``EINVAL`` error code when the device
has no audio inputs, or none which combine with the current video
output.

Audio outputs have no writable properties. Nevertheless, to select the
current audio output applications can initialize the ``index`` field and
``reserved`` array (which in the future may contain writable properties)
of a struct :c:type:`v4l2_audioout` structure and call the
``VIDIOC_S_AUDOUT`` ioctl. Drivers switch to the requested output or
return the ``EINVAL`` error code when the index is out of bounds. This is a
write-only ioctl, it does not return the current audio output attributes
as ``VIDIOC_G_AUDOUT`` does.

.. note::

   Connectors on a TV card to loop back the received audio signal
   to a sound card are not audio outputs in this sense.

v4l2_audioout 구조체

`index`는 조회에서는 드라이버의 출력값이고 선택에서는 응용 프로그램의 입력값입니다. `name`은 사용자가 실제 단자를 식별할 수 있는 문자열이어야 합니다.

현재 `capability`, `mode`, `reserved`에는 정의된 출력 속성이 없으므로 모두 0이어야 합니다. 특히 미래 확장용 공간에 임의 값을 넣어서는 안 됩니다.

.. c:type:: v4l2_audioout

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

.. flat-table:: struct v4l2_audioout
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __u32
      - ``index``
      - Identifies the audio output, set by the driver or application.
    * - __u8
      - ``name``\ [32]
      - Name of the audio output, a NUL-terminated ASCII string, for
	example: "Line Out". This information is intended for the user,
	preferably the connector label on the device itself.
    * - __u32
      - ``capability``
      - Audio capability flags, none defined yet. Drivers must set this
	field to zero.
    * - __u32
      - ``mode``
      - Audio mode, none defined yet. Drivers and applications (on
	``VIDIOC_S_AUDOUT``) must set this field to zero.
    * - __u32
      - ``reserved``\ [2]
      - Reserved for future extensions. Drivers and applications must set
	the array to zero.

반환값과 EINVAL

성공하면 0을 반환합니다. 오류가 발생하면 -1을 반환하고 `errno`를 설정하며, 공통 오류 코드는 Generic Error Codes 장을 따릅니다.

Return Value
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

EINVAL
    No audio outputs combine with the current video output, or the
    number of the selected audio output is out of bounds or it does not
    combine.