PKEY_AudioEndpoint_StableId

La proprietà PKEY_AudioEndpoint_StableId fornisce un identificatore opaco aggiuntivo per un endpoint audio. Windows tenta di mantenere questo identificatore tra gli aggiornamenti del sistema operativo e gli aggiornamenti dei driver audio.

L'ID endpoint ordinario restituito da IMMDevice::GetId non è stabile. Un aggiornamento del sistema operativo o un aggiornamento del driver audio può causare l'assegnazione della stessa periferica fisica a un ID endpoint diverso. Di conseguenza, un'app non può usare l'ID endpoint ordinario per tenere traccia in modo affidabile di un endpoint audio fisico. La proprietà PKEY_AudioEndpoint_StableId , se disponibile, può essere usata per tenere traccia di un endpoint audio fisico. Uno scenario di esempio è un'app per le comunicazioni che ricorda il microfono o l'altoparlante selezionato dall'utente e ripristina la selezione in una sessione successiva.

Il membro vt della struttura PROPVARIANT è impostato su VT_LPWSTR.

Il membro pwszVal della struttura PROPVARIANT punta a una stringa di caratteri wide con terminazione Null che contiene l'identificatore stabile per il dispositivo endpoint audio. Se l'endpoint non ha un ID stabile, il valore della proprietà viene VT_EMPTY. Non tutti gli endpoint hanno un ID stabile.

Osservazioni:

Considerare il valore della proprietà come stringa opaca, con distinzione tra maiuscole e minuscole e confrontarlo con distinzione tra maiuscole e minuscole. Non modificare, normalizzare, ricostruire o analizzare il valore e non estrarre o fare affidamento su alcuna sottostringa interna. Il formato interno della stringa è un dettaglio di implementazione. Memorizzare nella cache il valore solo per identificare nuovamente lo stesso endpoint in un secondo momento.

Non considerare l'ID stabile come identificatore non modificabile per tutte le caratteristiche del dispositivo. Altre proprietà dell'endpoint, ad esempio il nome descrittivo e le caratteristiche di formato, possono cambiare mentre l'ID stabile rimane invariato. Dopo aver risolto il dispositivo da un ID stabile memorizzato nella cache, eseguire nuovamente una query su eventuali proprietà modificabili da cui dipende l'app.

L'ID stabile è più durevole dell'ID endpoint ordinario, ma non è garantito che non cambi mai. Windows tenta di conservarlo tra gli aggiornamenti del sistema operativo e dei driver audio. Windows'abilità di mantenere questo valore dipende dal comportamento del driver audio, dal firmware periferico, dal tipo di bus (ad esempio USB e Bluetooth) e dalle informazioni esposte dalla periferica. Una piccola percentuale di periferiche potrebbe ricevere un ID stabile diverso dopo un aggiornamento del sistema operativo o del driver.

Un'app deve gestire ognuno dei casi seguenti:

• Il valore della proprietà è VT_EMPTY.
• La lettura dell'archivio delle proprietà ha esito negativo.
• Un ID stabile memorizzato nella cache non viene più risolto in un endpoint tramite IMMDeviceEnumerator::GetDevice.

Recupero dell'ID stabile

Per recuperare l'ID stabile per l'endpoint selezionato dall'utente, eseguire le operazioni seguenti:

1. Iniziare con un'interfaccia IMMDevice per l'endpoint selezionato.
2. Chiamare il metodo IMMDevice::OpenPropertyStore con il flag STGM_READ.
3. Chiamare il metodo IPropertyStore::GetValue con la chiave della proprietà PKEY_AudioEndpoint_StableId.
4. Se il membro vt dell'oggetto PROPVARIANT restituito è VT_LPWSTR, rendere persistente l'intera stringa pwszVal .
5. Se la proprietà non è disponibile o non è VT_LPWSTR (ad esempio, in una versione precedente di Windows o quando il valore è VT_EMPTY), è possibile eseguire facoltativamente il fallback a IMMDevice::GetId. Si noti che il valore di fallback è meno durevole e può diventare obsoleto dopo gli aggiornamenti del sistema operativo o del driver audio.

Nell'esempio seguente viene recuperato e salvato in modo permanente l'ID stabile.

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

Ripristino del dispositivo in un secondo momento

Per ripristinare il dispositivo in una sessione successiva, creare un oggetto MMDeviceEnumerator chiamando CoCreateInstance e quindi passare la stringa stable-ID memorizzata nella cache come argomento pwstrId al metodo IMMDeviceEnumerator::GetDevice per ottenere nuovamente l'interfaccia IMMDevice . Gestire il caso di errore in cui non viene trovato alcun endpoint corrispondente.

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

Vedere anche

Proprietà dell'endpoint audio

Proprietà audio principali

IMMDevice::OpenPropertyStore

IMMDeviceEnumerator::GetDevice

IMMDevice::GetId

Stringhe ID endpoint