RTL_RUN_ONCE_INIT_FN回调函数 (ntddk.h)
RunOnceInitialization 例程执行一次性初始化操作。
语法
ULONG /* LOGICAL */
NTAPI
RTL_RUN_ONCE_INIT_FN (
_Inout_ PRTL_RUN_ONCE RunOnce,
_Inout_opt_ PVOID Parameter,
_Inout_opt_ PVOID *Context
);
typedef RTL_RUN_ONCE_INIT_FN *PRTL_RUN_ONCE_INIT_FN;
参数
[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 调用。 |