GetPointerFrameInfo-Funktion (winuser.h)

Ruft den gesamten Informationsrahmen für die angegebenen Zeiger ab, die der aktuellen Nachricht zugeordnet sind.

Syntax

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

Parameter

[in] pointerId

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

[in, out] pointerCount

Ein Zeiger auf eine Variable, die die Anzahl der Strukturen im Puffer angibt, auf die pointerInfo verweist. Wenn GetPointerFrameInfo erfolgreich ist, wird pointerCount mit der Gesamtzahl der Zeiger im Frame aktualisiert.

[out] pointerInfo

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

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.

GetPointerFrameInfo ruft den gesamten Zeigereingaberahmen ab, der einer Zeigernachricht zugeordnet ist. Verwenden Sie GetPointerInfo , um Informationen für einen einzelnen Zeiger abzurufen, der einer Zeigernachricht zugeordnet ist.

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

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 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.

Beachten Sie, dass die abgerufenen Informationen dem zuletzt vom aufrufenden Thread abgerufenen Zeigerrahmen zugeordnet sind. Sobald der aufrufende Thread seine nächste Nachricht abgerufen hat, sind die Informationen, die dem vorherigen Zeigerrahmen zugeordnet sind, möglicherweise nicht mehr verfügbar.

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

Anforderung	Wert
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

Siehe auch

Funktionen

GetPointerFrameInfoHistory

GetPointerInfo

GetPointerInfoHistory