ActivateAudioInterfaceAsync function (mmdeviceapi.h)

Article
10/13/2021

Enables Windows Store apps to access preexisting Component Object Model (COM) interfaces in the WASAPI family.

Syntax

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

Parameters

[in] deviceInterfacePath

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.

[in] riid

The IID of a COM interface in the WASAPI family, such as IAudioClient.

[in] activationParams

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.

[in] completionHandler

An interface implemented by the caller that is called by Windows when the result of the activation procedure is available.

activationOperation

Returns an IActivateAudioInterfaceAsyncOperation interface that represents the asynchronous operation of activating the requested WASAPI interface.

Return value

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	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).

Remarks

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.

Windows holds a reference to the application's IActivateAudioInterfaceCompletionHandler interface until the operation is complete and the application releases the IActivateAudioInterfaceAsyncOperation interface.

Important

Applications must not free the object implementing the IActivateAudioInterfaceCompletionHandler until the completion handler callback has executed.

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 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 devices that access personal data.

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.

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2012 [desktop apps \| UWP apps]
Target Platform	Windows
Header	mmdeviceapi.h (include Mmdevapi.idl)
Library	Mmdevapi.lib
DLL	Mmdevapi.dll
IRQL	No