PulseAudio:プロパティリスト

作成など
pa_proplist_new作成
pa_proplist_free削除
pa_proplist_clearクリア
pa_proplist_copy複製を作成
pa_proplist_from_string文字列から作成
色々
pa_proplist_isemptyリストが空かどうか
pa_proplist_sizeエントリの数を取得
pa_proplist_equal全体が同じか比較
pa_proplist_updateプロパティリストを結合
取得
pa_proplist_contains指定キーがあるか
pa_proplist_key_validキーが有効かどうか
pa_proplist_getキーの値を取得
pa_proplist_getsキーの値の文字列ポインタを取得
pa_proplist_iterateすべてのキー文字列を反復処理
セット
pa_proplist_setデータをセット
pa_proplist_sets通常の文字列エントリをセット
pa_proplist_setf文字列エントリをフォーマット付きでセット
pa_proplist_setp"name=val" の形で文字列エントリをセット
削除
pa_proplist_unset指定キーのエントリを削除
pa_proplist_unset_many複数のキーを削除
文字列フォーマット
pa_proplist_to_stringすべてのデータを文字列としてフォーマットして返す(改行区切り)
pa_proplist_to_string_sepすべてのデータを文字列としてフォーマットして返す(区切り指定)
作成など
pa_proplist *pa_proplist_new(void);
作成
void pa_proplist_free(pa_proplist *p);
削除
void pa_proplist_clear(pa_proplist *p);
クリア
pa_proplist *pa_proplist_copy(const pa_proplist *p);
複製を作成
pa_proplist *pa_proplist_from_string(const char *str);
"key=name" のような形で定義された文字列からプロパティリストを作成。
色々
int pa_proplist_isempty(const pa_proplist *p);
リストが空の場合は 0 を返し、それ以外の場合は正を返す。
unsigned pa_proplist_size(const pa_proplist *p);
エントリの数を取得
int pa_proplist_equal(const pa_proplist *a, const pa_proplist *b);
a と b のキーと値が全く同じなら 0 以外が返る。
void pa_proplist_update(pa_proplist *p, pa_update_mode_t mode, const pa_proplist *other);
mode の結合モードで、other を p に結合する。
mode
結合モード
PA_UPDATE_SET: すべて other に置き換える
PA_UPDATE_MERGE: 同じキーは p のまま維持し、存在していないものだけ追加
PA_UPDATE_REPLACE: 同じキーは other で置き換え、存在していないものは追加
取得
int pa_proplist_contains(const pa_proplist *p, const char *key);
指定キーが存在すれば 1。負の値でエラー。
int pa_proplist_key_valid(const char *key);
キーが有効なら 0 以外の値が返る。
int pa_proplist_get(const pa_proplist *p, const char *key, const void **data, size_t *nbytes);
指定されたキーの値を取得する。
data
内部で確保されているデータのポインタが入る。ヌル文字を含む。
データの複製はされないため、この後に指定キーが変更/削除される場合は、参照できなくなるので注意。
nbytes
データのバイト数が入る。
戻り値
成功時は 0、エラー時は負の値。
const char *pa_proplist_gets(const pa_proplist *p, const char *key);
指定されたキーの値の文字列のポインタ (内部で確保されているポインタ) を返す。
データが有効な UTF-8 でない場合は NULL を返す。
const char *pa_proplist_iterate(const pa_proplist *p, void **state);
state で状態を判断しつつ、複数回呼んですべてのキー文字列を取得する。
まず void* 型の変数を用意して、NULL で初期化する。そのポインタを引数に渡して関数を呼ぶと、順にキー文字列が返る。
NULL が返ると終了。

※現在のエントリはループ中に削除しても良いが、ループ内でリストの変更はしないこと。
セット
int pa_proplist_set(pa_proplist *p, const char *key, const void *data, size_t nbytes);
新しい任意のデータエントリをプロパティリストに追加、または既存のエントリを同じキーで上書き。
渡されたデータは内部でコピーされる。成功するとゼロを返す。
int pa_proplist_sets(pa_proplist *p, const char *key, const char *value);
通常の文字列エントリをセット
int pa_proplist_setf(pa_proplist *p, const char *key, const char *format, ...);
プロパティリストに新しい文字列エントリ (UTF-8) を追加または上書き。
データは内部でコピーされる。printf() スタイルのフォーマット文字列として渡すことができる。
成功するとゼロを返す。
int pa_proplist_setp(pa_proplist *p, const char *pair);
"name=val" の形で文字列を指定して、文字列エントリを追加/上書き。
削除
int pa_proplist_unset(pa_proplist *p, const char *key);
指定されたキー名で識別される単一のエントリを削除。
成功した場合はゼロを返し、エラーの場合は負を返す。
int pa_proplist_unset_many(pa_proplist *p, const char *const keys[]);
keys の配列で指定された複数のキーのエントリを削除。NULL でデータの終了。
失敗した場合は -1 を返す。それ以外の場合は、実際に削除されたエントリの数 (一致するエントリがない場合は 0 になる場合もあり)。
文字列フォーマット
char *pa_proplist_to_string(const pa_proplist *p);
プロパティリストを人間が読める文字列として適切にフォーマットする。
これは pa_proplist_to_string_sep() と非常によく似た働きをし、区切り文字として改行を使用し、最後の行を 1 つ追加する。
pa_xfree() で解放すること。
char *pa_proplist_to_string_sep(const pa_proplist *p, const char *sep);
sep で区切り文字を指定して、フォーマットする。