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

2023-08-07

Функция 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. Если значение RegistryKeyTypeGeneralRegistryKey, функция 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и параметры ликвидации принимают значения, определенные для параметров с теми же именами в вызове ZwCreateKey.

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

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

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

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

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

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

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

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

Требования

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