RTL_RUN_ONCE_INIT_FN回呼函式 (ntddk.h)

發行項
02/29/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

驅動程式傳遞給呼叫這個 RunOnceInitialization 例程之 RtlRunOnceExecuteOnce 例程的參數值。

[out] Context

例程寫入初始化數據的 PVOID 變數指標。

傳回值

RunOnceInitialization 例程會傳回非零值來表示成功，並傳回零表示失敗。

備註

驅動程序實作 的 RunOnceInitialization 例程會執行驅動程式特定的初始化，然後將初始化數據寫入 Context 參數指向的記憶體位置。驅動程式會使用 RtlRunOnceExecuteOnce 例程，對 RunOnceInitialization 例程進行一次性呼叫。操作系統保證 RunOnceInitialization 例程不會針對 RunOnce 參數的相同值呼叫兩次。

Context 參數所指向位置的少量低序位會保留供操作系統使用。驅動程式的 RunOnceInitialization 例程應該在寫入 *Context 的輸出值中，將這些保留位設定為零。 Ntddk.h 中定義的RTL_RUN_ONCE_CTX_RESERVED_BITS常數會指定保留的低序位數目。目前，RTL_RUN_ONCE_CTX_RESERVED_BITS定義為兩個，這表示驅動程序必須將 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呼叫。