IMMDeviceEnumerator：：GetDefaultAudioEndpoint 方法 (mmdeviceapi.h)

  • 项目

GetDefaultAudioEndpoint 方法检索指定数据流方向和角色的默认音频终结点。

语法

HRESULT GetDefaultAudioEndpoint(
  [in]  EDataFlow dataFlow,
  [in]  ERole     role,
  [out] IMMDevice **ppEndpoint
);

参数

[in] dataFlow

终结点设备的数据流方向。 调用方应将此参数设置为以下两个 EDataFlow 枚举值之一：

eRender

eCapture

呈现设备的数据流方向为 eRender。 捕获设备的数据流方向为 eCapture。

[in] role

终结点设备的角色。 调用方应将此参数设置为以下 ERole 枚举值之一：

eConsole

eMultimedia

eCommunications

有关详细信息，请参阅“备注”。

[out] ppEndpoint

指向指针变量的指针，方法在其中写入默认音频终结点设备的终结点对象的 IMMDevice 接口的地址。 通过此方法，调用方获取对 接口的计数引用。 调用方负责在不再需要接口时通过调用接口的 Release 方法释放接口。 如果 GetDefaultAudioEndpoint 调用失败， 则 *ppDevice 为 NULL。

返回值

如果该方法成功，则它会返回 S_OK。 如果失败，可能的返回代码包括但不限于下表中显示的值。

返回代码 说明
E_POINTER
 参数 ppDevice 为 NULL。
E_INVALIDARG
 参数 数据流 或 角色 在范围外。
E_NOTFOUND
 没有可用的设备。
E_OUTOFMEMORY
 内存不足。

注解

注意

在 Windows Vista 中，MMDevice API 支持 设备角色 ，但系统提供的用户界面程序不支持。 Windows Vista 中的用户界面使用户能够选择用于呈现的默认音频设备和用于捕获的默认音频设备。 当用户更改默认呈现或捕获设备时，系统会将 eConsole、eMultimedia 和 eCommunications () 的所有三个设备角色分配给该设备。 因此， GetDefaultAudioEndpoint 始终选择默认呈现或捕获设备，而不管 角色 参数指示哪个角色。 在 Windows 的未来版本中，用户界面可能使用户能够将各个角色分配给不同的设备。 在这种情况下， GetDefaultAudioEndpoint 选择呈现或捕获设备可能取决于 角色 参数。 因此，在将来的 Windows 版本中运行时，开发为在 Windows Vista 中运行的音频应用程序的行为可能会更改。 有关详细信息，请参阅 Windows Vista 中的设备角色。

此方法检索指定数据流方向的默认终结点设备， (呈现或捕获) 和角色。 例如，客户端可以通过进行以下调用来获取默认控制台播放设备：


  hr = pDevEnum->GetDefaultAudioEndpoint(
                   eRender, eConsole, &pDeviceOut);

在前面的代码片段中，变量 hr 的类型为 HRESULT，pDevEnum 是指向 IMMDeviceEnumerator 接口的指针，pDeviceOut 是指向 IMMDevice 接口的指针。

Windows 系统可能包含音频终结点设备的某种组合，例如桌面扬声器、高保真耳机、桌面麦克风、带扬声器和麦克风的头戴显示设备以及高保真多声道扬声器。 用户可以向设备分配适当的角色。 例如，管理语音通信流的应用程序可以调用 GetDefaultAudioEndpoint 来标识该角色的指定呈现和捕获设备。

如果只有一个呈现或捕获设备可用，则系统始终将所有三个呈现或捕获角色分配给该设备。 如果 方法无法找到指定角色的呈现或捕获设备，则表示根本没有可用的呈现或捕获设备。 如果没有可用的设备，方法将 设置 *ppEndpoint = NULL 并返回ERROR_NOT_FOUND。

有关调用 GetDefaultAudioEndpoint 方法的代码示例，请参阅以下主题：

要求

要求 值
最低受支持的客户端 Windows Vista [仅限桌面应用]
最低受支持的服务器 Windows Server 2008 [仅限桌面应用]
目标平台 Windows
标头 mmdeviceapi.h

另请参阅

IMMDevice 接口

IMMDeviceEnumerator 接口