WdfUsbTargetDeviceCreate 函数 (wdfusb.h)

  • 项目

[适用于 KMDF 和 UMDF]

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

注意 如果使用 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 方法可能返回的其他返回值的列表，请参阅 框架对象创建错误。

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

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

注解

使用 USB I/O 目标的驱动程序必须在设备进入其工作 (D0) 状态后调用 WdfUsbTargetDeviceCreate 。 通常，驱动程序从其 EvtDevicePrepareHardware 回调函数中调用 WdfUsbTargetDeviceCreate。 (驱动程序无法从其 EvtDriverDeviceAdd 回调 function 中调用 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)
Library 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