exCreateCallback 函式 (wdm.h)

  • 發行項

ExCreateCallback 例程會建立新的回呼物件，或代表呼叫端開啟現有的回呼物件。

語法

NTSTATUS ExCreateCallback(
  [out] PCALLBACK_OBJECT   *CallbackObject,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in]  BOOLEAN            Create,
  [in]  BOOLEAN            AllowMultipleCallbacks
);

參數

[out] CallbackObject

接收回呼對象指標之位置的指標，這是不透明的系統結構。 如果 ExCreateCallback 呼叫成功，例程會將新建立或開啟的回呼對象的位址寫入此位置。 從這個例程取得的回呼對象指標可以做為 ExRegisterCallback 或 ExNotifyCallback 例程的參數提供。

[in] ObjectAttributes

包含回呼物件屬性 之OBJECT_ATTRIBUTES 結構的指標。 此結構先前是由 InitializeObjectAttributes 例程初始化。

[in] Create

是否要建立回呼物件。 如果無法開啟要求的物件，請將 設定為 TRUE 以建立新的回呼物件。 否則，請將 設定為 FALSE。

[in] AllowMultipleCallbacks

新建立的回呼物件是否應該允許多個已註冊的回呼例程。 設定為 TRUE 以允許多個已註冊的回呼例程。 否則，請將 設定為 FALSE。 當 Create 為 FALSE 或開啟現有物件時，會忽略此參數。

傳回值

如果已開啟或建立回呼物件，ExCreateCallback 會傳回STATUS_SUCCESS。 否則，它會傳回NTSTATUS錯誤碼，以指出失敗的本質。

備註

驅動程式會呼叫 ExCreateCallback 來建立新的回呼物件，或開啟現有的回呼物件。 建立或開啟對象之後，其他元件可以呼叫 ExRegisterCallback 例程，向回呼物件註冊回呼例程。

呼叫 ExCreateCallback 之前，驅動程式必須先呼叫 InitializeObjectAttributes ，才能初始化回呼物件的 OBJECT_ATTRIBUTES 結構。 不允許未命名的回呼物件。 呼叫端必須指定物件的名稱;否則，呼叫會因為STATUS_UNSUCCESSFUL而失敗。 呼叫端應該在回呼物件中指定OBJ_PERMANENT屬性，以防止刪除物件，才能向物件管理員註冊該物件。 呼叫端也應該指定可能需要的任何其他屬性，例如OBJ_CASE_INSENSITIVE。

當所有作業都使用回呼物件完成時，驅動程式必須刪除物件，以避免記憶體流失。 如需刪除使用 OBJ_PERMANENT 物件屬性所建立之物件的資訊，請參閱 ObDereferenceObject。

下表顯示操作系統建立供驅動程式使用的回呼物件。

回呼物件名稱 使用方式
\Callback\SetSystemTime 每當系統時間變更時，操作系統就會呼叫針對這個物件註冊的任何回呼例程。
\Callback\PowerState 每當特定系統電源特性變更時，操作系統就會呼叫針對這個物件註冊的任何回呼例程。 當驅動程式藉由呼叫 ExRegisterCallback) 註冊回呼通知 (時，它可以指定應通知的變更。
 

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

規格需求

需求 值
最低支援的用戶端 從 Windows 2000 開始提供。
目標平台 Universal
標頭 wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫 NtosKrnl.lib
Dll NtosKrnl.exe
IRQL <= APC_LEVEL
DDI 合規性規則 HwStorPortProhibitedDDIs (storport) 、 IrqlExApcLte2 (wdm) 、IrqlExPassive

另請參閱

ExNotifyCallback

ExRegisterCallback

InitializeObjectAttributes

ObDereferenceObject