IOCTL_HID_GET_STRING IOCTL (hidport.h)

Article
02/07/2025

La demande IOCTL_HID_GET_STRING obtient un ID de fabricant, un ID de produit ou un numéro de série pour un 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’homme.

Pour obtenir des 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 mémoires tampons d’entrée.

Parameters.DeviceIoControl.OutputBufferLength à 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 à Irp->UserBuffer. Si la mémoire tampon de sortie n’est pas suffisamment grande pour contenir l’intégralité de la chaîne incorporée terminée par NULL, la requête ne retourne rien dans la mémoire tampon de sortie. Le nombre maximal 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 inclure le caractère NULL de fin).

Parameters.DeviceIoControl.Type3InputBuffer à l’emplacement de la 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 lequel 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 de l’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 indices de chaîne réels des ID. Ces constantes représentent les décalages dans le descripteur d’appareil où les index de chaîne correspondants sont trouvés.

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

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

Taille du OutputBufferLength et de la taille du Type3InputBuffer.

Mémoire tampon de sortie

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

Longueur de la mémoire tampon de sortie

Taille du UserBuffer.

Bloc d’état

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

Informations est définie sur le nombre d’octets transférés à partir de l’appareil.
'é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 ce IOCTL pour effectuer les E/S sur leur appareil, doivent s’assurer que le champ Information du bloc d’état est correct et ne modifie pas le contenu du champ Status.