Função WdfUsbInterfaceSelectSetting (wdfusb.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

O método WdfUsbInterfaceSelectSetting seleciona uma configuração alternativa especificada para uma interface USB especificada.

Sintaxe

NTSTATUS WdfUsbInterfaceSelectSetting(
  [in]           WDFUSBINTERFACE                          UsbInterface,
  [in, optional] PWDF_OBJECT_ATTRIBUTES                   PipesAttributes,
  [in]           PWDF_USB_INTERFACE_SELECT_SETTING_PARAMS Params
);

Parâmetros

[in] UsbInterface

Um identificador para um objeto de interface USB que foi obtido chamando WdfUsbTargetDeviceGetInterface.

[in, optional] PipesAttributes

Um ponteiro para uma estrutura WDF_OBJECT_ATTRIBUTES que especifica atributos de objeto para objetos de pipe que a estrutura cria para a interface. Esse parâmetro é opcional e pode ser WDF_NO_OBJECT_ATTRIBUTES.

[in] Params

Um ponteiro para uma estrutura de WDF_USB_INTERFACE_SELECT_SETTING_PARAMS fornecida pelo chamador que contém parâmetros de seleção de interface.

Retornar valor

WdfUsbInterfaceSelectSetting retorna o valor de 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_INSUFFICIENT_RESOURCES	Não havia memória suficiente para criar um novo objeto de pipe.

Para obter uma lista de outros valores retornados que o método WdfUsbInterfaceSelectSetting pode retornar, consulte Erros de criação de objeto de estrutura.

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

Depois que o driver chama WdfUsbTargetDeviceSelectConfig para selecionar uma configuração, o driver pode chamar WdfUsbInterfaceSelectSetting para selecionar uma configuração alternativa para uma das interfaces do dispositivo.

O driver pode selecionar a configuração alternativa de uma interface especificando um descritor de interface USB ou um URB ou apenas fornecendo uma configuração alternativa para a interface. Em todos os casos, o driver deve fornecer um identificador para um objeto de interface.

Se o driver fornecer apenas uma configuração alternativa, a estrutura usará o objeto de interface para determinar a interface à qual a configuração pertence.

Se o driver especificar um descritor de interface ou um URB, a estrutura usará a interface especificada no descritor ou URB.

A estrutura cria um objeto de pipe USB da estrutura para cada pipe associado à interface, depois de excluir quaisquer objetos de pipe que a estrutura possa ter criado anteriormente para a interface. Para obter informações sobre objetos de pipe de uma interface, seu driver pode chamar WdfUsbInterfaceGetNumConfiguredPipes e WdfUsbInterfaceGetConfiguredPipe.

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

Exemplos

O exemplo de código a seguir inicializa uma estrutura WDF_OBJECT_ATTRIBUTES com atributos para os objetos de pipe que a estrutura criará. Em seguida, o exemplo inicializa uma estrutura WDF_USB_INTERFACE_SELECT_SETTING_PARAMS para especificar a configuração alternativa 1. Por fim, o exemplo chama WdfUsbInterfaceSelectSetting para selecionar a configuração alternativa e criar objetos de pipe para os pipes da interface.

WDF_OBJECT_ATTRIBUTES  pipesAttributes;
WDF_USB_INTERFACE_SELECT_SETTING_PARAMS  selectSettingParams;
NTSTATUS  Status;

WDF_OBJECT_ATTRIBUTES_INIT(&pipesAttributes);
WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE(
                                       &pipesAttributes,
                                       MY_PIPE_CONTEXT
                                       );

WDF_USB_INTERFACE_SELECT_SETTING_PARAMS_INIT_SETTING(
                                      &selectSettingParams,
                                      1
                                      );

Status = WdfUsbInterfaceSelectSetting(
                                      UsbInterface,
                                      &pipesAttributes,
                                      &selectSettingParams
                                      );

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)