IAudioClient：：IsFormatSupported 方法 (audioclient.h)

  • 项目

IsFormatSupported 方法指示音频终结点设备是否支持特定的流格式。

语法

HRESULT IsFormatSupported(
  [in]  AUDCLNT_SHAREMODE  ShareMode,
  [in]  const WAVEFORMATEX *pFormat,
  [out] WAVEFORMATEX       **ppClosestMatch
);

参数

[in] ShareMode

流格式的共享模式。 通过此参数，客户端指示是要在独占模式还是共享模式下使用指定的格式。 客户端应将此参数设置为以下 AUDCLNT_SHAREMODE 枚举值之一：

AUDCLNT_SHAREMODE_EXCLUSIVE

AUDCLNT_SHAREMODE_SHARED

[in] pFormat

指向指定流格式的指针。 此参数指向类型 为 WAVEFORMATEX 或 WAVEFORMATEXTENSIBLE 的调用方分配的格式描述符。 客户端在调用此方法之前将格式说明写入此结构。 有关 WAVEFORMATEX 和 WAVEFORMATEXTENSIBLE 的信息，请参阅 Windows DDK 文档。

[out] ppClosestMatch

指向指针变量的指针，方法在其中写入 WAVEFORMATEX 或 WAVEFORMATEXTENSIBLE 结构的地址。 此结构指定最接近客户端通过 pFormat 参数指定的格式的支持格式。 对于共享模式 (即，如果 ShareMode 参数AUDCLNT_SHAREMODE_SHARED) ，请将 ppClosestMatch 设置为指向有效的非 NULL 指针变量。 对于独占模式，请将 ppClosestMatch 设置为 NULL。 方法为 结构分配存储。 当不再需要存储时，调用方负责通过调用 CoTaskMemFree 函数来释放存储。 如果 IsFormatSupported 调用失败且 ppClosestMatch 为非 NULL，则 方法将 *ppClosestMatch 设置为 NULL。 有关 CoTaskMemFree 的信息，请参阅 Windows SDK 文档。

返回值

返回代码 说明
S_OK
 成功且音频终结点设备支持指定的流格式。
S_FALSE
 与指定格式最接近的匹配项成功。
AUDCLNT_E_UNSUPPORTED_FORMAT
 成功，但在独占模式下不支持指定的格式。
 

如果操作失败，可能的返回代码包括但不限于下表中显示的值。

返回代码 说明
E_POINTER
 参数 pFormat 为 NULL，或 ppClosestMatch 为 NULL，ShareMode 为 AUDCLNT_SHAREMODE_SHARED。
E_INVALIDARG
 参数 ShareMode 是除 AUDCLNT_SHAREMODE_SHARED 或 AUDCLNT_SHAREMODE_EXCLUSIVE 以外的值。
AUDCLNT_E_DEVICE_INVALIDATED
 音频终结点设备已拔出，或者音频硬件或关联的硬件资源已重新配置、禁用、删除或以其他方式不可用。
AUDCLNT_E_SERVICE_NOT_RUNNING
 Windows 音频服务未运行。

注解

此方法为客户端提供了一种在调用 IAudioClient：：Initialize 之前确定音频引擎是否支持特定流格式的方法。

对于独占模式，如果音频终结点设备支持调用方指定的格式， IsFormatSupported 将返回S_OK;如果设备不支持格式，则返回AUDCLNT_E_UNSUPPORTED_FORMAT。 ppClosestMatch 参数可以为 NULL。 如果它不是 NULL，该方法会将 NULL 写入 到 *ppClosestMatch。

对于共享模式，如果音频引擎支持调用方指定的格式， IsFormatSupported 会将 *ppClosestMatch 设置为 NULL 并返回S_OK。 如果音频引擎不支持调用方指定的格式，但支持类似的格式，该方法将通过 ppClosestMatch 参数检索类似的格式，并返回S_FALSE。 如果音频引擎不支持调用方指定的格式或任何类似的格式，则 方法将 *ppClosestMatch 设置为 NULL 并返回AUDCLNT_E_UNSUPPORTED_FORMAT。

在共享模式下，音频引擎始终支持混合格式，客户端可以通过调用 IAudioClient：：GetMixFormat 方法获取该格式。 此外，音频引擎可能支持与混合格式具有相同采样率和通道数但音频样本值的表示形式不同的类似格式。 音频引擎在内部将样本值表示为浮点数，但如果调用方指定的格式将样本值表示为整数，则音频引擎通常可以在整数样本值与其内部浮点表示形式之间进行转换。

如果音频设备的安装包包含本地效果 (LFX) 音频处理对象， (可以处理格式转换的 APO) ，则音频引擎可能能够支持更广泛的共享模式格式。 LFX APO 是一个软件模块，用于对音频流执行特定于设备的处理。 Windows 音频服务中的音频图形生成器将 LFX APO 插入到每个客户端和音频引擎之间的流中。 当客户端调用 IsFormatSupported 方法并且 该方法确定已安装 LFX APO 以用于设备时，该方法会将查询定向到 LFX APO，该查询指示它是否支持调用方指定的格式。

例如，特定 LFX APO 可能接受来自客户端的 6 声道环绕声流，并将该流转换为可以通过耳机播放的立体声格式。 通常，LFX APO 仅支持采样率与混合格式的采样率匹配的客户端格式。

有关 ADO 的详细信息，请参阅 Windows 音频处理对象。 有关 IsFormatSupported 方法的详细信息，请参阅 设备格式。

要求

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

另请参阅

IAudioClient 接口

IAudioClient：：GetMixFormat

IAudioClient：：Initialize