WdfDeviceCreate 函数 (wdfdevice.h)

项目
05/14/2024

[适用于 KMDF 和 UMDF]

WdfDeviceCreate 方法创建框架设备对象。

语法

NTSTATUS WdfDeviceCreate(
  [in, out]      PWDFDEVICE_INIT        *DeviceInit,
  [in, optional] PWDF_OBJECT_ATTRIBUTES DeviceAttributes,
  [out]          WDFDEVICE              *Device
);

参数

[in, out] DeviceInit

指向 WDFDEVICE_INIT 结构的指针的地址。如果 WdfDeviceCreate 未遇到任何错误，则会将指针设置为 NULL。

[in, optional] DeviceAttributes

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

[out] Device

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

返回值

如果 WdfDeviceCreate 方法未遇到任何错误，则返回STATUS_SUCCESS。其他返回值包括：

|返回代码 |说明| |--- |--- | |STATUS_INVALID_PARAMETER |提供了无效 的 Device 或 DeviceInit 句柄。||STATUS_INVALID_DEVICE_STATE|驱动程序已为设备创建了设备对象。||STATUS_INVALID_SECURITY_DESCR|名为 WdfDeviceInitAssignSDDLString 或 WdfDeviceInitSetDeviceClass 的驱动程序，但没有提供设备对象的名称。||STATUS_INSUFFICIENT_RESOURCES |无法分配设备对象。||STATUS_OBJECT_NAME_COLLISION|通过调用 WdfDeviceInitAssignName 指定的设备名称已存在。驱动程序可以再次调用 WdfDeviceInitAssignName 来分配新名称。| 有关 WdfDeviceCreate 可以返回的其他返回值的列表，请参阅框架对象创建错误。

方法可能会返回其他 NTSTATUS 值。

注解

在调用 WdfDeviceCreate 之前，驱动程序必须调用框架提供的用于初始化WDFDEVICE_INIT结构的函数。有关初始化此结构的详细信息，请参阅 WDFDEVICE_INIT。如果驱动程序在调用初始化函数时遇到错误，则它不得调用 WdfDeviceCreate。在这种情况下，驱动程序可能必须调用 WdfDeviceInitFree。有关何时调用 WdfDeviceInitFree 的信息，请参阅 WdfDeviceInitFree。

调用 WdfDeviceCreate 会创建一个框架设备对象，该对象表示 (FDO) 的功能设备对象或 (PDO) 的物理设备对象。函数创建的设备对象的类型取决于驱动程序如何获取WDFDEVICE_INIT结构：

如果驱动程序从 EvtDriverDeviceAdd 回调收到 WDFDEVICE_INIT 结构， 则 WdfDeviceCreate 将创建 FDO。
如果驱动程序从 EvtChildListCreateDevice 回调或从 WdfPdoInitAllocate 的调用接收了 WDFDEVICE_INIT 结构， 则 WdfDeviceCreate 将创建 PDO。

驱动程序调用 WdfDeviceCreate 后，它将无法再访问 WDFDEVICE_INIT 结构。

使用框架的微型端口驱动程序必须调用 WdfDeviceMiniportCreate ，而不是 WdfDeviceCreate。

每个框架设备对象的父级都是驱动程序的框架驱动程序对象。驱动程序无法更改此父级，并且 WDF_OBJECT_ATTRIBUTES 结构的 ParentObject 成员必须为 NULL。即插即用 (PnP () 管理器确定已删除设备时，框架会删除每个框架设备对象，但) 即插即用 (控制设备对象除外。

如果驱动程序为框架设备对象提供 EvtCleanupCallback 或 EvtDestroyCallback 回调函数，请注意，框架在 IRQL = PASSIVE_LEVEL调用这些回调函数。

有关创建设备对象的详细信息，请参阅创建框架设备对象。

示例

下面的代码示例演示 EvtDriverDeviceAdd 回调函数如何初始化和创建设备对象。

NTSTATUS
MyEvtDeviceAdd(
    IN WDFDRIVER  Driver,
    IN PWDFDEVICE_INIT  DeviceInit
    )
{
    WDF_PNPPOWER_EVENT_CALLBACKS  pnpPowerCallbacks;
    WDF_OBJECT_ATTRIBUTES  attributes;
    NTSTATUS  status;
    WDFDEVICE  device;
 
    //
    // Initialize the WDF_PNPPOWER_EVENT_CALLBACKS structure.
    //
    WDF_PNPPOWER_EVENT_CALLBACKS_INIT(&pnpPowerCallbacks);
    pnpPowerCallbacks.EvtDevicePrepareHardware = MyEvtDevicePrepareHardware;
    pnpPowerCallbacks.EvtDeviceD0Entry = MyEvtDeviceD0Entry;
    pnpPowerCallbacks.EvtDeviceD0Exit  = MyEvtDeviceD0Exit;
    WdfDeviceInitSetPnpPowerEventCallbacks(
                                           DeviceInit,
                                           &pnpPowerCallbacks
                                           );
    //
    // This driver uses buffered I/O.
    //
    WdfDeviceInitSetIoType(
                           DeviceInit,
                           WdfDeviceIoBuffered
                           );
 
    //
    // Specify the device object's context space by
    // using a driver-defined DEVICE_CONTEXT structure.
 //
    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                            &attributes,
                                            DEVICE_CONTEXT
                                            );
 //
    // Create the device object.
    //
    status = WdfDeviceCreate(
                             &DeviceInit,
                             &attributes,
                             &device
                             );
    if (!NT_SUCCESS(status)) {
        return status;
    }
    return STATUS_SUCCESS;
}

要求

要求	值
目标平台	通用
最低 KMDF 版本	1.0
最低 UMDF 版本	2.0
标头	wdfdevice.h (包括 Wdf.h)
Library	Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI 符合性规则	AccessHardwareKey (kmdf) 、 AddPdoToStaticChildList (kmdf) 、 ChangeQueueState (kmdf) 、 ChildDeviceInitAPI (kmdf) 、 ChildListConfiguration (kmdf) 、 ControlDeviceDeleted (kmdf) 、 ControlDeviceInitAllocate (kmdf) 、 ControlDeviceInitAPI (kmdf) 、 CtlDeviceFinishInitDeviceAdd (kmdf) 、 CtlDeviceFinishInitDrEntry (kmdf) ， DeviceCreateFail (kmdf) 、 DeviceInitAllocate (kmdf) 、 DeviceInitAPI (kmdf) 、 DriverCreate (kmdf) 、 InitFreeDeviceCreate (kmdf) 、 InitFreeDeviceCreateType2 (kmdf) 、 InitFreeDeviceCreateType4 (kmdf) 、 InitFreeNull (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、KmdfIrqlExplicit (kmdf) ， PdoDeviceInitAPI (kmdf) 、 PdoInitFreeDeviceCreate (kmdf) 、 PdoInitFreeDeviceCreateType2 (kmdf) 、 PdoInitFreeDeviceCreateType4 (kmdf)