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