ActivateAudioInterfaceAsync function

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

Syntax

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

Parameters

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.

riid

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

activationParams

Interface-specific activation parameters. For more information, see the pActivationParams parameter in IMMDevice::Activate.

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

An application must call this function from the main UI thread to activate a COM interface in the WASAPI family. 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.

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.

ActivateAudioInterfaceAsync must be called on a thread in a COM Single-Threaded Apartment (STA). 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

   
Windows version Windows 8 [desktop apps | UWP apps] Windows Server 2012 [desktop apps | UWP apps]
Target Platform Windows
Header mmdeviceapi.h (include Mmdevapi.idl)
Library Mmdevapi.lib
DLL Mmdevapi.dll
IRQL No

See Also

Core Audio Functions

IActivateAudioInterfaceAsyncOperation

IActivateAudioInterfaceCompletionHandler