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_LOCAL_MACHINEHKEY_USERS

[in, optional] lpSubKey

要打开的注册表子项的名称。

键名称不区分大小写。

如果 lpSubKey 参数为 NULL 或指向空字符串的指针，并且 hKey 是预定义键，则系统会刷新预定义的键，并且 phkResult 接收传递到函数中的同一 hKey 句柄。否则， phkResult 将接收打开的密钥的新句柄。

有关详细信息，请参阅注册表元素大小限制。

[in] ulOptions

指定要在打开密钥时应用的选项。将此参数设置为零或以下参数：

值	含义
REG_OPTION_OPEN_LINK	键是符号链接。仅当绝对必要时才应使用注册表符号链接。

[in] samDesired

一个掩码，指定要打开的密钥的所需访问权限。如果密钥的安全描述符不允许对调用进程进行请求的访问，则函数将失败。有关详细信息，请参阅注册表项安全和访问权限。

[out] phkResult

一个变量的指针，此变量指向已打开键的句柄。如果该键不是预定义的注册表项之一，请在使用完句柄后调用 RegCloseKey 函数。

返回值

如果函数成功，则返回值为 ERROR_SUCCESS。

如果函数失败，则返回值为 Winerror.h 中定义的非零错误代码。可以将 FormatMessage 函数与 FORMAT_MESSAGE_FROM_SYSTEM 标志一起使用，以获取错误的泛型说明。

注意

在旧版 Windows 上，此 API 也由 kernel32.dll 公开。

注解

与 RegCreateKeyEx 函数不同，如果注册表中不存在指定键， RegOpenKeyEx 函数不会创建指定键。

某些注册表操作对密钥的安全描述符（而不是获取密钥句柄时指定的访问掩码）执行访问检查。例如，即使某个项以KEY_READ的 samDesir 打开，也可用于创建注册表项（如果密钥的安全描述符允许）。相比之下， 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 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	winreg.h (包括 Windows.h)
Library	Advapi32.lib
DLL	Advapi32.dll