Función WdfUsbInterfaceSelectSetting (wdfusb.h)

Artículo
08/08/2023

[Se aplica a KMDF y UMDF]

El método WdfUsbInterfaceSelectSetting selecciona una configuración alternativa especificada para una interfaz USB especificada.

Sintaxis

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

Parámetros

[in] UsbInterface

Identificador de un objeto de interfaz USB obtenido mediante una llamada a WdfUsbTargetDeviceGetInterface.

[in, optional] PipesAttributes

Puntero a una estructura WDF_OBJECT_ATTRIBUTES que especifica los atributos de objeto para los objetos de canalización que crea el marco para la interfaz. Este parámetro es opcional y se puede WDF_NO_OBJECT_ATTRIBUTES.

[in] Params

Puntero a una estructura de WDF_USB_INTERFACE_SELECT_SETTING_PARAMS proporcionada por el autor de la llamada que contiene parámetros de selección de interfaz.

Valor devuelto

WdfUsbInterfaceSelectSetting devuelve el valor de estado de finalización del destino de E/S si la operación se realiza correctamente. De lo contrario, este método puede devolver uno de los valores siguientes:

Código devuelto	Descripción
STATUS_INVALID_PARAMETER	Se ha detectado un parámetro no válido.
STATUS_INSUFFICIENT_RESOURCES	No había memoria suficiente para crear un nuevo objeto de canalización.

Para obtener una lista de otros valores devueltos que podría devolver el método WdfUsbInterfaceSelectSetting , vea Errores de creación de objetos de marco.

Este método también podría devolver otros valores NTSTATUS.

Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.

Comentarios

Después de que el controlador llame a WdfUsbTargetDeviceSelectConfig para seleccionar una configuración, el controlador puede llamar a WdfUsbInterfaceSelectSetting para seleccionar una configuración alternativa para una de las interfaces del dispositivo.

El controlador puede seleccionar la configuración alternativa de una interfaz especificando un descriptor de interfaz USB o un URB, o simplemente proporcionando una configuración alternativa para la interfaz. En todos los casos, el controlador debe proporcionar un identificador a un objeto de interfaz.

Si el controlador solo proporciona una configuración alternativa, el marco usa el objeto de interfaz para determinar la interfaz a la que pertenece la configuración.

Si el controlador especifica un descriptor de interfaz o un URB, el marco usa la interfaz especificada en el descriptor o urB.

El marco crea un objeto de canalización USB de marco para cada canalización asociada a la interfaz, después de eliminar los objetos de canalización que el marco podría haber creado previamente para la interfaz. Para obtener información sobre los objetos de canalización de una interfaz, el controlador puede llamar a WdfUsbInterfaceGetNumConfiguredPipes y WdfUsbInterfaceGetConfiguredPipe.

Para obtener más información sobre el método WdfUsbInterfaceSelectSetting y los destinos de E/S USB, consulte Destinos de E/S USB.

Ejemplos

En el ejemplo de código siguiente se inicializa una estructura de WDF_OBJECT_ATTRIBUTES con atributos para los objetos de canalización que creará el marco. A continuación, el ejemplo inicializa una estructura de WDF_USB_INTERFACE_SELECT_SETTING_PARAMS para especificar la configuración alternativa 1. Por último, el ejemplo llama a WdfUsbInterfaceSelectSetting para seleccionar la configuración alternativa y crear objetos de canalización para las canalizaciones de la interfaz.

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	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Versión mínima de UMDF	2.0
Encabezado	wdfusb.h (incluya Wdfusb.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)