GetPointerFrameInfo 関数 (winuser.h)
現在のメッセージに関連付けられている指定されたポインターの情報フレーム全体を取得します。
構文
BOOL GetPointerFrameInfo(
[in] UINT32 pointerId,
[in, out] UINT32 *pointerCount,
[out] POINTER_INFO *pointerInfo
);
パラメーター
[in] pointerId
フレーム情報を取得するポインターの識別子。
[in, out] pointerCount
pointerInfo が指すバッファー内の構造体の数を指定する変数へのポインター。 GetPointerFrameInfo が成功した場合、pointerCount はフレーム内のポインターの合計数で更新されます。
[out] pointerInfo
ポインター情報を受け取 るPOINTER_INFO 構造体の配列のアドレス。 *pointerCount が 0 の場合、このパラメーターは NULL にすることができます。
戻り値
関数が成功した場合、戻り値は 0 以外です。
関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
並列モード デバイスは、フレーム内のポインター入力を報告する場合があります。つまり、1 つの入力レポート内のデバイスからのすべてのポインターの状態と位置をシステムに報告できます。 アプリケーション固有の要件で特に指示がない限り、アプリケーションはフレーム全体を 1 つの入力として表示することをお勧めします。
GetPointerFrameInfo は、ポインター メッセージに関連付けられているポインター入力フレーム全体を取得します。 GetPointerInfo を使用して、ポインター メッセージに関連付けられている 1 つのポインターの情報を取得します。
フレームには、指定したポインターと同じウィンドウによって現在所有されているポインターのみが含まれます。
GetPointerFrameInfo によって返される情報は、呼び出し元のスレッドによって取得された最新のポインター メッセージに関連付けられます。 呼び出し元のスレッドによって次のメッセージが取得されると、前のメッセージに関連付けられている情報が使用できなくなる可能性があります。
アプリケーションがポインター入力メッセージを生成ほど速く処理しない場合は、一部のメッセージが WM_POINTERUPDATE メッセージに結合される可能性があります。 GetPointerFrameInfoHistory を使用して、最新のWM_POINTERUPDATE メッセージからメッセージ履歴を取得します。
情報のフレーム全体を取得すると、アプリケーションは SkipPointerFrameMessages 関数を呼び出して、取得待ちのこのフレームに関連付けられている残りのポインター メッセージをスキップできます。 これにより、残りのメッセージを 1 つずつ取得して処理するオーバーヘッドがアプリケーションに節約されます。 ただし、 SkipPointerFrameMessages 関数は慎重に使用する必要があります。呼び出し元は、呼び出し元のスレッド上の他のエンティティが、取得時に残りのポインター メッセージを 1 つずつ表示することを期待していないことを確認できる場合にのみ使用してください。
取得された情報は、呼び出し元のスレッドによって最後に取得されたポインター フレームに関連付けられていることに注意してください。 呼び出し元のスレッドが次のメッセージを取得すると、前のポインター フレームに関連付けられている情報が使用できなくなる可能性があります。
ポインター フレームに、指定したポインター以外に追加のポインターが含まれない場合、この関数は成功し、指定されたポインターの情報のみを返します。
ポインター フレームに関連付けられている情報が使用できなくなった場合、この関数は最後のエラーが ERROR_NO_DATA に設定されて失敗します。
呼び出し元のスレッドが、ポインター メッセージが配信されたウィンドウ (入力が最初に配信されたウィンドウ、またはメッセージが転送された場所) を所有していない場合、この関数は最後のエラーを ERROR_ACCESS_DENIED に設定して失敗します。
クライアント領域とクライアント以外の領域の両方を持つアプリの場合、入力フレームにはクライアントデータとクライアント以外のデータの両方を含めることができます。 クライアント データとクライアント以外のデータを区別するには、ターゲット ウィンドウでヒット テストを実行する必要があります。
入力フレームからデータをフィルター処理する場合は、次のことをお勧めします。
- ポインターの接触 (POINTER_FLAG_INCONTACTのないPOINTER_FLAG_UPDATE) を含まない更新ごとに、ヒット テストを実行して、入力がクライアントかクライアント以外かを判断します。
- 新しい連絡先 (POINTER_FLAG_DOWN) ごとに、ヒット テストを実行して、入力がクライアントかクライアント以外かを判断し、この情報を追跡します。
- ポインターの連絡先 (POINTER_FLAG_INCONTACTを含むPOINTER_FLAG_UPDATE) を含む更新ごとに、追跡情報を使用して、入力がクライアントか非クライアントかを判断します。
- POINTER_FLAG_UPごとに、追跡情報を使用して入力がクライアントか非クライアントかを判断し、追跡データからこのポインターをクリアします。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 8 [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2012 [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | winuser.h (Windows.h を含む) |
| Library | User32.lib |
| [DLL] | User32.dll |