WdfDrivercreate 函数 (wdfdriver.h)

项目
03/05/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

指向 DRIVER_OBJECT 结构的指针，该结构表示 Windows 驱动程序模型 (WDM) 驱动程序对象。驱动程序接收此指针作为其 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	名为 WdfDriver 的驱动程序多次创建。
STATUS_INVALID_PARAMETER	非即插即用 (PnP) 驱动程序指定了 EvtDriverDeviceAdd 回调函数。

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

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

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

注解

使用 Kernel-Mode Driver Framework 的驱动程序必须在调用任何其他框架例程之前，从其 DriverEntry 例程中调用 WdfDriverCreate。有关 DriverEntry 的详细信息，请参阅 DriverEntry for Framework-based Drivers。

在驱动程序调用 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)
Library	Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI 符合性规则	ChangeQueueState (kmdf) 、 DriverAttributeChanged (kmdf) 、 DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、KmdfIrqlExplicit (kmdf) ， MiniportOnlyWdmDevice (kmdf)