ActivateAudioInterfaceAsync function (mmdeviceapi.h)
Enables Windows Store apps to access preexisting Component Object Model (COM) interfaces in the WASAPI family.
HRESULT ActivateAudioInterfaceAsync( [in] LPCWSTR deviceInterfacePath, [in] REFIID riid, [in] PROPVARIANT *activationParams, [in] IActivateAudioInterfaceCompletionHandler *completionHandler, IActivateAudioInterfaceAsyncOperation **activationOperation );
A device interface ID for an audio device. This is normally retrieved from a DeviceInformation object or one of the methods of the MediaDevice class.
The GUIDs DEVINTERFACE_AUDIO_CAPTURE and DEVINTERFACE_AUDIO_RENDER represent the default audio capture and render device respectively. Call StringFromIID to convert either of these GUIDs to an LPCWSTR to use for this argument.
Specify AUDIOCLIENT_ACTIVATION_TYPE_PROCESS_LOOPBACK to activate the audio interface for process loopback capture. For sample code that demonstrates the process loopback capture scenario, see the Application Loopback API Capture Sample.
The IID of a COM interface in the WASAPI family, such as IAudioClient.
Interface-specific activation parameters. For more information, see the pActivationParams parameter in IMMDevice::Activate.
Starting with TBD, you can specify AUDIOCLIENT_ACTIVATION_PARAMS to activate the interface to include or exclude audio streams associated with a specified process ID.
An interface implemented by the caller that is called by Windows when the result of the activation procedure is available.
Returns an IActivateAudioInterfaceAsyncOperation interface that represents the asynchronous operation of activating the requested WASAPI interface.
The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.
||The underlying object and asynchronous operation were created successfully.|
||On versions of Windows previous to Windows 10, this error may result if the function is called from an incorrect COM apartment, or if the passed IActivateAudioInterfaceCompletionHandler is not implemented on an agile object (aggregating a free-threaded marshaler).|
This function enables Windows Store apps to activate certain WASAPI COM interfaces after using Windows Runtime APIs in the Windows.Devices and Windows.Media.Devices namespaces to select an audio device.
For many implementations, an application must call this function from the main UI thread to activate a COM interface in the WASAPI family so that the system can show a dialog to the user. The application passes an IActivateAudioInterfaceCompletionHandler callback COM interface through completionHandler. Windows calls a method in the application’s IActivateAudioInterfaceCompletionHandler interface from a worker thread in the COM Multi-threaded Apartment (MTA) when the activation results are available. The application can then call a method in the IActivateAudioInterfaceAsyncOperation interface to retrieve the result code and the requested WASAPI interface. There are some activations that are explicitly safe and therefore don't require that this function be called from the main UI thread. These explicitly safe activations include:
- Calling ActivateAudioInterfaceAsync with a deviceInterfacePath that specifies an audio render device and an riid that specifies the IAudioClient interface.
- Calling ActivateAudioInterfaceAsync with a deviceInterfacePath that specifies an audio render device and an riid that specifies the IAudioEndpointVolume interface.
- Calling ActivateAudioInterfaceAsync from a session 0 service. For more information, see Services.
Applications must not free the object implementing the IActivateAudioInterfaceCompletionHandler until the completion handler callback has executed.
ActivateAudioInterfaceAsync must be called on the main UI thread so that the consent prompt can be shown. If the consent prompt can’t be shown, the user can’t grant device access to the app.
On versions of Windows previous to Windows 10, ActivateAudioInterfaceAsync must be called on a thread in a COM Single-Threaded Apartment (STA), when opening a device for audio capture. The completionHandler that is passed into ActivateAudioInterfaceAsync needs to implement IAgileObject to ensure that there is no deadlock when the completionHandler is called from the MTA. Otherwise, an E_ILLEGAL_METHOD_CALL will occur.
|Minimum supported client||Windows 8 [desktop apps | UWP apps]|
|Minimum supported server||Windows Server 2012 [desktop apps | UWP apps]|
|Header||mmdeviceapi.h (include Mmdevapi.idl)|