WdfUsbInterfaceSelectSetting 函数（wdfusb.h）

项目
02/07/2025

[适用于 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）
库	Wdf01000.sys（KMDF）：WUDFx02000.dll （UMDF）
IRQL	PASSIVE_LEVEL
DDI 符合性规则	DriverCreate（kmdf），KmdfIrql（kmdf），KmdfIrql2（kmdf），KmdfIrqlExplicit（kmdf）、UsbKmdfIrql（kmdf）、UsbKmdfIrql2（kmdf）、UsbKmdfIrqlExplicit（kmdf）