cmCallbackGetKeyObjectIDEx 函数 (wdm.h)

项目
02/27/2024

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

保留。设置为零。

返回值

如果操作成功，CmCallbackGetKeyObjectIDEx 将返回STATUS_SUCCESS。可能的错误返回值包括以下状态代码：

返回代码	说明
STATUS_INVALID_PARAMETER	Cookie、Object 或 Flags 参数无效。

注解

驱动程序可以使用 CmCallbackGetKeyObjectIDEx 通过为 ObjectID 或 ObjectName 参数提供非 NULL 值来获取注册表项标识符和/或对象名称。

调用方可以通过 ObjectID 参数获取密钥标识符。如果两个注册表项对象表示相同的注册表项，则从 CmCallbackGetKeyObjectIDEx 获取的两个对象的密钥标识符是相同的。如果注册表项的名称发生更改，则从 CmCallbackGetKeyObjectIDEx 获取的密钥标识符不会更改。调用方可以使用密钥标识符可靠地跟踪通过多个键对象甚至注册表项名称更改对特定注册表项的访问。

调用方可以通过 ObjectName 参数获取对象名称。在调用方调用 CmCallbackReleaseKeyObjectIDEx 以释放结构之前，包含对象名称的 UNICODE_STRING 结构的存储保持有效。

CmCallbackGetKeyObjectIDEx 是 CmCallbackGetKeyObjectID 例程的改进版本，从 Windows Vista 开始可用。在早于 Windows 8 的 Windows 版本中运行的驱动程序应调用 CmCallbackGetKeyObjectID，而不是 CmCallbackGetKeyObjectIDEx。仅在 Windows 8 及更高版本的 Windows 中运行的驱动程序应调用 CmCallbackGetKeyObjectIDEx，而不是 CmCallbackGetKeyObjectID。

CmCallbackGetKeyObjectIDEx 具有 CmCallbackGetKeyObjectID 中不可用的两个重要功能。

首先， CmCallbackGetKeyObjectIDEx 使注册表筛选器驱动程序能够显式控制 ObjectName 结构的生存期。驱动程序可以随时调用 CmCallbackReleaseKeyObjectIDEx 来释放此结构。相比之下，驱动程序无法显式释放从 CmCallbackGetKeyObjectID 接收的 ObjectName 结构。当键的所有句柄关闭时，将自动释放此结构。

其次，如果注册表筛选器驱动程序调用 CmCallbackGetKeyObjectID 以获取 ObjectName 结构指针，并且在此调用之后，注册表项的名称发生更改，则对 CmCallbackGetKeyObjectID 的后续调用将获取指向包含旧键名称的 ObjectName 结构的过时副本的指针。此结构的过时副本将一直存在，直到关闭键的所有句柄。相比之下，从 CmCallbackGetKeyObjectIDEx 获取的 ObjectName 结构始终包含最新的密钥名称。

有关注册表筛选器驱动程序的详细信息，请参阅筛选注册表调用。

要求

要求	值
最低受支持的客户端	从Windows 8开始可用。
目标平台	通用
标头	wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL