ActivateAudioInterfaceAsync-Funktion (mmdeviceapi.h)

Ermöglicht Windows Store-Apps den Zugriff auf bereits vorhandene COM-Schnittstellen (Component Object Model) in der WASAPI-Familie .

Syntax

HRESULT ActivateAudioInterfaceAsync(
  [in] LPCWSTR                                  deviceInterfacePath,
  [in] REFIID                                   riid,
  [in] PROPVARIANT                              *activationParams,
  [in] IActivateAudioInterfaceCompletionHandler *completionHandler,
       IActivateAudioInterfaceAsyncOperation    **activationOperation
);

Parameter

[in] deviceInterfacePath

Eine Geräteschnittstellen-ID für ein Audiogerät. Dies wird normalerweise von einem DeviceInformation-Objekt oder einer der Methoden der MediaDevice-Klasse abgerufen.

Die GUIDs DEVINTERFACE_AUDIO_CAPTURE und DEVINTERFACE_AUDIO_RENDER stellen die Standardaudioaufnahme bzw. das Rendergerät dar. Rufen Sie StringFromIID auf, um eine dieser GUIDs in einen LPCWSTR zu konvertieren, der für dieses Argument verwendet werden soll.

Geben Sie VIRTUAL_AUDIO_DEVICE_PROCESS_LOOPBACK an, um die Audioschnittstelle für die Prozessschleifenaufnahme zu aktivieren. Beispielcode, der das Prozessschleifenerfassungsszenario veranschaulicht, finden Sie im Beispiel zur Anwendungsschleifen-API-Erfassung.

[in] riid

Die IID einer COM-Schnittstelle in der WASAPI-Familie , z. B. IAudioClient.

[in] activationParams

Schnittstellenspezifische Aktivierungsparameter. Weitere Informationen finden Sie im Parameter "pActivationParams " in IMMDevice::Activate.

Ab Windows 10 Build 20438 können Sie AUDIOCLIENT_ACTIVATION_PARAMS angeben, um die Schnittstelle zu aktivieren, um Audiodatenströme einzuschließen oder auszuschließen, die einer angegebenen Prozess-ID zugeordnet sind.

[in] completionHandler

Eine Schnittstelle, die vom Aufrufer implementiert wird, der von Windows aufgerufen wird, wenn das Ergebnis der Aktivierungsprozedur verfügbar ist.

activationOperation

Gibt eine IActivateAudioInterfaceAsyncOperation-Schnittstelle zurück, die den asynchronen Vorgang der Aktivierung der angeforderten WASAPI-Schnittstelle darstellt.

Rückgabewert

Die Funktion gibt ein HRESULT zurück. Mögliche Werte sind die Werte in der folgenden Tabelle, sind jedoch nicht beschränkt.

Rückgabecode	Beschreibung
S_OK	Das zugrunde liegende Objekt und der asynchrone Vorgang wurden erfolgreich erstellt.
E_ILLEGAL_METHOD_CALL	In Versionen von Windows vor Windows 10 kann dieser Fehler auftreten, wenn die Funktion von einem falschen COM-Apartment aufgerufen wird oder wenn der übergebene IActivateAudioInterfaceCompletionHandler nicht für ein agiles Objekt implementiert ist (aggregieren eines Freethreaded Marshalers).

Bemerkungen

Mit dieser Funktion können Windows Store-Apps bestimmte WASAPI-COM-Schnittstellen aktivieren, nachdem Sie Windows-Runtime-APIs in den Namespaces "Windows.Devices " und "Windows.Media.Devices " verwendet haben, um ein Audiogerät auszuwählen.

