RTL_RUN_ONCE_INIT_FN回调函数 (ntddk.h)

项目
02/26/2024

RunOnceInitialization 例程执行一次性初始化操作。

语法

RTL_RUN_ONCE_INIT_FN (
    _Inout_ PRTL_RUN_ONCE RunOnce,
    _Inout_opt_ PVOID Parameter,
    _Inout_opt_ PVOID *Context
  );

参数

[in, out] RunOnce

指向 RTL_RUN_ONCE一次性初始化结构的指针，驱动程序之前将该结构作为参数传递给调用此 RunOnceInitialization 例程的 RtlRunOnceExecuteOnce 例程。

[in, out] Parameter

驱动程序传递给 RtlRunOnceExecuteOnce 例程的 Parameter 值，该例程调用此 RunOnceInitialization 例程。

[out] Context

指向例程写入初始化数据的 PVOID 变量的指针。

返回值

RunOnceInitialization 例程返回非零值表示成功，返回零表示失败。

注解

驱动程序实现的 RunOnceInitialization 例程执行特定于驱动程序的初始化，然后将初始化数据写入 Context 参数指向的内存位置。驱动程序使用 RtlRunOnceExecuteOnce 例程对 RunOnceInitialization 例程进行一次性调用。操作系统保证 RunOnceInitialization 例程不会针对 RunOnce 参数的相同值调用两次。

上下文参数指向的位置中保留少量低序位供操作系统使用。驱动程序的 RunOnceInitialization 例程应在写入到 *Context 的输出值中将这些保留位设置为零。 Ntddk.h 中定义的RTL_RUN_ONCE_CTX_RESERVED_BITS常量指定保留的低序位数。目前，RTL_RUN_ONCE_CTX_RESERVED_BITS定义为 2，这意味着驱动程序必须将 Context 指向的 PVOID 值的两个最小有效位设置为零。

示例

若要定义 RunOnceInitialization 回调例程，必须先提供一个函数声明来标识要定义的回调例程的类型。 Windows 为驱动程序提供了一组回调函数类型。使用回调函数类型声明函数可帮助驱动程序的代码分析、静态驱动程序验证程序 (SDV) 和其他验证工具查找错误，这是为 Windows 操作系统编写驱动程序的要求。

例如，若要定义名为 MyRunOnceInitialization的 RunOnceInitialization 回调例程，请使用 RTL_RUN_ONCE_INIT_FN 类型，如以下代码示例所示：

RTL_RUN_ONCE_INIT_FN MyRunOnceInitialization;

然后，按如下所示实现回调例程：

_Use_decl_annotations_
ULONG 
  MyRunOnceInitialization(
    PRTL_RUN_ONCE  RunOnce,
    PVOID  Parameter,
    PVOID  *Context
    )
  {
      // Function body
  }

RTL_RUN_ONCE_INIT_FN函数类型在 Wdm.h 头文件中定义。若要在运行代码分析工具时更准确地识别错误，请务必将 _Use_decl_annotations_ 注释添加到函数定义。注释 _Use_decl_annotations_ 可确保使用应用于头文件中RTL_RUN_ONCE_INIT_FN函数类型的注释。有关函数声明要求的详细信息，请参阅使用 WDM 驱动程序的函数角色类型声明函数。有关的信息 _Use_decl_annotations_，请参阅批注函数行为。

要求

要求	值
最低受支持的客户端	驱动程序只能在 Windows Vista 和更高版本的 Windows 上实现 RunOnceInitialization 例程。
目标平台	桌面
标头	ntddk.h (包括 Ntddk.h、Ntifs.h)
IRQL	在 IRQL <= APC_LEVEL 调用。