WdfUsbTargetDeviceSelectConfig 函数（wdfusb.h）

项目
02/07/2025

[适用于 KMDF 和 UMDF]

WdfUsbTargetDeviceSelectConfig 方法为设备选择 USB 配置，或者取消配置设备。

语法

NTSTATUS WdfUsbTargetDeviceSelectConfig(
  [in]           WDFUSBDEVICE                         UsbDevice,
  [in, optional] PWDF_OBJECT_ATTRIBUTES               PipeAttributes,
  [in, out]      PWDF_USB_DEVICE_SELECT_CONFIG_PARAMS Params
);

参数

[in] UsbDevice

从上一次调用 WdfUsbTargetDeviceCreateWithParameters获取的 USB 设备对象的句柄。

[in, optional] PipeAttributes

指向调用方分配的 WDF_OBJECT_ATTRIBUTES 结构的指针，该结构包含框架为设备接口创建的新框架 USB 管道对象的属性。对于 KMDF 驱动程序，此参数是可选的，可以WDF_NO_OBJECT_ATTRIBUTES。 UMDF 驱动程序必须将此参数设置为 NULL。

[in, out] Params

指向调用方分配的 WDF_USB_DEVICE_SELECT_CONFIG_PARAMS 结构的指针，调用方和框架用于指定配置参数。

返回值

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

返回代码	描述
STATUS_INVALID_PARAMETER	检测到无效参数。
STATUS_INFO_LENGTH_MISMATCH	参数指向的 WDF_USB_DEVICE_SELECT_CONFIG_PARAMS 结构的大小成员不正确。
STATUS_INSUFFICIENT_RESOURCES	无法分配内存缓冲区。
STATUS_NOT_SUPPORTED	如果 UMDF 驱动程序调用 WdfUsbTargetDeviceSelectConfig 且 Params->类型设置为以下任一类型，则框架将返回此值： WdfUsbTargetDeviceSelectConfigTypeDeconfig WdfUsbTargetDeviceSelectConfigTypeInterfacesDescriptor WdfUsbTargetDeviceSelectConfigTypeUrb 有关详细信息，请参阅 WdfUsbTargetDeviceSelectConfigType。

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

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

言论

驱动程序可以使用 WDF_USB_DEVICE_SELECT_CONFIG_PARAMS 结构来指定 USB 描述符、URB 或框架 USB 接口对象的句柄来选择设备配置。

框架为配置中的每个接口关联的框架 USB 管道对象创建一个框架 USB 管道对象，然后删除框架以前可能为配置创建的任何管道对象。除非驱动程序指定不同的备用设置，否则框架为每个接口使用备用设置零。

若要获取有关接口管道对象的信息，驱动程序可以调用 WdfUsbInterfaceGetNumConfiguredPipes，WdfUsbInterfaceGetConfiguredPipe。

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

警告

可以使用 WdfUsbTargetDeviceSelectConfig 仅选择描述符列表中列出的第一个 USB 配置，但可以在此单个配置中选择多个接口。

例子

下面的代码示例选择具有单个指定接口的配置。

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS  configParams;
NTSTATUS  status;

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_SINGLE_INTERFACE(&configParams);

status = WdfUsbTargetDeviceSelectConfig(
                                        UsbDevice,
                                        WDF_NO_OBJECT_ATTRIBUTES,
                                        &configParams
                                        );

下面的代码示例使用所有接口上的备用设置零选择具有多个接口的配置。此示例仅适用于 KMDF 驱动程序。

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS  configParams;
PWDF_USB_INTERFACE_SETTING_PAIR settingPairs;
UCHAR numInterfaces;
NTSTATUS  status;

numInterfaces = WdfUsbTargetDeviceGetNumInterfaces(UsbDevice);

settingPairs = ExAllocatePoolWithTag(
    PagedPool,
    sizeof(WDF_USB_INTERFACE_SETTING_PAIR) * numInterfaces,
    MY_DRIVER_TAG
);

if (settingPairs == NULL){
    return STATUS_INSUFFICIENT_RESOURCES;
}

for (interfaceIndex = 0; interfaceIndex < numInterfaces; interfaceIndex++) {
        
    settingPairs[interfaceIndex].UsbInterface = 
                                    WdfUsbTargetDeviceGetInterface(
                                        UsbDevice,
                                        interfaceIndex);

    // Select alternate setting zero on all interfaces.
       
    settingPairs[interfaceIndex].SettingIndex = 0;
}

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_MULTIPLE_INTERFACES(
    &configParams,
    numInterfaces,
    settingPairs
);

status = WdfUsbTargetDeviceSelectConfig(
    UsbDevice,
    NULL,
    &configParams
);

if (!NT_SUCCESS(status)) {
    ExFreePoolWithTag(
        settingPairs,
        MY_DRIVER_TAG
    );
    return status;
}

要求

要求	价值
目标平台	普遍
最低 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）