Share via

GetPointerFrameTouchInfoHistory 函数 (winuser.h)

  • 项目

获取基于触摸的信息的整个帧， (包括与当前消息关联的指定指针 (类型 PT_TOUCH) 的合并输入) 帧。

语法

BOOL GetPointerFrameTouchInfoHistory(
  [in]      UINT32             pointerId,
  [in, out] UINT32             *entriesCount,
  [in, out] UINT32             *pointerCount,
  [out]     POINTER_TOUCH_INFO *touchInfo
);

参数

[in] pointerId

要检索其帧信息的指针的标识符。

[in, out] entriesCount

指向变量的指针，该变量指定 touchInfo 指向的二维数组中的行计数。 如果 GetPointerFrameTouchInfoHistory 成功， 则 entriesCount 将更新为历史记录中可用的帧总数。

[in, out] pointerCount

指向变量的指针，该变量指定 touchInfo 指向的二维数组中的列计数。 如果 GetPointerFrameTouchInfoHistory 成功，则 pointerCount 将更新为每个帧中的指针总数。

[out] touchInfo

用于接收指针信息的 POINTER_TOUCH_INFO 结构的二维数组的地址。 如果 *entriesCount 和 *pointerCount 均为零，则此参数可以为 NULL。

此数组被解释为 POINTER_TOUCH_INFO[*entriesCount][*pointerCount]。

返回值

如果函数成功，则返回值为非零。

如果函数失败，则返回值为零。 要获得更多的错误信息，请调用 GetLastError。

注解

并行模式设备可以在帧中报告指针输入，也就是说，它们可以在单个输入报告中向系统报告来自该设备的所有指针的状态和位置。 理想情况下，除非应用程序特定的要求另有规定，否则应用程序应将整个帧视为单个输入。

GetPointerFrameTouchInfo 返回的信息与调用线程检索到的最新指针 (PT_TOUCH) 消息相关联。 当调用线程检索下一条消息时，与上一条消息关联的信息可能不再可用。

如果应用程序处理指针输入消息的速度不及生成消息的速度，则某些消息可能会合并为 WM_POINTERUPDATE 消息。 使用 GetPointerFrameTouchInfoHistory 检索消息历史记录 (包括最近WM_POINTERUPDATE 消息) 合并的输入帧。

检索到整个信息帧后，应用程序可以调用 SkipPointerFrameMessages 函数，以跳过与此帧关联的挂起检索的剩余指针消息。 这可节省应用程序逐个检索和处理剩余消息的开销。 但是，应谨慎使用 SkipPointerFrameMessages 函数，并且仅当调用方可以确保调用方线程上没有其他实体期望在检索剩余指针消息时逐个看到它们时才使用。

框架仅包含当前由指定指针所在的同一窗口拥有的指针。

检索的信息表示一个二维数组，其中每个历史记录条目对应一行，帧中的每个指针对应一列。

检索到的信息按倒序显示，返回的数组的第一行中包含最新的条目。 最新的条目与 GetPointerFrameTouchInfo 函数返回的条目相同。

如果提供的缓冲区中的行计数不足以容纳所有可用的历史记录条目，则此函数会成功，并且包含最新条目的缓冲区和 *entriesCount ，其中包含可用条目的总计数。

如果指针帧除了指定的指针之外没有其他指针，则此函数将成功并仅返回指定指针的信息。

如果与指针帧关联的信息不再可用，此函数将失败，最后一个错误设置为 ERROR_NO_DATA。

如果调用线程不拥有最初传递输入的窗口 (或消息转发) 指针消息传递到的位置，则此函数将失败，最后一个错误设置为 ERROR_ACCESS_DENIED。

如果指定的指针的类型不是 PT_TOUCH，则此函数将失败，最后一个错误设置为 ERROR_DATATYPE_MISMATCH。

对于同时具有客户端和非工作区的应用，输入帧可以同时包含客户端和非客户端数据。 若要区分客户端和非客户端数据，必须在目标窗口中执行命中测试。

如果要筛选输入帧中的数据，建议执行以下操作：

  • 对于不包含指针触点 (没有POINTER_FLAG_INCONTACT) 的POINTER_FLAG_UPDATE的每个更新，点击测试以确定输入是客户端还是非客户端输入。
  • 对于每个新联系人 (POINTER_FLAG_DOWN) ，点击测试以确定输入是客户端还是非客户端，并跟踪此信息。
  • 对于包含指针触点 (具有POINTER_FLAG_INCONTACT) 的POINTER_FLAG_UPDATE的每个更新，请使用跟踪信息来确定输入是客户端输入还是非客户端输入。
  • 对于每个 POINTER_FLAG_UP，使用跟踪信息来确定输入是客户端还是非客户端，然后从跟踪数据中清除此指针。

要求

   
最低受支持的客户端 Windows 8 [仅限桌面应用]
最低受支持的服务器 Windows Server 2012 [仅限桌面应用]
目标平台 Windows
标头 winuser.h (包括 Windows.h)
Library User32.lib
DLL User32.dll

请参阅

函数

GetPointerFrameTouchInfo

GetPointerTouchInfo

GetPointerTouchInfoHistory