InjectTouchInput 함수(winuser.h)
터치 입력을 시뮬레이션합니다.
구문
BOOL InjectTouchInput(
[in] UINT32 count,
[in] const POINTER_TOUCH_INFO *contacts
);
매개 변수
[in] count
연락처의 배열 크기 입니다.
count의 최대값은 InitializeTouchInjection 함수의 maxCount 매개 변수에 의해 지정됩니다.
[in] contacts
바탕 화면의 모든 연락처를 나타내는 POINTER_TOUCH_INFO 구조체의 배열입니다. 각 접촉의 화면 좌표는 바탕 화면 범위 내에 있어야 합니다.
반환 값
함수가 성공하면 반환 값은 0이 아닙니다.
함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.
설명
삽입된 입력은 삽입 프로세스가 실행되는 세션의 바탕 화면으로 전송됩니다.
터치 입력 주입(대화형 및 가리키기)에 대한 두 가지 입력 상태는 연락처의 pointerFlag 조합으로 표시됩니다.
| pointerFlags(POINTER_FLAG_*) | 상태 |
|---|---|
| INRANGE | 업데이트 | 터치 가리키기 시작 또는 이동 |
| INRANGE | INCONTACT | 아래로 | 터치 터치 다운 |
| INRANGE | INCONTACT | 업데이트 | 터치 접촉 이동 |
| INRANGE | UP(UP) | 터치 위로 터치하고 가리키기로 전환 |
| UPDATE | 터치 가리키기 끝 |
| UP | 터치 끝 |
다음 다이어그램은 가리키기 상태로 시작하고 대화형으로 전환하며 가리키기로 끝나는 터치 삽입 시퀀스를 보여 줍니다.
길게 누르기 제스처의 경우 입력이 취소되지 않도록 여러 프레임을 보내야 합니다. 길게 누르고 있는 지점(x,y)의 경우 지점에서 WM_POINTERDOWN (x,y) 뒤에 WM_POINTERUPDATE 메시지(x,y)를 보냅니다.
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 상태로 이동될 때까지 모든 후속 프레임에 타임스탬프가 포함되어야 합니다. 연락처 배열의 첫 번째 요소에 대해 사용자 지정 타임스탬프 값을 제공해야 합니다. 첫 번째 요소 뒤의 타임스탬프 값은 무시됩니다. 사용자 지정 타임스탬프 값은 모든 삽입 프레임에서 증가해야 합니다.
PerformanceCount 필드를 지정하면 타임스탬프는 실제 삽입 시 .1밀리초 해상도로 현재 시간으로 변환됩니다. 사용자 지정 PerformanceCount로 인해 이전 삽입과 동일한 .1밀리초의 창이 발생한 경우 API는 오류(ERROR_NOT_READY)를 반환하고 데이터를 삽입하지 않습니다. 삽입이 오류에 의해 즉시 무효화되지는 않지만 다음에 성공한 삽입에는 이전에 성공한 삽입과는 별도로 최소 0.1밀리초의 PerformanceCount 값이 있어야 합니다. 마찬가지로 필드를 사용하는 경우 사용자 지정 dwTime 값은 1밀리초 이상 떨어져 있어야 합니다.
삽입 매개 변수에 dwTime 및 PerformanceCount를 모두 지정하면 오류 코드(ERROR_INVALID_PARAMETER)로 인해 InjectTouchInput 이 실패합니다. 삽입 애플리케이션이 dwTime 또는 PerformanceCount 매개 변수로 시작되면 타임스탬프 필드를 올바르게 채워야 합니다. 삽입 시퀀스가 시작된 후에는 사용자 지정 타임스탬프 필드를 서로 전환할 수 없습니다.
dwTime 또는 PerformanceCount 값을 지정하지 않으면 InjectTouchInput 은 API 호출 타이밍에 따라 타임스탬프를 할당합니다. 호출이 0.1밀리초 미만인 경우 API는 오류(ERROR_NOT_READY)를 반환할 수 있습니다. 이 오류는 입력을 즉시 무효화하지 않지만 삽입 애플리케이션은 삽입에 성공하려면 동일한 프레임을 다시 시도해야 합니다.
요구 사항
| 지원되는 최소 클라이언트 | Windows 8 [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows Server 2012 [데스크톱 앱만 해당] |
| 대상 플랫폼 | Windows |
| 헤더 | winuser.h |
| 라이브러리 | User32.lib |
| DLL | User32.dll |
| API 세트 | ext-ms-win-rtcore-ntuser-wmpointer-l1-1-0(Windows 10 버전 10.0.14393에 도입됨) |