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

Статья
11/20/2024

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

Для выполнения транзакционированных операций реестра с ключом вызовите функцию 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_LOCAL_MACHINEHKEY_USERS

[in, optional] lpSubKey

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

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

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

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

[in] ulOptions

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

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

[in] samDesired

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

[out] phkResult

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

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

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

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

Заметка

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

Замечания

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

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

Требования

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