Für viele Implementierungen muss eine Anwendung diese Funktion aus dem Haupt-UI-Thread aufrufen, um eine COM-Schnittstelle in der WASAPI-Familie zu aktivieren, damit das System dem Benutzer ein Dialogfeld anzeigen kann. Die Anwendung übergibt eine IActivateAudioInterfaceCompletionHandler-Callback-COM-Schnittstelle über den CompletionHandler. Windows ruft eine Methode in der IActivateAudioInterfaceCompletionHandler-Schnittstelle der Anwendung aus einem Arbeitsthread im COM Multithreaded Apartment (MTA) auf, wenn die Aktivierungsergebnisse verfügbar sind. Die Anwendung kann dann eine Methode in der IActivateAudioInterfaceAsyncOperation-Schnittstelle aufrufen, um den Ergebniscode und die angeforderte WASAPI-Schnittstelle abzurufen. Es gibt einige Aktivierungen, die explizit sicher sind und daher nicht erfordern, dass diese Funktion aus dem Haupt-UI-Thread aufgerufen wird. Zu diesen explizit sicheren Aktivierungen gehören:

• Aufrufen von ActivateAudioInterfaceAsync mit einem deviceInterfacePath-Gerät , das ein Audiowiedergabegerät und eine Riid angibt, die die IAudioClient-Schnittstelle angibt.
• Aufrufen von ActivateAudioInterfaceAsync mit einem deviceInterfacePath-Gerät , das ein Audiorendergerät und eine Riid angibt, die die IAudioEndpointVolume-Schnittstelle angibt.
• Aufrufen von ActivateAudioInterfaceAsync aus einem Sitzungs-0-Dienst. Weitere Informationen finden Sie unter "Dienste".

Windows enthält einen Verweis auf die IActivateAudioInterfaceCompletionHandler-Schnittstelle der Anwendung, bis der Vorgang abgeschlossen ist und die Anwendung die IActivateAudioInterfaceAsyncOperation-Schnittstelle freigibt.

Wichtig  

Anwendungen dürfen das Objekt, das den IActivateAudioInterfaceCompletionHandler implementiert, erst freigeben, wenn der Abschlusshandlerrückruf ausgeführt wurde.

 

Je nachdem, welche WASAPI-Schnittstelle aktiviert ist, zeigt diese Funktion möglicherweise eine Zustimmungsaufforderung an, wenn sie zum ersten Mal aufgerufen wird. Wenn die Anwendung diese Funktion beispielsweise aufruft, um IAudioClient für den Zugriff auf ein Mikrofon zu aktivieren, besteht der Zweck der Zustimmungsaufforderung darin, die Berechtigung des Benutzers für den Zugriff auf das Mikrofon zu erhalten. Weitere Informationen zur Zustimmungsaufforderung finden Sie unter Richtlinien für Geräte, die auf personenbezogene Daten zugreifen.

ActivateAudioInterfaceAsync muss im Haupt-UI-Thread aufgerufen werden, damit die Zustimmungsaufforderung angezeigt werden kann. Wenn die Zustimmungsaufforderung nicht angezeigt werden kann, kann der Benutzer der App keinen Gerätezugriff gewähren.

In Versionen von Windows vor Windows 10 muss ActivateAudioInterfaceAsync für einen Thread in einem COM-Single-Threaded Apartment (STA) aufgerufen werden, wenn ein Gerät für die Audioaufnahme geöffnet wird. Der completionHandler , der an ActivateAudioInterfaceAsync übergeben wird, muss IAgileObject implementieren, um sicherzustellen, dass kein Deadlock vorhanden ist, wenn der CompletionHandler vom MTA aufgerufen wird. Andernfalls tritt ein E_ILLEGAL_METHOD_CALL auf.

Anforderungen

Anforderung	Wert
Mindestens unterstützter Client	Windows 8 [Desktop-Apps | UWP-Apps]
Mindestens unterstützter Server	Windows Server 2012 [Desktop-Apps | UWP-Apps]
Zielplattform	Fenster
Kopfball	mmdeviceapi.h (enthalten Mmdevapi.idl)
Bibliothek	Mmdevapi.lib
DLL	Mmdevapi.dll
IRQL	Nein

Siehe auch

Kernaudiofunktionen

IActivateAudioInterfaceAsyncOperation

IActivateAudioInterfaceCompletionHandler