WdfDeviceCreate 函数 (wdfdevice.h)

[适用于 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 |提供了无效 的 DeviceDeviceInit 句柄。||STATUS_INVALID_DEVICE_STATE|驱动程序已为设备创建了设备对象。||STATUS_INVALID_SECURITY_DESCR|名为 WdfDeviceInitAssignSDDLStringWdfDeviceInitSetDeviceClass 的驱动程序,但没有提供设备对象的名称。||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结构:

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

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

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

如果驱动程序为框架设备对象提供 EvtCleanupCallbackEvtDestroyCallback 回调函数,请注意,框架在 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)

另请参阅

WDFDEVICE_INIT

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE

WDF_PNPPOWER_EVENT_CALLBACKS_INIT

WdfDeviceInitFree

WdfDeviceInitSetIoType

WdfDeviceInitSetPnpPowerEventCallbacks

WdfDeviceMiniportCreate