ActivateAudioInterfaceAsync 函数 (mmdeviceapi.h)

  • 项目

使 Windows 应用商店应用能够访问 WASAPI 系列中预先存在的组件对象模型 (COM) 接口。

语法

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

parameters

[in] deviceInterfacePath

音频设备的设备接口 ID。 这通常是从 DeviceInformation 对象或 MediaDevice 类的方法之一检索的。

DEVINTERFACE_AUDIO_CAPTURE和DEVINTERFACE_AUDIO_RENDER GUID 分别表示默认音频捕获和呈现设备。 调用 StringFromIID 将任一 GUID 转换为要用于此参数的 LPCWSTR 。

指定 AUDIOCLIENT_ACTIVATION_TYPE_PROCESS_LOOPBACK 以激活进程环回捕获的音频接口。 有关演示进程环回捕获方案的示例代码，请参阅 应用程序环回 API 捕获示例。

[in] riid

WASAPI 系列中 COM 接口的 IID，例如 IAudioClient。

[in] activationParams

特定于接口的激活参数。 有关详细信息，请参阅 IMMDevice：：Activate 中的 pActivationParams 参数。

从 TBD 开始，可以指定 AUDIOCLIENT_ACTIVATION_PARAMS 激活接口，以包含或排除与指定进程 ID 关联的音频流。

[in] completionHandler

当激活过程的结果可用时，由 Windows 调用的调用方实现的接口。

activationOperation

返回一个 IActivateAudioInterfaceAsyncOperation 接口，该接口表示激活请求的 WASAPI 接口的异步操作。

返回值

函数返回 HRESULT。 可能的值包括（但并不限于）下表中的项。

返回代码 说明
S_OK
 已成功创建基础对象和异步操作。
E_ILLEGAL_METHOD_CALL
在以前Windows 10的 Windows 版本中，如果从错误的 COM 单元调用函数，或者传递的 IActivateAudioInterfaceCompletionHandler 未在敏捷对象上实现， (聚合自由线程封送处理程序) ，则可能会导致此错误。

注解

此函数使 Windows 应用商店应用能够在使用 Windows.Devices 和 Windows.Media.Devices 命名空间中的Windows 运行时 API 来选择音频设备后激活某些 WASAPI COM 接口。

对于许多实现，应用程序必须从main UI 线程调用此函数，以激活 WASAPI 系列中的 COM 接口，以便系统可以向用户显示对话框。 应用程序通过 completionHandler 传递 IActivateAudioInterfaceCompletionHandler 回调 COM 接口。 当激活结果可用时，Windows 从 COM 多线程单元 (MTA) 的工作线程调用应用程序的 IActivateAudioInterfaceCompletionHandler 接口中的方法。 然后，应用程序可以在 IActivateAudioInterfaceAsyncOperation 接口中调用方法，以检索结果代码和请求的 WASAPI 接口。 某些激活是显式安全的，因此不需要从main UI 线程调用此函数。 这些显式安全的激活包括：

  • 使用指定音频呈现设备的 deviceInterfacePath 和指定 IAudioClient 接口的 riid 调用 ActivateAudioInterfaceAsync。
  • 使用指定音频呈现设备的 deviceInterfacePath 和指定 IAudioEndpointVolume 接口的 riid 调用 ActivateAudioInterfaceAsync。
  • 从会话 0 服务调用 ActivateAudioInterfaceAsync 。 有关详细信息，请参阅 服务。
Windows 保留对应用程序的 IActivateAudioInterfaceCompletionHandler 接口的引用，直到操作完成并且应用程序释放 IActivateAudioInterfaceAsyncOperation 接口。
重要说明  

在完成处理程序回调执行之前，应用程序不得释放实现 IActivateAudioInterfaceCompletionHandler 的对象。

 
根据激活的 WASAPI 接口，此函数可能会在首次调用时显示同意提示。 例如，当应用程序调用此函数以激活 IAudioClient 以访问麦克风时，同意提示的目的是获取应用访问麦克风的用户权限。 有关同意提示的详细信息，请参阅 访问个人数据的设备指南。

必须在main UI 线程上调用 ActivateAudioInterfaceAsync，以便显示同意提示。 如果无法显示同意提示，则用户无法授予设备对应用的访问权限。

在 Windows 10 之前的 Windows 版本中，打开设备进行音频捕获时，必须在 COM Single-Threaded 单元 (STA) 的线程上调用 ActivateAudioInterfaceAsync。 传递到 ActivateAudioInterfaceAsync 的 completionHandler 需要实现 IAgileObject，以确保从 MTA 调用 completionHandler 时没有死锁。 否则，将发生 E_ILLEGAL_METHOD_CALL 。

要求

   
最低受支持的客户端 Windows 8 [桌面应用 |UWP 应用]
最低受支持的服务器 Windows Server 2012 [桌面应用 |UWP 应用]
目标平台 Windows
标头 mmdeviceapi.h (包括 Mmdevapi.idl)
Library Mmdevapi.lib
DLL Mmdevapi.dll
IRQL 否

另请参阅

核心音频函数

IActivateAudioInterfaceAsyncOperation

IActivateAudioInterfaceCompletionHandler