IOCTL_HID_GET_STRING IOCTL (hidport.h)

Artigo
02/07/2025

A solicitação IOCTL_HID_GET_STRING obtém uma ID do fabricante, uma ID do produto ou um número de série para uma coleção de de nível superior. A cadeia de caracteres recuperada é uma cadeia de caracteres largos terminada em NULL em um formato legível por humanos.

Para obter informações gerais sobre dispositivos HIDClass, consulte coleções HID.

Código principal

IRP_MJ_DEVICE_CONTROL

Buffer de entrada

IOCTL_HID_GET_STRING usa dois buffers de entrada.

Parameters.DeviceIoControl.OutputBufferLength no local da pilha de E/S do IRP indica o tamanho, em bytes, do buffer de saída bloqueado em >UserBuffer. Se o buffer de saída não for grande o suficiente para manter toda a cadeia de caracteres inserida terminada em NULL, a solicitação não retornará nada no buffer de saída. O número máximo possível de caracteres em uma cadeia de caracteres inserida é específico do dispositivo. Para dispositivos USB, o comprimento máximo da cadeia de caracteres é de 126 caracteres de largura (sem incluir o caractere NULL de terminação).

Parameters.DeviceIoControl.Type3InputBuffer no local da pilha de E/S do IRP contém um valor composto. Os dois bytes mais significativos contêm a ID do idioma da cadeia de caracteres a ser recuperada. Os dois bytes menos significativos contêm um dos três valores constantes a seguir:

HID_STRING_ID_IMANUFACTURER
HID_STRING_ID_IPRODUCT
HID_STRING_ID_ISERIALNUMBER

O minidriver HID determina qual dessas três constantes está presente nos dois bytes inferiores do buffer de entrada e, em seguida, deve recuperar o índice de cadeia de caracteres correspondente do descritor do dispositivo. As informações do descritor de dispositivo são armazenadas na extensão do dispositivo de uma coleção de nível superior associada ao dispositivo.

É importante não confundir essas três constantes com os índices de cadeia de caracteres reais das IDs. Essas constantes representam os deslocamentos no descritor do dispositivo em que os índices de cadeia de caracteres correspondentes podem ser encontrados.

Por exemplo, HID_STRING_ID_IMANUFACTURER indica o local no descritor do dispositivo em que o índice da ID do fabricante é encontrado. Esse índice, por sua vez, serve como um deslocamento para o descritor de cadeia de caracteres em que a forma legível por humanos da ID do fabricante está localizada.

Comprimento do buffer de entrada

O tamanho do OutputBufferLength e o tamanho do type3InputBuffer.

Buffer de saída

O minidriver HID preenche o buffer em >UserBuffer com a cadeia de caracteres solicitada (uma cadeia de caracteres larga terminada em NULL).

Comprimento do buffer de saída

O tamanho do UserBuffer.

Bloco de status

Os minidrivers HID que executam a E/S para o dispositivo definem os seguintes campos de Irp->IoStatus:

de Informações é definido como o número de bytes transferidos do dispositivo.
Status será definido como STATUS_SUCCESS se a transferência for concluída sem erros. Caso contrário, ele será definido como um código de erro NTSTATUS apropriado.

Os minidrivers HID que chamam outros drivers com esse IOCTL para realizar a E/S em seu dispositivo devem garantir que o campo Informações do bloco de status esteja correto e não altere o conteúdo do campo Status.