PKEY_AudioEndpoint_StableId

La propriété PKEY_AudioEndpoint_StableId fournit un identificateur supplémentaire opaque pour un point de terminaison audio. Windows tente de conserver cet identificateur entre les mises à jour du système d’exploitation et les mises à jour du pilote audio.

L’ID de point de terminaison ordinaire retourné par IMMDevice ::GetId n’est pas stable. Une mise à jour du système d’exploitation ou une mise à jour du pilote audio peut entraîner l’attribution d’un id de point de terminaison différent au même périphérique physique. Par conséquent, une application ne peut pas utiliser l’ID de point de terminaison ordinaire pour suivre de manière fiable un point de terminaison audio physique. La propriété PKEY_AudioEndpoint_StableId , lorsqu’elle est disponible, peut être utilisée pour suivre un point de terminaison audio physique. Un exemple de scénario est une application de communication qui mémorise le microphone ou le haut-parleur que l’utilisateur a sélectionné et restaure cette sélection dans une session ultérieure.

Le membre vt de la structure PROPVARIANT est défini sur VT_LPWSTR.

Le membre pwszVal de la structure PROPVARIANT pointe vers une chaîne à caractères larges null qui contient l’identificateur stable de l’appareil de point de terminaison audio. Si le point de terminaison n’a pas d’ID stable, la valeur de la propriété est VT_EMPTY. Tous les points de terminaison ne sont pas garantis pour avoir un ID stable.

Remarques

Traitez la valeur de la propriété comme une chaîne opaque et sensible à la casse et comparez-la de façon sensible à la casse. Ne modifiez pas, normalisez, reconstruisez ou analysez la valeur, et n’extrayez ni ne reposez sur aucune sous-chaîne interne. Le format interne de la chaîne est un détail d’implémentation. Cachez la valeur uniquement pour identifier le même point de terminaison ultérieurement.

Ne traitez pas l’ID stable comme un identificateur immuable pour toutes les caractéristiques de l’appareil. D’autres propriétés de point de terminaison( par exemple, le nom convivial et les caractéristiques de format) peuvent changer pendant que l’ID stable reste le même. Après avoir résolu l’appareil à partir d’un ID stable mis en cache, interrogez à nouveau les propriétés mutables dont dépend votre application.

L’ID stable est plus durable que l’ID de point de terminaison ordinaire, mais il n’est pas garanti de ne jamais changer. Windows tente de le conserver entre les mises à jour du système d’exploitation et du pilote audio. Windows la possibilité de conserver cette valeur dépend du comportement du pilote audio, du microprogramme périphérique, du type de bus (par exemple, USB et Bluetooth) et des informations exposées par le périphérique. Un petit pourcentage de périphériques peut recevoir un ID stable différent après une mise à niveau d’un système d’exploitation ou d’un pilote.

Une application doit gérer chacun des cas suivants :

• La valeur de la propriété est VT_EMPTY.
• La lecture du magasin de propriétés échoue.
• Un ID stable mis en cache ne se résout plus en point de terminaison via IMMDeviceEnumerator ::GetDevice.

Récupération de l’ID stable

Pour récupérer l’ID stable du point de terminaison sélectionné par l’utilisateur, procédez comme suit :

1. Commencez par une interface IMMDevice pour le point de terminaison sélectionné.
2. Appelez la méthode IMMDevice ::OpenPropertyStore avec l’indicateur STGM_READ.
3. Appelez la méthode IPropertyStore ::GetValue avec la clé de propriété PKEY_AudioEndpoint_StableId.
4. Si le membre vt du PROPVARIANT retourné est VT_LPWSTR, conservez l’intégralité de la chaîne pwszVal .
5. Si la propriété n’est pas disponible ou n’est pas VT_LPWSTR (par exemple, sur une version antérieure de Windows ou lorsque la valeur est VT_EMPTY), vous pouvez éventuellement revenir à IMMDevice ::GetId. Notez que la valeur de secours est moins durable et peut devenir obsolète après les mises à jour du système d’exploitation ou du pilote audio.

L’exemple suivant récupère et conserve l’ID stable.

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

Restauration de l’appareil ultérieurement

Pour restaurer l’appareil dans une session ultérieure, créez un objet MMDeviceEnumerator en appelant CoCreateInstance, puis transmettez la chaîne stable-ID mise en cache en tant qu’argument pwstrId à la méthode IMMDeviceEnumerator ::GetDevice pour récupérer l’interface IMMDevice . Gérez le cas d’échec dans lequel aucun point de terminaison correspondant n’est trouvé.

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

Exigences

Voir aussi

Propriétés du point de terminaison audio

Propriétés audio principales

IMMDevice ::OpenPropertyStore

IMMDeviceEnumerator ::GetDevice

IMMDevice ::GetId

Chaînes d’ID de point de terminaison