Descritores de cadeia de caracteres USB

  • Artigo

Os descritores de dispositivo, configuração e interface podem conter referências a descritores de cadeia de caracteres. Este tópico descreve como obter um descritor de cadeia de caracteres específico do dispositivo.

Os descritores de cadeia de caracteres são referenciados por seu número de índice baseado em um. Um descritor de cadeia de caracteres contém uma ou mais cadeias de caracteres Unicode; cada cadeia de caracteres é uma tradução das outras para outro idioma.

Os drivers cliente usam UsbBuildGetDescriptorRequest, com DescriptorType = USB_STRING_DESCRIPTOR_TYPE, para criar a solicitação para obter um descritor de cadeia de caracteres. O parâmetro Index especifica o número de índice e o parâmetro LanguageID especifica a ID do idioma (os mesmos valores são usados como nos valores LANGID do Microsoft Win32). Os drivers podem solicitar o número de índice especial de zero para determinar quais IDs de idioma o dispositivo dá suporte. Para esse valor especial, o dispositivo retorna uma matriz de IDs de linguagem em vez de uma cadeia de caracteres Unicode.

Como o descritor de cadeia de caracteres consiste em dados de comprimento variável, o driver deve obtê-los em duas etapas. Primeiro, o driver deve emitir a solicitação, passando um buffer de dados grande o suficiente para manter o cabeçalho de um descritor de cadeia de caracteres, uma estrutura USB_STRING_DESCRIPTOR. O membro bLength de USB_STRING_DESCRIPTOR especifica o tamanho em bytes de todo o descritor. Em seguida, o driver faz a mesma solicitação com um buffer de dados de tamanho bLength.

O código a seguir demonstra como solicitar o descritor de cadeia de caracteres i-th, com iD de linguagem langID:

USB_STRING_DESCRIPTOR USD, *pFullUSD;
UsbBuildGetDescriptorRequest(
    pURB, // points to the URB to be filled in
    sizeof(struct _URB_CONTROL_DESCRIPTOR_REQUEST),
    USB_STRING_DESCRIPTOR_TYPE,
    i, // index of string descriptor
    langID, // language ID of string.
    &USD, // points to a USB_STRING_DESCRIPTOR.
    NULL,
    sizeof(USB_STRING_DESCRIPTOR),
    NULL
);
pFullUSD = ExAllocatePool(NonPagedPool, USD.bLength);
UsbBuildGetDescriptorRequest(
    pURB, // points to the URB to be filled in
    sizeof(struct _URB_CONTROL_DESCRIPTOR_REQUEST),
    USB_STRING_DESCRIPTOR_TYPE,
    i, // index of string descriptor
    langID, // language ID of string
    pFullUSD,
    NULL,
    USD.bLength,
    NULL
);