Freigeben über

Abrufen von HID-Berichten

  • Artikel

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

Abrufen von HID-Berichten durch Benutzermodusanwendungen

In diesem Thema wird das Abrufen von HID-Eingabeberichten oder HID-Featureberichten durch Benutzermodusanwendungen mit ReadFile oder der 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 möglicherweise nicht HidD_GetInputReport und reagieren nicht mehr, wenn diese Routine verwendet wird.

Verwenden von ReadFile

Eine Anwendung verwendet das geöffnete Dateihandle, das sie mithilfe von CreateFile erhalten hat, um eine Datei in der Auflistung zu öffnen. Wenn die Anwendung ReadFile aufruft, muss sie keine überlappenden E/A-Vorgänge angeben, da die HID-Clienttreiberpuffer Berichte in einem Ringpuffer melden. Eine Anwendung kann jedoch überlappende E/A verwenden, um mehr als eine ausstehende Leseanforderung zu haben.

Verwenden HidD_GetXxx Routinen

Eine Anwendung kann die folgenden HIDClass-Unterstützungsroutinen verwenden, um die aktuellsten Eingabeberichte und Featureberichte aus einer HID-Sammlung abzurufen:

  • HidD_GetInputReport Gibt einen Eingabebericht aus einer HID-Sammlung (Windows XP und höhere Versionen) zurück.

  • HidD_GetFeature Gibt einen Featurebericht aus einer HID-Auflistung zurück.

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

Abrufen von HID-Berichten durch Kernelmodustreiber

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

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

Verwenden von IRP_MJ_READ Anforderungen

Windows 2000-Nicht-WDM-Treiber und Treiber für Windows XP und höhere Versionen können eine einzelne IRP für alle Leseanforderungen an ein Gerät verwenden. Windows 2000 WDM-Treiber müssen jedoch für jede Leseanforderung eine neue IRP zuweisen. Allgemeine Informationen zur Verwendung und Wiederverwendung von IRPs finden Sie unter Behandeln von IRPs und Wiederverwendung von IRPs.

Wenn ein Treiber einen IRP wiederverwendet, sollte die IoCompletion-Routine des IRP die Anforderung mit einem status von STATUS_MORE_PROCESSING_REQUIRED abschließen (und die IRP nicht freistellen). Wenn der Treiber die IRP nicht mehr benötigt, sollte er das IRP abschließen und freigeben, indem Er IoCompleteRequest und IoFreeIrp aufruft. Beispielsweise kann ein Treiber in der Regel den IRP in seiner Entladen-Routine oder nach dem Entfernen eines Geräts abschließen und freigeben.

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

Bevor ein Treiber einen Eingabebericht anfordern kann, muss er zuerst einen null initialisierten Eingabeberichtspuffer aus einem Nicht-Auslagerspeicherpool zuordnen. Die Größe des Puffers in Bytes wird durch das InputReportByteLength-Element der HIDP_CAPS Struktur einer HID-Auflistung angegeben. Ein Treiber muss dann eine MDL verwenden, um den Eingabeberichtspuffer für eine Leseanforderung zuzuordnen. Der Treiber ruft IoAllocateMdl auf, um die MDL für einen Eingabeberichtpuffer zuzuordnen, und legt den Irp-MdlAddress-Member des Lese-IRP 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 Speicherort des E/A-Stapels des nächsten Treibers auf niedrigerer Ebene festlegen. Ein Treiber erhält Zugriff auf den E/A-Stapelspeicherort des nächsten Treibers auf niedrigerer Ebene, indem er IoGetNextIrpStackLocation aufruft. Der Treiber legt die folgenden Elemente des E/A-Stapelspeicherorts fest:

Parameters.Read.Length
Legen Sie die Größe des Lesepuffers in Bytes fest. Dies muss größer oder gleich dem Wert sein, der vom InputReportByteLength-Member der HIDP_CAPS Struktur einer HID-Auflistung angegeben wird.

Parameters.Read.Key
Auf NULL festlegen.

Parameters.Read.ByteOffset.QuadPart
Auf NULL festlegen.

MajorFunction
Legen Sie auf IRP_MJ_READ fest.

FileObject
Legen Sie auf den Dateiobjektzeiger fest, der die geöffnete Datei in der HID-Auflistung darstellt.

Nachdem der Treiber einen Eingabebericht abgerufen hat, kann er auf Steuerungsdaten zugreifen, wie unter Interpretieren von HID-Berichten beschrieben.

Verwenden IOCTL_HID_GET_Xxx Anforderungen

Ein Treiber kann die folgenden E/A-Anforderungen verwenden, um die aktuellsten Eingabe- und Featureberichte 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 Ausgabeberichtspuffer zu, initialisiert dann den Puffer null und legt das erste Byte im Puffer auf die spezifische Berichts-ID fest.

Weitere Informationen finden Sie unter Interpretieren von HID-Berichten.