IOCTL_HID_GET_STRING IOCTL (hidport.h)

Article
02/26/2024

La demande IOCTL_HID_GET_STRING obtient un ID de fabricant, un ID de produit ou un numéro de série pour une collection de niveau supérieur. La chaîne récupérée est une chaîne de caractères larges terminée par null dans un format lisible par l’utilisateur.

Pour plus d’informations générales sur les appareils HIDClass, consultez Collections HID.

Code principal

IRP_MJ_DEVICE_CONTROL

Mémoire tampon d'entrée

IOCTL_HID_GET_STRING utilise deux tampons d’entrée.

Parameters.DeviceIoControl.OutputBufferLength dans l’emplacement de la pile d’E/S de l’IRP indique la taille, en octets, de la mémoire tampon de sortie verrouillée sur Irp-UserBuffer>. Si la mémoire tampon de sortie n’est pas assez grande pour contenir l’intégralité de la chaîne incorporée terminée par NULL, la demande ne retourne rien dans la mémoire tampon de sortie. Le nombre maximal possible de caractères dans une chaîne incorporée est spécifique à l’appareil. Pour les périphériques USB, la longueur maximale de chaîne est de 126 caractères larges (sans le caractère NULL de fin).

Parameters.DeviceIoControl.Type3InputBuffer dans l’emplacement de pile d’E/S de l’IRP contient une valeur composite. Les deux octets les plus significatifs contiennent l’ID de langue de la chaîne à récupérer. Les deux octets les moins significatifs contiennent l’une des trois valeurs constantes suivantes :

HID_STRING_ID_IMANUFACTURER
HID_STRING_ID_IPRODUCT
HID_STRING_ID_ISERIALNUMBER

Le minidriver HID détermine laquelle de ces trois constantes est présente dans les deux octets inférieurs de la mémoire tampon d’entrée, puis il doit récupérer l’index de chaîne correspondant à partir du descripteur d’appareil. Les informations de descripteur d’appareil sont stockées dans l’extension d’appareil d’une collection de niveau supérieur associée à l’appareil.

Il est important de ne pas confondre ces trois constantes avec les index de chaîne réels des ID. Ces constantes représentent les décalages dans le descripteur d’appareil où se trouvent les index de chaîne correspondants.

Par exemple, HID_STRING_ID_IMANUFACTURER indique l’emplacement dans le descripteur d’appareil où se trouve l’index de l’ID du fabricant. Cet index, à son tour, sert de décalage dans le descripteur de chaîne où se trouve la forme lisible par l’homme de l’ID du fabricant.

Longueur de la mémoire tampon d’entrée

Taille du OutputBufferLength et taille du Type3InputBuffer.

Mémoire tampon de sortie

Le minidriver HID remplit la mémoire tampon sur Irp-UserBuffer> avec la chaîne demandée (chaîne de caractères larges terminée par NULL).

Longueur de la mémoire tampon de sortie

Taille de UserBuffer.

Bloc d’état

Les minidrivers HID qui effectuent les E/S sur l’appareil définissent les champs suivants d’Irp-IoStatus> :

Les informations sont définies sur le nombre d’octets transférés à partir de l’appareil.
L’état est défini sur STATUS_SUCCESS si le transfert s’est terminé sans erreur. Sinon, il est défini sur un code d’erreur NTSTATUS approprié.

Les minidrivers HID qui appellent d’autres pilotes avec cette IOCTL pour effectuer les E/S sur leur appareil doivent s’assurer que le champ Informations du bloc status est correct et ne pas modifier le contenu du champ État.