PKEY_AudioEndpoint_StableId プロパティは、オーディオ エンドポイントの追加の不透明な識別子を提供します。 Windowsは、オペレーティング システムの更新プログラムとオーディオ ドライバーの更新プログラム全体でこの識別子を保持しようとします。
IMMDevice::GetId によって返される通常のエンドポイント ID は安定していません。 オペレーティング システムの更新プログラムまたはオーディオ ドライバーの更新により、同じ物理周辺機器に別のエンドポイント ID が割り当てられる可能性があります。 その結果、アプリは通常のエンドポイント ID を使用して物理オーディオ エンドポイントを確実に追跡することはできません。 PKEY_AudioEndpoint_StableIdプロパティ (使用可能な場合) を使用して、物理オーディオ エンドポイントを追跡できます。 シナリオの例は、ユーザーが選択したマイクまたはスピーカーを記憶し、後のセッションでその選択内容を復元する通信アプリです。
PROPVARIANT 構造体の vt メンバーは、VT_LPWSTRに設定されます。
PROPVARIANT 構造体の pwszVal メンバーは、オーディオ エンドポイント デバイスの安定した識別子を含む null で終わるワイド文字列を指します。 エンドポイントに安定した ID がない場合、プロパティ値はVT_EMPTY。 すべてのエンドポイントが安定した ID を持つことが保証されているわけではありません。
注釈
プロパティ値は、大文字と小文字を区別する不透明な文字列として扱い、大文字と小文字を区別して比較します。 値を変更、正規化、再構築、解析したり、内部部分文字列を抽出したり、依存したりしないでください。 文字列の内部形式は実装の詳細です。 後でもう一度同じエンドポイントを識別するためにのみ、値をキャッシュします。
安定した ID は、デバイスのすべての特性の不変識別子として扱わないでください。 その他のエンドポイント プロパティ (フレンドリ名や形式の特性など) は、安定した ID が変わらない間に変更される可能性があります。 キャッシュされた安定した ID からデバイスを解決した後、アプリが依存する変更可能なプロパティを再クエリします。
安定した ID は通常のエンドポイント ID よりも持続性が高くなりますが、決して変更されないことは保証されません。 Windowsは、オペレーティング システムとオーディオ ドライバーの更新プログラム全体でそれを保持しようとします。 この値を保持するWindows機能は、オーディオ ドライバーの動作、周辺機器のファームウェア、バスの種類 (USB、Bluetoothなど)、周辺機器が公開する情報によって異なります。 オペレーティング システムまたはドライバーのアップグレード後に、少数の周辺機器が異なる安定した ID を受け取る可能性があります。
アプリでは、次の各ケースを処理する必要があります。
- プロパティ値はVT_EMPTY。
- プロパティ ストアの読み取りが失敗します。
- キャッシュされた安定した ID は、 IMMDeviceEnumerator::GetDevice を介してエンドポイントに解決されなくなりました。
安定した ID の取得
ユーザーが選択したエンドポイントの安定した ID を取得するには、次の操作を行います。
- 選択したエンドポイントの IMMDevice インターフェイスから始めます。
- STGM_READ フラグを指定 して IMMDevice::OpenPropertyStore メソッドを呼び出します。
- PKEY_AudioEndpoint_StableId プロパティ キーを使用して IPropertyStore::GetValue メソッドを呼び出します。
- 返された PROPVARIANT の vt メンバーがVT_LPWSTR場合は、pwszVal 文字列全体を保持します。
- プロパティが使用できない場合、またはVT_LPWSTRされていない場合 (たとえば、古いバージョンのWindowsの場合、または値がVT_EMPTY場合)、必要に応じて IMMDevice::GetId にフォールバックできます。 フォールバック値は持続性が低く、オペレーティング システムまたはオーディオ ドライバーの更新後に古くなる可能性があることに注意してください。
次の例では、安定した ID を取得して保持します。
wil::unique_cotaskmem_string deviceId;
wil::com_ptr_nothrow<IPropertyStore> propertyStore;
if (SUCCEEDED(userSelectedEndpoint->OpenPropertyStore(STGM_READ, &propertyStore)))
{
wil::unique_prop_variant var;
if (SUCCEEDED(propertyStore->GetValue(PKEY_AudioEndpoint_StableId, &var)))
{
if (var.vt == VT_LPWSTR)
{
deviceId.reset(var.release().pwszVal);
}
}
}
後でデバイスを復元する
後のセッションでデバイスを復元するには、CoCreateInstance を呼び出して MMDeviceEnumerator オブジェクトを作成し、pwstrId 引数としてキャッシュされた stable-ID 文字列を IMMDeviceEnumerator::GetDevice メソッドに渡して IMMDevice インターフェイスを取得します。 一致するエンドポイントが見つからないエラーケースを処理します。
HRESULT GetUserAudioEndpoint(_In_ PCWSTR endpointStableId, _COM_Outptr_ IMMDevice** userSelectedEndpoint)
{
*userSelectedEndpoint = nullptr;
wil::com_ptr_nothrow<IMMDeviceEnumerator> enumerator;
RETURN_IF_FAILED(CoCreateInstance(__uuidof(MMDeviceEnumerator), nullptr, CLSCTX_ALL, IID_PPV_ARGS(&enumerator)));
RETURN_IF_FAILED(enumerator->GetDevice(endpointStableId, userSelectedEndpoint));
return S_OK;
}
Requirements
| 要件 | 価値 |
|---|---|
| サポートされる最小クライアント |
Windows 11バージョン 24H2 (ビルド 26100) [デスクトップ アプリのみ] |
| サポートされている最小のサーバー |
Windows Server 2025 (ビルド 26100) [デスクトップ アプリのみ] |
| Header |
|