GetPointerFrameTouchInfoHistory

現在のメッセージに関連付けられた指定ポインタ(PT_TOUCH 型)のタッチベースのフレーム情報全体(統合された入力フレームを含む)を取得する。

GetPointerFrameTouchInfoHistory pointerId, entriesCount, pointerCount, touchInfo

pointerId : [int] フレーム情報を取得する対象のポインタ識別子。
entriesCount : [var] touchInfo が指す 2 次元配列の行数を指定する変数へのポインタ。GetPointerFrameTouchInfoHistory が成功した場合、履歴で利用可能なフレーム総数で entriesCount が更新される。
pointerCount : [var] touchInfo が指す 2 次元配列の列数を指定する変数へのポインタ。GetPointerFrameTouchInfoHistory が成功した場合、各フレーム内のポインタ総数で pointerCount が更新される。
touchInfo : [var] ポインタ情報を受け取る POINTER_TOUCH_INFO 構造体の 2 次元配列のアドレス。*entriesCount と *pointerCount の両方がゼロの場合は NULL でもよい。配列は POINTER_TOUCH_INFO[*entriesCount][*pointerCount] として解釈される。

(プラグイン / モジュール : user32.dll)

解説

現在のメッセージに関連付けられた指定ポインタ(PT_TOUCH
型)のタッチベースのフレーム情報全体(統合された入力フレームを含む)を取得する。

[戻り値]
関数が成功した場合、戻り値は非ゼロである。関数が失敗した場合、戻り値はゼロである。拡張エラー情報を取得するには GetLastError
を呼ぶ。

[備考]
並列モードデバイスは、複数ポインタの状態と位置を 1
つの入力レポートとしてシステムに報告することがある。原則としてアプリケーションはフレーム全体を 1
つの入力単位として扱うべきである。GetPointerFrameTouchInfo
が返す情報は呼び出しスレッドがもっとも最近取得したポインタ(PT_TOUCH)メッセージに関連付けられており、次のメッセージが取得されると失われる可能性がある。アプリケーションがポインタ入力メッセージを生成速度ほど速く処理できない場合、一部のメッセージが
WM_POINTERUPDATE メッセージに統合されることがある。統合された入力フレームを含むメッセージ履歴を直近の
WM_POINTERUPDATE メッセージから取得するには GetPointerFrameTouchInfoHistory
を使用する。フレーム全体を取得した後は SkipPointerFrameMessages
を呼んで残りのポインタメッセージをスキップできる。ただし SkipPointerFrameMessages
は同一スレッドの他のエンティティが個別にメッセージを受け取ることを期待していないと確実な場合にのみ慎重に使うべきである。フレームには、指定ポインタと同じウィンドウが現在所有するポインタのみが含まれる。取得される情報は
2 次元配列として表され、履歴エントリごとに 1 行、フレーム内のポインタごとに 1
列となる。取得される情報は逆時系列順で、最新エントリが配列の 1 行目に入る。最新エントリは
GetPointerFrameTouchInfo
が返すものと同じである。提供バッファの行数が利用可能な履歴エントリ全部を収めるのに不十分な場合、関数は成功し、バッファには最新エントリ群が入り、*entriesCount
には利用可能なエントリ総数が入る。

フレームに指定ポインタ以外のポインタが含まれない場合、関数は成功して指定ポインタの情報のみを返す。フレーム情報がもう利用できない場合、関数は失敗し最終エラーが
ERROR_NO_DATA
に設定される。呼び出しスレッドがポインタメッセージが配信されたウィンドウ(あるいは転送先ウィンドウ)を所有していない場合、関数は失敗し最終エラーが
ERROR_ACCESS_DENIED に設定される。指定ポインタが PT_TOUCH 型でない場合、関数は失敗し最終エラーが
ERROR_DATATYPE_MISMATCH に設定される。

クライアント領域と非クライアント領域の両方を持つアプリでは、入力フレームに両方のデータが含まれることがある。両者を区別するには対象ウィンドウに対してヒットテストを行う必要がある。入力フレームからデータを絞り込みたい場合は次を推奨する。
（以下省略）

情報