Функция GetPointerFrameInfo (winuser.h)
Возвращает весь кадр сведений для указанных указателей, связанных с текущим сообщением.
Синтаксис
BOOL GetPointerFrameInfo(
[in] UINT32 pointerId,
[in, out] UINT32 *pointerCount,
[out] POINTER_INFO *pointerInfo
);
Параметры
[in] pointerId
Идентификатор указателя, для которого требуется получить сведения о кадре.
[in, out] pointerCount
Указатель на переменную, указывающую количество структур в буфере, на которые указывает pointerInfo. Если GetPointerFrameInfo завершается успешно, параметр pointerCount обновляется с учетом общего количества указателей в кадре.
[out] pointerInfo
Адрес массива POINTER_INFO структур для получения сведений о указателе. Этот параметр может иметь значение NULL, если *pointerCount равно нулю.
Возвращаемое значение
Если функция выполняется успешно, возвращаемое значение не равно нулю.
Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.
Комментарии
Устройства с параллельным режимом могут сообщать о входных данных указателя в кадрах, то есть они могут сообщать о состоянии и положении всех указателей с этого устройства в одном входном отчете в систему. В идеале приложения должны рассматривать весь кадр как единый вход, если только требования конкретного приложения не диктуют иное.
GetPointerFrameInfo извлекает весь входной кадр указателя, связанный с сообщением указателя. Используйте GetPointerInfo для получения сведений об одном указателе, связанном с сообщением указателя.
Фрейм содержит только указатели, которые в настоящее время принадлежат тому же окну, что и указанный указатель.
Сведения, возвращаемые GetPointerFrameInfo , связаны с последним сообщением указателя, извлеченным вызывающим потоком. Когда вызывающий поток извлекает следующее сообщение, сведения, связанные с предыдущим сообщением, могут быть недоступны.
Если приложение не обрабатывает входные сообщения указателя так быстро, как они создаются, некоторые сообщения могут быть объединены в сообщение WM_POINTERUPDATE . Используйте GetPointerFrameInfoHistory , чтобы получить журнал сообщений из последнего сообщения WM_POINTERUPDATE .
Получив весь кадр сведений, приложение может затем вызвать функцию SkipPointerFrameMessages , чтобы пропустить оставшиеся сообщения указателя, связанные с этим кадром, ожидающие извлечения. Это позволяет приложению сэкономить затраты на получение и обработку оставшихся сообщений по одному. Однако функцию SkipPointerFrameMessages следует использовать с осторожностью и только в том случае, если вызывающий объект может быть уверен, что ни одна другая сущность в потоке вызывающего объекта не ожидает видеть остальные сообщения указателя по одному по мере их извлечения.
Обратите внимание, что полученные сведения связаны с кадром указателя, который последний раз был получен вызывающим потоком. Когда вызывающий поток получает следующее сообщение, сведения, связанные с предыдущим кадром указателя, могут перестать быть доступными.
Если рамка указателя не содержит дополнительных указателей, кроме указанного указателя, эта функция выполняется успешно и возвращает только сведения для указанного указателя.
Если сведения, связанные с рамкой указателя, больше недоступны, эта функция завершается ошибкой с последней ошибкой ERROR_NO_DATA.
Если вызывающий поток не владеет окном (куда изначально были доставлены входные данные или куда было переадресовлено сообщение), в которое было доставлено сообщение указателя, эта функция завершается сбоем с последней ошибкой ERROR_ACCESS_DENIED.
Для приложений, имеющих как клиентские, так и не клиентские области, входной кадр может включать как клиентские, так и не клиентские данные. Чтобы различать данные клиента и данные, не относящиеся к клиенту, необходимо выполнить проверку попадания в целевом окне.
Если требуется отфильтровать данные из входного кадра, рекомендуется следующее:
- Для каждого обновления, не включающего контакт указателя ( POINTER_FLAG_UPDATE без POINTER_FLAG_INCONTACT), нажмите тест, чтобы определить, является ли входные данные клиентскими или не клиентскими.
- Для каждого нового контакта (POINTER_FLAG_DOWN) нажмите тест, чтобы определить, являются ли входные данные клиентскими или не клиентскими, и отслеживать эти сведения.
- Для каждого обновления, включающего контакт указателя ( POINTER_FLAG_UPDATE с POINTER_FLAG_INCONTACT), используйте сведения для отслеживания, чтобы определить, являются ли входные данные клиентскими или не клиентскими.
- Для каждого POINTER_FLAG_UP используйте сведения для отслеживания, чтобы определить, являются ли входные данные клиентскими или не клиентскими, а затем очистите этот указатель из данных отслеживания.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 8 [только классические приложения] |
| Минимальная версия сервера | Windows Server 2012 [только классические приложения] |
| Целевая платформа | Windows |
| Header | winuser.h (включая Windows.h) |
| Библиотека | User32.lib |
| DLL | User32.dll |