GetPointerFrameTouchInfo 함수(winuser.h)

현재 메시지와 연결된 지정된 포인터( PT_TOUCH 형식)에 대한 터치 기반 정보의 전체 프레임을 가져옵니다.

구문

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

매개 변수

[in] pointerId

프레임 정보를 검색할 포인터의 식별자입니다.

[in, out] pointerCount

touchInfo가 가리키는 버퍼의 구조 개수를 지정하는 변수에 대한 포인터입니다. GetPointerFrameTouchInfo가 성공하면 pointerCount가 프레임의 총 포인터 수로 업데이트됩니다.

[out] touchInfo

포인터 정보를 수신할 POINTER_TOUCH_INFO 구조체 배열의 주소입니다. *pointerCount가 0인 경우 이 매개 변수는 NULL일 수 있습니다.

반환 값

함수가 성공하면 반환 값은 0이 아닙니다.

함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.

설명

병렬 모드 디바이스는 프레임에서 포인터 입력을 보고할 수 있습니다. 즉, 단일 입력 보고서에서 해당 디바이스의 모든 포인터의 상태와 위치를 시스템에 보고할 수 있습니다. 애플리케이션별 요구 사항이 달리 지시하지 않는 한 애플리케이션은 전체 프레임을 단일 입력으로 보는 것이 가장 좋습니다.

GetPointerFrameTouchInfo 는 포인터( PT_TOUCH 형식) 메시지와 연결된 전체 포인터 입력 프레임을 검색합니다. GetPointerTouchInfo를 사용하여 포인터 메시지와 연결된 단일 포인터에 대한 정보를 검색합니다.

프레임에는 지정된 포인터와 동일한 창에서 현재 소유하고 있는 포인터만 포함됩니다.

GetPointerFrameTouchInfo에서 반환된 정보는 호출 스레드에서 검색한 가장 최근의 포인터 메시지와 연결됩니다. 호출 스레드에서 다음 메시지를 검색하면 이전 메시지와 연결된 정보를 더 이상 사용할 수 없습니다.

애플리케이션이 포인터 입력 메시지를 생성한 만큼 빠르게 처리하지 않으면 일부 메시지가 WM_POINTERUPDATE 메시지로 병합될 수 있습니다. GetPointerFrameTouchInfoHistory를 사용하여 가장 최근 WM_POINTERUPDATE 메시지에서 메시지 기록을 검색합니다.

전체 정보 프레임을 검색한 후 애플리케이션은 SkipPointerFrameMessages 함수를 호출하여 검색 보류 중인 이 프레임과 연결된 나머지 포인터 메시지를 건너뛸 수 있습니다. 이렇게 하면 나머지 메시지를 하나씩 검색하고 처리하는 오버헤드가 애플리케이션에 저장됩니다. 그러나 SkipPointerFrameMessages 함수는 호출자가 호출자의 스레드에 있는 다른 엔터티가 검색될 때 나머지 포인터 메시지를 하나씩 볼 것으로 예상되는 경우에만 주의해서 사용해야 합니다.

검색된 정보는 호출 스레드에서 가장 최근에 검색한 포인터 프레임과 연결됩니다. 호출 스레드가 다음 메시지를 검색하면 이전 포인터 프레임과 연결된 정보를 더 이상 사용할 수 없습니다.

포인터 프레임에 지정된 포인터 외에 추가 포인터가 없는 경우 이 함수는 성공하고 지정된 포인터에 대한 정보만 반환합니다.

포인터 프레임과 연결된 정보를 더 이상 사용할 수 없는 경우 이 함수는 마지막 오류가 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 포함)
라이브러리	User32.lib
DLL	User32.dll
API 세트	ext-ms-win-rtcore-ntuser-wmpointer-l1-1-0(Windows 10 버전 10.0.14393에 도입됨)

참조

함수

GetPointerFrameTouchInfoHistory

GetPointerTouchInfo

GetPointerTouchInfoHistory