次の方法で共有


EX_CALLBACK_FUNCTION コールバック関数 (wdm.h)

フィルター ドライバーの RegistryCallback ルーチンは、レジストリ操作を監視、ブロック、または変更できます。

構文

EX_CALLBACK_FUNCTION ExCallbackFunction;

NTSTATUS ExCallbackFunction(
  [in]           PVOID CallbackContext,
  [in, optional] PVOID Argument1,
  [in, optional] PVOID Argument2
)
{...}

パラメーター

[in] CallbackContext

この RegistryCallback ルーチンを登録したときに、ドライバーが Context パラメーターとして CmRegisterCallback または CmRegisterCallbackEx に渡した値。

[in, optional] Argument1

実行されているレジストリ操作の種類と、レジストリ操作の実行前または実行後に RegistryCallback ルーチンが呼び出されているかどうかを識別する、REG_NOTIFY_CLASS型指定された値。

[in, optional] Argument2

レジストリ操作の種類に固有の情報を含む構造体へのポインター。 構造体の型は、次の表に示すように、Argument1REG_NOTIFY_CLASS型指定された値によって異なります。 オペレーティング システムのバージョンに使用できるREG_NOTIFY_CLASS型指定された値については、「 REG_NOTIFY_CLASS」を参照してください。

REG_NOTIFY_CLASS値 構造の種類
RegNtDeleteKey REG_DELETE_KEY_INFORMATION
RegNtPreDeleteKey REG_DELETE_KEY_INFORMATION
RegNtPostDeleteKey REG_POST_OPERATION_INFORMATION
RegNtSetValueKey REG_SET_VALUE_KEY_INFORMATION
RegNtPreSetValueKey REG_SET_VALUE_KEY_INFORMATION
RegNtPostSetValueKey REG_POST_OPERATION_INFORMATION
RegNtDeleteValueKey REG_DELETE_VALUE_KEY_INFORMATION
RegNtPreDeleteValueKey REG_DELETE_VALUE_KEY_INFORMATION
RegNtPostDeleteValueKey REG_POST_OPERATION_INFORMATION
RegNtSetInformationKey REG_SET_INFORMATION_KEY_INFORMATION
RegNtPreSetInformationKey REG_SET_INFORMATION_KEY_INFORMATION
RegNtPostSetInformationKey REG_POST_OPERATION_INFORMATION
RegNtRenameKey REG_RENAME_KEY_INFORMATION
RegNtPreRenameKey REG_RENAME_KEY_INFORMATION
RegNtPostRenameKey REG_POST_OPERATION_INFORMATION
RegNtEnumerateKey REG_ENUMERATE_KEY_INFORMATION
RegNtPreEnumerateKey REG_ENUMERATE_KEY_INFORMATION
RegNtPostEnumerateKey REG_POST_OPERATION_INFORMATION
RegNtEnumerateValueKey REG_ENUMERATE_VALUE_KEY_INFORMATION
RegNtPreEnumerateValueKey REG_ENUMERATE_VALUE_KEY_INFORMATION
RegNtPostEnumerateValueKey REG_POST_OPERATION_INFORMATION
RegNtQueryKey REG_QUERY_KEY_INFORMATION
RegNtPreQueryKey REG_QUERY_KEY_INFORMATION
RegNtPostQueryKey REG_POST_OPERATION_INFORMATION
RegNtQueryValueKey REG_QUERY_VALUE_KEY_INFORMATION
RegNtPreQueryValueKey REG_QUERY_VALUE_KEY_INFORMATION
RegNtPostQueryValueKey REG_POST_OPERATION_INFORMATION
RegNtQueryMultipleValueKey REG_QUERY_MULTIPLE_VALUE_KEY_INFORMATION
RegNtPreQueryMultipleValueKey REG_QUERY_MULTIPLE_VALUE_KEY_INFORMATION
RegNtPostQueryMultipleValueKey REG_POST_OPERATION_INFORMATION
RegNtPreCreateKey REG_PRE_CREATE_KEY_INFORMATION
RegNtPreCreateKeyEx REG_CREATE_KEY_INFORMATION**
RegNtPostCreateKey REG_POST_CREATE_KEY_INFORMATION
RegNtPostCreateKeyEx REG_POST_OPERATION_INFORMATION
RegNtPreOpenKey REG_PRE_OPEN_KEY_INFORMATION**
RegNtPreOpenKeyEx REG_OPEN_KEY_INFORMATION
RegNtPostOpenKey REG_POST_OPEN_KEY_INFORMATION
RegNtPostOpenKeyEx REG_POST_OPERATION_INFORMATION
RegNtKeyHandleClose REG_KEY_HANDLE_CLOSE_INFORMATION
RegNtPreKeyHandleClose REG_KEY_HANDLE_CLOSE_INFORMATION
RegNtPostKeyHandleClose REG_POST_OPERATION_INFORMATION
RegNtPreFlushKey REG_FLUSH_KEY_INFORMATION
RegNtPostFlushKey REG_POST_OPERATION_INFORMATION
RegNtPreLoadKey REG_LOAD_KEY_INFORMATION
RegNtPostLoadKey REG_POST_OPERATION_INFORMATION
RegNtPreUnLoadKey REG_UNLOAD_KEY_INFORMATION
RegNtPostUnLoadKey REG_POST_OPERATION_INFORMATION
RegNtPreQueryKeySecurity REG_QUERY_KEY_SECURITY_INFORMATION
RegNtPostQueryKeySecurity REG_POST_OPERATION_INFORMATION
RegNtPreSetKeySecurity REG_SET_KEY_SECURITY_INFORMATION
RegNtPostSetKeySecurity REG_POST_OPERATION_INFORMATION
RegNtCallbackObjectContextCleanup REG_CALLBACK_CONTEXT_CLEANUP_INFORMATION
RegNtPreRestoreKey REG_RESTORE_KEY_INFORMATION
RegNtPostRestoreKey REG_POST_OPERATION_INFORMATION
RegNtPreSaveKey REG_SAVE_KEY_INFORMATION
RegNtPostSaveKey REG_POST_OPERATION_INFORMATION
RegNtPreReplaceKey REG_REPLACE_KEY_INFORMATION
RegNtPostReplaceKey REG_POST_OPERATION_INFORMATION
RegNtPreQueryKeyName REG_QUERY_KEY_NAME
RegNtPostQueryKeyName REG_POST_OPERATION_INFORMATION
RegNtPreSaveMergedKey REG_SAVE_MERGED_KEY_INFORMATION
RegNtPostSaveMergedKey REG_POST_OPERATION_INFORMATION

