WdfUsbInterfaceSelectSetting 函数 (wdfusb.h)

项目
08/08/2023

[适用于 KMDF 和 UMDF]

WdfUsbInterfaceSelectSetting 方法为指定的 USB 接口选择指定的备用设置。

语法

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

参数

[in] UsbInterface

通过调用 WdfUsbTargetDeviceGetInterface 获取的 USB 接口对象的句柄。

[in, optional] PipesAttributes

指向 WDF_OBJECT_ATTRIBUTES 结构的指针，该结构指定框架为接口创建的管道对象的对象属性。此参数是可选的，可以WDF_NO_OBJECT_ATTRIBUTES。

[in] Params

指向调用方提供的 WDF_USB_INTERFACE_SELECT_SETTING_PARAMS 结构的指针，该结构包含接口选择参数。

返回值

如果操作成功，WdfUsbInterfaceSelectSetting 将返回 I/O 目标的完成状态值。否则，此方法可以返回以下值之一：

返回代码	说明
STATUS_INVALID_PARAMETER	检测到参数无效。
STATUS_INSUFFICIENT_RESOURCES	内存不足，无法创建新的管道对象。

有关 WdfUsbInterfaceSelectSetting 方法可能返回的其他返回值的列表，请参阅 Framework 对象创建错误。

此方法还可能返回其他 NTSTATUS 值。

如果驱动程序提供无效的对象句柄，则会发生 bug 检查。

注解

驱动程序调用 WdfUsbTargetDeviceSelectConfig 以选择配置后，驱动程序可以调用 WdfUsbInterfaceSelectSetting ，为设备接口之一选择备用设置。

驱动程序可以通过指定 USB 接口描述符或 URB 或仅提供接口的备用设置来选择接口的备用设置。在所有情况下，驱动程序都必须提供接口对象的句柄。

如果驱动程序仅提供备用设置，框架将使用接口对象来确定该设置所属的接口。

如果驱动程序指定接口描述符或 URB，框架将使用在描述符或 URB 中指定的接口。

在删除框架之前可能为接口创建的任何管道对象后，框架为与接口关联的每个管道创建一个框架 USB 管道对象。若要获取有关接口管道对象的信息，驱动程序可以调用 WdfUsbInterfaceGetNumConfiguredPipes 和 WdfUsbInterfaceGetConfiguredPipe。

有关 WdfUsbInterfaceSelectSetting 方法和 USB I/O 目标的详细信息，请参阅 USB I/O 目标。

示例

下面的代码示例使用框架将创建的管道对象的属性初始化 WDF_OBJECT_ATTRIBUTES 结构。然后，该示例初始化 WDF_USB_INTERFACE_SELECT_SETTING_PARAMS 结构以指定备用设置 1。最后，该示例调用 WdfUsbInterfaceSelectSetting 以选择备用设置并为接口的管道创建管道对象。

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
                                      );

要求

要求	值
目标平台	通用
最低 KMDF 版本	1.0
最低 UMDF 版本	2.0
标头	wdfusb.h (包括 Wdfusb.h)
Library	Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI 符合性规则	DriverCreate (kmdf) ， KmdfIrql (kmdf) ， KmdfIrql2 (kmdf) ， KmdfIrqlExplicit (kmdf) ， UsbKmdfIrql (kmdf) 、 UsbKmdfIrql2 (kmdf) 、UsbKmdfIrqlExplicit (kmdf)