Função WdfUsbTargetDeviceAllocAndQueryString (wdfusb.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

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

Sintaxe

NTSTATUS WdfUsbTargetDeviceAllocAndQueryString(
  [in]            WDFUSBDEVICE           UsbDevice,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES StringMemoryAttributes,
  [out]           WDFMEMORY              *StringMemory,
  [out, optional] 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] StringMemoryAttributes

Um ponteiro para uma estrutura de WDF_OBJECT_ATTRIBUTES alocada pelo chamador que contém atributos fornecidos pelo chamador para o novo objeto de memória. Esse parâmetro é opcional e pode ser WDF_NO_OBJECT_ATTRIBUTES.

[out] StringMemory

Um ponteiro para um local que recebe um identificador para o objeto de memória que contém a cadeia de caracteres Unicode. A cadeia de caracteres será terminada em NULL somente se o dispositivo fornecer uma cadeia de caracteres terminada em NULL.

[out, optional] NumCharacters

Um ponteiro para um local que recebe o número de caracteres contidos no descritor de cadeia de caracteres. Se a cadeia de caracteres Unicode for terminada em NULL, esse número incluirá o caractere NULL. Esse parâmetro é opcional e pode ser NULL.

[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

WdfUsbTargetDeviceAllocAndQueryString 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

O método WdfUsbTargetDeviceAllocAndQueryString , que seu driver só precisa chamar uma vez para obter um descritor de cadeia de caracteres, é uma alternativa ao método WdfUsbTargetDeviceQueryString , que deve ser chamado duas vezes para obter uma cadeia de caracteres.

O método localiza o descritor de cadeia de caracteres USB especificado, copia a cadeia de caracteres Unicode do descritor em um objeto de memória e retorna um identificador para o objeto de memória.

Depois de chamar WdfUsbTargetDeviceAllocAndQueryString, o driver pode passar o identificador StringMemory para WdfMemoryGetBuffer para acessar o conteúdo do objeto de memória.

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 WdfUsbTargetDeviceAllocAndQueryString e destinos de E/S USB, consulte Destinos de E/S USB.

Exemplos

O exemplo de código a seguir chama WdfUsbTargetDeviceAllocAndQueryString 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;
WDFMEMORY  memoryHandle;
USHORT  numCharacters;

myDeviceContext = GetDeviceContext(device);

status = WdfUsbTargetDeviceAllocAndQueryString(
                                        myDeviceContext->UsbTargetDevice,
                                        WDF_NO_OBJECT_ATTRIBUTES,
                                        &memoryHandle,
                                        &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)