ALSA:コントロール(要素関連)

値から文字列取得
snd_ctl_elem_type_name要素タイプの名前を取得
snd_ctl_elem_iface_name要素のインターフェースタイプから名前を取得
ロック
snd_ctl_elem_lock要素をロック
snd_ctl_elem_unlock要素をアンロック
追加/削除
snd_ctl_elem_removeユーザー要素を削除
snd_ctl_add_integer_elem_set整数の要素を追加
snd_ctl_add_integer64_elem_set64bit整数の要素を追加
snd_ctl_add_boolean_elem_set真偽値の要素を追加
snd_ctl_add_enumerated_elem_set列挙型の要素を追加
snd_ctl_add_bytes_elem_setバイトデータの要素を追加
snd_ctl_elem_add_integer整数の要素を追加 [非推奨]
snd_ctl_elem_add_integer6464bit整数の要素を追加 [非推奨]
snd_ctl_elem_add_boolean真偽値の要素を追加 [非推奨]
snd_ctl_elem_add_enumerated列挙型の要素を追加 [非推奨]
snd_ctl_elem_add_iec958IEC958データの要素を追加 [非推奨]
dB
snd_ctl_get_dB_rangedB 値の最小値と最大値を取得
snd_ctl_convert_to_dB生の音量値を dB に変換
snd_ctl_convert_from_dBdB 値を生の音量に変換
TLV
SND_CTL_TLVT_*TLV タイプ
snd_ctl_elem_tlv_readTLVで要素の値を読み込み
snd_ctl_elem_tlv_writeTLVで要素の値を書き込み
snd_ctl_elem_tlv_commandTLVで要素を操作
TLV の値
snd_tlv_parse_dB_infoTLV データから dB 情報を見つける
snd_tlv_get_dB_rangedB の範囲を取得
snd_tlv_convert_to_dB音量を dB 単位に変換
snd_tlv_convert_from_dBdB から生の音量に変換
値から文字列取得
const char *snd_ctl_elem_type_name(snd_ctl_elem_type_t type);
要素タイプの名前を取得
const char *snd_ctl_elem_iface_name(snd_ctl_elem_iface_t iface);
要素のインターフェースタイプから名前を取得
ロック
int snd_ctl_elem_lock(snd_ctl_t *ctl, snd_ctl_elem_id_t *id);
要素をロックして、所有権を得る。
ロック中は、他のアプリから値が変更されない。
戻り値
0 で成功、負の値でエラーコード
int snd_ctl_elem_unlock(snd_ctl_t *ctl, snd_ctl_elem_id_t *id);
要素をアンロック
戻り値
0 で成功、負の値でエラーコード
追加/削除
int snd_ctl_elem_remove(snd_ctl_t *ctl, snd_ctl_elem_id_t *id);
ユーザー要素を削除
戻り値
0 で成功、負の値でエラーコード
int snd_ctl_add_integer_elem_set(snd_ctl_t *ctl, snd_ctl_elem_info_t *info,
    unsigned int element_count, unsigned int member_count, long min, long max, long step);
//ver 1.1.2
ユーザー要素として、整数タイプの要素を追加する。

新しい要素は初期状態でロックされ、各メンバの値は最小値で初期化される。
info
要素の識別子を含む、要素情報。
識別子の name で、一意の文字列をセットする必要がある。要素の追加後、識別子の他のデータがセットされる。
この要素は、名前とインデックス、または numid で識別される。
element_count
追加する要素の数
member_count
要素のメンバの数
min
各メンバの最小値
max
各メンバの最大値
step
各メンバのステップ値
戻り値
0 で成功、負の値でエラーコード。

-EBUSY同じ識別子が存在する
-EINVAL引数に無効な値が含まれている。
element_count が 1〜127 の範囲外など。
-ENOMEMメモリ不足、またはユーザー要素が多すぎる
-ENXIOこのバックエンドモジュールは、整数型のユーザー要素をサポートしていない
-ENODEVデバイスが取り外された
int snd_ctl_add_integer64_elem_set(snd_ctl_t *ctl, snd_ctl_elem_info_t *info,
    unsigned int element_count, unsigned int member_count, long long min, long long max, long long step);
