Función WdfUsbInterfaceSelectSetting (wdfusb.h)

Artículo
02/07/2025

[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 que se obtuvo llamando a WdfUsbTargetDeviceGetInterface.

[in, optional] PipesAttributes

Puntero a una estructura de 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 siguientes valores:

Código devuelto	Descripción
STATUS_INVALID_PARAMETER	Se detectó 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 puede devolver otros valores de NTSTATUS.

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

Observaciones

Una vez que el controlador llama 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 anteriormente 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 de trabajo. 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	Valor
de la plataforma de destino de	Universal
versión mínima de KMDF	1.0
versión mínima de UMDF	2.0
encabezado de	wdfusb.h (incluya Wdfusb.h)
biblioteca de	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)