cmCallbackGetKeyObjectID 函数 (wdm.h)

项目
03/08/2023

CmCallbackGetKeyObjectID 例程检索与指定注册表项对象关联的唯一标识符和对象名称。

从 Windows 8 开始，注册表筛选器驱动程序应调用 CmCallbackGetKeyObjectIDEx 例程，而不是 CmCallbackGetKeyObjectID。有关详细信息，请参阅下面的 “备注 ”部分。

语法

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

参数

[in] Cookie

驱动程序之前通过调用 CmRegisterCallback 或 CmRegisterCallbackEx 例程获取的 Cookie 值。

[in] Object

驱动程序的 RegistryCallback 回调例程在 REG_XXX_KEY_INFORMATION 结构之一的 Object 成员中接收的指针值。

警告

在某些情况下，注册表回调通知结构可能包含无效的非 NULL 对象指针。注册表筛选驱动程序不得将此类指针传递给此例程。有关详细信息，请参阅注册表通知中的无效键对象指针。

[out, optional] ObjectID

指向位置的指针，该位置接收指向表示 Object 指定的注册表项的唯一标识符的指针。此参数是可选的，可以为 NULL。

[out, optional] ObjectName

指向接收指向UNICODE_STRING结构的指针的位置的指针的指针。此结构包含 Object 指定的注册表项对象的对象名称。对象名称实际上是对象表示的注册表项的完整路径名称。调用方不得写入此 UNICODE_STRING 结构或释放它。此参数是可选的，可以为 NULL。

返回值

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

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

注解

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

驱动程序可以使用 CmCallbackGetKeyObjectID 获取注册表项标识符和/或对象名称，方法是为 ObjectID 或 ObjectName 参数提供非 NULL 值。

驱动程序获取标识符或名称后，标识符或名称有效，直到驱动程序的 RegistryCallback 例程收到句柄关闭的预先通知。

驱动程序不得修改对象名称。

如果两个注册表项对象表示相同的注册表项，则这两个对象的密钥标识符是相同的。

有关 CmCallbackGetKeyObjectID 和注册表筛选操作的详细信息，请参阅筛选注册表调用。