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

Статья
03/13/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 после завершения использования дескриптора.

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

Если функция выполнена успешно, возвращаемое значение будет 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 или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

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