通过

WdfUsbTargetDeviceCreate 函数 （wdfusb.h）

  • 项目

[适用于 KMDF 和 UMDF]

WdfUsbTargetDeviceCreate 方法为指定的框架设备对象创建框架 USB 设备对象，并为 I/O作打开 USB 设备。

注意 如果使用 KMDF 1.11 或 UMDF 2.0 或更高版本生成驱动程序，建议调用 WdfUsbTargetDeviceCreateWithParameters 而不是 WdfUsbTargetDeviceCreate。
 

语法

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

参数

[in] Device

框架设备对象的句柄。

[in, optional] Attributes

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

[out] UsbDevice

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

返回值

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

返回代码 描述
STATUS_INVALID_PARAMETER
 检测到无效参数。
STATUS_INSUFFICIENT_RESOURCES
 内存不足，无法创建新的 USB 设备对象。
STATUS_UNSUCCESSFUL
 尝试获取 USB 配置信息失败。
 

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

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

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

言论

使用 USB I/O 目标的驱动程序必须在设备进入工作状态（D0）后调用 WdfUsbTargetDeviceCreate。 通常，驱动程序从其 EvtDevicePrepareHardware 回调函数中调用 WdfUsbTargetDeviceCreate。 （驱动程序无法从其 EvtDriverDeviceAdd 回调函数中调用 WdfUsbTargetDeviceCreate。

WdfUsbTargetDeviceCreate 从设备获取 USB 设备描述符和第一个 USB 配置描述符并存储它们。 它还为设备的第一个配置中的每个接口创建框架 USB 接口对象。 若要确定配置支持的接口数，驱动程序可以调用 WdfUsbTargetDeviceGetNumInterfaces。

调用 WdfUsbTargetDeviceCreate后，驱动程序可以调用 框架 USB 设备对象方法。

每个 USB 设备对象的父对象是驱动程序的框架驱动程序对象。 驱动程序无法更改此父级，并且 ParentObject 成员或 WDF_OBJECT_ATTRIBUTES 结构必须 NULL。

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

例子

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

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

    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;
    }
 status = WdfUsbTargetDeviceCreate(
                                      Device,
                                      WDF_NO_OBJECT_ATTRIBUTES,
                                      &pMyDeviceContext->UsbDevice
                                      );
    if (!NT_SUCCESS(status)) {
        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），UsbDeviceCreate（kmdf），UsbDeviceCreateFail（kmdf）， UsbDeviceCreateTarget（kmdf）， UsbKmdfIrql（kmdf）， UsbKmdfIrql2（kmdf）， UsbKmdfIrqlExplicit（kmdf）

另请参阅

EvtDevicePrepareHardware

WDF_OBJECT_ATTRIBUTES

WdfUsbTargetDeviceGetNumInterfaces