ExRegisterCallback 関数 (wdm.h)

[アーティクル]
02/29/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 を呼び出して、コールバックルーチンを指定されたコールバックオブジェクトに登録します。

オブジェクトが登録されたコールバックルーチンを 1 つだけ許可し、そのようなルーチンが既に登録されている場合、 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 になります。
引数 1 がPO_CB_LID_SWITCH_STATEの場合、引数 2 は蓋が現在開いている場合は TRUE、蓋が閉じている場合は FALSE です。
引数 1 がPO_CB_PROCESSOR_POWER_POLICY場合、Argument2 は使用されません。
引数 1 が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 型にキャストされます。特定の条件下では、コールバックルーチンはエラー状態値をこの変数に書き込んで、新しいプロセッサを追加しない理由を示すことができます。次の 3 つの条件がすべて当てはまる場合を除き、デバイスドライバーはこの変数の値を変更しないでください。

新しいプロセッサが追加されないようにする必要があるコールバックルーチンの処理中にエラーが発生します。
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 で実行されるドライバーの場合は、可能であれば、\Callback\ProcessorAdd コールバックオブジェクトの代わりに KeRegisterProcessorChangeCallback を使用します。

コールバックオブジェクトの詳細については、「コールバックオブジェクト」を参照してください。

オペレーティングシステムは、コールバックを作成したドライバーが ExNotifyCallback ルーチンを呼び出したのと同じ IRQL で登録済みのコールバックルーチンを呼び出します。

要件

要件	値
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL
DDI コンプライアンス規則	HwStorPortProhibitedDDIs(storport), IrqlExApcLte2(wdm)