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