Interpretieren von HID-Berichten

Dieser Artikel beschreibt, wie Benutzermodusanwendungen und Kernelmodustreiber die HIDClass-Unterstützungsroutinen HidP_Xxx verwenden, um Steuerdaten in einem HID-Bericht zu interpretieren.

Extrahieren von Wertdaten durch Angeben der 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 vorzeichenlosen Format oder einen skalierten Wert zurück, der sich außerhalb des Normalbereichs befindet.
• HidP_GetUsageValueArray gibt ein Nutzungswertarray zurück.

Um HidP_GetUsageValueArray zu verwenden, müssen Anwendungen und Treiber einen mit Null initialisierten Puffer zuordnen, der groß genug ist, um das Nutzungswert-Array aufzunehmen. Die erforderliche Größe in Byte ist das Produkt aus den Mitgliedern BitSize und ReportCount der HIDP_VALUE_CAPS-Struktur des Verwendungswertarrays, auf das nächste Byte aufgerundet.

Extrahieren von Schaltflächenverwendungen, die auf EIN festgelegt sind

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

• HidP_GetButtons (oder HidP_GetUsages) gibt die Benutzer-ID aller Schalter auf einer angegebenen Verwendungsseite zurück, die auf EIN festgelegt sind.
• HidP_GetButtonsEx (oder HidP_GetUsagesEx) gibt die Usage Page und die Usage ID aller Schaltflächen zurück, die auf EIN festgelegt sind.

Diese Routinen geben ein Array mit allen Verwendungsinformationen für alle Schaltflächen zurück, die aktuell auf EIN eingestellt sind. Implizit werden Schaltflächen, deren Verwendung von diesen Routinen nicht zurückgegeben wird, auf AUS (Null) gesetzt.

Um diese Routinen aufzurufen, müssen Anwendungen und Treiber zuerst den Puffer zuordnen und auf Null initialisieren, der zum Zurückgeben des Arrays der Schaltflächenverwendungen verwendet wird. Eine Anwendung oder ein Treiber ruft HidP_MaxUsageListLength auf, um die Anzahl der Schaltflächennutzungen auf einer angegebenen Seite im Bericht zu ermitteln. Wenn die Anwendung oder der Treiber eine Verwendungsseite von Null angibt, gibt die Routine die Anzahl aller Schaltflächenverwendungen im Bericht zurück.

Die erforderliche Puffergröße in Byte beträgt:

• (Für HidP_GetButtons) Der von HidP_MaxUsageListLength mal der Größe von USAGE zurückgegebene Wert
• (Für HidP_GetButtonsEx) Der von HidP_MaxUsageListLength zurückgegebene Wert mal der Größe von USAGE_AND_PAGE

Nachdem eine Anwendung oder ein Treiber diese Routinen verwendet hat, um Informationen darüber zu erhalten, welche Schaltflächen derzeit auf EIN eingestellt sind, kann er den Unterschied zwischen dem aktuellen Status und dem vorherigen Status der Schaltflächen feststellen, indem er eine der folgenden HIDClass-Supportroutinen aufruft. Diese Routinen geben den Unterschied zwischen zwei Arrays von Verwendungsinformationen zurück:

• HidP_UsageListDifference
• HidP_UsageAndPageListDifference

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-Supportroutinen 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 Setzt ein Nutzungswert-Array in einem Bericht.

Festlegen des Schaltflächenzustands durch Angeben der Verwendung

Eine Anwendung oder ein Treiber kann den Zustand von Schaltflächen in einem korrekt initialisierten HID-Bericht festlegen, indem sie eine der folgenden HIDClass-Supportroutinen aufruft:

• HidP_SetButtons (oder HidP_SetUsages) legt einen angegebenen Satz von Schaltflächen auf EIN (1) fest.
• HidP_UnsetButtons (oder HidP_UnsetUsages) deaktiviert einen angegebenen Satz von Schaltflächen auf AUS (Null).

Extrahieren und Festlegen von Kontrolldaten durch Datenindizes

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

• HidP_GetData
• HidP_SetData

Diese Routinen sind nützlich für eine Anwendung oder einen Treiber, der einen „Mehrwert“-Dienst bereitstellt. Beispielsweise einen, der eine benutzerdefinierte Schnittstelle für alle von einem HIDClass-Gerät unterstützten Steuerelemente bereitstellt. Microsoft DirectInput ist ein Beispiel.

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

Eine Anwendung oder ein Treiber verwendet die in den Button Capability Arrays und Value Capability Arrays einer Sammlung angegebenen Datenindizes, um HID-Nutzungen zu identifizieren.

Siehe auch

• Initialisieren von HID-Berichten