Função WdfUsbTargetDeviceSelectConfig (wdfusb.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

O método WdfUsbTargetDeviceSelectConfig seleciona uma configuração USB para um dispositivo ou desconfigure o dispositivo.

Sintaxe

NTSTATUS WdfUsbTargetDeviceSelectConfig(
  [in]           WDFUSBDEVICE                         UsbDevice,
  [in, optional] PWDF_OBJECT_ATTRIBUTES               PipeAttributes,
  [in, out]      PWDF_USB_DEVICE_SELECT_CONFIG_PARAMS Params
);

Parâmetros

[in] UsbDevice

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

[in, optional] PipeAttributes

Um ponteiro para uma estrutura de WDF_OBJECT_ATTRIBUTES alocada pelo chamador que contém atributos para novos objetos de pipe USB de estrutura que a estrutura cria para as interfaces do dispositivo. Para drivers KMDF, esse parâmetro é opcional e pode ser WDF_NO_OBJECT_ATTRIBUTES. Os drivers UMDF devem definir esse parâmetro como NULL.

[in, out] Params

Um ponteiro para uma estrutura de WDF_USB_DEVICE_SELECT_CONFIG_PARAMS alocada pelo chamador que o chamador e a estrutura usam para especificar parâmetros de configuração.

Retornar valor

WdfUsbTargetDeviceSelectConfig retorna o valor status de conclusão do destino de E/S 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_INFO_LENGTH_MISMATCH	O membro Size da estrutura WDF_USB_DEVICE_SELECT_CONFIG_PARAMS para a qual Params aponta estava incorreto.
STATUS_INSUFFICIENT_RESOURCES	Não foi possível alocar um buffer de memória.
STATUS_NOT_SUPPORTED	A estrutura retornará esse valor se um driver UMDF chamar WdfUsbTargetDeviceSelectConfig como Tipoparamsdefinido como qualquer um dos seguintes->: WdfUsbTargetDeviceSelectConfigTypeDeconfig WdfUsbTargetDeviceSelectConfigTypeInterfacesDescriptor WdfUsbTargetDeviceSelectConfigTypeUrb Para obter mais informações, consulte WdfUsbTargetDeviceSelectConfigType.

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 driver pode selecionar uma configuração de dispositivo usando uma estrutura WDF_USB_DEVICE_SELECT_CONFIG_PARAMS para especificar descritores USB, um URB ou identificadores para estruturar objetos de interface USB.

A estrutura cria um objeto de pipe USB de estrutura para cada pipe associado a cada interface na configuração, depois de excluir quaisquer objetos de pipe que a estrutura possa ter criado anteriormente para a configuração. A estrutura usa a configuração alternativa zero para cada interface, a menos que o driver especifique uma configuração alternativa diferente.

Para obter informações sobre objetos de pipe de uma interface, o driver pode chamar WdfUsbInterfaceGetNumConfiguredPipes e WdfUsbInterfaceGetConfiguredPipe.

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

Cuidado

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.

Exemplos

O exemplo de código a seguir seleciona uma configuração com uma única interface especificada.

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS  configParams;
NTSTATUS  status;

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_SINGLE_INTERFACE(&configParams);

status = WdfUsbTargetDeviceSelectConfig(
                                        UsbDevice,
                                        WDF_NO_OBJECT_ATTRIBUTES,
                                        &configParams
                                        );

O exemplo de código a seguir seleciona uma configuração com várias interfaces, usando a configuração alternativa zero em todas as interfaces. Este exemplo se aplica somente a drivers KMDF.

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS  configParams;
PWDF_USB_INTERFACE_SETTING_PAIR settingPairs;
UCHAR numInterfaces;
NTSTATUS  status;

numInterfaces = WdfUsbTargetDeviceGetNumInterfaces(UsbDevice);

settingPairs = ExAllocatePoolWithTag(
    PagedPool,
    sizeof(WDF_USB_INTERFACE_SETTING_PAIR) * numInterfaces,
    MY_DRIVER_TAG
);

if (settingPairs == NULL){
    return STATUS_INSUFFICIENT_RESOURCES;
}

for (interfaceIndex = 0; interfaceIndex < numInterfaces; interfaceIndex++) {
        
    settingPairs[interfaceIndex].UsbInterface = 
                                    WdfUsbTargetDeviceGetInterface(
                                        UsbDevice,
                                        interfaceIndex);

    // Select alternate setting zero on all interfaces.
       
    settingPairs[interfaceIndex].SettingIndex = 0;
}

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_MULTIPLE_INTERFACES(
    &configParams,
    numInterfaces,
    settingPairs
);

status = WdfUsbTargetDeviceSelectConfig(
    UsbDevice,
    NULL,
    &configParams
);

if (!NT_SUCCESS(status)) {
    ExFreePoolWithTag(
        settingPairs,
        MY_DRIVER_TAG
    );
    return status;
}

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)