GetPointerFrameInfoHistory-Funktion (winuser.h)

Ruft den gesamten Informationsrahmen (einschließlich zusammengekniffelter Eingabeframes) für die angegebenen Zeiger ab, die der aktuellen Nachricht zugeordnet sind.

Syntax

BOOL GetPointerFrameInfoHistory(
  [in]      UINT32       pointerId,
  [in, out] UINT32       *entriesCount,
  [in, out] UINT32       *pointerCount,
  [out]     POINTER_INFO *pointerInfo
);

Parameter

[in] pointerId

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

[in, out] entriesCount

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

[in, out] pointerCount

Ein Zeiger auf eine Variable, der die Anzahl der Spalten im zweidimensionalen Array angibt, auf das pointerInfo verweist. Wenn GetPointerFrameInfoHistory erfolgreich ist, wird pointerCount mit der Gesamtzahl der Zeiger in jedem Frame aktualisiert.

[out] pointerInfo

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

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

Rückgabewert

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

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 GetPointerFrameInfo zurückgegebenen Informationen sind der neuesten Zeigernachricht 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 GetPointerFrameInfoHistory , um den Nachrichtenverlauf (einschließlich zusammengeknockter Eingabeframes) aus der neuesten WM_POINTERUPDATE Nachricht abzurufen.

Nachdem der gesamte Datenrahmen abgerufen wurde, kann die Anwendung die SkipPointerFrameMessages-Funktion aufrufen, um die verbleibenden Zeigernachrichten zu überspringen, die diesem Frame zugeordnet sind und die ausstehend abgerufen werden. Dies spart der Anwendung den Mehraufwand beim Abrufen und Verarbeiten der verbleibenden Nachrichten nacheinander. Die SkipPointerFrameMessages-Funktion sollte jedoch sorgfältig und nur dann 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 mit dem letzten Eintrag in der ersten Zeile des zurückgegebenen Arrays angezeigt. Der neueste Eintrag ist mit dem von der GetPointerFrameInfo-Funktion zurückgegebenen Eintrag identisch.

Wenn die Anzahl der Zeilen im bereitgestellten Puffer nicht ausreicht, um alle verfügbaren Verlaufseinträge aufzunehmen, ist diese Funktion erfolgreich, wenn der Puffer die neuesten Einträge und *entriesCount enthält, die die Gesamtanzahl der verfügbaren Einträge enthält.

Wenn der Zeigerrahmen neben dem angegebenen Zeiger keine weiteren 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, wobei der letzte Fehler auf ERROR_NO_DATA festgelegt ist.

Wenn der aufrufende Thread nicht im Besitz des Fensters ist (in dem die Eingabe ursprünglich übermittelt wurde oder an 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.

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

Wenn Sie Daten aus dem Eingaberahmen filtern möchten, wird Folgendes empfohlen:

• Klicken Sie für jedes Update, das keinen Zeigerkontakt enthält (ein POINTER_FLAG_UPDATE ohne POINTER_FLAG_INCONTACT), um zu ermitteln, ob es sich bei der Eingabe um einen Client oder nicht um einen Client handelt.
• Klicken Sie für jeden neuen Kontakt (POINTER_FLAG_DOWN) auf Test, um zu ermitteln, ob die Eingabe Client oder Nicht-Client ist, und verfolgen Sie diese Informationen nach.
• 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 einen Client oder nicht um einen 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 (einschließlich Windows.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

GetPointerFrameInfo

GetPointerInfo

GetPointerInfoHistory