WdfDriverCreate 函式 (wdfdriver.h)

發行項
02/27/2024

[適用於 KMDF 和 UMDF]

WdfDriverCreate 方法會建立呼叫驅動程式的架構驅動程序物件。

語法

NTSTATUS WdfDriverCreate(
  [in]            PDRIVER_OBJECT         DriverObject,
  [in]            PCUNICODE_STRING       RegistryPath,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES DriverAttributes,
  [in]            PWDF_DRIVER_CONFIG     DriverConfig,
  [out, optional] WDFDRIVER              *Driver
);

參數

[in] DriverObject

代表 Windows 驅動程式模型 ( WDM) 驅動程式物件的DRIVER_OBJECT結構的指標。驅動程式會接收此指標作為其 DriverEntry 例程的輸入。

[in] RegistryPath

UNICODE_STRING 結構的指標，其中包含驅動程式收到作為其 DriverEntry 例程輸入的登錄路徑字串。

[in, optional] DriverAttributes

呼叫端配置 WDF_OBJECT_ATTRIBUTES 結構的指標。 (結構的 ParentObject 成員必須是 NULL。) 此參數是選擇性的，而且可以WDF_NO_OBJECT_ATTRIBUTES。

[in] DriverConfig

呼叫端配置 WDF_DRIVER_CONFIG 結構的指標。

[out, optional] Driver

接收新架構驅動程序物件句柄之位置的指標。這個參數是選擇性的，而且可以WDF_NO_HANDLE。

傳回值

如果作業成功，WdfDriverCreate 會傳回STATUS_SUCCESS。否則，這個方法可能會傳回下列其中一個值：

傳回碼	Description
STATUS_DRIVER_INTERNAL_ERROR	名為 WdfDriverCreate 的驅動程式多次。
STATUS_INVALID_PARAMETER	非隨插即用 (PnP) 驅動程式指定了 EvtDriverDeviceAdd 回呼函式。

如需傳回值的詳細資訊，請參閱 Framework 物件建立錯誤。

這個方法也可能傳回其他 NTSTATUS值。

如果 DriverObject、 RegistryPath 或 DriverConfig 參數為 NULL，就會發生系統錯誤檢查。

備註

使用 Kernel-Mode Driver Framework 的驅動程式必須先從其 DriverEntry 例程內呼叫 WdfDriverCreate，再呼叫任何其他架構例程。如需 DriverEntry 的詳細資訊，請參閱 DriverEntry for Framework 型驅動程式。

在驅動程式呼叫 WdfDriverCreate 之前，驅動程式必須先呼叫 WDF_DRIVER_CONFIG_INIT ，才能初始化其 WDF_DRIVER_CONFIG 結構。

Framework 驅動程式對象是驅動程式架構物件樹狀結構頂端，因此沒有父物件。

如果您的驅動程式為驅動程序物件提供 EvtCleanupCallback 或 EvtDestroyCallback 回呼函式，請注意架構會在 IRQL = PASSIVE_LEVEL呼叫這些回呼函式。

範例

下列程式代碼範例是 DriverEntry 例程，它會初始化WDF_DRIVER_CONFIG結構，然後建立架構驅動程序物件。

NTSTATUS
DriverEntry(
    IN PDRIVER_OBJECT  DriverObject,
    IN PUNICODE_STRING  RegistryPath
    )
{
    WDF_DRIVER_CONFIG  config;
    NTSTATUS  status = STATUS_SUCCESS;

    WDF_DRIVER_CONFIG_INIT(
                           &config,
                           MyEvtDeviceAdd
                           );
    config.EvtDriverUnload = MyEvtDriverUnload;
    status = WdfDriverCreate(
                             DriverObject,
                             RegistryPath,
                             WDF_NO_OBJECT_ATTRIBUTES,
                              &config,
                             WDF_NO_HANDLE
                             );
    if (!NT_SUCCESS(status)) {
        TraceEvents(
                    TRACE_LEVEL_ERROR,
                    DBG_PNP,
                    "WdfDriverCreate failed with status %!STATUS!",
                    status
                    );
    }
    return status;
}

規格需求

需求	值
目標平台	Universal
最低 KMDF 版本	1.0
最低UMDF版本	2.0
標頭	wdfdriver.h (包含 Wdf.h)
程式庫	Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI 合規性規則	ChangeQueueState (kmdf) 、DriverAttributeChanged (kmdf) 、DriverCreate (kmdf) 、KmdfIrql (kmdf ) 、KmdfIrql2 (kmdf) 、KmdfIrqlExplicit (kmdf) 、 MiniportOnlyWdmDevice (kmdf)