Метод IPort::NewRegistryKey (portcls.h)

Статья
08/07/2023

Метод NewRegistryKey открывает существующий раздел реестра или создает новый раздел в реестре. Метод создает объект раздела реестра для представления ключа и выводит ссылку на этот объект вызывающей объект. Затем вызывающий объект обращается к ключу через интерфейс IRegistryKey объекта.

Синтаксис

NTSTATUS NewRegistryKey(
  PREGISTRYKEY       *OutRegistryKey,
  PUNKNOWN           OuterUnknown,
  ULONG              RegistryKeyType,
  ACCESS_MASK        DesiredAccess,
  POBJECT_ATTRIBUTES ObjectAttributes,
  ULONG              CreateOptions,
  PULONG             Disposition
);

Параметры

OutRegistryKey

Указатель на выделенную вызывающим объектом переменную указателя, в которую метод записывает ссылку на объект IRegistryKey. Этот объект представляет открываемый или создаваемый раздел реестра. Вызывающий объект должен указать допустимое значение указателя, отличное от NULL, для этого параметра.

OuterUnknown

Указатель на интерфейс IUnknown объекта, который должен агрегировать объект раздела реестра. Этот параметр является необязательным. Если агрегирование не требуется, укажите этот параметр как NULL.

RegistryKeyType

Указывает тип раздела реестра, к которому вызывающий объект запрашивает доступ. Дополнительные сведения см. в разделе "Примечания".

DesiredAccess

Маска управления доступом, указывающая тип доступа, который требуется вызывающей стороны к ключу. Этот параметр имеет тип ACCESS_MASK. Дополнительные сведения см. в разделе "Примечания".

ObjectAttributes

Указатель на атрибуты объекта создаваемого или открываемого ключа. Если RegistryKeyType имеет значение GeneralRegistryKey, этот параметр должен указывать на допустимую инициализированную системную структуру типа OBJECT_ATTRIBUTES с допустимой строкой ObjectName для ключа; В противном случае метод не использует этот параметр. Дополнительные сведения см. в разделе "Примечания".

CreateOptions

Флаги, указывающие параметры создания. Может быть равен нулю, если они не нужны. Этот параметр является обязательным, если RegistryKeyType имеет значение GeneralRegistryKey; В противном случае метод не использует этот параметр. Дополнительные сведения см. в разделе "Примечания".

Disposition

Указатель на выделенную вызывающим объектом переменную ULONG, в которую метод записывает значение состояния, указывающее, был ли создан новый ключ или был открыт существующий ключ. Этот параметр является необязательным и может быть указан как NULL, если вызывающей объекту не требуется значение состояния. Метод использует этот параметр, только если RegistryKeyType имеет значение GeneralRegistryKey. Метод не использует параметр ни для одного из других типов ключей. Дополнительные сведения см. в разделе "Примечания".

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

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

Если параметр RegistryKeyType имеет значение GeneralRegistryKey, то метод NewRegistryKey либо открывает существующий раздел реестра, либо создает новый раздел в реестре, как указано в значении, которое метод выводит с помощью параметра Disposition. Если тип ключа имеет значение, отличное от GeneralRegistryKey, метод открывает уже существующий ключ, который был ранее создан во время перечисления Plug and Play устройства.

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

Значение RegistryKeyType	Значение
GeneralRegistryKey	Предоставьте универсальный доступ к любому типу ключа. Открывает ключ, если он существует, или создает ключ, если это не так.
DeviceRegistryKey	Откройте существующий ключ, содержащий сведения об устройстве.
DriverRegistryKey	Откройте существующий ключ, содержащий сведения о драйвере.
HwProfileRegistryKey	Откройте существующий ключ относительно текущего профиля оборудования, чтобы получить сведения об устройстве или драйвере. Это позволяет драйверу получать доступ к сведениям о конфигурации, которые зависят от профиля оборудования.
DeviceInterfaceRegistryKey	Откройте существующий раздел реестра, содержащий сведения о конкретном экземпляре интерфейса устройства.

Для значения RegistryKeyType generalRegistryKey вызывающий объект должен предоставить допустимое значение параметра ObjectAttributes, а параметры CreateOptions и Disposition являются необязательными. Для любого другого значения RegistryKeyType вызывающий объект должен предоставить допустимое значение параметра DeviceObject, а параметры CreateOptions и Disposition не используются.

Параметр ObjectAttributes указывает на непрозрачную структуру типа OBJECT_ATTRIBUTES, которая содержит атрибуты объекта, такие как имя ключа и дескриптор безопасности. Используйте макрос InitializeObjectAttributes для инициализации структуры. В параметре Атрибуты для этого макроса установите флаг OBJ_KERNEL_HANDLE, если вы не планируете разрешить небезопасным приложениям в пользовательском режиме доступ к разделу реестра на чтение и запись.

Параметр DesiredAccess является маской управления доступом. Он указывает тип управления доступом, который должен иметь вызывающий объект к новому разделу реестра при доступе к нему через объект OutRegistryKey. Эту маску не следует путать с ACL (списком управления доступом), который управляет доступом пользователей к разделу реестра. При вызове NewRegistryKey для создания раздела реестра типа GeneralRegistryKey параметр ObjectAttributes указывает атрибуты ключа, включая дескриптор безопасности, содержащий ACL. Однако если тип ключа — GeneralRegistryKey и либо указатель дескриптора безопасности в структуре ObjectAttributes имеет значение NULL, либо указатель ACL в дескрипторе безопасности имеет значение NULL, то новый ключ, созданный вызовом, по умолчанию наследует ACL родительского ключа.

Если ключ не имеет типа GeneralRegistryKey, то ключ сохраняет список управления доступом, который Plug and Play назначен ключу при его создании во время перечисления устройства.

Метод NewRegistryKey аналогичен функции PcNewRegistryKey, за исключением того, что объект device и объект порта должны быть явно указаны в вызове PcNewRegistryKey, но просто подразумеваются в вызове NewRegistryKey. PcNewRegistryKey обычно вызывается драйверами адаптера. Драйверы miniport обычно вызывают NewRegistryKey.

После создания или открытия раздела реестра путем вызова метода NewRegistryKey или PcNewRegistryKey можно использовать метод IRegistryKey::NewSubKey для создания подразделов в этом разделе.

Параметры OutRegistryKey и OuterUnknown следуют соглашениям о подсчете ссылок для COM-объектов.

Требования

Требование	Значение
Заголовок	portcls.h
IRQL	PASSIVE_LEVEL

См. также раздел

IPort

Поделиться через