InjectTouchInput-Funktion (winuser.h)

Simuliert toucheingaben.

HinweisInitializeTouchInjection muss jedem Aufruf von InjectTouchInput vorangehen.

 

Syntax

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

Parameter

[in] count

Die Größe des Arrays in Kontakten.

Der maximale Wert für count wird durch den maxCount-Parameter der InitializeTouchInjection-Funktion angegeben.

[in] contacts

Array von POINTER_TOUCH_INFO Strukturen, die alle Kontakte auf dem Desktop darstellen. Die Bildschirmkoordinaten jedes Kontakts müssen innerhalb der Grenzen des Desktops sein.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich 0 (null).

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Die eingefügte Eingabe wird an den Desktop der Sitzung gesendet, auf der der Einschleusungsprozess ausgeführt wird.

Es gibt zwei Eingabezustände für die Toucheingabeeinschleusung (interaktiv und Hover), die durch die folgenden Kombinationen von Zeigerflags in Kontakten angegeben werden:

pointerFlags (POINTER_FLAG_*)	Status
INRANGE | AKTUALISIEREN	Fingerzeiger wird gestartet oder bewegt
INRANGE | INCONTACT | NACH UNTEN	Kontakt nach unten
INRANGE | INCONTACT | AKTUALISIEREN	Touchkontaktverschiebungen
INRANGE | OBEN	Touchkontakt nach oben und Übergang zum Zeigen
UPDATE	Ende des Fingerzeigers
UP	Touchenden

 

Hinweis Der interaktive Zustand stellt einen Touchkontakt dar, der sich auf dem Bildschirm befindet und mit jeder touchfähigen App interagieren kann. Der Mauszeigerzustand stellt toucheingaben dar, die nicht mit dem Bildschirm in Kontakt stehen und nicht mit Anwendungen interagieren können. Die Fingereingabeeinschleusung kann im Hover- oder interaktiven Zustand beginnen, aber der Zustand kann nur über INRANGE | INCONTACT | NACH-UNTEN, um auf den interaktiven Zustand zu zeigen, oder über INRANGE | UP für den interaktiven Hoverzustand.

 

Alle Touch-Injektionssequenzen enden entweder mit UPDATE oder UP.

Das folgende Diagramm zeigt eine Toucheingabe-Sequenz, die mit einem Hoverzustand beginnt, in interaktiv übergeht und mit dem Hover endet.

Für Gedrückthalten-Gesten müssen mehrere Frames gesendet werden, um sicherzustellen, dass die Eingabe nicht abgebrochen wird. Wenn Sie am Punkt (x,y) gedrückt halten möchten, senden Sie WM_POINTERDOWN an Punkt (x,y), gefolgt von WM_POINTERUPDATE Nachrichten an Punkt(x,y).

Achten Sie auf WM_DISPLAYCHANGE , um Änderungen an der Anzeigeauflösung und -ausrichtung zu behandeln und Aktualisierungen der Bildschirmkoordinate zu verwalten. Alle aktiven Kontakte werden abgebrochen, wenn ein WM_DISPLAYCHANGE empfangen wird.

Brechen Sie einzelne Kontakte ab, indem Sie POINTER_FLAG_CANCELED mit POINTER_FLAG_UP oder POINTER_FLAG_UPDATE festlegen. Das Abbrechen der Fingereingabeeinspritzung ohne POINTER_FLAG_UP oder POINTER_FLAG_UPDATE entfällt die Injektion.

Wenn POINTER_FLAG_UP festgelegt ist, sollte ptPixelLocation von POINTER_INFO mit dem Wert des vorherigen Toucheinschleusungsrahmens mit POINTER_FLAG_UPDATE identisch sein. Andernfalls schlägt die Injektion mit ERROR_INVALID_PARAMETER fehl, und alle aktiven Injektionskontakte werden abgebrochen. Das System ändert die ptPixelLocation des WM_POINTERUP-Ereignisses , während die Einschleusung abgebrochen wird.

Der Eingabezeitstempel kann entweder im Feld dwTime oder PerformanceCount von POINTER_INFO angegeben werden. Der Wert darf nicht aktueller sein als die aktuelle Teilstrichanzahl oder der QueryPerformanceCounter-Wert des Injektionsthreads. Sobald ein Frame mit einem Zeitstempel eingefügt wurde, müssen alle nachfolgenden Frames einen Zeitstempel enthalten, bis alle Kontakte im Frame in den UP-Zustand wechseln. Der benutzerdefinierte Zeitstempelwert muss für das erste Element im Kontaktearray bereitgestellt werden. Die Zeitstempelwerte nach dem ersten Element werden ignoriert. Der benutzerdefinierte Zeitstempelwert muss in jedem Injektionsrahmen inkrementiert werden.

Wenn ein PerformanceCount-Feld angegeben wird, wird der Zeitstempel bei der tatsächlichen Injektion in die aktuelle Zeit in einer Auflösung von 1 Millisekunden konvertiert. Wenn ein benutzerdefinierter PerformanceCount zu demselben 1-Millisekunden-Fenster wie bei der vorherigen Injektion geführt hat, gibt die API einen Fehler (ERROR_NOT_READY) zurück und fügt die Daten nicht ein. Während die Injektion durch den Fehler nicht sofort für ungültig erklärt wird, muss die nächste erfolgreiche Injektion den PerformanceCount-Wert aufweisen, der mindestens 0,1 Millisekunden abgesehen von der zuvor erfolgreichen Injektion beträgt. Entsprechend muss ein benutzerdefinierter dwTime-Wert mindestens 1 Millisekunde auseinander liegen, wenn das Feld verwendet wurde.

Wenn sowohl dwTime als auch PerformanceCount im Injection-Parameter angegeben sind, schlägt InjectTouchInput mit einem Fehlercode (ERROR_INVALID_PARAMETER) fehl. Sobald die Injektionsanwendung mit einem dwTime- oder PerformanceCount-Parameter beginnt, muss das Zeitstempelfeld ordnungsgemäß ausgefüllt werden. Die Injektion kann das benutzerdefinierte Zeitstempelfeld nach dem Start der Injektionssequenz nicht mehr in ein anderes ändern.

Wenn keine dwTime- oder PerformanceCount-Werte angegeben werden, ordnet InjectTouchInput den Zeitstempel basierend auf dem Zeitpunkt des API-Aufrufs zu. Wenn die Aufrufe weniger als 0,1 Millisekunden voneinander entfernt sind, gibt die API möglicherweise einen Fehler (ERROR_NOT_READY) zurück. Durch den Fehler wird die Eingabe nicht sofort ungültig, aber die Einschleusungsanwendung muss denselben Frame erneut versuchen, um sicherzustellen, dass die Einschleusung erfolgreich ist.

Anforderungen

Unterstützte Mindestversion (Client)	Windows 8 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winuser.h
Bibliothek	User32.lib
DLL	User32.dll
APIs	ext-ms-win-rtcore-ntuser-wmpointer-l1-1-0 (eingeführt in Windows 10, Version 10.0.14393)

Siehe auch

Funktionen