WdfDriverCreate 函数（wdfdriver.h）

2025-03-22

[适用于 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。否则，此方法可能会返回以下值之一：

返回代码	说明
STATUS_DRIVER_INTERNAL_ERROR	多次调用 WdfDriverCreate 的驱动程序。
STATUS_INVALID_PARAMETER	非即插即用（PnP）驱动程序指定了 EvtDriverDeviceAdd 回调函数。

有关返回值的详细信息，请参阅 Framework 对象创建错误。

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

如果 DriverObject、RegistryPath或 DriverConfig 参数 NULL，则会发生系统 bug 检查。

注解

使用 Kernel-Mode Driver Framework 的驱动程序必须先从其 DriverEntry 例程中调用 WdfDriverCreate，然后才能调用任何其他框架例程。有关 DriverEntry的详细信息，请参阅 DriverEntry for Framework。

在驱动程序调用 WdfDriverCreate之前，驱动程序必须调用 WDF_DRIVER_CONFIG_INIT 来初始化其 WDF_DRIVER_CONFIG 结构。

框架驱动程序对象是驱动程序框架对象的树的顶部，因此没有父对象。

如果驱动程序为驱动程序对象提供 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;
}

要求

要求	价值
目标平台	普遍
最低 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）