# Interfaces

此文档介绍了 alsa-ucm-aw-lib 提供的 C 语言 API

(前缀 "aua" 是 "ALSA UCM AW" 的首字母缩写)

## 使用方法

在应用程序代码中包含头文件 `alsa-ucm-aw.h` , 在编译时加上链接参数 `-lalsa-ucm-aw`

## API

### 通用 API

#### aua_use_case_enable, aua_use_case_disable
```c
/**
 * Run the EnableSequence/DisableSequence of a use case
 * @param card_name:    sound card name
 * @param verb_name:    verb name
 * @param dev_name:     device name
 * @param mod_name:     modifier name
 * @return: 0 on success, otherwise on error
 */
int aua_use_case_enable(const char *card_name, const char *verb_name,
                        const char *dev_name, const char *mod_name);
int aua_use_case_disable(const char *card_name, const char *verb_name,
                         const char *dev_name, const char *mod_name);
```

用于执行配置文件中的某个 `EnableSequence` / `DisableSequence`

参数中的 `card_name` 和 `verb_name` 不能为 `NULL` , `dev_name` 和 `mod_name` 中
至少有一个不为 `NULL`

#### aua_value_get
```c
/**
 * Get the "Value" defined in UCM configurations
 * @param value_name:       value name (e.g. PlaybackPCM, PlaybackVolume, CapturePCM, etc.)
 * @param card_name:        sound card name
 * @param verb_name:        verb name
 * @param dev_or_mod_name:  device or modifier name
 * @return: the string of "Value" on success; NULL on errer
 *
 * Note:
 *      The returned string is dynamically allocated. It needs be deallocated
 *      with free().
 */
char *aua_value_get(const char *value_name, const char *card_name,
                    const char *verb_name, const char *dev_or_mod_name);
```

用于获取 UCM 配置文件中的某个 *Value* 的值

参数中的 `card_name` , `verb_name` 和 `dev_or_mod_name` 可为 `NULL` , 它们用于决
定 *Value* 所在的位置

#### aua_playback_volume_get, aua_capture_volume_get
```c
/**
 * Get the volume according to the ALSA control defined in "PlaybackVolume" /
 * "CaptureVolume" in UCM configurations
 * @param card_name:        (in) sound card name
 * @param verb_name:        (in) verb name
 * @param dev_or_mod_name:  (in) device or modifier name
 * @param volume:           (out) the volume value got
 * @return: 0 on success, otherwise on error
 */
int aua_playback_volume_get(const char *card_name, const char *verb_name,
                            const char *dev_or_mod_name, int *volume);
int aua_capture_volume_get(const char *card_name, const char *verb_name,
                           const char *dev_or_mod_name, int *volume);
```

根据 `PlaybackVolume` 或 `CaptureVolume` 中 ALSA 控件的名字获取对应控件的值

参数 `card_name` , `verb_name` , `dev_or_mod_name` 的使用与 `aua_value_get` 的相同

#### aua_playback_volume_set, aua_capture_volume_set
```c
/**
 * Set the volume according to the ALSA control defined in "PlaybackVolume" /
 * "CaptureVolume" in UCM configurations
 * @param card_name:        sound card name
 * @param verb_name:        verb name
 * @param dev_or_mod_name:  device or modifier name
 * @param volume:           the volume value to set
 * @return: 0 on success, otherwise on error
 */
int aua_playback_volume_set(const char *card_name, const char *verb_name,
                            const char *dev_or_mod_name, int volume);
int aua_capture_volume_set(const char *card_name, const char *verb_name,
                           const char *dev_or_mod_name, int volume);
```

与 `aua_playback_volume_get` 和 `aua_capture_volume_get` 相反的函数, 根据
`PlaybackVolume` 或 `CaptureVolume` 中 ALSA 控件的名字设置该控件的值

#### aua_playback_volume_set_default, aua_capture_volume_set_default
```c
/**
 * Set the volume according to the ALSA control and its default value defined in
 * "PlaybackVolume"/"CaptureVolume" in UCM configurations
 * @param card_name:        sound card name
 * @param verb_name:        verb name
 * @param dev_or_mod_name:  device or modifier name
 * @return: 0 on success, otherwise on error
 */
int aua_playback_volume_set_default(const char *card_name, const char *verb_name,
                                    const char *dev_or_mod_name);
int aua_capture_volume_set_default(const char *card_name, const char *verb_name,
                                   const char *dev_or_mod_name);
```

