Функция PcNewRegistryKey (portcls.h)

Статья
08/07/2023

Функция PcNewRegistryKey открывает или создает новый раздел реестра и создает объект IRegistryKey для представления ключа. Вызывающий объект обращается к ключу через этот объект .

Синтаксис

PORTCLASSAPI NTSTATUS PcNewRegistryKey(
  [out]           PREGISTRYKEY       *OutRegistryKey,
  [in, optional]  PUNKNOWN           OuterUnknown,
  [in]            ULONG              RegistryKeyType,
  [in]            ACCESS_MASK        DesiredAccess,
  [in, optional]  PVOID              DeviceObject,
  [in, optional]  PVOID              SubDevice,
  [in, optional]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional]  ULONG              CreateOptions,
  [out, optional] PULONG             Disposition
);

Параметры

[out] OutRegistryKey

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

[in, optional] OuterUnknown

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

[in] RegistryKeyType

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

[in] DesiredAccess

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

[in, optional] DeviceObject

Указатель на объект устройства драйвера адаптера. Этот указатель приводится к типу PVOID. Если RegistryKeyType имеет любое значение, отличное от GeneralRegistryKey, этот параметр должен указывать на допустимую инициализированную системную структуру типа DEVICE_OBJECT. Если параметр RegistryKeyType имеет значение GeneralRegistryKey, функция PcNewRegistryKey не использует этот параметр. Дополнительные сведения см. в разделе "Примечания".

[in, optional] SubDevice

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

[in, optional] ObjectAttributes

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

[in, optional] CreateOptions

Задает параметры создания. Может быть равен нулю, если они не нужны. Если RegistryKeyType не имеет значение GeneralRegistryKey, функция PcNewRegistryKey игнорирует этот параметр. Дополнительные сведения см. в разделе "Примечания".

[out, optional] Disposition

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

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

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

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

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

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

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

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

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

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

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

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

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

Требования

Требование	Значение
Минимальная версия клиента	Системный драйвер PortCls реализует функцию PcNewRegistryKey в Microsoft Windows 98/Me, а также в операционных системах Windows 2000 и более поздних версий.
Целевая платформа	Универсальное
Верхняя часть	portcls.h (включая Portcls.h)
Библиотека	Portcls.lib
IRQL	PASSIVE_LEVEL