8.3 KiB

Raw Blame History

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

/**
 * 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

/**
 * 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

/**
 * 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

/**
 * 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

/**
 * 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

/**
 * 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 的使用方法如下 (忽略了错误返回值的判断)

/* 执行 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:

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

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

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

8.3 KiB Raw Blame History