PKEY_AudioEndpoint_StableId

Die PKEY_AudioEndpoint_StableId-Eigenschaft stellt einen zusätzlichen, undurchsichtigen Bezeichner für einen Audioendpunkt dar. Windows versucht, diesen Bezeichner über Betriebssystemupdates und Audiotreiberupdates hinweg beizubehalten.

Die normale Endpunkt-ID, die von IMMDevice::GetId zurückgegeben wird, ist nicht stabil. Ein Betriebssystemupdate oder ein Audiotreiberupdate kann dazu führen, dass demselben physischen Peripheriegerät eine andere Endpunkt-ID zugewiesen wird. Daher kann eine App die normale Endpunkt-ID nicht verwenden, um einen physischen Audioendpunkt zuverlässig nachzuverfolgen. Die PKEY_AudioEndpoint_StableId-Eigenschaft kann verwendet werden, wenn verfügbar, um einen physischen Audioendpunkt nachzuverfolgen. Ein Beispielszenario ist eine Kommunikations-App, die sich an das Mikrofon oder den Lautsprecher erinnert, das der Benutzer ausgewählt und diese Auswahl in einer späteren Sitzung wiederhergestellt hat.

Das vt-Element der PROPVARIANT-Struktur wird auf VT_LPWSTR festgelegt.

Das pwszVal-Element der PROPVARIANT-Struktur verweist auf eine null-beendete, breite Zeichenfolge, die den stabilen Bezeichner für das Audioendpunktgerät enthält. Wenn der Endpunkt keine stabile ID aufweist, wird der Eigenschaftswert VT_EMPTY. Nicht jeder Endpunkt ist garantiert über eine stabile ID verfügen.

Hinweise

Behandeln Sie den Eigenschaftswert als undurchsichtige, groß-bezogene Zeichenfolge, und vergleichen Sie die Groß-/Kleinschreibung. Ändern Sie den Wert nicht, normalisieren, rekonstruieren oder analysieren Sie den Wert, und extrahieren oder verlassen Sie sich nicht auf eine interne Teilzeichenfolge. Das interne Format der Zeichenfolge ist ein Implementierungsdetails. Speichern Sie den Wert nur zwischen, um denselben Endpunkt später erneut zu identifizieren.

Behandeln Sie die stabile ID nicht als unveränderlichen Bezeichner für alle Merkmale des Geräts. Andere Endpunkteigenschaften , z. B. der Anzeigename und die Formatmerkmale, können sich ändern, während die stabile ID unverändert bleibt. Nachdem Sie das Gerät aus einer zwischengespeicherten stabilen ID aufgelöst haben, fragen Sie alle veränderbaren Eigenschaften, von denen Ihre App abhängt, erneut ab.

Die stabile ID ist langlebiger als die normale Endpunkt-ID, aber es wird nicht garantiert, dass sie nie geändert wird. Windows versucht, sie über Betriebssystem- und Audiotreiberupdates hinweg beizubehalten. die Fähigkeit Windows, diesen Wert beizubehalten, hängt vom Verhalten des Audiotreibers, der Peripheriefirmware, dem Bustyp (z. B. USB und Bluetooth) und den Informationen ab, die das Peripheriegerät verfügbar macht. Ein kleiner Prozentsatz der Peripheriegeräte erhält möglicherweise eine andere stabile ID nach einem Betriebssystem- oder Treiberupgrade.

Eine App muss jeden der folgenden Fälle behandeln:

• Der Eigenschaftswert ist VT_EMPTY.
• Fehler beim Lesen des Eigenschaftenspeichers.
• Eine zwischengespeicherte stabile ID wird nicht mehr über IMMDeviceEnumerator::GetDevice zu einem Endpunkt aufgelöst.

Abrufen der stabilen ID

Gehen Sie wie folgt vor, um die stabile ID für den vom Benutzer ausgewählten Endpunkt abzurufen:

1. Beginnen Sie mit einer IMMDevice-Schnittstelle für den ausgewählten Endpunkt.
2. Rufen Sie die IMMDevice::OpenPropertyStore-Methode mit dem STGM_READ-Flag auf.
3. Rufen Sie die IPropertyStore::GetValue-Methode mit dem PKEY_AudioEndpoint_StableId-Eigenschaftsschlüssel auf.
4. Wenn das vt-Element des zurückgegebenen PROPVARIANT-Elements VT_LPWSTR ist, speichern Sie die gesamte pwszVal-Zeichenfolge .
5. Wenn die Eigenschaft nicht verfügbar ist oder nicht VT_LPWSTR ist (z. B. bei einer älteren Version von Windows oder wenn der Wert VT_EMPTY ist), können Sie optional auf IMMDevice::GetId zurückgreifen. Beachten Sie, dass der Fallbackwert weniger langlebig ist und nach Updates des Betriebssystems oder des Audiotreibers veraltet werden kann.

Im folgenden Beispiel wird die stabile ID abgerufen und beibehalten.

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

Wiederherstellen des Geräts später

Um das Gerät in einer späteren Sitzung wiederherzustellen, erstellen Sie ein MMDeviceEnumerator-Objekt durch Aufrufen von CoCreateInstance, und übergeben Sie dann die zwischengespeicherte Stable-ID-Zeichenfolge als pwstrId-Argument an die IMMDeviceEnumerator::GetDevice-Methode , um die IMMDevice-Schnittstelle zurück abzurufen. Behandeln Sie den Fehlerfall, in dem kein übereinstimmenden Endpunkt gefunden wird.

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

Anforderungen

Siehe auch

Audioendpunkteigenschaften

Kernaudioeigenschaften

IMMDevice::OpenPropertyStore

IMMDeviceEnumerator::GetDevice

IMMDevice::GetId

Endpunkt-ID-Zeichenfolgen