Функция RegCreateKeyExA (winreg.h)

Статья
03/08/2023

Создает указанный раздел реестра. Если ключ уже существует, функция открывает его. Обратите внимание, что в именах ключей регистр не учитывается.

Для выполнения транзакций с реестром с ключом вызовите функцию RegCreateKeyTransacted .

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

Синтаксис

LSTATUS RegCreateKeyExA(
  [in]            HKEY                        hKey,
  [in]            LPCSTR                      lpSubKey,
                  DWORD                       Reserved,
  [in, optional]  LPSTR                       lpClass,
  [in]            DWORD                       dwOptions,
  [in]            REGSAM                      samDesired,
  [in, optional]  const LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [out]           PHKEY                       phkResult,
  [out, optional] LPDWORD                     lpdwDisposition
);

Параметры

[in] hKey

Дескриптор открытого раздела реестра. Вызывающий процесс должен иметь KEY_CREATE_SUB_KEY доступ к ключу. Дополнительные сведения см. в разделе Безопасность раздела реестра и права доступа.

Доступ для создания ключа проверяется по дескриптору безопасности раздела реестра, а не по маске доступа, указанной при получении дескриптора. Таким образом, даже если ключ hKey был открыт с помощью samDesired KEY_READ, его можно использовать в операциях, изменяющих реестр, если это разрешено дескриптором безопасности.

Этот дескриптор возвращается функцией RegCreateKeyEx или RegOpenKeyEx или может быть одним из следующих предопределенных ключей:

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

[in] lpSubKey

Имя подраздела, открываемого или создаваемого этой функцией. Указанный подраздел должен быть подразделом ключа, определяемого параметром hKey ; В дереве реестра может быть до 32 уровней. Дополнительные сведения об именах ключей см. в разделе Структура реестра.

Если lpSubKey является указателем на пустую строку, phkResult получает новый дескриптор ключа, указанного в hKey.

Этот параметр не может иметь значение NULL.

Reserved

Этот параметр зарезервирован и должен быть равен нулю.

[in, optional] lpClass

Определяемый пользователем тип класса этого ключа. Этот параметр можно игнорировать. Этот параметр может принимать значение NULL.

[in] dwOptions

Этот параметр может принимать одно из указанных ниже значений.

Значение	Значение
REG_OPTION_BACKUP_RESTORE 0x00000004L	Если этот флаг установлен, функция игнорирует параметр samDesired и пытается открыть ключ с доступом, необходимым для резервного копирования или восстановления ключа. Если для вызывающего потока включено разрешение SE_BACKUP_NAME, ключ открывается с ACCESS_SYSTEM_SECURITY и KEY_READ права доступа. Если в вызывающем потоке включена SE_RESTORE_NAME привилегия, начиная с Windows Vista, ключ открывается с правами доступа ACCESS_SYSTEM_SECURITY, DELETE и KEY_WRITE. Если включены обе привилегии, ключ имеет объединенные права доступа для обоих привилегий. Дополнительные сведения см. в разделе Выполнение с особыми привилегиями.
REG_OPTION_CREATE_LINK 0x00000002L	Примечание Символьные ссылки реестра следует использовать только для обеспечения совместимости приложений при крайней необходимости. Этот ключ является символьной ссылкой. Целевой путь назначается значению L"SymbolicLinkValue" ключа. Целевой путь должен быть абсолютным путем реестра.
REG_OPTION_NON_VOLATILE 0x00000000L	Этот ключ не является переменным; это значение по умолчанию. Эти сведения хранятся в файле и сохраняются при перезапуске системы. Функция RegSaveKey сохраняет ключи, которые не являются переменными.
REG_OPTION_VOLATILE 0x00000001L	Все ключи, созданные функцией, являются переменными. Информация хранится в памяти и не сохраняется при выгрузке соответствующего куста реестра. Для HKEY_LOCAL_MACHINE это происходит только в том случае, если система инициирует полное завершение работы. Для разделов реестра, загруженных функцией RegLoadKey , это происходит при выполнении соответствующего regUnLoadKey . Функция RegSaveKey не сохраняет переменные ключи. Этот флаг игнорируется для уже существующих ключей. Примечание При выбранном пользователем завершении работы быстрое завершение работы является поведением по умолчанию для системы.

[in] samDesired

Маска, указывающая права доступа для создаваемого ключа. Дополнительные сведения см. в разделе Безопасность раздела реестра и права доступа.

[in, optional] lpSecurityAttributes

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

Элемент lpSecurityDescriptor структуры задает дескриптор безопасности для нового ключа. Если lpSecurityAttributes имеет значение NULL, ключ получает дескриптор безопасности по умолчанию. Списки управления доступом в дескрипторе безопасности по умолчанию для ключа наследуются от его прямого родительского ключа.

[out] phkResult

Указатель на переменную, которая получает дескриптор открытого или созданного ключа. Если раздел не является одним из предопределенных разделов реестра, вызовите функцию RegCloseKey после завершения использования дескриптора.

[out, optional] lpdwDisposition

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

Значение	Значение
REG_CREATED_NEW_KEY 0x00000001L	Ключ не существует и был создан.
REG_OPENED_EXISTING_KEY 0x00000002L	Ключ существовал и был просто открыт без изменения.

Если lpdwDisposition имеет значение NULL, сведения о ликвидации не возвращаются.

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

Если функция выполняется успешно, возвращаемое значение будет ERROR_SUCCESS.

Если функция завершается сбоем, возвращаемое значение представляет собой ненулевой код ошибки, определенный в Winerror.h. Чтобы получить общее описание ошибки, можно использовать функцию FormatMessage с флагом FORMAT_MESSAGE_FROM_SYSTEM.

Функция RegCreateKeyEx создает все отсутствующие ключи по указанному пути. Приложение может воспользоваться этим поведением для создания нескольких ключей одновременно. Например, приложение может создать подраздел с четырьмя уровнями глубины одновременно с тремя предыдущими подразделами, указав строку следующей формы для параметра lpSubKey :

subkey1\subkey2\subkey3\subkey4

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

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

Если служба или приложение олицетворяет разных пользователей, не используйте эту функцию с HKEY_CURRENT_USER. Вместо этого вызовите функцию RegOpenCurrentUser .

Обратите внимание, что операции, которые обращаются к определенным разделам реестра, перенаправляются. Дополнительные сведения см. в статье Виртуализация реестра и 32-разрядные и 64-разрядные данные приложений в реестре.

Примечание

Заголовок winreg.h определяет RegCreateKeyEx в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	winreg.h (включая Windows.h)
Библиотека	Advapi32.lib
DLL	Advapi32.dll