GetPointerFrameInfoHistory 함수(winuser.h)
현재 메시지와 연결된 지정된 포인터에 대한 전체 정보 프레임(병합된 입력 프레임 포함)을 가져옵니다.
구문
BOOL GetPointerFrameInfoHistory(
[in] UINT32 pointerId,
[in, out] UINT32 *entriesCount,
[in, out] UINT32 *pointerCount,
[out] POINTER_INFO *pointerInfo
);
매개 변수
[in] pointerId
프레임 정보를 검색할 포인터의 식별자입니다.
[in, out] entriesCount
pointerInfo가 가리키는 2차원 배열의 행 수를 지정하는 변수에 대한 포인터입니다. GetPointerFrameInfoHistory가 성공하면 entriesCount가 기록에서 사용할 수 있는 총 프레임 수로 업데이트됩니다.
[in, out] pointerCount
pointerInfo가 가리키는 2차원 배열의 열 수를 지정하는 변수에 대한 포인터입니다. GetPointerFrameInfoHistory가 성공하면 pointerCount가 각 프레임의 총 포인터 수로 업데이트됩니다.
[out] pointerInfo
포인터 정보를 수신할 POINTER_INFO 구조체의 2차원 배열 주소입니다. *entriesCount 및 *pointerCount가 모두 0인 경우 이 매개 변수는 NULL일 수 있습니다.
이 배열은 로 POINTER_INFO[*entriesCount][*pointerCount]해석됩니다.
반환 값
함수가 성공하면 반환 값은 0이 아닙니다.
함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.
설명
병렬 모드 디바이스는 프레임에서 포인터 입력을 보고할 수 있습니다. 즉, 단일 입력 보고서에서 해당 디바이스의 모든 포인터의 상태와 위치를 시스템에 보고할 수 있습니다. 애플리케이션별 요구 사항이 달리 지시하지 않는 한 애플리케이션은 전체 프레임을 단일 입력으로 보는 것이 가장 좋습니다.
GetPointerFrameInfo에서 반환된 정보는 호출 스레드에서 검색한 가장 최근의 포인터 메시지와 연결됩니다. 호출 스레드에서 다음 메시지를 검색하면 이전 메시지와 연결된 정보를 더 이상 사용할 수 없습니다.
애플리케이션이 포인터 입력 메시지를 생성한 만큼 빠르게 처리하지 않으면 일부 메시지가 WM_POINTERUPDATE 메시지로 병합될 수 있습니다. GetPointerFrameInfoHistory를 사용하여 가장 최근 WM_POINTERUPDATE 메시지에서 메시지 기록(병합된 입력 프레임 포함)을 검색합니다.
전체 정보 프레임을 검색한 후 애플리케이션은 SkipPointerFrameMessages 함수를 호출하여 검색 보류 중인 이 프레임과 연결된 나머지 포인터 메시지를 건너뛸 수 있습니다. 이렇게 하면 나머지 메시지를 하나씩 검색하고 처리하는 오버헤드가 애플리케이션에 저장됩니다. 그러나 SkipPointerFrameMessages 함수는 호출자가 호출자의 스레드에 있는 다른 엔터티가 검색될 때 나머지 포인터 메시지를 하나씩 볼 것으로 예상되는 경우에만 주의해서 사용해야 합니다.
프레임에는 지정된 포인터와 동일한 창에서 현재 소유하고 있는 포인터만 포함됩니다.
검색된 정보는 각 기록 항목에 대해 하나의 행과 프레임의 각 포인터에 대해 하나의 열이 있는 2차원 배열을 나타냅니다.
검색된 정보는 역순으로 나타나며 반환된 배열의 첫 번째 행에 가장 최근 항목이 있습니다. 가장 최근 항목은 GetPointerFrameInfo 함수에서 반환한 항목과 동일합니다.
제공된 버퍼의 행 수가 사용 가능한 모든 기록 항목을 포함하기에 충분하지 않은 경우 이 함수는 가장 최근 항목이 포함된 버퍼와 사용 가능한 총 항목 수를 포함하는 *entriesCount 로 성공합니다.
포인터 프레임에 지정된 포인터 외에 추가 포인터가 없는 경우 이 함수는 성공하고 지정된 포인터에 대한 정보만 반환합니다.
포인터 프레임과 연결된 정보를 더 이상 사용할 수 없는 경우 이 함수는 마지막 오류가 ERROR_NO_DATA 설정하여 실패합니다.
호출 스레드가 포인터 메시지가 전달된 창(입력이 원래 전달되었거나 메시지가 전달된 위치)을 소유하지 않는 경우 이 함수는 마지막 오류가 ERROR_ACCESS_DENIED 설정하여 실패합니다.
클라이언트 영역과 비 클라이언트 영역이 모두 있는 앱의 경우 입력 프레임에 클라이언트 및 비 클라이언트 데이터가 모두 포함될 수 있습니다. 클라이언트 데이터와 비 클라이언트 데이터를 구분하려면 대상 창에서 적중 테스트를 수행해야 합니다.
입력 프레임에서 데이터를 필터링하려면 다음을 사용하는 것이 좋습니다.
- 포인터 접점(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에 도입됨) |