Função WdfUsbTargetDeviceQueryString (wdfusb.h)

Artigo
08/08/2023

[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 do 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 que foi 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á terminada em NULL somente se o dispositivo fornecer uma cadeia de caracteres terminada em 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 NumCharacters aponta.

[in, out] NumCharacters

Um ponteiro para uma variável alocada pelo 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 String recebe.

[in] StringIndex

Um valor de índice que identifica a cadeia de caracteres Unicode. Esse valor de índice é obtido de uma estrutura de USB_DEVICE_DESCRIPTOR, USB_CONFIGURATION_DESCRIPTOR ou 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.

Retornar valor

WdfUsbTargetDeviceQueryString retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, esse método pode 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.

Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.

Comentários

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

Defina o ponteiro String como NULL, para que WdfUsbTargetDeviceQueryString retorne o tamanho do buffer necessário no endereço para o 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 String como um ponteiro para o novo buffer e definindo NumCharacters com 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 não NULL para o parâmetro Request , 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 Request, a estrutura usará um objeto de solicitação interno que o driver não pode cancelar.

O driver pode especificar um parâmetro RequestOptions não NULL, independentemente de o driver fornecer um parâmetro de solicitação não NULL ou NULL. 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 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
Plataforma de Destino	Universal
Versão mínima do KMDF	1.0
Versão mínima do UMDF	2,0
Cabeçalho	wdfusb.h (include Wdfusb.h)
Biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Regras de conformidade da DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)