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

Статья
08/27/2023

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

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

Синтаксис

LSTATUS RegOpenKeyExA(
  [in]           HKEY   hKey,
  [in, optional] LPCSTR lpSubKey,
  [in]           DWORD  ulOptions,
  [in]           REGSAM samDesired,
  [out]          PHKEY  phkResult
);

Параметры

[in] hKey

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

HKEY_CLASSES_ROOTHKEY_CURRENT_CONFIGHKEY_CURRENT_USERHKEY_USERS HKEY_LOCAL_MACHINE

[in, optional] lpSubKey

Имя открываемого подраздела реестра.

В именах ключей регистр не учитывается.

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

Дополнительные сведения см. в разделе Ограничения размера элементов реестра.

[in] ulOptions

Указывает параметр, применяемый при открытии ключа. Задайте для этого параметра значение 0 или следующее:

Значение	Значение
REG_OPTION_OPEN_LINK	Ключ является символьной ссылкой. Символические ссылки реестра следует использовать только при крайней необходимости.

[in] samDesired

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

[out] phkResult

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

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

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

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

Примечание

В устаревших версиях Windows этот API также предоставляется kernel32.dll.

Некоторые операции реестра выполняют проверки доступа по дескриптору безопасности ключа, а не по маске доступа, указанной при получении дескриптора ключа. Например, даже если ключ открывается с помощью samDesired KEY_READ, его можно использовать для создания разделов реестра, если это разрешено дескриптором безопасности ключа. В отличие от этого, функция RegSetValueEx требует, чтобы ключ был открыт с KEY_SET_VALUE права доступа.

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

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

Примеры

lResult = RegOpenKeyEx (hKeyRoot, lpSubKey, 0, KEY_READ, &hKey);

if (lResult != ERROR_SUCCESS) 
{
    if (lResult == ERROR_FILE_NOT_FOUND) {
        printf("Key not found.\n");
        return TRUE;
    } 
    else {
        printf("Error opening key.\n");
        return FALSE;
    }
}

Чтобы увидеть этот пример в контексте, см. раздел Удаление ключа с подразделами.

Примечание

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

Требования

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