Функция RegCreateKeyExA (winreg.h)
Создает указанный раздел реестра. Если ключ уже существует, функция открывает его. Обратите внимание, что в именах ключей регистр не учитывается.
Для выполнения транзакций с реестром с ключом вызовите функцию 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
Этот параметр может принимать одно из указанных ниже значений.
| Значение | Значение |
|---|---|
|
Если этот флаг установлен, функция игнорирует параметр samDesired и пытается открыть ключ с доступом, необходимым для резервного копирования или восстановления ключа. Если для вызывающего потока включено разрешение SE_BACKUP_NAME, ключ открывается с ACCESS_SYSTEM_SECURITY и KEY_READ права доступа. Если в вызывающем потоке включена SE_RESTORE_NAME привилегия, начиная с Windows Vista, ключ открывается с правами доступа ACCESS_SYSTEM_SECURITY, DELETE и KEY_WRITE. Если включены обе привилегии, ключ имеет объединенные права доступа для обоих привилегий. Дополнительные сведения см. в разделе Выполнение с особыми привилегиями. |
|
Примечание Символьные ссылки реестра следует использовать только для обеспечения совместимости приложений при крайней необходимости.
|
|
Этот ключ не является переменным; это значение по умолчанию. Эти сведения хранятся в файле и сохраняются при перезапуске системы. Функция RegSaveKey сохраняет ключи, которые не являются переменными. |
|
Все ключи, созданные функцией, являются переменными. Информация хранится в памяти и не сохраняется при выгрузке соответствующего куста реестра. Для HKEY_LOCAL_MACHINE это происходит только в том случае, если система инициирует полное завершение работы. Для разделов реестра, загруженных функцией RegLoadKey , это происходит при выполнении соответствующего regUnLoadKey . Функция RegSaveKey не сохраняет переменные ключи. Этот флаг игнорируется для уже существующих ключей.
Примечание При выбранном пользователем завершении работы быстрое завершение работы является поведением по умолчанию для системы.
|
[in] samDesired
Маска, указывающая права доступа для создаваемого ключа. Дополнительные сведения см. в разделе Безопасность раздела реестра и права доступа.
[in, optional] lpSecurityAttributes
Указатель на структуру SECURITY_ATTRIBUTES , которая определяет, может ли возвращенный дескриптор наследоваться дочерними процессами. Если lpSecurityAttributes имеет значение NULL, дескриптор не может быть унаследован.
Элемент lpSecurityDescriptor структуры задает дескриптор безопасности для нового ключа. Если lpSecurityAttributes имеет значение NULL, ключ получает дескриптор безопасности по умолчанию. Списки управления доступом в дескрипторе безопасности по умолчанию для ключа наследуются от его прямого родительского ключа.
[out] phkResult
Указатель на переменную, которая получает дескриптор открытого или созданного ключа. Если раздел не является одним из предопределенных разделов реестра, вызовите функцию RegCloseKey после завершения использования дескриптора.
[out, optional] lpdwDisposition
Указатель на переменную, которая получает одно из следующих значений перед ликвидацией.
| Значение | Значение |
|---|---|
|
Ключ не существует и был создан. |
|
Ключ существовал и был просто открыт без изменения. |
Если lpdwDisposition имеет значение NULL, сведения о ликвидации не возвращаются.
Возвращаемое значение
Если функция выполняется успешно, возвращаемое значение будет ERROR_SUCCESS.
Если функция завершается сбоем, возвращаемое значение представляет собой ненулевой код ошибки, определенный в Winerror.h. Чтобы получить общее описание ошибки, можно использовать функцию FormatMessage с флагом FORMAT_MESSAGE_FROM_SYSTEM.
Комментарии
Ключ, создаваемый функцией RegCreateKeyEx , не имеет значений. Приложение может использовать функцию RegSetValueEx для задания значений ключа.
Функция 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 |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по