GetPointerFrameTouchInfoHistory-Funktion (winuser.h)

Ruft den gesamten Frame der touchbasierten Informationen (einschließlich zusammengekniffelter Eingabeframes) für die angegebenen Zeiger (vom Typ PT_TOUCH) ab, die der aktuellen Nachricht zugeordnet sind.

Syntax

BOOL GetPointerFrameTouchInfoHistory(
  [in]      UINT32             pointerId,
  [in, out] UINT32             *entriesCount,
  [in, out] UINT32             *pointerCount,
  [out]     POINTER_TOUCH_INFO *touchInfo
);

Parameter

[in] pointerId

Ein Bezeichner des Zeigers, für den Frameinformationen abgerufen werden sollen.

[in, out] entriesCount

Ein Zeiger auf die Variable, der die Anzahl der Zeilen im zweidimensionalen Array angibt, auf das touchInfo zeigt. Wenn GetPointerFrameTouchInfoHistory erfolgreich ist, wird entriesCount mit der Gesamtanzahl der im Verlauf verfügbaren Frames aktualisiert.

[in, out] pointerCount

Ein Zeiger auf eine Variable, die die Anzahl der Spalten im zweidimensionalen Array angibt, auf das touchInfo zeigt. Wenn GetPointerFrameTouchInfoHistory erfolgreich ist, wird pointerCount mit der Gesamtanzahl der Zeiger in jedem Frame aktualisiert.

[out] touchInfo

Adresse eines zweidimensionalen Arrays von POINTER_TOUCH_INFO Strukturen, um die Zeigerinformationen zu empfangen. Dieser Parameter kann NULL sein, wenn *entriesCount und *pointerCount beide null sind.

Dieses Array wird als POINTER_TOUCH_INFO[*entriesCount][*pointerCount]interpretiert.

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

Geräte im Parallelmodus können Zeigereingaben in Frames melden, d. h., sie können den Zustand und die Position aller Zeiger von diesem Gerät in einem einzelnen Eingabebericht an das System melden. Im Idealfall sollten Anwendungen den gesamten Frame als einzelne Eingabe anzeigen, es sei denn, die anwendungsspezifischen Anforderungen sehen etwas anderes vor.

Die von GetPointerFrameTouchInfo zurückgegebenen Informationen sind der letzten Zeigernachricht (PT_TOUCH) zugeordnet, die vom aufrufenden Thread abgerufen wurde. Wenn die nächste Nachricht vom aufrufenden Thread abgerufen wird, sind die Informationen, die der vorherigen Nachricht zugeordnet sind, möglicherweise nicht mehr verfügbar.

Wenn die Anwendung Zeigereingabenachrichten nicht so schnell verarbeitet, wie sie generiert werden, werden einige Nachrichten möglicherweise zu einer WM_POINTERUPDATE Nachricht zusammengefasst. Verwenden Sie GetPointerFrameTouchInfoHistory , um den Nachrichtenverlauf (einschließlich zusammengeknockter Eingabeframes) aus der letzten WM_POINTERUPDATE-Nachricht abzurufen.

Nachdem sie den gesamten Datenrahmen abgerufen hat, kann die Anwendung dann die SkipPointerFrameMessages-Funktion aufrufen, um die verbleibenden Zeigermeldungen zu überspringen, die diesem Frame zugeordnet sind und ausstehen. Dies spart der Anwendung den Mehraufwand beim Abrufen und Verarbeiten der verbleibenden Nachrichten nacheinander. Die SkipPointerFrameMessages-Funktion sollte jedoch mit Sorgfalt und nur verwendet werden, wenn der Aufrufer sicher sein kann, dass keine andere Entität im Thread des Aufrufers erwartet, dass die verbleibenden Zeigernachrichten nacheinander angezeigt werden, wenn sie abgerufen werden.

Der Frame enthält nur Zeiger, die sich derzeit im Besitz desselben Fensters wie der angegebene Zeiger befinden.

Die abgerufenen Informationen stellen ein zweidimensionales Array mit einer Zeile für jeden Verlaufseintrag und einer Spalte für jeden Zeiger im Frame dar.

Die abgerufenen Informationen werden in umgekehrter chronologischer Reihenfolge angezeigt, wobei der letzte Eintrag in der ersten Zeile des zurückgegebenen Arrays enthalten ist. Der letzte Eintrag entspricht dem eintrag, der von der GetPointerFrameTouchInfo-Funktion zurückgegeben wurde.

Wenn die Anzahl der Zeilen im bereitgestellten Puffer nicht ausreicht, um alle verfügbaren Verlaufseinträge zu speichern, ist diese Funktion erfolgreich, wobei der Puffer die letzten Einträge und *entriesCount die Gesamtzahl der verfügbaren Einträge enthält.

Wenn der Zeigerrahmen neben dem angegebenen Zeiger keine zusätzlichen Zeiger enthält, ist diese Funktion erfolgreich und gibt nur die Informationen für den angegebenen Zeiger zurück.

Wenn die dem Zeigerrahmen zugeordneten Informationen nicht mehr verfügbar sind, schlägt diese Funktion fehl, wenn der letzte Fehler auf ERROR_NO_DATA festgelegt ist.

Wenn der aufrufende Thread nicht der Besitzer des Fensters ist (in dem die Eingabe ursprünglich übermittelt wurde oder in dem die Nachricht weitergeleitet wurde), an das die Zeigernachricht übermittelt wurde, schlägt diese Funktion fehl, wobei der letzte Fehler auf ERROR_ACCESS_DENIED festgelegt ist.

Wenn der angegebene Zeiger nicht vom Typ PT_TOUCH ist, schlägt diese Funktion fehl, wobei der letzte Fehler auf ERROR_DATATYPE_MISMATCH festgelegt ist.

Für Apps, die sowohl Client- als auch Nicht-Client-Bereiche haben, kann der Eingaberahmen sowohl Clientdaten als auch Nicht-Clientdaten enthalten. Um zwischen Client- und Nichtclientdaten zu unterscheiden, müssen Sie Treffertests im Zielfenster durchführen.

Wenn Sie Daten aus dem Eingaberahmen filtern möchten, empfehlen wir Folgendes:

• Für jedes Update, das keinen Zeigerkontakt (eine POINTER_FLAG_UPDATE ohne POINTER_FLAG_INCONTACT) enthält, wird ein Treffertest durchgeführt, um zu ermitteln, ob es sich bei der Eingabe um einen Client oder nicht um einen Client handelt.
• Treffertest für jeden neuen Kontakt (POINTER_FLAG_DOWN), um festzustellen, ob die Eingabe client- oder nicht clientseitig ist, und verfolgen Sie diese Informationen.
• Verwenden Sie für jedes Update, das einen Zeigerkontakt (eine POINTER_FLAG_UPDATE mit POINTER_FLAG_INCONTACT) enthält, die Nachverfolgungsinformationen, um zu bestimmen, ob es sich bei der Eingabe um einen Client oder nicht um einen Client handelt.
• Verwenden Sie für jeden POINTER_FLAG_UP die Nachverfolgungsinformationen, um zu bestimmen, ob es sich bei der Eingabe um Client oder Nicht-Client handelt, und löschen Sie dann diesen Zeiger aus den Nachverfolgungsdaten.

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 (windows.h einschließen)
Bibliothek	User32.lib
DLL	User32.dll

Siehe auch

Funktionen

GetPointerFrameTouchInfo

GetPointerTouchInfo

GetPointerTouchInfoHistory