//ver 1.1.2
64bit整数の要素を追加
int snd_ctl_add_boolean_elem_set(snd_ctl_t *ctl, snd_ctl_elem_info_t *info,
    unsigned int element_count, unsigned int member_count);
//ver 1.1.2
真偽値の要素を追加。
値の初期値は false になる。
int snd_ctl_add_enumerated_elem_set(snd_ctl_t *ctl, snd_ctl_elem_info_t *info,
    unsigned int element_count, unsigned int member_count, unsigned int items, const char *const labels[]);
//ver 1.1.2
列挙型の要素を追加。
初期値は、ラベルの先頭の項目になる。
items
列挙型の数
labels
列挙型のラベルの配列
戻り値
0 で成功、負の値でエラーコード。
-EINVAL : items が 1 未満、ラベルが空文字列、1つのラベルが 64 byte 以上、ラベルの合計長が 64 KB を超える場合も起こる。
int snd_ctl_add_bytes_elem_set(snd_ctl_t *ctl, snd_ctl_elem_info_t *info, unsigned int element_count, unsigned int member_count);
//ver 1.1.2
バイトデータの要素を追加
member_count
1〜511 まで
int snd_ctl_elem_add_integer(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id,
    unsigned int count, long imin, long imax, long istep);
ユーザー要素として、整数タイプの要素を追加。
snd_ctl_add_integer_elem_set() のラッパーだが、識別子に完全な情報をセットしないため、snd_ctl_add_integer_elem_set() を使うことが推奨される。
int snd_ctl_elem_add_integer64(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id,
    unsigned int count, long long imin, long long imax, long long istep);
64bit整数の要素を追加 [非推奨]
int snd_ctl_elem_add_boolean(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id, unsigned int count);
真偽値の要素を追加 [非推奨]
int snd_ctl_elem_add_enumerated(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id,
    unsigned int count, unsigned int items, const char *const names[]);
列挙型の要素を追加 [非推奨]
int snd_ctl_elem_add_iec958(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id);
IEC958データの要素を追加 [非推奨]
dB
int snd_ctl_get_dB_range(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id, long *min, long *max);
dB 値の最小値と最大値を取得する。
内部で、TLV データや、要素の値の最小値と最大値を読み込んで、処理を行う。
min
dB 最小値が返る (0.01 dB 単位)
max
dB 最大値が返る (0.01 dB 単位)
戻り値
0 で成功、負の値でエラーコード
int snd_ctl_convert_to_dB(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id, long volume, long *db_gain);
生の音量値を dB に変換
volume
変換する生の音量
db_gain
dB 値が返る (0.01 dB 単位)
戻り値
0 で成功、負の値でエラーコード
int snd_ctl_convert_from_dB(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id, long db_gain, long *value, int xdir);
dB 値を生の音量に変換
db_gain
変換する dB 値 (0.01 dB 単位)
value
生の音量が返る
xdir
切り上げの方向。
正の場合、値は切り上げられる。負の値は切り捨て。
0 は最も近い値に切り上げられる。
戻り値
0 で成功、負の値でエラーコード
TLV
#define SND_CTL_TLVT_CONTAINER   0x0000
#define SND_CTL_TLVT_DB_SCALE    0x0001
#define SND_CTL_TLVT_DB_LINEAR   0x0002
#define SND_CTL_TLVT_DB_RANGE    0x0003
#define SND_CTL_TLVT_DB_MINMAX   0x0004
#define SND_CTL_TLVT_DB_MINMAX_MUTE   0x0005

