Função WdfUsbTargetDeviceRetrieveConfigDescriptor (wdfusb.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

O método WdfUsbTargetDeviceRetrieveConfigDescriptor recupera o descritor de configuração USB para o dispositivo USB associado a um objeto de dispositivo USB de estrutura especificado.

Sintaxe

NTSTATUS WdfUsbTargetDeviceRetrieveConfigDescriptor(
  [in]      WDFUSBDEVICE UsbDevice,
  [out]     PVOID        ConfigDescriptor,
  [in, out] PUSHORT      ConfigDescriptorLength
);

Parâmetros

[in] UsbDevice

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

[out] ConfigDescriptor

Um ponteiro para um buffer alocado pelo chamador que recebe uma estrutura de USB_CONFIGURATION_DESCRIPTOR , seguido por uma ou mais estruturas de USB_INTERFACE_DESCRIPTOR e USB_ENDPOINT_DESCRIPTOR . Esse parâmetro é opcional e pode ser NULL, nesse caso , WdfUsbTargetDeviceRetrieveConfigDescriptor retorna o comprimento do buffer necessário. Para obter mais informações, consulte a seção Comentários a seguir.

[in, out] ConfigDescriptorLength

Um ponteiro para um local que fornece o comprimento do buffer para o qual ConfigDescriptor aponta. Se o ponteiro fornecido para ConfigDescriptor for NULL, WdfUsbTargetDeviceRetrieveConfigDescriptor retornará o comprimento do buffer necessário no local apontado por ConfigDescriptorLength.

Retornar valor

WdfUsbTargetDeviceRetrieveConfigDescriptor 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_DEVICE_STATE	Um descritor de configuração não estava disponível para o destino especificado.
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi detectado.
STATUS_BUFFER_TOO_SMALL	O tamanho do buffer especificado era muito pequeno para os dados ou o chamador forneceu NULL para o parâmetro ConfigDescriptor .

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 WdfUsbTargetDeviceRetrieveConfigDescriptor recupera todas as informações de configuração do dispositivo USB especificado (ou seja, o descritor de configuração mais qualquer interface ou descritor de ponto de extremidade que possa estar presente). Para saber mais sobre o formato dessas informações, consulte a especificação USB.

Você pode usar WdfUsbTargetDeviceSelectConfig para selecionar apenas a primeira configuração USB listada na lista de descritores, mas você pode selecionar várias interfaces nessa única configuração.

Os drivers devem chamar WdfUsbTargetDeviceRetrieveConfigDescriptor duas vezes, da seguinte maneira:

Defina o ponteiro ConfigDescriptor como NULL, de modo que WdfUsbTargetDeviceRetrieveConfigDescriptor retornará o tamanho do buffer necessário no endereço para o qual ConfigDescriptorLength aponta.
Aloque espaço de buffer para manter as informações de configuração. 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 WdfUsbTargetDeviceRetrieveConfigDescriptor novamente, passando-o um ponteiro para o novo buffer e o tamanho do buffer.

Após o retorno da segunda chamada para WdfUsbTargetDeviceRetrieveConfigDescriptor , o buffer apontado por ConfigDescriptor contém uma estrutura USB_CONFIGURATION_DESCRIPTOR , seguida por uma ou mais estruturas USB_INTERFACE_DESCRIPTOR e USB_ENDPOINT_DESCRIPTOR . Essas últimas estruturas são organizadas na ordem descrita na especificação USB.

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

Exemplos

O exemplo de código a seguir chama WdfUsbTargetDeviceRetrieveConfigDescriptor para obter o tamanho do buffer necessário, chama WdfMemoryCreate para criar um objeto de memória e um buffer e, em seguida, chama WdfUsbTargetDeviceRetrieveConfigDescriptor novamente para obter as informações de configuração de um dispositivo.

USHORT  size;
NTSTATUS  ntStatus;
PMY_DEVICE_CONTEXT  myDeviceContext;
PUSB_CONFIGURATION_DESCRIPTOR  configurationDescriptor = NULL;
WDF_OBJECT_ATTRIBUTES  objectAttribs;
WDFMEMORY  memoryHandle;

myDeviceContext = GetDeviceContext(Device);

ntStatus = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                            myDeviceContext->WdfUsbTargetDevice,
                                            NULL,
                                            &size
                                            );

if (ntStatus != STATUS_BUFFER_TOO_SMALL) {
    return ntStatus;
}

WDF_OBJECT_ATTRIBUTES_INIT(&objectAttribs);
objectAttribs.ParentObject = myDeviceContext->WdfUsbTargetDevice;

ntStatus = WdfMemoryCreate(
                           &objectAttribs,
                           NonPagedPool,
                           POOL_TAG,
                           size,
                           &memoryHandle,
                           (PVOID)&configurationDescriptor
                           );
if (!NT_SUCCESS(ntStatus)) {
    return ntStatus;
}

ntStatus = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                            myDeviceContext->WdfUsbTargetDevice,
                                            configurationDescriptor,
                                            &size
                                            );
if (!NT_SUCCESS(ntStatus)) {
    return ntStatus;
}

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 (inclua Wdfusb.h)
Biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Regras de conformidade de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)