WdfDeviceCreate 函式 (wdfdevice.h)

發行項
02/27/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。其他傳回值包括：

傳回碼	Description
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 可以傳回的其他傳回值清單，請參閱 Framework 物件建立錯誤。

方法可能會傳回其他 NTSTATUS值。

備註

呼叫 WdfDeviceCreate 之前，驅動程式必須呼叫架構提供的函式，以初始化WDFDEVICE_INIT結構。如需初始化此結構的詳細資訊，請參閱 WDFDEVICE_INIT。如果驅動程式在呼叫初始化函式時遇到錯誤，它不得呼叫 WdfDeviceCreate。在此情況下，驅動程式可能必須呼叫 WdfDeviceInitFree。如需何時呼叫 WdfDeviceInitFree 的相關信息，請參閱 WdfDeviceInitFree。

呼叫 WdfDeviceCreate 會建立架構裝置物件，此物件代表 FDO) 的功能裝置物件 (，或 PDO) (實體裝置物件。函式所建立的裝置物件類型取決於驅動程式如何取得WDFDEVICE_INIT結構：

如果驅動程式從 EvtDriverDeviceAdd 回呼收到WDFDEVICE_INIT結構， WdfDeviceCreate 會 建立 FDO。
如果驅動程式從 EvtChildListCreateDevice 回呼收到WDFDEVICE_INIT結構，或從呼叫 WdfPdoInitAllocate，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;
}

規格需求

需求	值
目標平台	Universal
最低 KMDF 版本	1.0
最低UMDF版本	2.0
標頭	wdfdevice.h (包含 Wdf.h)
程式庫	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)