InjectTouchInput 函数 (winuser.h)

  • 项目

模拟触摸输入。

注意InitializeTouchInjection 必须在对 InjectTouchInput 的任何调用之前。

 

语法

BOOL InjectTouchInput(
  [in] UINT32                   count,
  [in] const POINTER_TOUCH_INFO *contacts
);

参数

[in] count

联系人中数组的大小。

count 的最大值由 InitializeTouchInjection 函数的 maxCount 参数指定。

[in] contacts

表示桌面上所有联系人 的POINTER_TOUCH_INFO 结构的数组。 每个联系人的屏幕坐标必须在桌面的边界内。

返回值

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

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

注解

注入的输入将发送到运行注入进程的会话的桌面。

触摸输入注入 (交互和悬停) 有两种输入状态，由触点中的以下 pointerFlags 组合指示：

pointerFlags (POINTER_FLAG_*) 状态
INRANGE |更新 触摸悬停开始或移动
INRANGE |INCONTACT |DOWN 向下触摸触点
INRANGE |INCONTACT |更新 触摸触点移动
INRANGE |UP 向上触摸接触并转换为悬停
UPDATE 触摸悬停结束
UP 触摸端
 
注意 交互状态表示在屏幕上能够与任何支持触摸的应用进行交互的触摸触点。 悬停状态表示不与屏幕接触且无法与应用程序交互的触摸输入。 触摸注入可以在悬停或交互状态下启动，但状态只能通过 INRANGE 转换 |INCONTACT |向下悬停到交互状态，或通过 INRANGE |向上以交互方式将鼠标悬停状态。
 
所有触摸注入序列都以 UPDATE 或 UP 结尾。

下图演示了一个以悬停状态开始、转换为交互式、以悬停结束的触摸注入序列。

显示从悬停到交互到悬停的状态转换的触摸注入序列图。

对于长按手势，必须发送多个帧以确保不会取消输入。 若要在 x，y) 点 (长按，请在 x，y) (点发送WM_POINTERDOWN，然后在 x，y) (点发送WM_POINTERUPDATE消息。

侦听 WM_DISPLAYCHANGE 以处理对显示分辨率和方向的更改以及管理屏幕坐标更新。 收到 WM_DISPLAYCHANGE 后，将取消所有活动联系人。

通过使用POINTER_FLAG_UP或POINTER_FLAG_UPDATE设置POINTER_FLAG_CANCELED来取消单个联系人。 取消不POINTER_FLAG_UP或POINTER_FLAG_UPDATE的触摸注入会使注入失效。

设置POINTER_FLAG_UP后， POINTER_INFO 的 ptPixelLocation 应与具有POINTER_FLAG_UPDATE的上一个触摸注入帧的值相同。 否则，注入失败并出现ERROR_INVALID_PARAMETER并取消所有活动的注入触点。 系统在取消注入时修改 WM_POINTERUP 事件的 ptPixelLocation。

可以在 POINTER_INFO的 dwTime 或 PerformanceCount 字段中指定输入时间戳。 该值不能比注入线程的当前计时周期计数或 QueryPerformanceCounter 值更新。 为帧注入时间戳后，所有后续帧都必须包含时间戳，直到帧中的所有触点都进入 UP 状态。 必须为 contacts 数组中的第一个元素提供自定义时间戳值。 忽略第一个元素后的时间戳值。 自定义时间戳值必须在每个注入帧中递增。

指定 PerformanceCount 字段时，时间戳在实际注入时以 0.1 毫秒分辨率转换为当前时间。 如果自定义 PerformanceCount 导致与上一次注入相同的 0.1 毫秒窗口，API 将返回错误 (ERROR_NOT_READY) ，并且不会注入数据。 虽然错误不会立即使注入失效，但下一次成功注入的 PerformanceCount 值必须与之前成功的注入相差至少 0.1 毫秒。 同样，如果使用字段，自定义 dwTime 值必须至少相隔 1 毫秒。

如果在注入参数中同时指定了 dwTime 和 PerformanceCount， InjectTouchInput 将失败并 (ERROR_INVALID_PARAMETER) 错误代码。 使用 dwTime 或 PerformanceCount 参数启动注入应用程序后，必须正确填充时间戳字段。 注入序列启动后，无法将自定义时间戳字段从一个字段切换到另一个。

如果未指定 dwTime 或 PerformanceCount 值， InjectTouchInput 将根据 API 调用的计时分配时间戳。 如果调用间隔小于 0.1 毫秒，则 API 可能会 (ERROR_NOT_READY) 返回错误。 此错误不会立即使输入失效，但注入应用程序需要再次重试同一帧，以确保注入成功。

要求

   
最低受支持的客户端 Windows 8 [仅限桌面应用]
最低受支持的服务器 Windows Server 2012 [仅限桌面应用]
目标平台 Windows
标头 winuser.h
Library User32.lib
DLL User32.dll
API 集 ext-ms-win-rtcore-ntuser-wmpointer-l1-1-0 (在 Windows 10 版本 10.0.14393 中引入)

请参阅

函数