Enables apps to access existing Component Object Model (COM) interfaces in the WASAPI family.
HRESULT ActivateAudioInterfaceAsync(
LPCWSTR deviceInterfacePath,
REFIID riid,
PROPVARIANT *activationParams,
IActivateAudioInterfaceCompletionHandler *completionHandler,
IActivateAudioInterfaceAsyncOperation **activationOperation
)
deviceInterfacePath
Type: LPCWSTR
[in] 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.
On Xbox One the Audio Device ID can be entered for this parameter. Refer to the IAudioDeviceInfo class.
riid
Type: REFIID
[in] The IID of a Component Object Model (COM) interface in the WASAPI family, such as IAudioClient, or the Widnows Sonic interface, ISpatialAudioClient.
activationParams
Type: PROPVARIANT *
[in, optional] Interface-specific activation parameters.
For more information, see the pActivationParams parameter in IMMDevice::Activate.
completionHandler
Type: IActivateAudioInterfaceCompletionHandler *
[in] An interface implemented by the caller that is called by Windows when the result of the activation procedure is available.
activationOperation
Type: IActivateAudioInterfaceAsyncOperation **
[out] Pointer to a pointer to the activated asynchronous opertation.
Type: HRESULT
The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.
| Return code | Description |
|---|---|
| S_OK | The underlying object and asynchronous operation were created successfully. |
| E_ILLEGAL_METHOD_CALL | This error may result if the function is called from an incorrect Component Object Model (COM) apartment, or if the passed IActivateAudioInterfaceCompletionHandler is not implemented on an agile object (aggregating a free-threaded marshaler). |
| E_NOINTERFACE | ActivateAudioInterface was called with IID_ISpatialAudioClient specified without calling EnableSpatialAudio. |
Refer to WASAPI error codes.
This function enables apps to activate certain WASAPI Component Object Model (COM) interfaces after using Windows Runtime APIs in the Windows.Devices and Windows.Media.Devices namespaces to select an audio device.
An application must call this function from the main UI thread to activate a Component Object Model (COM) interface in the WASAPI family. The application passes an IActivateAudioInterfaceCompletionHandler callback Component Object Model (COM) interface through completionHandler. Windows calls a method in the application’s IActivateAudioInterfaceCompletionHandler interface from a worker thread in the Component Object Model (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.
Windows holds a reference to the application’s IActivateAudioInterfaceCompletionHandler interface until the operation is complete and the application releases the IActivateAudioInterfaceAsyncOperation interface.
Depending on which WASAPI interface is activated, this function may display a consent prompt the first time it is called. For example, when the application calls this function to activate a IAudioClient to access a microphone, the purpose of the consent prompt is to get the user’s permission for the app to access the microphone. For more information about the consent prompt, see Guidelines for using sensitive devices.
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.
ActivateAudioInterfaceAsync must be called on a thread in a Component Object Model (COM) Single-Threaded Apartment (STA). Calls from a thread on the Component Object Model (COM) MTA will result in an error code of E_ILLEGAL_METHOD_CALL.
Header: Declared in mmdeviceapi.h.
Library: Use MMDevApi.lib.