InjectTouchInput 関数 (winuser.h)

  • [アーティクル]

タッチ入力をシミュレートします。

NoteInitializeTouchInjection must precede any call to InjectTouchInput.

 

構文

BOOL InjectTouchInput(
  [in] UINT32                   count,
  [in] const POINTER_TOUCH_INFO *contacts
);

パラメーター

[in] count

連絡先の配列のサイズ。

count の最大値は、InitializeTouchInjection 関数の maxCount パラメーターによって指定されます。

[in] contacts

デスクトップ上のすべての連絡先を表す POINTER_TOUCH_INFO 構造体の配列。 各連絡先の画面座標は、デスクトップの境界内にある必要があります。

戻り値

関数が成功した場合、戻り値は 0 以外です。

関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

挿入された入力は、インジェクション プロセスが実行されているセッションのデスクトップに送信されます。

タッチ入力の挿入 (対話型とホバー) には、連絡先の pointerFlags の次の組み合わせによって示される 2 つの入力状態があります。

pointerFlags (POINTER_FLAG_*) Status
INRANGE |更新 タッチ ホバーの開始または移動
INRANGE |INCONTACT |ダウン 接触を下にタッチする
INRANGE |INCONTACT |更新 タッチ接触の移動
INRANGE |を タッチ接触を上にしてホバーに切り替える
UPDATE タッチ ホバーの終了
UP タッチエンド
 
メモ 対話型状態は、画面上にあり、タッチ対応アプリと対話できるタッチ連絡先を表します。 ホバー状態は、画面に接触せず、アプリケーションと対話できないタッチ入力を表します。 タッチ インジェクションはホバーまたは対話型の状態で開始できますが、状態は INRANGE を介してのみ切り替えることができます |INCONTACT |対話型の状態にポインターを合わせる場合は DOWN、INRANGE を使用する場合は |対話型のホバー状態の場合は UP。
 
すべてのタッチ インジェクション シーケンスは、UPDATE または UP で終了します。

次の図は、ホバー状態で始まり、対話型に遷移し、ホバーで終了するタッチ インジェクション シーケンスを示しています。

ホバーから対話型からホバーへの状態遷移を示すタッチ インジェクション シーケンスの図。

長押しジェスチャの場合は、入力が取り消されないように複数のフレームを送信する必要があります。 ポイント (x,y) を長押しする場合は、ポイント (x,y) で WM_POINTERDOWN を送信し、その後にポイント (x,y) に WM_POINTERUPDATE メッセージを送信します。

WM_DISPLAYCHANGEをリッスンして、ディスプレイの解像度と向きの変更を処理し、画面座標の更新を管理します。 WM_DISPLAYCHANGEを受信すると、すべてのアクティブな連絡先が取り消されます。

POINTER_FLAG_UPまたはPOINTER_FLAG_UPDATEでPOINTER_FLAG_CANCELEDを設定して、個々の連絡先をキャンセルします。 POINTER_FLAG_UPやPOINTER_FLAG_UPDATEを使用せずにタッチインジェクションをキャンセルすると、インジェクションが無効になります。

POINTER_FLAG_UPが設定されている場合、 POINTER_INFO の ptPixelLocation は、POINTER_FLAG_UPDATEを持つ前のタッチ インジェクション フレームの値と同じである必要があります。 それ以外の場合は、ERROR_INVALID_PARAMETERでインジェクションが失敗し、アクティブなすべてのインジェクション接触が取り消されます。 システムは、挿入をキャンセルする WM_POINTERUP イベントの ptPixelLocation を変更します。

入力タイムスタンプは、 POINTER_INFOの dwTime フィールドまたは PerformanceCount フィールドで指定できます。 この値は、現在のティック数または挿入スレッドの QueryPerformanceCounter 値より新しい値にすることはできません。 フレームにタイムスタンプが挿入されたら、フレーム内のすべての連絡先が UP 状態になるまで、後続のすべてのフレームにタイムスタンプを含める必要があります。 連絡先配列の最初の要素には、カスタム タイムスタンプ値を指定する必要があります。 最初の要素の後のタイムスタンプ値は無視されます。 カスタム タイムスタンプ値は、挿入フレームごとにインクリメントする必要があります。

PerformanceCount フィールドを指定すると、タイムスタンプは実際の挿入時に .1 ミリ秒の解像度で現在の時刻に変換されます。 カスタム PerformanceCount の結果、前回の挿入と同じ .1 ミリ秒のウィンドウになった場合、API はエラー (ERROR_NOT_READY) を返し、データを挿入しません。 挿入はエラーによってすぐに無効になりませんが、次に成功した挿入には、以前に成功した挿入から少なくとも 0.1 ミリ秒離れた PerformanceCount 値が必要です。 同様に、ユーザー設定の dwTime 値は、フィールドが使用された場合、少なくとも 1 ミリ秒離れている必要があります。

インジェクション パラメーターに dwTime と PerformanceCount の両方が指定されている場合、 InjectTouchInput はエラー コード (ERROR_INVALID_PARAMETER) で失敗します。 インジェクション アプリケーションが dwTime パラメーターまたは PerformanceCount パラメーターで開始されたら、タイムスタンプ フィールドに正しく入力する必要があります。 インジェクション シーケンスが開始されると、ユーザー設定のタイムスタンプ フィールドを切り替えることはできません。

dwTime 値も PerformanceCount 値も指定されていない場合、 InjectTouchInput は API 呼び出しのタイミングに基づいてタイムスタンプを割り当てます。 呼び出しが 0.1 ミリ秒未満の場合、API はエラー (ERROR_NOT_READY) を返す可能性があります。 エラーによって入力がすぐに無効になるわけではありませんが、インジェクション アプリケーションは、挿入が成功するように同じフレームをもう一度再試行する必要があります。

要件

   
サポートされている最小のクライアント Windows 8 [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2012 [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー winuser.h
Library User32.lib
[DLL] User32.dll
API セット ext-ms-win-rtcore-ntuser-wmpointer-l1-1-0 (Windows 10 バージョン 10.0.14393 で導入)

関連項目

関数