Freigeben über

Abrufen von HID-Berichten

  • Artikel

In diesem Artikel wird beschrieben, wie Benutzermodusanwendungen und Kernelmodustreiber HID-Berichte aus einer HID-Sammlung erhalten.

Abrufen von HID-Berichten durch Benutzermodusanwendungen

In diesem Abschnitt werden das Abrufen von HID-Eingabeberichten oder HID-Featureberichten durch Benutzermodusanwendungen mit ReadFile oder den HidD_GetXxx-Routinen erläutert.

Eine Anwendung sollte jedoch nur die HidD_GetXxx-Routinen verwenden, um den aktuellen Zustand eines Geräts abzurufen. Wenn eine Anwendung versucht, HidD_GetInputReport zum kontinuierlichen Abrufen von Eingabeberichten zu verwenden, können die Berichte verloren gehen. Darüber hinaus unterstützen einige Geräte nicht HidD_GetInputReport und reagieren nicht mehr, wenn diese Routine verwendet wird.

Verwenden von ReadFile

Eine Anwendung verwendet das geöffnete Dateihandle, das mithilfe von CreateFile abgerufen wird, um eine Datei in der Sammlung zu öffnen. Wenn die Anwendung ReadFile aufruft, muss sie keinen überlappenden E/A-Vorgang angeben, da die HID-Clienttreiber-Puffer in einem Ringpuffer berichten. Eine Anwendung kann jedoch einen überlappenden E/A-Vorgang verwenden, um mehr als eine ausstehende Leseanforderung zu haben.

Verwenden von HidD_GetXxx-Routinen

Eine Anwendung kann die folgenden HIDClass-Supportroutinen verwenden, um die aktuellen Eingabeberichte und Featureberichte aus einer HID-Auflistung abzurufen:

  • HidD_GetInputReport: Gibt einen Eingabebericht aus einer HID-Sammlung (Windows XP und höher) zurück.
  • HidD_GetFeature: Gibt einen Featurebericht aus einer HID-Sammlung zurück.

Eine Anwendung kann die Rückgabe eines bestimmten Berichts anfordern. Um einen bestimmten Bericht mithilfe von HidD_GetXxx-Routinen abzurufen, weist die Anwendung den Berichtsausgabepuffer zu, initialisiert den Puffer mit Nullen und setzt das erste Byte im Puffer auf die bestimmte Berichts-ID. Weitere Informationen finden Sie unter Initialisieren von HID-Berichten.

Abrufen von HID-Berichten durch Kernelmodustreiber

In diesem Abschnitt wird erläutert, wie ein Kernelmodustreiber IRP_MJ_READ-Anforderungen als Hauptansatz zum kontinuierlichen Abrufen von HID-Eingabeberichten verwenden sollte.

Aufeinanderfolgende Leseanforderungen geben Eingabeberichte in der Reihenfolge zurück, in der sie von der Sammlung empfangen wurden. Der Treiber kann auch IOCTL_HID_GET_Xxx-Anforderungen verwenden, um Eingabe- und Featureberichte abzurufen. Ein Treiber sollte jedoch nur IOCTL_HID_GET_Xxx-Anforderungen verwenden, um den aktuellen Zustand eines Geräts abzurufen. Wenn der Treiber versucht, IOCTL_HID_GET_INPUT_REPORT zu verwenden, um kontinuierliche Eingabeberichte zu erhalten, können Berichte verloren gehen. Darüber hinaus unterstützen einige Geräte IOCTL_HID_GET_INPUT_REPORT nicht und reagieren nicht mehr, wenn diese Anforderung verwendet wird.

Verwenden von IRP_MJ_READ-Anforderungen

Allgemeine Informationen zur Verwendung und Wiederverwendung von E/A-Anforderungspaketen (IRPs) finden Sie unter Behandeln von IRPs und Wiederverwenden von IRPs.

Wenn ein Treiber ein IRP wiederverwendet, sollte die IoCompletion-Routine die Anforderung mit dem Status STATUS_MORE_PROCESSING_REQUIRED abschließen (und das IRP nicht freigeben). Wenn der Treiber das IRP nicht mehr benötigt, sollte er das IRP durch Aufrufen von IoCompleteRequest und IoFreeIrp freigeben. Beispielsweise kann ein Treiber das IRP in der Regel in seiner Unload-Routine abschließen und freigeben oder nachdem ein Gerät entfernt wurde.

Wenn ein Treiber nur für eine Leseanforderung ein IRP verwendet, sollte die IoCompletion-Routine das IRP abschließen und freigeben und STATUS_SUCCESS zurückgeben.

Bevor ein Treiber einen Eingabebericht anfordern kann, muss er zunächst einen mit Null initialisierten Eingabeberichtspuffer aus einem nicht ausgelagerten Speicherpool zuordnen. Die Größe des Puffers in Bytes wird durch das InputReportByteLength-Mitglied der HIDP_CAPS-Struktur einer HID-Sammlung angegeben. Ein Treiber muss dann eine MDL verwenden, um den Eingabeberichtpuffer einer Leseanforderung zuzuordnen. Der Treiber ruft IoAllocateMdl auf, um die MDL für einen Eingabeberichtpuffer zuzuweisen, und legt das Irp->MdlAddress-Mitglied auf die MDL-Adresse des Eingabeberichtpuffers fest. Der Treiber sollte den Berichtspuffer und die MDL freigeben, wenn sie nicht mehr benötigt werden.

Zusätzlich zum Festlegen der MDL-Adresse des Lese-IRP muss der Treiber auch den E/A-Stapelspeicherort des Treibers auf der nächsten niedrigeren Ebene festlegen. Ein Treiber erhält Zugriff auf den E/A-Stapelspeicherort des nächsten Treibers auf niedrigerer Ebene durch Aufrufen von IoGetNextIrpStackLocation. Der Treiber legt die folgenden Elemente des E/A-Stapelspeicherorts fest:

  • Parameters.Read.Length: Legt die Größe des Lesepuffers in Bytes fest. Die Größe muss größer oder gleich dem Wert sein, der durch das InputReportByteLength-Mitglied der HIDP_CAPS-Struktur einer HID-Sammlung angegeben wird.
  • Parameters.Read.Key: Auf Null festgelegt.
  • Parameters.Read.ByteOffset.QuadPart: Auf Null festgelegt.
  • MajorFunction: Auf IRP_MJ_READ festgelegt.
  • FileObject: Auf den Dateiobjektzeiger festgelegt, der die geöffnete Datei in der HID-Sammlung darstellt.

Nachdem der Treiber einen Eingabebericht abgerufen hat, kann er auf Steuerdaten zugreifen, wie in der Interpretation von HID-Berichten beschrieben.

Verwenden von IOCTL_HID_GET_Xxx-Anforderungen

Ein Treiber kann die folgenden E/A-Anforderungen verwenden, um die aktuellen Eingabe- und Funktionsberichte aus einer HID-Sammlung abzurufen:

Ein Treiber kann die Rückgabe eines bestimmten Berichts anfordern. Um einen bestimmten Bericht mithilfe dieser E/A-Anforderungen abzurufen, weist der Treiber zuerst den Ausgabeberichtpuffer zu, initialisiert dann den Puffer und legt das erste Byte im Puffer auf die spezifische Berichts-ID fest.

Weitere Informationen finden Sie unter Interpretieren von HID-Berichten.