Функция 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, представляющее регистрацию вызывающего объекта для получения обратных вызовов фильтра реестра. Драйвер ранее получил это значение файла cookie из подпрограммы CmRegisterCallback или CmRegisterCallbackEx .

[in] Object

Указатель на объект раздела реестра. Этот параметр является значением указателя, которое получает подпрограмма обратного вызова RegistryCallback драйвера в элементе Object одной из структур REG_XXX_KEY_INFORMATION .

Предупреждение

В некоторых случаях структуры уведомлений о обратном вызове реестра могут содержать недопустимые указатели объектов, отличные от NULL. Драйверы фильтрации реестра не должны передавать такие указатели на эту подпрограмму. Дополнительные сведения см. в разделе Недопустимые указатели на объекты ключа в уведомлениях реестра.

[out, optional] ObjectID

Указатель на расположение, которое получает указатель на идентификатор ключа для раздела реестра, который представляет Объект . Этот идентификатор уникален во всех разделах реестра. Этот параметр является необязательным и может иметь значение NULL. Дополнительные сведения см. в разделе Примечания ниже.

[out, optional] ObjectName

Указатель на расположение, которое получает указатель на структуру UNICODE_STRING . Эта структура содержит имя объекта раздела реестра, указанного объектом Object . На самом деле имя объекта — это полный путь к разделу реестра, который представляет объект. Вызывающий объект отвечает за освобождение этой структуры путем вызова подпрограммы CmCallbackReleaseKeyObjectIDEx . Этот параметр является необязательным и может иметь значение NULL. Дополнительные сведения см. в подразделе "Примечания".

[in] Flags

Зарезервировано. Задайте нулевое значение.

Возвращаемое значение

CmCallbackGetKeyObjectIDEx возвращает STATUS_SUCCESS, если операция выполнена успешно. Возможные возвращаемые значения ошибки включают следующий код состояния:

Код возврата	Описание
STATUS_INVALID_PARAMETER	Недопустимый параметр Cookie, Object или Flags .

Драйверы могут использовать CmCallbackGetKeyObjectIDEx для получения идентификатора раздела реестра, имени объекта или и того, и другого, указав значения, отличные от NULL , для параметров ObjectID или ObjectName .

Вызывающий объект может получить идентификатор ключа с помощью параметра ObjectID . Если два объекта раздела реестра представляют один и тот же раздел реестра, идентификаторы ключей, полученные из CmCallbackGetKeyObjectIDEx для этих двух объектов, идентичны. Если имя раздела реестра меняется, идентификатор ключа, полученный из CmCallbackGetKeyObjectIDEx , не изменяется. Вызывающий объект может использовать идентификатор ключа для надежного отслеживания доступа к определенному разделу реестра с помощью нескольких объектов ключей и даже при изменении имени раздела реестра.

Вызывающий объект может получить имя объекта с помощью параметра ObjectName . Хранилище для структуры UNICODE_STRING , содержащей имя объекта, остается действительным до тех пор, пока вызывающий объект не вызовет CmCallbackReleaseKeyObjectIDEx , чтобы освободить структуру.

CmCallbackGetKeyObjectIDEx — это улучшенная версия подпрограммы CmCallbackGetKeyObjectID , которая доступна начиная с Windows Vista. Драйверы, которые работают в версиях Windows до Windows 8, должны вызывать CmCallbackGetKeyObjectID вместо CmCallbackGetKeyObjectIDEx. Драйверы, которые работают только в Windows 8 и более поздних версиях Windows, должны вызывать CmCallbackGetKeyObjectIDEx вместо CmCallbackGetKeyObjectID.

CmCallbackGetKeyObjectIDEx имеет две важные функции, недоступные в CmCallbackGetKeyObjectID.

Во-первых, CmCallbackGetKeyObjectIDEx позволяет драйверу фильтра реестра явно управлять временем существования структуры ObjectName . Драйвер может в любое время вызвать CmCallbackReleaseKeyObjectIDEx , чтобы освободить эту структуру. В отличие от этого, драйвер не может явно освободить структуру ObjectName , полученную от CmCallbackGetKeyObjectID. Эта структура автоматически освобождается при закрытии всех дескрипторов ключа.

Во-вторых, если драйвер фильтра реестра вызывает CmCallbackGetKeyObjectID для получения указателя структуры ObjectName , а после этого вызова имя раздела реестра меняется, последующие вызовы CmCallbackGetKeyObjectID получают указатель на устаревшую копию структуры ObjectName , которая содержит старое имя ключа. Устаревшая копия этой структуры сохраняется до тех пор, пока не будут закрыты все дескрипторы ключа. В отличие от этого, структура ObjectName , полученная из CmCallbackGetKeyObjectIDEx , всегда содержит самое актуальное имя ключа.

Дополнительные сведения о драйверах фильтров реестра см. в разделе Фильтрация вызовов реестра.

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 8.
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL