Поделиться через

Функция 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

См. также

Функции

GetPointerFrameTouchInfo

GetPointerTouchInfo

GetPointerTouchInfoHistory