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 jeweils das Standardgerät für Audioaufnahme und -render dar. Rufen Sie StringFromIID auf, um eine dieser GUIDs in eine LPCWSTR zu konvertieren, die für dieses Argument verwendet werden soll.
Geben Sie AUDIOCLIENT_ACTIVATION_TYPE_PROCESS_LOOPBACK an, um die Audioschnittstelle für die Prozessschleifebackerfassung zu aktivieren. Beispielcode, der das Prozessschleifebackerfassungsszenario veranschaulicht, finden Sie im Beispiel zur Anwendungsschleifeback-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 pActivationParams-Parameter in IMMDevice::Activate.
Ab TBD können Sie angeben, AUDIOCLIENT_ACTIVATION_PARAMS zum Aktivieren der Schnittstelle zum Ein- oder Ausschließen von Audiodatenströmen, die einer angegebenen Prozess-ID zugeordnet sind.
[in] completionHandler
Eine vom Aufrufer implementierte Schnittstelle, die 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ögliches Werte (aber nicht die Einzigen) sind die in der folgenden Tabelle.
| Rückgabecode | BESCHREIBUNG |
|---|---|
|
Das zugrunde liegende Objekt und der asynchrone Vorgang wurden erfolgreich erstellt. |
|
Bei Windows-Versionen 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 Freethread-Marshallers). |
Hinweise
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 zum Auswählen eines Audiogeräts verwendet haben.
Bei vielen Implementierungen muss eine Anwendung diese Funktion aus dem Standard 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-Rückruf-COM-Schnittstelle über completionHandler. Windows ruft eine Methode in der IActivateAudioInterfaceCompletionHandler-Schnittstelle der Anwendung aus einem Workerthread im COM Multi-Threaded 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 über den Standard UI-Thread aufgerufen wird. Zu diesen explizit sicheren Aktivierungen gehören:
- Aufrufen von ActivateAudioInterfaceAsync mit einem deviceInterfacePath , das ein Audiorendergerät und eine riid angibt, die die IAudioClient-Schnittstelle angibt.
- Aufrufen von ActivateAudioInterfaceAsync mit einem deviceInterfacePath , das ein Audiorendergerät und eine riid angibt, die die IAudioEndpointVolume-Schnittstelle angibt.
- Aufrufen von ActivateAudioInterfaceAsync über einen Sitzung 0-Dienst. Weitere Informationen finden Sie unter Dienste.
Anwendungen dürfen das Objekt, das den IActivateAudioInterfaceCompletionHandler implementiert, erst freigeben, wenn der Rückruf des Vervollständigungshandlers ausgeführt wurde.
ActivateAudioInterfaceAsync muss im Standard UI-Thread aufgerufen werden, damit die Zustimmungsaufforderung angezeigt werden kann. Wenn die Zustimmungsaufforderung nicht angezeigt werden kann, kann der Benutzer dem Benutzer keinen Gerätezugriff auf die App gewähren.
In Windows-Versionen vor Windows 10 muss ActivateAudioInterfaceAsync in einem 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 es kein Deadlock gibt, wenn der CompletionHandler vom MTA aufgerufen wird. Andernfalls tritt eine E_ILLEGAL_METHOD_CALL auf.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows 8 [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2012 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | mmdeviceapi.h (include Mmdevapi.idl) |
| Bibliothek | Mmdevapi.lib |
| DLL | Mmdevapi.dll |
| IRQL | Nein |