PKEY_AudioEndpoint_StableId

Свойство PKEY_AudioEndpoint_StableId предоставляет дополнительный непрозрачный идентификатор для конечной точки звука. Windows пытается сохранить этот идентификатор в обновлениях операционной системы и обновлениях звукового драйвера.

Обычный идентификатор конечной точки, возвращаемый IMMDevice::GetId , не является стабильным. Обновление операционной системы или обновление звукового драйвера может привести к назначению одного физического периферийного устройства другого идентификатора конечной точки. В результате приложение не может использовать обычный идентификатор конечной точки для надежной отслеживания физической конечной точки аудио. Свойство PKEY_AudioEndpoint_StableId , если доступно, можно использовать для отслеживания физической конечной точки звука. Пример сценария — это приложение для обмена данными, которое запоминает микрофон или динамик, выбранный пользователем и восстанавливающий его в последующем сеансе.

Для элемента vt структуры PROPVARIANT задано значение VT_LPWSTR.

Член pwszVal структуры PROPVARIANT указывает на строку со значением NULL, которая содержит стабильный идентификатор для звукового устройства конечной точки. Если конечная точка не имеет стабильного идентификатора, значение свойства VT_EMPTY. Не каждая конечная точка гарантированно имеет стабильный идентификатор.

Замечания

Рассматривайте значение свойства как непрозрачную, регистрно-конфиденциальную строку и сравнивайте регистр с учетом регистра. Не изменяйте, не изменяйте, нормализуйте, реконструируйте или анализируйте значение и не извлекайте или не полагается на внутреннюю подстроку. Внутренний формат строки — это сведения о реализации. Кэшируйте значение только для определения той же конечной точки позже.

Не рассматривайте стабильный идентификатор как неизменяемый идентификатор для всех характеристик устройства. Другие свойства конечной точки, например понятное имя и характеристики формата, могут изменяться, пока стабильный идентификатор остается неизменным. После разрешения устройства из кэшированного стабильного идентификатора повторно запрашивайте все изменяемые свойства, от которые зависит ваше приложение.

Стабильный идентификатор является более устойчивым, чем обычный идентификатор конечной точки, но он не гарантирует, что никогда не изменяется. Windows пытается сохранить его в операционной системе и обновлениях звукового драйвера. Windows возможность сохранения этого значения зависит от поведения звукового драйвера, периферийного встроенного ПО, типа шины (например, USB и Bluetooth), а также информации, предоставляемой периферийным устройством. Небольшой процент периферийных устройств может получить другой стабильный идентификатор после обновления операционной системы или драйвера.

Приложение должно обрабатывать каждый из следующих случаев:

  • Значение свойства — VT_EMPTY.
  • Сбой чтения в хранилище свойств.
  • Кэшированный стабильный идентификатор больше не разрешается в конечную точку через IMMDeviceEnumerator::GetDevice.

Получение стабильного идентификатора

Чтобы получить стабильный идентификатор конечной точки, выбранной пользователем, сделайте следующее:

  1. Начните с интерфейса IMMDevice для выбранной конечной точки.
  2. Вызовите метод IMMDevice::OpenPropertyStore с флагом STGM_READ.
  3. Вызовите метод IPropertyStore::GetValue с ключом свойства PKEY_AudioEndpoint_StableId.
  4. Если элемент vt возвращаемого PROPVARIANT VT_LPWSTR, сохраните всю строку pwszVal .
  5. Если свойство недоступно или не VT_LPWSTR (например, в более старой версии Windows или если значение VT_EMPTY), можно при необходимости вернуться к IMMDevice::GetId. Обратите внимание, что резервное значение является менее устойчивым и может стать устаревшим после обновления операционной системы или звукового драйвера.

В следующем примере извлекается и сохраняется стабильный идентификатор.

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

Восстановление устройства позже

Чтобы восстановить устройство в последующем сеансе, создайте объект MMDeviceEnumerator , вызвав CoCreateInstance, а затем передайте кэшированную строку стабильного идентификатора в качестве аргумента pwstrId в метод 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) [только классические приложения]
Заголовок
Mmdeviceapi.h

См. также

Свойства конечной точки аудио

Основные свойства звука

IMMDevice::OpenPropertyStore

IMMDeviceEnumerator::GetDevice

IMMDevice::GetId

Строки идентификатора конечной точки

  • Последнее обновление: