Функция 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

Значение файла cookie, полученное драйвером ранее путем вызова процедуры CmRegisterCallback или CmRegisterCallbackEx .

[in] Object

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

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

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

[out, optional] ObjectID

Указатель на расположение, которое получает указатель на уникальный идентификатор, представляющий раздел реестра, задающий объект . Этот параметр является необязательным и может иметь значение 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 для получения идентификатора раздела реестра, имени объекта или и того, и другого, указав значения, отличные от NULL , для параметров ObjectID или ObjectName .

После того как драйвер получит идентификатор или имя, идентификатор или имя будет действительным, пока подпрограмма RegistryCallback драйвера не получит предварительное уведомление о закрытии дескриптора.

Драйвер не должен изменять имя объекта.

Если два объекта раздела реестра представляют один и тот же раздел реестра, идентификаторы ключей для обоих объектов идентичны.

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

Требования

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