Função WdfUsbTargetDeviceQueryString (wdfusb.h)

Artigo
07/16/2024

[Aplica-se a KMDF e UMDF]

O método WdfUsbTargetDeviceQueryString recupera a cadeia de caracteres Unicode associada a um dispositivo USB especificado e um valor de índice de descritor.

Sintaxe

NTSTATUS WdfUsbTargetDeviceQueryString(
  [in]            WDFUSBDEVICE              UsbDevice,
  [in, optional]  WDFREQUEST                Request,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [out, optional] PUSHORT                   String,
  [in, out]       PUSHORT                   NumCharacters,
  [in]            UCHAR                     StringIndex,
  [in, optional]  USHORT                    LangID
);

Parâmetros

[in] UsbDevice

Um identificador para um objeto de dispositivo USB obtido de uma chamada anterior para WdfUsbTargetDeviceCreateWithParameters.

[in, optional] Request

Um identificador para um objeto de solicitação de estrutura. Esse parâmetro é opcional e pode ser NULL. Para obter mais informações, consulte a seção Comentários a seguir.

[in, optional] RequestOptions

Um ponteiro para uma estrutura de WDF_REQUEST_SEND_OPTIONS alocada pelo chamador que especifica opções para a solicitação. Esse ponteiro é opcional e pode ser NULL. Para obter mais informações, consulte a seção Comentários a seguir.

[out, optional] String

Um ponteiro para um buffer alocado pelo chamador que recebe a cadeia de caracteres Unicode solicitada. A cadeia de caracteres será encerrada em NULL somente se o dispositivo fornecer uma cadeia de caracteres terminada por NULL. Se esse ponteiro for NULL, WdfUsbTargetDeviceQueryString retornará o tamanho do buffer necessário (ou seja, o número necessário de caracteres Unicode) no local para o qual o NumCharacters aponta.

[in, out] NumCharacters

Um ponteiro para uma variável alocada por chamador. O chamador fornece o número de caracteres Unicode que o buffer pode conter. Quando WdfUsbTargetDeviceQueryString retorna, a variável recebe o número de caracteres (incluindo o terminador NULL, se fornecido) que estão na cadeia de caracteres Unicode que o buffer cadeia de caracteres recebe.

[in] StringIndex

Um valor de índice que identifica a cadeia de caracteres Unicode. Esse valor de índice é obtido de uma estrutura USB_DEVICE_DESCRIPTOR, USB_CONFIGURATION_DESCRIPTORou USB_INTERFACE_DESCRIPTOR.

[in, optional] LangID

Um identificador de idioma. A cadeia de caracteres Unicode será recuperada para o idioma especificado por esse identificador. Para obter informações sobre como obter os identificadores de idioma com suporte de um dispositivo, consulte a especificação USB.

Valor de retorno

WdfUsbTargetDeviceQueryString retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, esse método poderá retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi detectado.
STATUS_INSUFFICIENT_RESOURCES	Não foi possível alocar um buffer de memória.
STATUS_DEVICE_DATA_ERROR	O dispositivo USB retornou um descritor inválido.
STATUS_BUFFER_OVERFLOW	O buffer fornecido era muito pequeno.

Esse método também pode retornar outros valores NTSTATUS .

Uma verificação de bug ocorre se o driver fornece um identificador de objeto inválido.

Observações

Os drivers devem chamar WdfUsbTargetDeviceQueryString duas vezes, usando as seguintes etapas:

Defina o ponteiro de cadeia de caracteres como NULL, de modo que WdfUsbTargetDeviceQueryString retornará o tamanho do buffer necessário no endereço ao qual o parâmetro NumCharacters aponta.
Aloque espaço em buffer para manter o número de caracteres Unicode que estão na cadeia de caracteres solicitada. Por exemplo, um driver pode chamar ExAllocatePoolWithTag para alocar um buffer ou pode chamar WdfMemoryCreate para criar um objeto de memória de estrutura.
Chame WdfUsbTargetDeviceQueryString novamente, definindo o valor cadeia de caracteres como um ponteiro para o novo buffer e definindo NumCharacters para o comprimento do buffer (ou seja, o número de caracteres Unicode, não o comprimento do byte).

WdfUsbTargetDeviceQueryString localiza o descritor de cadeia de caracteres USB especificado e copia a cadeia de caracteres Unicode do descritor para o buffer fornecido.

Se o driver especificar um valor NULL nãopara o parâmetro solicitação , a estrutura usará o objeto de solicitação especificado e outro thread de driver poderá chamar WdfRequestCancelSentRequest, se necessário, para tentar cancelar a solicitação de consulta de cadeia de caracteres. Se o driver especificar um valor NULL para de Solicitação, a estrutura usará um objeto de solicitação interno que o driver não pode cancelar.

O driver pode especificar um parâmetroNULL nãoRequestOptions, independentemente de o driver fornecer uma NULL nãoou um parâmetro de solicitação deNULL . Você pode, por exemplo, usar o parâmetro RequestOptions para especificar um valor de tempo limite.

Para obter mais informações sobre descritores de cadeia de caracteres USB, consulte a especificação USB.

Para obter mais informações sobre o método WdfUsbTargetDeviceQueryString e destinos de E/S USB, consulte de destinos de E/S USB.

Exemplos

O exemplo de código a seguir chama WdfUsbTargetDeviceQueryString para obter o tamanho do buffer necessário, chama WdfMemoryCreate para criar um objeto de memória e um buffer e, em seguida, chama WdfUsbTargetDeviceQueryString novamente para obter a cadeia de caracteres de nome do fabricante, em inglês dos EUA (0x0409), de um descritor de dispositivo USB. (O driver armazenou anteriormente o descritor no espaço de contexto definido pelo driver.)

PMY_DEVICE_CONTEXT  myDeviceContext;
USHORT  numCharacters;
PUSHORT  stringBuf;
WDFMEMORY  memoryHandle;

myDeviceContext = GetDeviceContext(device);

status = WdfUsbTargetDeviceQueryString(
                                       myDeviceContext->UsbTargetDevice,
                                       NULL,
                                       NULL,
                                       NULL,
                                       &numCharacters,
                                       myDeviceContext->UsbDeviceDescr.iManufacturer,
                                       0x0409
                                       );

ntStatus = WdfMemoryCreate(
                           WDF_NO_OBJECT_ATTRIBUTES,
                           NonPagedPool,
                           POOL_TAG,
                           numCharacters * sizeof(WCHAR),
                           &memoryHandle,
                           (PVOID)&stringBuf
                           );
if (!NT_SUCCESS(ntStatus)) {
    return ntStatus;
}
status = WdfUsbTargetDeviceQueryString(
                                       myDeviceContext->UsbTargetDevice,
                                       NULL,
                                       NULL,
                                       stringBuf,
                                       &numCharacters,
                                       myDeviceContext->UsbDeviceDescr.iManufacturer,
                                       0x0409
                                       );

Requisitos

Requisito	Valor
da Plataforma de Destino	Universal
versão mínima do KMDF	1.0
versão mínima do UMDF	2.0
cabeçalho	wdfusb.h (inclua Wdfusb.h)
biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
regras de conformidade de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExpUsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)