类似于 `aua_playback_volume_set` 和 `aua_capture_volume_set` , 不过会将 ALSA 控件
的值设置为 `PlaybackVolume` 或 `CaptureVolume` 中指定的默认值

#### aua_playback_volume_min_get, aua_playback_volume_max_get, aua_capture_volume_min_get, aua_capture_volume_max_get
```c
/**
 * Get the min/max volume according to "PlaybackVolumeMin"/"PlaybackVolumeMax"/
 * "CaptureVolumeMin"/"CaptureVolumeMax" in UCM configurations
 * @param card_name:        sound card name
 * @param verb_name:        verb name
 * @param dev_or_mod_name:  device or modifier name
 * @param volume:           (out) the volume value got
 * @return: 0 on success, otherwise on error
 */
int aua_playback_volume_min_get(const char *card_name, const char *verb_name,
                                const char *dev_or_mod_name, int *volume);
int aua_playback_volume_max_get(const char *card_name, const char *verb_name,
                                const char *dev_or_mod_name, int *volume);
int aua_capture_volume_min_get(const char *card_name, const char *verb_name,
                               const char *dev_or_mod_name, int *volume);
int aua_capture_volume_max_get(const char *card_name, const char *verb_name,
                               const char *dev_or_mod_name, int *volume);
```

获取 `PlaybackVolumeMin` 或 `PlaybackVolumeMax` 或 `CaptureVolumeMin` 或
`CaptureVolumeMax` 中的数值

#### 例子

假设 card *audiocodec* 的 verb *Play* 中有如下的 device *Headphone* 的定义:
```
SectionDevice."Headphone" {
    EnableSequence [
        cdev "hw:demo"
        cset "name='Headphone Switch' 1"
    ]

    DisableSequence [
        cdev "hw:foobar"
        cset "name='Headphone Switch' 0"
    ]

    Value {
        PlaybackVolume "name='Headphone Volume' 40"
        PlaybackVolumeMin "0"
        PlaybackVolumeMax "63"
    }
}
```

当前系统中控件 name='Headphone Volume' 的实际值为 35

则上述 API 的使用方法如下 (忽略了错误返回值的判断)
```c
/* 执行 EnableSequence 的内容 */
err = aua_use_case_enable("audiocodec", "Play", "Headphone", NULL);

/* 字符串 str 的值为 "name='Headphone Volume' 40" (使用完后需释放 str: free(str))*/
str = aua_value_get("PlaybackVolume", "audiocodec", "Play", "Headphone");

/* 返回成功后变量 vol 的值为 35*/
err = aua_playback_volume_get("audiocodec", "Play", "Headphone", &vol);

/* 返回成功后系统中控件 name='Headphone Volume' 的值为 45 */
err = aua_playback_volume_set("audiocodec", "Play", "Headphone", 45);

/* 返回成功后系统中控件 name='Headphone Volume' 的值为 40 */
err = aua_playback_volume_set_default("audiocodec", "Play", "Headphone");

/* 返回成功后变量 vol_min 的值为 0, vol_max 的值为 63 */
err = aua_playback_volume_min_get("audiocodec", "Play", "Headphone", &vol_min);
err = aua_playback_volume_max_get("audiocodec", "Play", "Headphone", &vol_max);
```

### 默认使用案例 API

函数名均以 `aua_default_play_` 和 `aua_default_record_` 为前缀, 使用方法与通用
API 类似, 但它们的参数 `card_name` , `verb_name` , `dev_name` , `mod_name` 允许为
`NULL` , 此时它们会自动在当前系统的配置文件中按照以下策略寻找默认的 card, verb,
device 或 modifier:

1. 当 `card_name` 为 `NULL` 时, 优先选择 `audiocodec` 作为默认的 card, 若不存在
`audiocodec` , 则选择 card 列表中的第一项
2. 当 `verb_name` 为 `NULL` 时, 前缀 `aua_default_play_` 的函数会优先选择 `Play`
为默认的 verb (前缀 `aua_default_capture_` 的函数则会优先选择 `Record` ), 若不存
在, 则选择 verb 列表中的第一项
3. 当 `dev_name` 和 `mod_name` 均为 `NULL` 时, 才会去寻找默认的 device 或 modifier,
这两者没有优先选择的名字, 会直接选择列表中的第一项

若这些参数不为 `NULL` , 则函数的使用效果与通用 API 中的相同

从应用程序的角度而言, 若没有特殊的需求, 可以将全部的这些参数设为 `NULL` , 让其自
动根据当前系统的配置文件选择合适设备, 保证了代码的可移植性