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

Метод 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, если вызов выполнен успешно. В противном случае метод возвращает соответствующий код ошибки.

Замечания

Параметры DesiredAccess, ObjectAttributes и Ликвидации принимают значения, определенные для параметров с теми же именами в вызове ZwCreateKey.

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

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

Для значения RegistryKeyType generalRegistryKey вызывающий объект должен предоставить допустимое значение параметра ObjectAttributes, а параметры CreateOptions и ликвидации являются необязательными. Для любого другого значения 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, ключ сохраняет ACL, назначенный ключу Plug and Play при его создании во время перечисления устройств.

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

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

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

Требования

См. также

IPort