PKEY_AudioEndpoint_StableId

Properti PKEY_AudioEndpoint_StableId menyediakan pengidentifikasi buram tambahan untuk titik akhir audio. Windows mencoba mempertahankan pengidentifikasi ini di seluruh pembaruan sistem operasi dan pembaruan driver audio.

ID titik akhir biasa yang dikembalikan oleh IMMDevice::GetId tidak stabil. Pembaruan sistem operasi atau pembaruan driver audio dapat menyebabkan periferal fisik yang sama diberi ID titik akhir yang berbeda. Akibatnya, aplikasi tidak dapat menggunakan ID titik akhir biasa untuk melacak titik akhir audio fisik dengan andal. Properti PKEY_AudioEndpoint_StableId , jika tersedia, dapat digunakan untuk melacak titik akhir audio fisik. Contoh skenario adalah aplikasi komunikasi yang mengingat mikrofon atau speaker yang dipilih pengguna dan memulihkan pilihan tersebut di sesi selanjutnya.

Anggota vt dari struktur PROPVARIANT diatur ke VT_LPWSTR.

Anggota pwszVal dari struktur PROPVARIANT menunjuk ke string karakter lebar yang dihentikan null yang berisi pengidentifikasi stabil untuk perangkat titik akhir audio. Jika titik akhir tidak memiliki ID yang stabil, nilai properti VT_EMPTY. Tidak setiap titik akhir dijamin memiliki ID yang stabil.

Komentar

Perlakukan nilai properti sebagai string buram, peka huruf besar/kecil, dan bandingkan dengan huruf besar/kecil. Jangan ubah, normalisasi, rekonstruksi, atau uraikan nilai, dan jangan ekstrak atau andalkan substring internal apa pun. Format internal string adalah detail implementasi. Cache nilai hanya untuk mengidentifikasi titik akhir yang sama lagi nanti.

Jangan perlakukan ID stabil sebagai pengidentifikasi yang tidak dapat diubah untuk semua karakteristik perangkat. Properti titik akhir lainnya—misalnya, nama yang mudah diingat dan karakteristik format—dapat berubah sementara ID stabil tetap sama. Setelah Anda menyelesaikan perangkat dari ID stabil yang di-cache, kueri ulang properti yang dapat diubah yang bergantung pada aplikasi Anda.

ID stabil lebih tahan lama daripada ID titik akhir biasa, tetapi tidak dijamin tidak akan pernah berubah. Windows mencoba mempertahankannya di seluruh pembaruan sistem operasi dan driver audio. Windows kemampuan untuk mempertahankan nilai ini tergantung pada perilaku driver audio, firmware periferal, jenis bus (misalnya, USB dan Bluetooth), dan informasi yang diekspos periferal. Persentase kecil periferal mungkin menerima ID stabil yang berbeda setelah sistem operasi atau peningkatan driver.

Aplikasi harus menangani setiap kasus berikut:

  • Nilai properti VT_EMPTY.
  • Pembacaan penyimpanan properti gagal.
  • ID stabil yang di-cache tidak lagi diselesaikan ke titik akhir melalui IMMDeviceEnumerator::GetDevice.

Mengambil ID stabil

Untuk mengambil ID stabil untuk titik akhir yang dipilih pengguna, lakukan hal berikut:

  1. Mulai dengan antarmuka IMMDevice untuk titik akhir yang dipilih.
  2. Panggil metode IMMDevice::OpenPropertyStore dengan bendera STGM_READ.
  3. Panggil metode IPropertyStore::GetValue dengan kunci properti PKEY_AudioEndpoint_StableId.
  4. Jika anggota vt dari PROPVARIANT yang dikembalikan VT_LPWSTR, pertahankan seluruh string pwszVal .
  5. Jika properti tidak tersedia atau tidak VT_LPWSTR (misalnya, pada versi Windows yang lebih lama, atau ketika nilainya VT_EMPTY), Anda dapat secara opsional kembali ke IMMDevice::GetId. Perhatikan bahwa nilai fallback kurang tahan lama dan dapat menjadi basi setelah sistem operasi atau pembaruan driver audio.

Contoh berikut mengambil dan mempertahankan ID stabil.

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);
        }
    }
}

Memulihkan perangkat nanti

Untuk memulihkan perangkat di sesi selanjutnya, buat objek MMDeviceEnumerator dengan memanggil CoCreateInstance, lalu teruskan string ID stabil yang di-cache sebagai argumen pwstrId ke metode IMMDeviceEnumerator::GetDevice untuk mendapatkan antarmuka IMMDevice kembali. Tangani kasus kegagalan di mana tidak ada titik akhir yang cocok yang ditemukan.

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

Persyaratan Nilai
Klien minimum yang didukung
 Windows 11, versi 24H2 (build 26100) [hanya aplikasi desktop]
Server minimum yang didukung
 Windows Server 2025 (build 26100) [hanya aplikasi desktop]
Header
Mmdeviceapi.h

Baca juga

Properti Titik Akhir Audio

Properti Audio Inti

IMMDevice::OpenPropertyStore

IMMDeviceEnumerator::GetDevice

IMMDevice::GetId

String ID Titik Akhir

  • Terakhir diperbarui pada