InjectTouchInput function

Simulates touch input.

Note  InitializeTouchInjection must precede any call to InjectTouchInput.

Syntax


BOOL InjectTouchInput(
  _In_  UINT32 count,
  _In_  const POINTER_TOUCH_INFO *contacts
);

Parameters

count [in]

The size of the array in contacts.

The maximum value for count is specified by the maxCount parameter of the InitializeTouchInjection function.

contacts [in]

Array of POINTER_TOUCH_INFO structures that represents all contacts on the desktop. The screen coordinates of each contact must be within the bounds of the desktop.

Return value

If the function succeeds, the return value is non-zero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Error codes

NameMeaning
ERROR_INVALID_PARAMETER

Injection parameter was invalid.

STATUS_ACCESS_DENIED

Injection was attempted without a successful initialization.

ERROR_TIMEOUT

Indicates that the generated input is in an expired state: More than 100ms (10Hz) has passed since previous input frame.

ERROR_NOT_READY

The system is not ready to receive another touch injection.

Error codes

NameMeaning
ERROR_INVALID_PARAMETER

Injection parameter was invalid.

STATUS_ACCESS_DENIED

Injection was attempted without a successful initialization.

ERROR_TIMEOUT

Indicates that the generated input is in an expired state: More than 100ms (10Hz) has passed since previous input frame.

ERROR_NOT_READY

The system is not ready to receive another touch injection.

Remarks

The injected input is sent to the desktop of the session where the injection process is running.

There are two input states for touch input injection (interactive and hover) that are indicated by the following combinations of pointerFlags in contacts:

pointerFlags (POINTER_FLAG_*)Status
INRANGE | UPDATETouch hover starts or moves
INRANGE | INCONTACT | DOWNTouch contact down
INRANGE | INCONTACT | UPDATE Touch contact moves
INRANGE | UPTouch contact up and transition to hover
UPDATETouch hover ends
UPTouch ends

 

Note  Interactive state represents a touch contact that is on-screen and able to interact with any touch-capable app. Hover state represents touch input that is not in contact with the screen and cannot interact with applications. Touch injection can start in hover or interactive state, but the state can only transition through INRANGE | INCONTACT | DOWN for hover to interactive state, or through INRANGE | UP for interactive to hover state.

All touch injection sequences end with either UPDATE or UP.

The following diagram demonstrates a touch injection sequence that starts with a hover state, transitions to interactive, and concludes with hover.

Hh802881.inputstates(en-us,VS.85).png

For press and hold gestures, multiple frames must be sent to ensure input is not cancelled. For a press and hold at point (x,y), send WM_POINTERDOWN at point (x,y) followed by WM_POINTERUPDATE messages at point(x,y).

Listen for WM_DISPLAYCHANGE to handle changes to display resolution and orientation and manage screen coordinate updates. All active contacts are cancelled when a WM_DISPLAYCHANGE is received.

Cancel individual contacts by setting POINTER_FLAG_CANCELED with POINTER_FLAG_UP or POINTER_FLAG_UPDATE. Cancelling touch injection without POINTER_FLAG_UP or POINTER_FLAG_UPDATE invalidates the injection.

When POINTER_FLAG_UP is set, ptPixelLocation of POINTER_INFO should be the same as the value of the previous touch injection frame with POINTER_FLAG_UPDATE. Otherwise, the injection fails with ERROR_INVALID_PARAMETER and all active injection contacts are cancelled. The system modifies the ptPixelLocation of the WM_POINTERUP event as it cancels the injection.

The input timestamp can be specified in either the dwTime or PerformanceCount field of POINTER_INFO. The value cannot be more recent than the current tick count or QueryPerformanceCounter value of the injection thread. Once a frame is injected with a timestamp, all subsequent frames must include a timestamp until all contacts in the frame go to the UP state. The custom timestamp value must be provided for the first element in the contacts array. The timestamp values after the first element are ignored. The custom timestamp value must increment in every injection frame.

When a PerformanceCount field is specified, the timestamp is converted into current time in .1 millisecond resolution upon actual injection. If a custom PerformanceCount resulted in the same .1 millisecond window from previous injection, the API will return an error (ERROR_NOT_READY) and will not inject the data. While injection is not immediately invalidated by the error, next successful injection must have PerformanceCount value that is at least 0.1 milliseconds apart from the previously successful injection. Similarly a custom dwTime value must be at least 1 millisecond apart if the field was used.

If both dwTime and PerformanceCount are specified in the injection parameter, InjectTouchInput fails with an Error Code (ERROR_INVALID_PARAMETER). Once the injection application starts with either a dwTime or PerformanceCount parameter, the timestamp field must be filled correctly. Injection cannot switch the custom timestamp field from one to another once the injection sequence has started.

When neither dwTime or PerformanceCount values are specified, the InjectTouchInput allocates the timestamp based on the timing of the API call. If the calls are less than 0.1 millisecond apart, the API may return an error (ERROR_NOT_READY). The error will not invalidate the input immediately, but the injection application needs to retry the same frame again to ensure injection is successful.

Requirements

Minimum supported client

Windows 8 [desktop apps only]

Minimum supported server

Windows Server 2012 [desktop apps only]

Header

Winuser.h

Library

User32.lib

DLL

User32.dll

See also

Functions

 

 

Community Additions

ADD
Show:
© 2014 Microsoft