Функция GetPointerFrameTouchInfoHistory (winuser.h)
Возвращает весь кадр сенсорной информации (включая объединяемые входные кадры) для указанных указателей (типа PT_TOUCH), связанных с текущим сообщением.
Синтаксис
BOOL GetPointerFrameTouchInfoHistory(
[in] UINT32 pointerId,
[in, out] UINT32 *entriesCount,
[in, out] UINT32 *pointerCount,
[out] POINTER_TOUCH_INFO *touchInfo
);
Параметры
[in] pointerId
Идентификатор указателя, для которого извлекаются сведения о кадре.
[in, out] entriesCount
Указатель на переменную, указывающую количество строк в двумерном массиве, на который указывает touchInfo. Если getPointerFrameTouchInfoHistory завершается успешно, параметр entriesCount обновляется с учетом общего количества кадров, доступных в журнале.
[in, out] pointerCount
Указатель на переменную, указывающую количество столбцов в двумерном массиве, на который указывает touchInfo. Если getPointerFrameTouchInfoHistory завершается успешно, функция pointerCount обновляется с указанием общего количества указателей в каждом кадре.
[out] touchInfo
Адрес двумерного массива POINTER_TOUCH_INFO структур для получения сведений о указателе. Этот параметр может иметь значение NULL, если значения *entriesCount и *pointerCount равны нулю.
Этот массив интерпретируется как POINTER_TOUCH_INFO[*entriesCount][*pointerCount].
Возвращаемое значение
Если функция выполняется успешно, возвращаемое значение не равно нулю.
Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.
Комментарии
Устройства с параллельным режимом могут сообщать о входных данных указателя в кадрах, то есть могут сообщать о состоянии и положении всех указателей с этого устройства в одном входном отчете в систему. В идеале приложения должны рассматривать весь кадр как единый вход, если только требования конкретного приложения не диктуют иное.
Сведения, возвращаемые GetPointerFrameTouchInfo , связаны с последним сообщением указателя (PT_TOUCH), полученном вызывающим потоком. Когда вызывающий поток извлекает следующее сообщение, сведения, связанные с предыдущим сообщением, могут быть недоступны.
Если приложение не обрабатывает входные сообщения указателя так быстро, как они создаются, некоторые сообщения могут быть объединены в WM_POINTERUPDATE сообщение. Используйте GetPointerFrameTouchInfoHistory , чтобы получить журнал сообщений (включая объединяемые входные кадры) из последнего сообщения WM_POINTERUPDATE .
Получив весь кадр данных, приложение может вызвать функцию SkipPointerFrameMessages , чтобы пропустить оставшиеся сообщения указателя, связанные с этим кадром, ожидающие извлечения. Это позволяет приложению сэкономить затраты на получение и обработку оставшихся сообщений по одному. Однако функцию SkipPointerFrameMessages следует использовать с осторожностью и только в том случае, если вызывающий объект может быть уверен, что ни одна другая сущность в потоке вызывающего объекта не ожидает видеть оставшиеся сообщения указателя по одному по мере их извлечения.
Фрейм содержит только указатели, которые в настоящее время принадлежат тому же окну, что и указанный указатель.
Полученные сведения представляют двумерный массив с одной строкой для каждой записи журнала и одним столбцом для каждого указателя в кадре.
Полученные сведения отображаются в обратном хронологическом порядке с последней записью в первой строке возвращаемого массива. Последняя запись совпадает с той, которая возвращается функцией GetPointerFrameTouchInfo .
Если количество строк в предоставленном буфере недостаточно для хранения всех доступных записей журнала, эта функция завершается успешно с буфером, содержащим последние записи, и *entriesCount , содержащим общее количество доступных записей.
Если рамка указателя не содержит дополнительных указателей, кроме указанного указателя, эта функция выполняется успешно и возвращает только сведения для указанного указателя.
Если сведения, связанные с рамкой указателя, больше не доступны, эта функция завершается сбоем с последней ошибкой ERROR_NO_DATA.
Если вызывающий поток не владеет окном (в которое изначально были доставлены входные данные или куда было переадресовывалось сообщение), в которое было доставлено сообщение указателя, эта функция завершается сбоем с последней ошибкой ERROR_ACCESS_DENIED.
Если указанный указатель не имеет типа PT_TOUCH, эта функция завершается сбоем с последней ошибкой, заданной как ERROR_DATATYPE_MISMATCH.
Для приложений, имеющих как клиентские, так и не клиентские области, входной кадр может включать как клиентские, так и не клиентские данные. Чтобы различать клиентские и не клиентские данные, необходимо выполнить проверку попадания в целевом окне.
Если вы хотите отфильтровать данные из входного кадра, рекомендуется следующее:
- Для каждого обновления, не включающего контакт указателя ( 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 |