0 out of 3 rated this helpful - Rate this topic

ActivateAudioInterfaceAsync function

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

Syntax


HRESULT WINAPI ActivateAudioInterfaceAsync(
  _In_  LPCWSTR deviceInterfacePath,
  _In_  REFIID riid,
  _In_  PROPVARIANT *activationParams,
  _In_  IActivateAudioInterfaceCompletionHandler *completionHandler,
  _COM_Outptr_ IActivateAudioInterfaceAsyncOperation **createAsync
);

Parameters

deviceInterfacePath [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.
riid [in]: The IID of a COM interface in the WASAPI family, such as IAudioClient.
activationParams [in]: Interface-specific activation parameters. For more information, see the pActivationParams parameter in IMMDevice::Activate.
completionHandler [in]: An interface implemented by the caller that is called by Windows when the result of the activation procedure is available.
createAsync: 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.

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 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 COM Single-Threaded Apartment (STA). Calls from a thread on the COM MTA will result in an error code of E_ILLEGAL_METHOD_CALL.

Requirements

Minimum supported client	Windows 8 [desktop apps \| Windows Store apps]
Minimum supported server	Windows Server 2012 [desktop apps \| Windows Store apps]
Header	Mmdevapi.idl
Library	Mmdevapi.lib
DLL	Mmdevapi.dll
IRQL	No

Community Additions

ADD