IOCTL_HID_GET_STRING IOCTL (hidport.h)

Artikel
02/26/2024

Die IOCTL_HID_GET_STRING Anforderung ruft eine Hersteller-ID, Produkt-ID oder Seriennummer für eine Sammlung der obersten Ebene ab. Die abgerufene Zeichenfolge ist eine MIT NULL endende Breitzeichenzeichenfolge in einem lesbaren Format.

Allgemeine Informationen zu HIDClass-Geräten finden Sie unter HID-Sammlungen.

Hauptcode

IRP_MJ_DEVICE_CONTROL

Eingabepuffer

IOCTL_HID_GET_STRING verwendet zwei Eingabepuffer.

Parameters.DeviceIoControl.OutputBufferLength in der E/A-Stapelposition des IRP gibt die Größe des gesperrten Ausgabepuffers bei Irp-UserBuffer> in Bytes an. Wenn der Ausgabepuffer nicht groß genug ist, um die gesamte mit NULL beendete eingebettete Zeichenfolge zu enthalten, gibt die Anforderung nichts im Ausgabepuffer zurück. Die maximal mögliche Anzahl von Zeichen in einer eingebetteten Zeichenfolge ist gerätespezifisch. Bei USB-Geräten beträgt die maximale Zeichenfolgenlänge 126 Breitzeichen (ohne das abschließende NULL-Zeichen).

Parameters.DeviceIoControl.Type3InputBuffer in der E/A-Stapelposition des IRP enthält einen zusammengesetzten Wert. Die beiden wichtigsten Bytes enthalten die Sprach-ID der abzurufenden Zeichenfolge. Die beiden am wenigsten signifikanten Bytes enthalten einen der folgenden drei konstanten Werte:

HID_STRING_ID_IMANUFACTURER
HID_STRING_ID_IPRODUCT
HID_STRING_ID_ISERIALNUMBER

Der HID-Minidriver bestimmt, welche dieser drei Konstanten in den unteren beiden Bytes des Eingabepuffers vorhanden ist, und muss dann den entsprechenden Zeichenfolgenindex aus dem Gerätedeskriptor abrufen. Gerätedeskriptorinformationen werden in der Geräteerweiterung einer Sammlung der obersten Ebene gespeichert, die dem Gerät zugeordnet ist.

Es ist wichtig, diese drei Konstanten nicht mit den tatsächlichen Zeichenfolgenindizes der IDs zu verwechseln. Diese Konstanten stellen die Offsets im Gerätedeskriptor dar, in dem die entsprechenden Zeichenfolgenindizes gefunden werden können.

Beispielsweise gibt HID_STRING_ID_IMANUFACTURER den Speicherort im Gerätedeskriptor an, an dem sich der Index für die Hersteller-ID befindet. Dieser Index wiederum dient als Offset in den Zeichenfolgendeskriptor, in dem sich die lesbare Form der Hersteller-ID befindet.

Länge des Eingabepuffers

Die Größe des OutputBufferLength und die Größe des Type3InputBuffer.

Ausgabepuffer

Der HID-Minidriver füllt den Puffer bei Irp-UserBuffer> mit der angeforderten Zeichenfolge (eine MIT NULL beendete Breitzeichenzeichenfolge).

Länge des Ausgabepuffers

Die Größe des UserBuffers.

Statusblock

HID-Minitreiber, die die E/A an das Gerät ausführen, legen die folgenden Felder von Irp-IoStatus> fest:

Informationen werden auf die Anzahl der vom Gerät übertragenen Bytes festgelegt.
Status wird auf STATUS_SUCCESS festgelegt, wenn die Übertragung ohne Fehler abgeschlossen wurde. Andernfalls wird er auf einen geeigneten NTSTATUS-Fehlercode festgelegt.

HID-Minitreiber, die andere Treiber mit dieser IOCTL aufrufen, um die E/A auf ihrem Gerät auszuführen, sollten sicherstellen, dass das Feld Information des status Blocks korrekt ist, und den Inhalt des Felds Status nicht ändern.