Функция 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, его можно использовать в операциях, которые изменяют реестр, если это разрешено дескриптором безопасности.
Этот дескриптор возвращается функцией
- 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
Примечание При выбранном завершении работы пользователя быстрое завершение работы — это поведение по умолчанию для системы.
|
[in] samDesired
Маска, указывающая права доступа для создаваемого ключа. Дополнительные сведения см. в разделе "Безопасность и права доступа реестра".
[in, optional] lpSecurityAttributes
Указатель на структуру SECURITY_ATTRIBUTES, которая определяет, может ли возвращаемый дескриптор наследоваться дочерними процессами. Если lpSecurityAttributesnull, то дескриптор нельзя наследовать.
Элемент lpSecurityDescriptor структуры задает дескриптор безопасности для нового ключа. Если lpSecurityAttributesNULL, ключ получает дескриптор безопасности по умолчанию. Списки управления доступом в дескрипторе безопасности по умолчанию для ключа наследуются от прямого родительского ключа.
[out] phkResult
Указатель на переменную, которая получает дескриптор открытого или созданного ключа. Если ключ не является одним из предопределенных разделов реестра, вызовите функцию RegCloseKey
[out, optional] lpdwDisposition
Указатель на переменную, которая получает одно из следующих значений ликвидации.
| Ценность | Значение |
|---|---|
|
Ключ не существовал и был создан. |
|
Ключ существовал и был просто открыт без изменения. |
Если lpdwDispositionNULL, данные о ликвидации не возвращаются.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение ERROR_SUCCESS.
Если функция завершается ошибкой, возвращаемое значение представляет собой ненулевой код ошибки, определенный в Winerror.h. Функцию FormatMessage можно использовать с флагом FORMAT_MESSAGE_FROM_SYSTEM для получения универсального описания ошибки.
Замечания
Ключ, который создает функция RegCreateKeyEx , не имеет значений. Приложение может использовать функцию regSetValueEx
Функция regCreateKeyEx
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 Профессиональный [только классические приложения] |
| минимальный поддерживаемый сервер | Windows 2000 Server [только классические приложения] |
| целевая платформа | Виндоус |
| заголовка | winreg.h (включая Windows.h) |
| библиотеки |
Advapi32.lib |
| DLL | Advapi32.dll |
См. также
Обзор реестра