WdfUsbTargetDeviceSelectConfig 函数 (wdfusb.h)

项目
08/08/2023

[适用于 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

USB 设备对象的句柄，该对象是从之前调用 WdfUsbTargetDeviceCreateWithParameters 获取的。

[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 结构的 Size 成员不正确。
STATUS_INSUFFICIENT_RESOURCES	无法分配内存缓冲区。
STATUS_NOT_SUPPORTED	如果 UMDF 驱动程序调用 WdfUsbTargetDeviceSelectConfig 且参数->类型设置为以下任一项，框架将返回此值： WdfUsbTargetDeviceSelectConfigTypeDeconfig WdfUsbTargetDeviceSelectConfigTypeInterfacesDescriptor WdfUsbTargetDeviceSelectConfigTypeUrb 有关详细信息，请参阅 WdfUsbTargetDeviceSelectConfigType。

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

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

注解

驱动程序可以通过使用 WDF_USB_DEVICE_SELECT_CONFIG_PARAMS 结构来指定 USB 描述符、URB 或框架 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)
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)