#define SND_CTL_TLVT_CHMAP_FIXED   0x00101
#define SND_CTL_TLVT_CHMAP_VAR     0x00102
#define SND_CTL_TLVT_CHMAP_PAIRED  0x00103
TLV タイプ
SND_CTL_TLVT_CONTAINER
コンテナ。
データの中に、複数の TLV データが含まれる。
SND_CTL_TLVT_DB_SCALE
基本的な dB スケール
SND_CTL_TLVT_DB_LINEAR
線形音量
SND_CTL_TLVT_DB_RANGE
dB 範囲のコンテナ
SND_CTL_TLVT_DB_MINMAX
dB の最小値/最大値
SND_CTL_TLVT_DB_MINMAX_MUTE
dB の最小値/最大値 (ミュート)
SND_CTL_TLVT_CHMAP_FIXED
チャンネルマップの位置固定
SND_CTL_TLVT_CHMAP_VAR
チャンネルマップの位置を自由に交換可能
SND_CTL_TLVT_CHMAP_PAIRED
ペアで交換可能なチャンネルマップ位置
int snd_ctl_elem_tlv_read(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id, unsigned int *tlv, unsigned int tlv_size);
TLVで要素の値を読み込み
tlv
配列に値が返る。
tlv[0]: TLV タイプ。SND_CTL_TLVT_* のいずれか。
tlv[1]: 値のバイト数 (sizeof(int) で割ると個数になる)。
tlv[2..]: 値。データの数や意味は、タイプによって異なる。

正しく読み込めなかった場合、tlv[0] = -1, tlv[1] = 0 になる。
tlv_size
tlv 配列全体のバイト数。読み込みに必要なサイズ分があること。
戻り値
0 で成功、負の値でエラーコード
int snd_ctl_elem_tlv_write(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id, const unsigned int *tlv);
TLVで要素の値を書き込み
戻り値
0 で成功。
正の値で、値が変更されたときに成功した。
負の値でエラーコード
int snd_ctl_elem_tlv_command(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id, const unsigned int *tlv);
TLVで要素を操作
戻り値
0 で成功。
正の値で、値が変更されたときに成功した。
負の値でエラーコード
TLV の値
int snd_tlv_parse_dB_info(unsigned int *tlv, unsigned int tlv_size, unsigned int **db_tlvp);
TLV データ内で、SND_CTL_TLVT_DB_* タイプのデータが見つかったら、その位置のポインタを返す。
tlv_size
tlv 配列全体のバイト数
db_tlvp
tlv 内で見つかった先頭位置のポインタが返る
戻り値
見つかった場合は、その TLV データの全体バイト数 (タイプやサイズのデータも含む)。
見つからない場合は -ENOENT。
エラーの場合は、負のエラーコード。
int snd_tlv_get_dB_range(unsigned int *tlv, long rangemin, long rangemax, long *min, long *max);
dB の範囲を取得
tlv
snd_tlv_parse_dB_info() で返ったポインタ
rangemin
生の音量の最小値
rangemax
生の音量の最大値
min
最小 dB (0.01 dB 単位)
max
最大 dB (0.01 dB 単位)
戻り値
0 で成功、負の値でエラーコード
int snd_tlv_convert_to_dB(unsigned int *tlv, long rangemin, long rangemax, long volume, long *db_gain);
音量を dB 単位に変換
tlv
snd_tlv_parse_dB_info() で返ったポインタ
rangemin
生の音量の最小値
rangemax
生の音量の最大値
volume
変換する生の音量
db_gain
変換された dB 値が返る (0.01 dB 単位)
戻り値
0 で成功、負の値でエラーコード
int snd_tlv_convert_from_dB(unsigned int *tlv, long rangemin, long rangemax, long db_gain, long *value, int xdir);
dB から生の音量に変換
tlv
snd_tlv_parse_dB_info() で返ったポインタ
rangemin
生の音量の最小値
rangemax
生の音量の最大値
db_gain
変換する dB (0.01 dB 単位)
value
変換された生の音量が返る
xdir
切り上げの方向。
正の場合、値は切り上げられる。負の値は切り捨て。
0 は最も近い値に切り上げられる。
戻り値
0 で成功、負の値でエラーコード