CmCallbackGetKeyObjectIDEx 関数 (wdm.h)

[アーティクル]
03/08/2023

CmCallbackGetKeyObjectIDEx ルーチンは、指定されたレジストリキーオブジェクトに関連付けられている一意の識別子とオブジェクト名を取得します。

このルーチンは、Windows 8 以降で使用できます。以前のバージョンの Windows では、代わりに CmCallbackGetKeyObjectID ルーチンを使用します。詳細については、以下の 「解説 」セクションを参照してください。

構文

NTSTATUS CmCallbackGetKeyObjectIDEx(
  [in]            PLARGE_INTEGER   Cookie,
  [in]            PVOID            Object,
  [out, optional] PULONG_PTR       ObjectID,
  [out, optional] PCUNICODE_STRING *ObjectName,
  [in]            ULONG            Flags
);

パラメーター

[in] Cookie

レジストリフィルターコールバックを受け取る呼び出し元の登録を表す Cookie 値。ドライバーは、以前に CmRegisterCallback または CmRegisterCallbackEx ルーチンからこの Cookie 値を取得しました。

[in] Object

レジストリキーオブジェクトへのポインター。このパラメーターは、ドライバーの RegistryCallback コールバックルーチンが、REG_XXX_KEY_INFORMATION 構造体のいずれかの Object メンバーで受け取ったポインター値です。

警告

特定の状況では、レジストリコールバック通知構造体に無効な NULL 以外のオブジェクトポインターが含まれている可能性があります。レジストリフィルタードライバーは、このようなポインターをこのルーチンに渡してはなりません。詳細については、「レジストリ通知の無効なキーオブジェクトポインター」を参照してください。

[out, optional] ObjectID

Object が表すレジストリキーのキー識別子へのポインターを受け取る場所へのポインター。この識別子は、レジストリ内のすべてのキーで一意です。このパラメーターは省略可能であり、 NULL にすることができます。詳細については、以下の 「解説 」セクションを参照してください。

[out, optional] ObjectName

UNICODE_STRING構造体へのポインターを受け取る場所へのポインター。この構造体には、 Object が指定するレジストリキーオブジェクトのオブジェクト名が含まれます。オブジェクト名は、実際には、オブジェクトが表すレジストリキーの完全なパス名です。呼び出し元は、 CmCallbackReleaseKeyObjectIDEx ルーチンを呼び出して、この構造体を解放します。このパラメーターは省略可能であり、 NULL にすることができます。詳細については、「解説」を参照してください。

[in] Flags

予約済み。 0 に設定します。

戻り値

CmCallbackGetKeyObjectIDEx は 、操作が成功した場合STATUS_SUCCESSを返します。エラーの戻り値として考えられるのは、次の状態コードです。

リターンコード	説明
STATUS_INVALID_PARAMETER	Cookie、Object、または Flags パラメーターが無効です。

注釈

ドライバーでは、CmCallbackGetKeyObjectIDEx を使用して、ObjectID パラメーターまたは ObjectName パラメーターに NULL 以外の値を指定することで、レジストリキー識別子、オブジェクト名、またはその両方を取得できます。

呼び出し元は 、ObjectID パラメーターを使用してキー識別子を取得できます。 2 つのレジストリキーオブジェクトが同じレジストリキーを表す場合、2 つのオブジェクトの CmCallbackGetKeyObjectIDEx から取得されたキー識別子は同じです。レジストリキーの名前が変更された場合、 CmCallbackGetKeyObjectIDEx から取得されたキー識別子は変更されません。呼び出し元は、キー識別子を使用して、特定のレジストリキーに対して行われたアクセスを、複数のキーオブジェクトを通じて、さらにはレジストリキー名の変更を通じて確実に追跡できます。

呼び出し元は、 ObjectName パラメーターを使用してオブジェクト名を取得できます。オブジェクト名を含む UNICODE_STRING 構造体のストレージは、呼び出し元が CmCallbackReleaseKeyObjectIDEx を呼び出して構造体を解放するまで有効です。

CmCallbackGetKeyObjectIDEx は、Windows Vista 以降で使用できる CmCallbackGetKeyObjectID ルーチンの改善されたバージョンです。 Windows 8より前のバージョンの Windows で実行されるドライバーは、CmCallbackGetKeyObjectIDEx ではなく CmCallbackGetKeyObjectID を呼び出す必要があります。 Windows 8 以降のバージョンの Windows でのみ実行されるドライバーは、CmCallbackGetKeyObjectID ではなく CmCallbackGetKeyObjectIDExを呼び出す必要があります。

CmCallbackGetKeyObjectIDEx には、 CmCallbackGetKeyObjectID からは使用できない 2 つの重要な機能があります。

まず、 CmCallbackGetKeyObjectIDEx を使用すると、レジストリフィルタードライバーで ObjectName 構造体の有効期間を明示的に制御できます。ドライバーは、この構造体を解放するために、いつでも CmCallbackReleaseKeyObjectIDEx を呼び出すことができます。これに対し、ドライバーは CmCallbackGetKeyObjectID から受信した ObjectName 構造体を明示的に解放できません。この構造体は、キーに対するすべてのハンドルが閉じられると自動的に解放されます。

次に、レジストリフィルタードライバーが CmCallbackReleaseKeyObjectID を呼び出して ObjectName 構造体ポインターを取得し、この呼び出しの後にレジストリキーの名前が変更された場合、 CmCallbackGetKeyObjectID への後続の呼び出しは、古いキー名を含む ObjectName 構造体の古いコピーへのポインターを取得します。この構造体の古いコピーは、キーに対するすべてのハンドルが閉じられるまで保持されます。これに対し、CmCallbackGetKeyObjectIDEx から取得された ObjectName 構造体には、常に最新のキー名が含まれます。

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

要件

要件	値
サポートされている最小のクライアント	Windows 8 以降で使用できます。
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL