Метод IRegistryKey::NewSubKey (portcls.h)

Статья
08/07/2023

Метод NewSubKey создает новый подраздел реестра или открывает существующий подраздел в разделе, представленном объектом IRegistryKey .

Синтаксис

NTSTATUS NewSubKey(
  [out]           IRegistryKey    **RegistrySubKey,
  [in]            PUNKNOWN        OuterUnknown,
  [in]            ACCESS_MASK     DesiredAccess,
  [in]            PUNICODE_STRING SubKeyName,
  [in]            ULONG           CreateOptions,
  [out, optional] PULONG          Disposition
);

Параметры

[out] RegistrySubKey

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

[in] OuterUnknown

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

[in] DesiredAccess

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

[in] SubKeyName

Указатель на имя, которое должно быть назначено подразделу. Этот параметр должен быть допустимым указателем, не имеющим значения NULL , на инициализированную структуру типа UNICODE_STRING.

[in] CreateOptions

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

[out, optional] Disposition

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

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

NewSubKey возвращает STATUS_SUCCESS, если вызов успешно вывести допустимый указатель IRegistryKey с помощью параметра RegistrySubKey . В противном случае метод возвращает соответствующий код ошибки.

Метод NewSubKey либо открывает указанный раздел реестра, если он уже существует, либо создает новый раздел в реестре, если он не существует. Метод выводит указатель на интерфейс IRegistryKey нового раздела с помощью параметра RegistrySubKey . Метод также выводит значение состояния с помощью необязательного параметра Disposition , чтобы указать, был ли открыт или создан ключ.

Параметры DesiredAccess, CreateOptions и Disposition принимают значения, определенные для параметров с одинаковыми именами в вызове PcNewRegistryKey .

Параметр DesiredAccess — это маска управления доступом, которая указывает тип управления доступом, который должен иметь вызывающий объект к подразделу при доступе к нему через объект RegistrySubKey . Эту маску не следует путать с ACL (списком управления доступом), который управляет доступом пользователей к подразделу реестра. Когда функция PcNewRegistryKey или метод IPort::NewRegistryKey создает раздел реестра типа GeneralRegistryKey, параметр ObjectAttributes указывает атрибуты ключа, включая дескриптор безопасности, содержащий ACL. NewSubKey Однако, когда метод создает новый подраздел реестра, этот подраздел просто наследует ACL от родительского ключа. Метод NewSubKey не предоставляет средств для указания ACL, который отличается от списка ACL родительского ключа.

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