Windows 7 以降では、notify クラスが RegNtPreCreateKeyEx または RegNtPreOpenKeyEx のときに渡される実際のデータ構造は、それぞれこの構造体の V1 バージョン REG_CREATE_KEY_INFORMATION_V1 または REG_OPEN_KEY_INFORMATION_V1です。 予約済みメンバーを調べて、構造体のバージョンを確認します。

バージョン番号 [構造名]
0 REG_CREATE_KEY_INFORMATIONとREG_OPEN_KEY_INFORMATION
1 REG_CREATE_KEY_INFORMATION_V1とREG_OPEN_KEY_INFORMATION_V1

戻り値

RegistryCallback ルーチンがこれらの各状態値を返すタイミングの詳細については、「レジストリ呼び出しのフィルター処理」を参照してください。

注釈

レジストリ操作の通知を受け取るために、カーネル モード コンポーネント (ウイルス対策ソフトウェア パッケージのドライバー コンポーネントなど) は 、CmRegisterCallback または CmRegisterCallbackEx を呼び出して RegistryCallback ルーチンを登録できます。

RegistryCallback ルーチンは、レジストリ操作用に提供される入力バッファーと出力バッファーの内容を検査できます。 レジストリ操作は、ユーザー モード レジストリ ルーチン ( RegCreateKeyExRegOpenKeyEx など) を呼び出すユーザー モード アプリケーション、またはカーネル モード レジストリ ルーチン ( ZwCreateKeyZwOpenKey など) を呼び出すドライバーによって開始できます。 入力バッファーは、操作の入力データをレジストリが読み取るイニシエーターによって提供されるメモリ バッファーです。 出力バッファーは、イニシエーターが要求した出力データをレジストリが書き込むイニシエーターによって提供されるバッファーです。

RegistryCallback ルーチンを呼び出す前に、カーネルは、ユーザー モード メモリ内の出力バッファーを指すが、システム メモリ内のユーザー モード出力バッファーをキャプチャしない Argument2 構造体のすべてのメンバーをプローブします (アラインメントとアクセシビリティを確認するため)。 コールバック ルーチンは、出力バッファーのアクセスを try/except ブロックで囲む必要があります。 コールバック ルーチンがシステム ルーチン ( ZwOpenKey など) に出力バッファー ポインターを渡す必要があり、バッファーがユーザー モード メモリ内にある場合、コールバック ルーチンは最初にバッファーをキャプチャする必要があります。

