IAudioClient3：：InitializeSharedAudioStream 方法 (audioclient.h)

  • 项目

使用指定的周期初始化共享流。

语法

HRESULT InitializeSharedAudioStream(
  [in]           DWORD              StreamFlags,
  [in]           UINT32             PeriodInFrames,
  [in]           const WAVEFORMATEX *pFormat,
  [in, optional] LPCGUID            AudioSessionGuid
);

参数

[in] StreamFlags

类型：DWORD

用于控制流的创建的标志。 客户端应将此参数设置为 0，或者将一个或多个受支持的 AUDCLNT_STREAMFLAGS_XXX常量 或 AUDCLNT_SESSIONFLAGS_XXX常量设置为按位 OR。 使用此方法时，此参数支持的 AUDCLNT_STREAMFLAGS_XXX常量 为：

  • AUDCLNT_STREAMFLAGS_EVENTCALLBACK

[in] PeriodInFrames

类型： UINT32

客户端请求的周期性。 此值必须是 pFundamentalPeriodInFrames 参数中返回到 IAudioClient3：：GetSharedModeEnginePeriod 的值的整数倍数。 PeriodInFrames 还必须大于或等于 pMinPeriodInFrames 中返回的值，并且必须小于或等于 pMaxPeriodInFrames 中返回的值。

[in] pFormat

类型： const WAVEFORMATEX*

指向格式描述符的指针。 此参数必须指向 WAVEFORMATEX 或WAVEFORMATEXTENSIBLE 类型的有效格式描述符。 有关详细信息，请参阅 IAudioClient：：Initialize 的“备注”部分。

[in, optional] AudioSessionGuid

类型： LPCGUID

指向会话 GUID 的指针。 此参数指向标识流所属的音频会话的 GUID 值。 如果 GUID 标识了以前打开的会话，该方法会将流添加到该会话。 如果 GUID 未标识现有会话，该方法将打开一个新会话，并将流添加到该会话。 流在其生存期内仍然是同一会话的成员。 将此参数设置为 NULL 等效于将指针传递到GUID_NULL值。

返回值

类型： HRESULT

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

返回代码 说明
AUDCLNT_E_ALREADY_INITIALIZED
 IAudioClient 对象已初始化。
AUDCLNT_E_WRONG_ENDPOINT_TYPE
 设置AUDCLNT_STREAMFLAGS_LOOPBACK标志，但终结点设备是捕获设备，而不是呈现设备。
AUDCLNT_E_CPUUSAGE_EXCEEDED
 指示进程传递持续时间超过了最大 CPU 使用率。 音频引擎通过保持进程传递持续时间超过最大 CPU 使用率的次数来跟踪 CPU 使用率。 最大 CPU 使用率按引擎周期的百分比计算。 百分比值是系统 CPU 限制值 (在 10% 和 90% ) 范围内。 如果未找到此值，则使用默认值 40% 来计算最大 CPU 使用率。
AUDCLNT_E_DEVICE_INVALIDATED
 音频终结点设备已拔出，或者音频硬件或关联的硬件资源已重新配置、禁用、删除或以其他方式不可用。
AUDCLNT_E_DEVICE_IN_USE
 终结点设备已在使用中。 设备正在独占模式下使用，或者设备正在共享模式下使用，调用方要求在独占模式下使用设备。
AUDCLNT_E_ENGINE_FORMAT_LOCKED
 调用 IAudioClient2：：SetClientProperties 时指定的客户端AUDCLNT_STREAMOPTIONS_MATCH_FORMAT，但音频引擎的格式已被其他客户端锁定。 在这种情况下，无需指定匹配格式选项即可调用 IAudioClient2：：SetClientProperties ，然后使用音频引擎的当前格式。
AUDCLNT_E_ENGINE_PERIODICITY_LOCKED
 调用 IAudioClient2：：SetClientProperties 时指定的客户端AUDCLNT_STREAMOPTIONS_MATCH_FORMAT，但音频引擎的周期已被另一个客户端锁定。 在这种情况下，无需指定匹配格式选项即可调用 IAudioClient2：：SetClientProperties ，然后使用音频引擎的当前周期。
AUDCLNT_E_ENDPOINT_CREATE_FAILED
 方法无法为呈现或捕获设备创建音频终结点。 如果音频终结点设备已拔下，或者音频硬件或关联的硬件资源已重新配置、禁用、删除或以其他方式无法使用，则可能会出现这种情况。
AUDCLNT_E_INVALID_DEVICE_PERIOD
 指示使用 PeriodInFrames 指定的请求设备周期不是音频引擎基本周期的整数倍，短于引擎的最小周期，或长于引擎的最长周期。 通过调用 IAudioClient3：：GetSharedModeEnginePeriod 获取引擎支持的周期值。
AUDCLNT_E_UNSUPPORTED_FORMAT
 音频引擎 (共享模式) 或音频终结点设备 (独占模式) 不支持指定的格式。
AUDCLNT_E_SERVICE_NOT_RUNNING
 Windows 音频服务未运行。
E_POINTER
 参数 pFormat 为 NULL。
E_INVALIDARG
 参数 pFormat 指向格式说明无效;或设置了 AUDCLNT_STREAMFLAGS_LOOPBACK 标志，但 ShareMode 不等于 AUDCLNT_SHAREMODE_SHARED;或设置了 AUDCLNT_STREAMFLAGS_CROSSPROCESS 标志，但 ShareMode 等于 AUDCLNT_SHAREMODE_EXCLUSIVE。

先前对 SetClientProperties 的调用是使用音频/呈现流的无效类别进行的。
E_OUTOFMEMORY
 内存不足。

注解

与 IAudioClient：：Initialize 不同，此方法不允许指定缓冲区大小。 缓冲区大小是根据 使用 PeriodInFrames 参数请求的周期计算的。 客户端应用负责确保音频样本及时传入和传出缓冲区。

音频客户端应通过调用 IAudioClient3：：GetSharedModeEnginePeriod 来检查 PeriodInFrames 参数的允许值。 PeriodInFrames 的值必须是 pFundamentalPeriodInFrames 参数中返回的值的整数倍数。 PeriodInFrames 还必须大于或等于 pMinPeriodInFrames 中返回的值，并且必须小于或等于 pMaxPeriodInFrames 的值。

例如，对于 44100 kHz 格式， GetSharedModeEnginePeriod 可能会返回：

  • pDefaultPeriodInFrames = 448 帧 (约 10.16 毫秒)

  • pFundamentalPeriodInFrames = 4 帧 (约 0.09 毫秒)

  • pMinPeriodInFrames = 48 帧 (约 1.09 毫秒)

  • pMaxPeriodInFrames = 448 帧 (与默认) 相同

InitializeSharedAudioStream 的 PeriodInFrames 参数允许的值包括 48 和 448。 它们还将包括 96 和 128 之类的内容。

它们不包括 4 个 (小于最小允许值) 或 98 (这不是基本) 的倍数或大于) 允许的最大值的 1000 (。

要求

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

另请参阅

IAudioClient

IAudioClient2

IAudioClient3