Функция 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. Если getPointerFrameInfoHistory завершается успешно, entriesCount обновляется с учетом общего количества кадров, доступных в журнале.

[in, out] pointerCount

Указатель на переменную, указывающую количество столбцов в двумерном массиве, на которые указывает pointerInfo. Если getPointerFrameInfoHistory выполняется успешно, параметр pointerCount обновляется с общим количеством указателей в каждом кадре.

[out] pointerInfo

Адрес двумерного массива POINTER_INFO структур для получения сведений указателя. Этот параметр может иметь значение NULL, если значения *entriesCount и *pointerCount равны нулю.

Этот массив интерпретируется как POINTER_INFO[*entriesCount][*pointerCount].

Возвращаемое значение

Если функция выполняется успешно, возвращаемое значение не равно нулю.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Комментарии

Устройства с параллельным режимом могут сообщать о входных данных указателя в кадрах, то есть они могут сообщать о состоянии и положении всех указателей с этого устройства в одном входном отчете в систему. В идеале приложения должны рассматривать весь кадр как единый вход, если только требования конкретного приложения не диктуют иное.

Сведения, возвращаемые GetPointerFrameInfo , связаны с последним сообщением указателя, извлеченным вызывающим потоком. Когда вызывающий поток извлекает следующее сообщение, сведения, связанные с предыдущим сообщением, могут быть недоступны.

Если приложение не обрабатывает входные сообщения указателя так быстро, как они создаются, некоторые сообщения могут быть объединены в сообщение WM_POINTERUPDATE . Используйте GetPointerFrameInfoHistory для получения журнала сообщений (включая объединенные входные кадры) из последнего сообщения WM_POINTERUPDATE .

Получив весь кадр сведений, приложение может затем вызвать функцию SkipPointerFrameMessages , чтобы пропустить оставшиеся сообщения указателя, связанные с этим кадром, ожидающие извлечения. Это позволяет приложению сэкономить затраты на получение и обработку оставшихся сообщений по одному. Однако функцию SkipPointerFrameMessages следует использовать с осторожностью и только в том случае, если вызывающий объект может быть уверен, что ни одна другая сущность в потоке вызывающего объекта не ожидает видеть остальные сообщения указателя по одному по мере их извлечения.

Фрейм содержит только указатели, которые в настоящее время принадлежат тому же окну, что и указанный указатель.

Полученные сведения представляют двумерный массив с одной строкой для каждой записи журнала и одним столбцом для каждого указателя в кадре.

Полученные сведения отображаются в обратном хронологическом порядке с последней записью в первой строке возвращаемого массива. Самая последняя запись совпадает с той, которая возвращается функцией GetPointerFrameInfo .

Если количество строк в предоставленном буфере недостаточно для хранения всех доступных записей журнала, эта функция завершается успешно с буфером, содержащим последние записи, и *entriesCount , содержащим общее количество доступных записей.

Если рамка указателя не содержит дополнительных указателей, кроме указанного указателя, эта функция выполняется успешно и возвращает только сведения для указанного указателя.

Если сведения, связанные с рамкой указателя, больше недоступны, эта функция завершается ошибкой с последней ошибкой ERROR_NO_DATA.

Если вызывающий поток не владеет окном (куда изначально были доставлены входные данные или куда было переадресовлено сообщение), в которое было доставлено сообщение указателя, эта функция завершается сбоем с последней ошибкой ERROR_ACCESS_DENIED.

Для приложений, имеющих как клиентские, так и не клиентские области, входной кадр может включать как клиентские, так и не клиентские данные. Чтобы различать данные клиента и данные, не относящиеся к клиенту, необходимо выполнить проверку попадания в целевом окне.

Если требуется отфильтровать данные из входного кадра, рекомендуется следующее:

• Для каждого обновления, не включающего контакт указателя ( POINTER_FLAG_UPDATE без POINTER_FLAG_INCONTACT), нажмите тест, чтобы определить, является ли входные данные клиентскими или не клиентскими.
• Для каждого нового контакта (POINTER_FLAG_DOWN) нажмите тест, чтобы определить, являются ли входные данные клиентскими или не клиентскими, и отслеживать эти сведения.
• Для каждого обновления, включающего контакт указателя ( POINTER_FLAG_UPDATE с POINTER_FLAG_INCONTACT), используйте сведения для отслеживания, чтобы определить, являются ли входные данные клиентскими или не клиентскими.
• Для каждого POINTER_FLAG_UP используйте сведения для отслеживания, чтобы определить, являются ли входные данные клиентскими или не клиентскими, а затем очистите этот указатель из данных отслеживания.

Требования

См. также

Функции

GetPointerFrameInfo

GetPointerInfo

GetPointerInfoHistory