exRegisterCallback 函式 (wdm.h)

發行項
02/27/2024

ExRegisterCallback 例程會向指定的回呼對象註冊指定的回呼例程。

語法

PVOID ExRegisterCallback(
  [in, out]      PCALLBACK_OBJECT   CallbackObject,
  [in]           PCALLBACK_FUNCTION CallbackFunction,
  [in, optional] PVOID              CallbackContext
);

參數

[in, out] CallbackObject

從 ExCreateCallback 例程取得之回呼物件的指標。

[in] CallbackFunction

驅動程式實作回呼例程的指標，必須不可分頁。回呼例程必須符合下列原型：

VOID
(*PCALLBACK_FUNCTION ) (
    IN PVOID CallbackContext,
    IN PVOID Argument1,
    IN PVOID Argument2
    );

回呼例程參數如下所示：

CallbackContext

驅動程式提供之內容區域的指標，如 ExRegisterCallback 的 CallbackContext 參數所指定。

Argument1

回呼物件所定義之參數的指標。

Argument2

回呼物件所定義之參數的指標。

[in, optional] CallbackContext

每次呼叫回呼例程時，要當做回呼例程內容參數傳遞之呼叫端定義之數據項結構的指標。內容通常是呼叫端裝置物件延伸模組的一部分。

傳回值

ExRegisterCallback 會傳回回回呼註冊句柄的指標，該句柄應該視為不透明且保留給系統使用。如果 ExRegisterCallback 完成併發生錯誤，則此指標為 NULL。

備註

驅動程式會呼叫 ExRegisterCallback ，以向指定的回呼物件註冊回呼例程。

如果物件只允許一個已註冊的回呼例程，而且已註冊這類例程， ExRegisterCallback 會傳回 NULL。

ExRegisterCallback 的呼叫端必須儲存傳回的指標，以供稍後在呼叫 ExUnregisterCallback 中使用。從回呼物件的已註冊回呼例程清單中移除回呼例程時，需要指標。

已註冊回呼例程之 Argument1 和 Argument2 的意義取決於回呼物件，並由建立它的元件所定義。以下是系統定義回呼物件的參數：

\Callback\SetSystemTime

Argument1 (SetSystemTime)

未使用。

Argument2 (SetSystemTime)

未使用。

\Callback\PowerState**

Argument1 (PowerState)

轉換成 PVOID 類型的PO_CB_XXX常數值。
PO_CB_AC_STATUS — 表示系統已從 A/C 變更為電池電源，反之亦然。
PO_CB_LID_SWITCH_STATE — 指出蓋子開關的狀態已變更。
PO_CB_PROCESSOR_POWER_POLICY — 指出系統處理器電源原則已變更。
PO_CB_SYSTEM_POWER_POLICY — 指出系統電源原則已變更。
PO_CB_SYSTEM_STATE_LOCK — 表示系統電源狀態變更即將發生。分頁路徑中的驅動程式可以註冊此回呼，以接收這類變更的早期警告，讓他們有機會在電源狀態變更之前鎖定其記憶體中的程序代碼。

Argument2 (PowerState)

轉換成 PVOID 類型的 TRUE 或 FALSE 值。

如果 Argument1 是PO_CB_AC_STATUS，如果電腦目前使用 A/C 電源供應器， 則 Argument2 為 TRUE ，如果電腦正在電池電源上執行，則為 FALSE 。
如果 Argument1 是PO_CB_LID_SWITCH_STATE，則如果 lid 目前開啟， 則 Argument2 為 TRUE ，如果蓋子已關閉，則為 FALSE 。
如果 Argument1 是PO_CB_PROCESSOR_POWER_POLICY，則不會使用 Argument2 。
如果 Argument1 是PO_CB_SYSTEM_POWER_POLICY，則不會使用 Argument2 。
如果 Argument1 是PO_CB_SYSTEM_STATE_LOCK，如果電腦即將結束系統電源狀態 S0， 則 Argument2 為 FALSE ，如果電腦剛重新進入 S0，則為 TRUE 。

\Callback\ProcessorAdd

Argument1 (ProcessorAdd)

描述處理器變更通知事件的 KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT 結構的指標。此指標會轉換成 PVOID 類型。回呼例程不得修改這個結構的內容。

Argument2 (ProcessorAdd)

包含 NTSTATUS 值的變數指標。此指標會轉換成 PVOID 類型。在特定情況下，回呼例程可以將錯誤狀態值寫入此變數，以指出為什麼不應該加入新的處理器。除非下列三個條件成立，否則設備驅動器不得變更此變數的值：

回呼例程的處理期間發生錯誤，應防止新增處理器。
Argument1 指向之KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT結構 State 成員的值是 KeProcessorAddStartNotify。
Argument2 指向的 NSTATUS 變數包含值STATUS_SUCCESS。也就是說，回呼例程不得覆寫先前由另一個回呼通知用戶端所撰寫的錯誤狀態值。

從 Windows Vista 開始， \Callback\ProcessorAdd 回呼物件可用來動態追蹤處理器母體擴展中的變更。 KeRegisterProcessorChangeCallback 例程提供類似的資訊，但另外也支援KE_PROCESSOR_CHANGE_ADD_EXISTING旗標，驅動程式可用來列舉初始多處理器系統設定中的處理器。對於在 Windows Server 2008 和更新版本的 Windows 中執行的驅動程式，請盡可能使用 KeRegisterProcessorChangeCallback ，而不是 \Callback\ProcessorAdd 回 呼物件。

如需回呼對象的詳細資訊，請參閱回呼物件。

操作系統會在建立回呼的驅動程式呼叫呼叫 ExNotifyCallback 例程的相同 IRQL 註冊回呼例程。

規格需求

需求	值
目標平台	Universal
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL
DDI 合規性規則	HwStorPortProhibitedDDIs (storport) 、 IrqlExApcLte2 (wdm)