Interpretieren von HID-Berichten

Artikel
06/15/2023

In diesem Abschnitt wird beschrieben, wie Benutzermodusanwendungen und Kernelmodustreiber die HidP_XxxHIDClass-Unterstützungsroutinen verwenden, um Steuerungsdaten in einem HID-Bericht zu interpretieren.

Extrahieren von Wertdaten durch Angeben ihrer Verwendung

Um Wertdaten aus einem HID-Bericht zu extrahieren, kann eine Anwendung oder ein Treiber eine der folgenden HID-Supportroutinen verwenden:

HidP_GetScaledUsageValue Gibt einen signierten und skalierten Wert zurück.
HidP_GetUsageValue Gibt einen nicht skalierten Wert in einem Format ohne Vorzeichen oder einen skalierten Wert zurück, der außerhalb des Normalen Bereichs liegt.
HidP_GetUsageValueArray Gibt ein Verwendungswertarray zurück.

Um HidP_GetUsageValueArray Anwendungen und Treiber zu verwenden, müssen Sie einen nullinitialisierten Puffer zuordnen, der groß genug ist, um das Verwendungswertarray zu enthalten. Die erforderliche Größe in Bytes ist das Produkt der BitSize - und ReportCount-Member der HIDP_VALUE_CAPS-Struktur des Verwendungswertarrays, aufgerundet auf das nächste Byte.

Extrahieren von Schaltflächenverwendungen, die auf ON festgelegt sind

Um die HID-Verwendung von Schaltflächen zu extrahieren, die auf ON (1) festgelegt sind, rufen Anwendungen und Treiber eine der folgenden HID-Supportroutinen auf:

HidP_GetButtons (oder HidP_GetUsages) gibt die Nutzungs-ID aller Schaltflächen auf einer angegebenen Nutzungsseite zurück, die auf ON festgelegt sind.
HidP_GetButtonsEx (oder HidP_GetUsagesEx) gibt die Nutzungsseite und die Nutzungs-ID aller Schaltflächen zurück, die auf ON festgelegt sind.

Diese Routinen geben ein Array aller Nutzungsinformationen für alle Schaltflächen zurück, die derzeit auf ON festgelegt sind. Implizit werden Schaltflächen, deren Verwendung von diesen Routinen nicht zurückgegeben wird, auf OFF (null) festgelegt.

Um diese Routinen aufzurufen, müssen Anwendungen und Treiber zuerst den Puffer zuordnen und null initialisieren, der verwendet wird, um das Array von Schaltflächennutzungen zurückzugeben. Eine Anwendung oder ein Treiber ruft HidP_MaxUsageListLength auf, um die Anzahl der Schaltflächennutzungen auf einer angegebenen Nutzungsseite im Bericht zu bestimmen. Wenn die Anwendung oder der Treiber eine Nutzungsseite von 0 (null) angibt, gibt die Routine die Anzahl aller Schaltflächennutzungen im Bericht zurück.

Die erforderliche Puffergröße in Bytes lautet wie folgt:

(Für HidP_GetButtons) Der von HidP_MaxUsageListLength mal sizeof(USAGE) zurückgegebene Wert
(Für HidP_GetButtonsEx) Der von HidP_MaxUsageListLength mal sizeof(USAGE_AND_PAGE) zurückgegebene Wert

Nachdem eine Anwendung oder ein Treiber diese Routinen verwendet hat, um Informationen darüber zu erhalten, welche Schaltflächen derzeit auf EIN festgelegt sind, kann sie den Unterschied zwischen dem aktuellen Zustand und dem vorherigen Zustand der Schaltflächen ermitteln, indem eine der folgenden HIDClass-Unterstützungsroutinen aufgerufen wird. Diese Routinen geben den Unterschied zwischen zwei Arrays von Nutzungsinformationen zurück:

Extrahieren und Festlegen von Steuerelementdaten nach Datenindizes

Um Datenindizes zum Extrahieren und Festlegen von Steuerungsdaten in einem HID-Bericht zu verwenden, kann eine Anwendung oder ein Treiber die folgenden HIDClass-Unterstützungsroutinen verwenden:

Diese Routinen sind besonders nützlich für eine Anwendung oder einen Treiber, der einen "Mehrwert"-Dienst bereitstellt. Ein Beispiel, das eine benutzerdefinierte Schnittstelle für alle Steuerelemente bereitstellt, die von einem HIDClass-Gerät unterstützt werden. Microsoft DirectInput ist ein Beispiel.

Durch aufrufen dieser Routinen kann eine Anwendung oder ein Treiber alle Werte in einem Bericht am effizientesten abrufen und festlegen. Um beispielsweise alle Wertdaten anhand ihrer HID-Verwendungen abzurufen, muss für jede Verwendung HidP_GetUsageValue aufgerufen werden. Um jedoch alle Wertdaten nach Datenindex abzurufen, muss HidP_GetData nur einmal aufgerufen werden.

Eine Anwendung oder ein Treiber verwendet die Datenindizes, die in den Schaltflächenfunktionsarrays und Wertfunktionsarrays einer Sammlung angegeben sind, um HID-Verwendungen zu identifizieren.

Festlegen von Wertdaten durch Angeben der Verwendung

Eine Anwendung oder ein Treiber kann einen Wert in einem ordnungsgemäß initialisierten HID-Bericht festlegen, indem eine der folgenden HID-Unterstützungsroutinen aufgerufen wird:

HidP_SetScaledUsageValue Legt einen signierten und skalierten Wert in einem Bericht fest.
HidP_SetUsageValue Legt einen Wert in einem Bericht fest.
HidP_SetUsageValueArray Legt ein Verwendungswertarray in einem Bericht fest.

Festlegen des Schaltflächenzustands durch Angeben der Verwendung

Eine Anwendung oder ein Treiber kann den Status von Schaltflächen in einem ordnungsgemäß initialisierten HID-Bericht festlegen, indem eine der folgenden HIDClass-Supportroutinen aufgerufen wird:

HidP_SetButtons (oder HidP_SetUsages) Legt einen angegebenen Satz von Schaltflächen auf ON (1) fest.
HidP_UnsetButtons (oder HidP_UnsetUsages) Legt einen angegebenen Satz von Schaltflächen auf OFF (null) fest.

Extrahieren und Festlegen von HID-Steuerungsdaten nach Datenindizes

Um Datenindizes zum Extrahieren und Festlegen von Steuerungsdaten in einem HID-Bericht zu verwenden, kann eine Anwendung oder ein Treiber die folgenden HIDClass-Unterstützungsroutinen verwenden:

Durch aufrufen dieser Routinen kann eine Anwendung oder ein Treiber alle Werte in einem Bericht am effizientesten abrufen und festlegen. Um beispielsweise alle Wertdaten durch ihre HID-Verwendungen abzurufen, muss für jede Verwendung HidP_GetUsageValue aufgerufen werden. Um jedoch alle Wertdaten nach Datenindex abzurufen, muss HidP_GetData nur einmal aufgerufen werden.

Eine Anwendung oder ein Treiber verwendet die Datenindizes, die in den Schaltflächenfunktionsarrays und Wertfunktionsarrays einer Sammlung angegeben sind, um HID-Verwendungen zu identifizieren.

Weitere Informationen

Initialisieren von HID-Berichten

Freigeben über