入力バッファーの処理は、Windows のバージョンによって異なります。 Windows 8以降、カーネルは RegistryCallback ルーチンを呼び出す前に、システム メモリ内の Argument2 構造体のメンバーが指すすべての入力バッファーをキャプチャします。 Windows 8より前のバージョンの Windows では、カーネルは、ユーザー モード メモリ内の入力バッファーを指す Argument2 構造体のすべてのメンバーをプローブしますが、システム メモリ内のこれらのバッファーの一部のみをキャプチャします。 これらの以前のバージョンの Windows では、コールバック ルーチンは、入力バッファーへのアクセスをtry except ブロックで/囲む必要があります。 さらに、コールバック ルーチンがシステム ルーチン ( ZwOpenKey など) に入力バッファー ポインターを渡す必要があり、バッファーがユーザー モード メモリにある場合、コールバック ルーチンは最初にバッファーをキャプチャする必要があります。

次の表は、 RegistryCallback ルーチンによるバッファー アクセスの要件をまとめたものです。

バッファーの種類 Windows のバージョン コールバック ルーチンに渡されるバッファー ポインター コールバック ルーチンが直接アクセスしても安全ですか? システム ルーチン ( ZwOpenKey など) に安全に渡すことができますか?
ユーザー モード入力 Windows 8 以降 キャプチャされたデータをポイントします。 Yes Yes
ユーザー モード入力 Windows 7 以前 キャプチャされたデータまたは元のユーザー モード バッファーを指します。 いいえ。 try/except の下で読む必要があります。 いいえ。 カーネル メモリを割り当て、try/except の元のバッファーからデータをコピーし、コピーしたデータをシステム ルーチンに渡す必要があります。
ユーザー モードの出力 すべて 元のユーザー モード バッファーをポイントします。 いいえ。 try/except の下に を記述する必要があります。 いいえ。 カーネル メモリを割り当て、カーネル メモリをシステム ルーチンに渡し、try/except の元のバッファーに結果をコピーし直す必要があります。
カーネル モードの入出力 すべて 元のカーネル モード バッファーをポイントします。 Yes Yes

RegistryCallback ルーチンとレジストリ フィルター ドライバーの詳細については、「レジストリ呼び出しのフィルター処理」を参照してください。

RegistryCallback は IRQL = PASSIVE_LEVELで実行され、レジストリ操作を実行しているスレッドのコンテキストで実行されます。

RegistryCallback コールバック ルーチンを定義するには、まず、定義するコールバック ルーチンの種類を識別する関数宣言を指定する必要があります。 Windows には、ドライバーのコールバック関数型のセットが用意されています。 コールバック関数の種類を使用して関数を宣言すると、 ドライバーのコード分析静的ドライバー検証ツール (SDV)、およびその他の検証ツールでエラーが検出され、Windows オペレーティング システムのドライバーを記述するための要件になります。

たとえば、 という名前MyRegistryCallbackRegistryCallback コールバック ルーチンを定義するには、次のコード例に示すように、EX_CALLBACK_FUNCTION型を使用します。

EX_CALLBACK_FUNCTION MyRegistryCallback;

次に、コールバック ルーチンを次のように実装します。

_Use_decl_annotations_
NTSTATUS 
  MyRegistryCallback(
    PVOID  CallbackContext,
    PVOID  Argument1,
    PVOID  Argument2 
    )
  {
      // Function body
  }

EX_CALLBACK_FUNCTION関数の種類は、Wdm.h ヘッダー ファイルで定義されています。 コード分析ツールの実行時にエラーをより正確に識別するには、 Use_decl_annotations 注釈を関数定義に追加してください。 Use_decl_annotations注釈を使用すると、ヘッダー ファイル内のEX_CALLBACK_FUNCTION関数型に適用される注釈が確実に使用されます。 関数宣言の要件の詳細については、「 WDM ドライバーの関数ロール型を使用して関数を宣言する」を参照してください。 Use_decl_annotationsの詳細については、「関数の動作に注釈を付ける」を参照してください。

要件

要件
サポートされている最小のクライアント Windows XP 以降でサポートされています (「戻り値」セクションを参照)。
対象プラットフォーム デスクトップ
Header wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
IRQL PASSIVE_LEVELで呼び出されます (「解説」セクションを参照)。

こちらもご覧ください

CmRegisterCallback

CmUnRegisterCallback

ProbeForRead

REG_NOTIFY_CLASS

ZwOpenKey