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

Статья
11/20/2024

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

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

Синтаксис

LSTATUS RegCreateKeyA(
  [in]           HKEY   hKey,
  [in, optional] LPCSTR lpSubKey,
  [out]          PHKEY  phkResult
);

Параметры

[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, optional] lpSubKey

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

Дополнительные сведения о именах ключей см. в структуре реестра.

Если hKey является одним из стандартных ключей, lpSubKey может быть NULL. В этом случае phkResult получает тот же дескриптор hKey, переданный в функцию.

[out] phkResult

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

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

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

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

Замечания

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

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

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

subkey1\subkey2\subkey3\subkey4

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

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	winreg.h (включая Windows.h)
библиотеки	Advapi32.lib
DLL	Advapi32.dll