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 回调例程在 Object 成员中接收的 REG_XXX_KEY_INFORMATION 结构的指针值。
警告
在某些情况下,注册表回调通知结构可能包含无效的非 NULL 对象指针。 注册表筛选驱动程序不得将此类指针传递给此例程。 有关详细信息,请参阅注册表通知 中无效的键对象指针。
[out, optional] ObjectID
指向一个位置的指针,该位置接收指向 对象 表示的注册表项的密钥标识符的指针。 此标识符在注册表中的所有键中都是唯一的。 此参数是可选的,可以 NULL。 有关详细信息,请参阅下面的 备注 部分。
[out, optional] ObjectName
指向接收指向 UNICODE_STRING 结构的指针的位置的指针。 此结构包含 对象 指定的注册表项对象的对象名称。 对象名称实际上是对象表示的注册表项的完整路径名称。 调用方负责通过调用 CmCallbackReleaseKeyObjectIDEx 例程来释放此结构。 此参数是可选的,可以 NULL。 有关详细信息,请参阅“备注”。
[in] Flags
保留。 设置为零。
CmCallbackGetKeyObjectIDEx 如果作成功,则返回STATUS_SUCCESS。 可能的错误返回值包括以下状态代码:
返回代码 | 描述 |
---|---|
STATUS_INVALID_PARAMETER | Cookie、对象或 标志 参数无效。 |
驱动程序可以使用 CmCallbackGetKeyObjectIDEx 为 ObjectID 或 ObjectName 参数提供非NULL 值来获取注册表项标识符、对象名称或两者。
调用方可以通过 ObjectID 参数获取密钥标识符。 如果两个注册表项对象表示相同的注册表项,则从 CmCallbackGetKeyObjectIDEx 获取的两个对象的密钥标识符是相同的。 如果注册表项的名称发生更改,则从 CmCallbackGetKeyObjectIDEx 获取的密钥标识符不会更改。 调用方可以使用密钥标识符可靠地跟踪通过多个密钥对象对特定注册表项进行的访问,甚至跨对注册表项名称所做的更改。
调用方可以通过 ObjectName 参数获取对象名称。 包含对象名称的 UNICODE_STRING 结构的存储将一直有效,直到调用方调用 CmCallbackReleaseKeyObjectIDEx 释放结构。
CmCallbackGetKeyObjectIDEx 是 CmCallbackGetKeyObjectID 例程的改进版本,从 Windows Vista 开始提供。 在早于 Windows 8 版本的 Windows 中运行的驱动程序应调用 CmCallbackGetKeyObjectID,而不是 CmCallbackGetKeyObjectIDEx。 仅在 Windows 8 及更高版本中运行的驱动程序应调用 CmCallbackGetKeyObjectIDEx,而不是 CmCallbackGetKeyObjectID。
CmCallbackGetKeyObjectIDEx 有两个重要功能,CmCallbackGetKeyObjectID不可用。
首先,CmCallbackGetKeyObjectIDEx 使注册表筛选器驱动程序能够显式控制 ObjectName 结构的生存期。 驱动程序可以随时调用 CmCallbackReleaseKeyObjectIDEx 以释放此结构。 相比之下,驱动程序无法显式释放从 CmCallbackGetKeyObjectID接收的 ObjectName 结构。 关闭密钥的所有句柄时,将自动释放此结构。
其次,如果注册表筛选器驱动程序调用 CmCallbackGetKeyObjectID 以获取 ObjectName 结构指针,并且在此调用后,注册表项的名称会更改,随后调用 CmCallbackGetKeyObjectID 获取指向包含旧密钥名称的 ObjectName 结构的过时副本的指针。 此结构的过时副本将一直保留,直到关闭密钥的所有句柄。 相比之下,从 CmCallbackGetKeyObjectID Ex 获取的 ObjectName 结构始终包含最 up-to日期键名称。
有关注册表筛选器驱动程序的详细信息,请参阅 筛选注册表调用。
要求 | 价值 |
---|---|
最低支持的客户端 | 从 Windows 8 开始可用。 |
目标平台 | 普遍 |
标头 | wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h) |
库 | NtosKrnl.lib |
DLL | NtosKrnl.exe |
IRQL | IRQL <= APC_LEVEL |