IAudioClock：：GetPosition 方法 (audioclient.h)

  • 项目

GetPosition 方法获取当前设备位置。

语法

HRESULT GetPosition(
  [out] UINT64 *pu64Position,
  [out] UINT64 *pu64QPCPosition
);

参数

[out] pu64Position

指向方法将设备位置写入其中的 UINT64 变量的指针。 设备位置是从流开始到流中当前位置的偏移量。 但是，表示此偏移量的单位未定义 - 设备位置值仅与 IAudioClock：：GetFrequency 方法报告的频率相关。 有关详细信息，请参阅“备注”。

[out] pu64QPCPosition

指向 UINT64 变量的指针，当音频终结点设备 (*pu64Position) 响应 GetPosition 调用时，方法将性能计数器的值写入其中。 方法将计数器值转换为 100 纳秒时间单位，然后再将其写入 *pu64QPCPosition。 如果客户端不需要性能计数器值，此参数可以为 NULL 。

返回值

如果该方法成功并获取位置的准确读数，则返回S_OK。 如果方法成功，但调用的持续时间足够长，足以降低位置读取的准确性，则该方法返回S_FALSE。 如果失败，可能的返回代码包括但不限于下表中显示的值。

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

注解

需要根据流的当前播放或录制位置公开时钟的呈现或捕获客户端可以使用此方法派生该时钟。

此方法检索两个相关的流位置值：

  • 设备位置。 客户端通过输出参数 pu64Position 获取设备位置。 这是当前通过呈现流) 的扬声器 (播放或通过捕获流) 的麦克风 (录制的示例的流位置。
  • 性能计数器。 客户端通过输出参数 pu64QPCPosition 获取性能计数器。 这是方法在音频终结点设备录制流位置时通过调用 QueryPerformanceCounter 函数获取的计数器值 (*pu64Position) 。 请注意， GetPosition 将计数器值转换为 100 纳秒的时间单位。
除非设备位置与 IAudioClock：：GetFrequency 方法报告的设备频率结合使用，否则设备位置毫无意义。 原因是表示不同流的设备位置的单位可能因各种因素而异，例如流是在共享模式还是独占模式下打开的。 但是，从 GetFrequency 获取的频率 f 始终以与设备位置 p 兼容的单位表示。 因此，流相对偏移量（以秒为单位）始终可以计算为 p/f。

设备位置是相对于流的偏移量。 也就是说，它被指定为与流开头的偏移量。 可将设备位置视为包含整个流的理想化缓冲区的偏移量，并且从头到尾是连续的。

给定 GetPosition 调用时的设备位置和性能计数器，客户端可以通过调用 QueryPerformanceCounter 获取当前性能计数器，并根据记录原始设备位置以来计数器的前进距离推断设备位置，从而在稍晚一点的时间更及时地估计设备位置。 客户端可以调用 QueryPerformanceFrequency 函数来确定递增计数器的时钟频率。 将从 QueryPerformanceCounter 获取的原始计数器值与 GetPosition 写入到 *pu64QPCPosition 的值进行比较之前，将原始计数器值转换为 100 纳秒的时间单位，如下所示：

  1. 将原始计数器值乘以 10,000,000。
  2. 将结果除以从 QueryPerformanceFrequency 获取的计数器频率。
有关 QueryPerformanceCounter 和 QueryPerformanceFrequency 的详细信息，请参阅 Windows SDK 文档。

创建新流后，设备位置立即为 0。 调用 IAudioClient：：Start 方法后，设备位置以统一速率递增。 IAudioClient：：Stop 方法冻结设备位置，后续的 Start 调用会导致设备位置在停止调用时从其值恢复递增。 对 IAudioClient：：Reset 的调用（应仅在流停止时发生）将设备位置重置为 0。

当新的或重置的呈现流最初开始运行时，其设备位置可能会保持 0 数毫秒，直到音频数据有时间从终结点缓冲区传播到呈现终结点设备。 当数据开始通过设备播放时，设备位置将从 0 更改为非零值。

连续的设备读数单调递增。 尽管设备位置可能不会在两个连续读数之间更改，但设备位置永远不会从一个读数减少到下一个读数。

pu64Position 参数必须是有效的非 NULL 指针，否则方法将失败并返回错误代码E_POINTER。

位置测量有时可能会因间歇性高优先级事件而延迟。 这些事件可能与音频无关。 对于独占模式流，如果方法成功，但调用的持续时间足够长，会降低报告位置的准确性，则该方法可以返回S_FALSE而不是S_OK。 发生这种情况时，调用方可以选择再次调用 方法，以尝试检索更准确的位置 (，如返回值S_OK) 所示。 但是，调用方应避免在方法一致返回S_FALSE的情况下在无限循环中执行此测试。

要求

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

另请参阅

IAudioClient：：Reset

IAudioClient：：Start

IAudioClient：：Stop

IAudioClock 接口

IAudioClock：：GetFrequency