WdfUsbTargetDeviceCreateWithParameters 函数 (wdfusb.h)

  • 项目

[适用于 KMDF 和 UMDF]

WdfUsbTargetDeviceCreateWithParameters 方法为指定的框架设备对象创建框架 USB 设备对象，并打开 USB 设备进行 I/O 操作。 方法还指定框架 USB 设备对象的配置信息。

语法

NTSTATUS WdfUsbTargetDeviceCreateWithParameters(
  [in]           WDFDEVICE                     Device,
  [in]           PWDF_USB_DEVICE_CREATE_CONFIG Config,
  [in, optional] PWDF_OBJECT_ATTRIBUTES        Attributes,
  [out]          WDFUSBDEVICE                  *UsbDevice
);

参数

[in] Device

框架设备对象的句柄。

[in] Config

指向包含框架 USB 设备对象的配置信息的 WDF_USB_DEVICE_CREATE_CONFIG 结构的指针。

[in, optional] Attributes

指向调用方提供的 WDF_OBJECT_ATTRIBUTES 结构的指针，该结构包含新框架 USB 设备对象的属性。 (结构的 ParentObject 成员必须为 NULL.) 此参数是可选的，可以WDF_NO_OBJECT_ATTRIBUTES。

[out] UsbDevice

指向接收新框架 USB 设备对象的句柄的位置的指针。

返回值

如果操作成功，WdfUsbTargetDeviceCreateWithParameters 将返回STATUS_SUCCESS。 否则，此方法可返回以下值之一：

返回代码 说明
STATUS_INFO_LENGTH_MISMATCH
 Config 参数的大小不正确。
STATUS_INSUFFICIENT_RESOURCES
 内存不足，无法创建新的框架 USB 设备对象。
STATUS_INVALID_PARAMETER
 检测到无效的参数。 有关详细信息，请参阅备注部分。
STATUS_UNSUCCESSFUL
 尝试获取 USB 配置信息失败。
 

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

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

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

注解

Windows 8包括支持 USB 3.0 设备的新 USB 驱动程序堆栈。

在基于框架的客户端驱动程序可以使用 USB 驱动程序堆栈的新功能进行Windows 8之前，驱动程序必须向 Windows 为设备加载的基础 USB 驱动程序堆栈注册自身。 若要注册客户端驱动程序，请调用 WdfUsbTargetDeviceCreateWithParameters 并在 WDF_USB_DEVICE_CREATE_CONFIG 结构中指定协定版本。

如果客户端驱动程序旨在生成、运行和使用 Windows 8 上的改进和新功能，则会USBD_CLIENT_CONTRACT_VERSION_602客户端协定版本。

通常，驱动程序从 EvtDevicePrepareHardware 回调函数中调用 WdfUsbTargetDeviceCreateWithParameters。 驱动程序还可以从 EvtDriverDeviceAdd 回调函数中调用 WdfUsbTargetDeviceCreateWithParameters。

有关 WDM USB 客户端驱动程序如何与 USB 3.0 驱动程序堆栈交互的信息，请参阅 最佳做法：使用 URL。

如果驱动程序调用 WdfUsbTargetDeviceCreateWithParameters 来创建框架 USB 设备对象，则驱动程序必须仅通过调用 WdfUsbTargetDeviceCreateUrb 或 WdfUsbTargetDeviceCreateIsochUrb 来创建 URB。

如果从 UMDF 驱动程序调用此方法，则必须在驱动程序的 INF 文件中指定 UmdfDispatcher 指令。 否则，此方法可能会返回 STATUS_INVALID_PARAMETER。 有关此指令的详细信息，请参阅 在 INF 文件中指定 WDF 指令。

示例

以下代码示例是调用 WdfUsbTargetDeviceCreateWithParameters 的 EvtDevicePrepareHardware 回调函数的一部分。 该示例将框架 USB 设备对象的句柄存储在驱动程序定义的上下文空间中。

NTSTATUS
MyEvtDevicePrepareHardware(
    IN WDFDEVICE  Device,
    IN WDFCMRESLIST  ResourceList,
    IN WDFCMRESLIST  ResourceListTranslated
    )
{
    NTSTATUS  status;
    PMY_DEVICE_CONTEXT  pMyDeviceContext;
    WDF_USB_DEVICE_CREATE_CONFIG  Config;

    pMyDeviceContext = GetDeviceContext(Device);

    // If object handle is not NULL, MyEvtDevicePrepareHardware
    // was called previously and the handle is still valid.
    if (pMyDeviceContext->UsbDevice != NULL) {
        return STATUS_SUCCESS;
    }

    WDF_USB_DEVICE_CREATE_CONFIG_INIT(
                                      &Config,
                                      USBD_CLIENT_CONTRACT_VERSION_602
                                      );

    status = WdfUsbTargetDeviceCreateWithParameters(
                                      Device,
                                      &Config,
                                      WDF_NO_OBJECT_ATTRIBUTES,
                                      &pMyDeviceContext->UsbDevice
                                      );
    if (!NT_SUCCESS(status)) {
        return status;
    }
...
}

要求

要求 值
目标平台 通用
最低 KMDF 版本 1.11
最低 UMDF 版本 2.0
标头 wdfusb.h (包括 Wdfusb.h)
Library Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL PASSIVE_LEVEL
DDI 符合性规则 DriverCreate (kmdf) 、 RequestForUrbXrb (kmdf) 、 UsbDeviceCreate (kmdf) 、 UsbDeviceCreateFail (kmdf) 、 UsbDeviceCreateTarget (kmdf)

另请参阅

USBD_CreateHandle

WDF_USB_DEVICE_CREATE_CONFIG

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceCreate