CmCallbackGetKeyObjectIDEx 関数 (wdm.h)
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 構造体を明示的に解放できません。 この構造体は、キーに対するすべてのハンドルが閉じられると自動的に解放されます。
次に、レジストリ フィルター ドライバーが CmCallbackGetKeyObjectID を呼び出して 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 |