VIDIOC_G_AUDIO·VIDIOC_S_AUDIO ioctl

목적, 호출 형식과 인자

`VIDIOC_G_AUDIO`는 현재 audio input과 속성을 조회하고, `VIDIOC_S_AUDIO`는 현재 audio input과 audio mode를 선택하는 ioctl입니다.

조회 형식은 `int ioctl(int fd, VIDIOC_G_AUDIO, struct v4l2_audio *argp)`, 선택 형식은 `int ioctl(int fd, VIDIOC_S_AUDIO, const struct v4l2_audio *argp)`입니다. `fd`는 `open()`이 반환한 장치 파일 디스크립터입니다.

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

.. _VIDIOC_G_AUDIO:

************************************
ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO
************************************

Name
====

VIDIOC_G_AUDIO - VIDIOC_S_AUDIO - Query or select the current audio input and its attributes

Synopsis
========

.. c:macro:: VIDIOC_G_AUDIO

``int ioctl(int fd, VIDIOC_G_AUDIO, struct v4l2_audio *argp)``

.. c:macro:: VIDIOC_S_AUDIO

``int ioctl(int fd, VIDIOC_S_AUDIO, const struct v4l2_audio *argp)``

Arguments
=========

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

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

현재 입력 조회와 선택

현재 audio input을 조회할 때 응용 프로그램은 `v4l2_audio.reserved` 배열을 0으로 만든 뒤 `VIDIOC_G_AUDIO`를 호출합니다. 드라이버가 `index`, `name`, `capability`, `mode`를 포함한 나머지 필드를 채웁니다.

장치에 audio input이 없거나 현재 video input과 조합할 수 있는 audio input이 없으면 조회는 `EINVAL`을 반환합니다.

audio input에서 응용 프로그램이 쓸 수 있는 속성은 audio mode 하나입니다. 입력을 선택하면서 mode도 바꾸려면 `index`, `mode`, `reserved`를 초기화해 `VIDIOC_S_AUDIO`를 호출합니다.

드라이버가 요청을 그대로 만족할 수 없으면 다른 audio mode로 전환할 수 있습니다. `VIDIOC_S_AUDIO`는 write-only이므로 실제로 적용된 새 mode를 구조체에 반환하지 않습니다.

적용 결과가 필요하면 선택 후 `VIDIOC_G_AUDIO`로 다시 조회해야 합니다.

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

To query the current audio input applications zero out the ``reserved``
array of a struct :c:type:`v4l2_audio` and call the
:ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` 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 input.

Audio inputs have one writable property, the audio mode. To select the
current audio input *and* change the audio mode, applications initialize
the ``index`` and ``mode`` fields, and the ``reserved`` array of a
struct :c:type:`v4l2_audio` structure and call the :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>`
ioctl. Drivers may switch to a different audio mode if the request
cannot be satisfied. However, this is a write-only ioctl, it does not
return the actual new audio mode.

v4l2_audio 구조체

`index`는 조회에서는 현재 입력을 드라이버가 알려 주는 출력값이고, 선택에서는 응용 프로그램이 원하는 입력을 지정하는 입력값입니다.

`name`은 사용자 표시용이므로 실제 장치에서 식별할 수 있는 커넥터 이름을 제공하는 것이 좋습니다.

`capability`는 지원 여부를, `mode`는 현재 또는 요청 상태를 나타냅니다. 두 필드의 의미를 혼동해서는 안 됩니다.

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

.. c:type:: v4l2_audio

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

    * - __u32
      - ``index``
      - Identifies the audio input, set by the driver or application.
    * - __u8
      - ``name``\ [32]
      - Name of the audio input, a NUL-terminated ASCII string, for
	example: "Line In". This information is intended for the user,
	preferably the connector label on the device itself.
    * - __u32
      - ``capability``
      - Audio capability flags, see :ref:`audio-capability`.
    * - __u32
      - ``mode``
      - Audio mode flags set by drivers and applications (on
	:ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl), see :ref:`audio-mode`.
    * - __u32
      - ``reserved``\ [2]
      - Reserved for future extensions. Drivers and applications must set
	the array to zero.

Audio capability 플래그

`V4L2_AUDCAP_STEREO`는 입력 자체가 stereo를 지원한다는 뜻이지 현재 stereo 신호가 수신됐다는 뜻은 아닙니다. audio input이 tuner에 속한 경우를 제외하면 이 API에는 현재 stereo 수신을 감지하는 방법이 없습니다.

.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|

.. _audio-capability:

.. flat-table:: Audio Capability Flags
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4

    * - ``V4L2_AUDCAP_STEREO``
      - 0x00001
      - This is a stereo input. The flag is intended to automatically
	disable stereo recording etc. when the signal is always monaural.
	The API provides no means to detect if stereo is *received*,
	unless the audio input belongs to a tuner.
    * - ``V4L2_AUDCAP_AVL``
      - 0x00002
      - Automatic Volume Level mode is supported.

Audio mode 플래그

AVL mode는 `V4L2_AUDCAP_AVL` capability가 있는 입력에서 의미가 있으며, 선택 결과는 필요하면 다시 조회해야 합니다.

.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|

.. _audio-mode:

.. flat-table:: Audio Mode Flags
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4

    * - ``V4L2_AUDMODE_AVL``
      - 0x00001
      - AVL mode is on.

반환값과 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 inputs combine with the current video input, or the number
    of the selected audio input is out of bounds or it does not combine.