RegQueryValueExA 函数 (winreg.h)

项目
03/11/2023

检索与打开的注册表项关联的指定值名称的类型和数据。

警告

如果要查询的值是字符串 (REG_SZ、REG_MULTI_SZ和REG_EXPAND_SZ) 则不保证返回的值以 null 结尾。如果要确保返回的字符串值以 null 结尾，请使用 RegGetValue 函数。有关详细信息，请参阅下面的备注。

语法

LSTATUS RegQueryValueExA(
  [in]                HKEY    hKey,
  [in, optional]      LPCSTR  lpValueName,
                      LPDWORD lpReserved,
  [out, optional]     LPDWORD lpType,
  [out, optional]     LPBYTE  lpData,
  [in, out, optional] LPDWORD lpcbData
);

参数

[in] hKey

打开的注册表项的句柄。密钥必须已使用KEY_QUERY_VALUE访问权限打开。有关详细信息，请参阅注册表项安全和访问权限。

此句柄由 RegCreateKeyEx、 RegCreateKeyTransacted、 RegOpenKeyEx 或 RegOpenKeyTransacted 函数返回。它也可以是以下预定义键之一：

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_PERFORMANCE_NLSTEXT

HKEY_PERFORMANCE_TEXT

HKEY_USERS

[in, optional] lpValueName

注册表值的名称。

如果 lpValueName 为 NULL 或空字符串“”，则函数将检索键的未命名值或默认值的类型和数据（如果有）。

如果 lpValueName 指定的值不在注册表中，则函数将返回ERROR_FILE_NOT_FOUND。

键不会自动具有未命名值或默认值。未命名的值可以是任何类型的值。有关详细信息，请参阅注册表元素大小限制。

lpReserved

此参数是保留的，必须为 NULL。

[out, optional] lpType

指向变量的指针，该变量接收指示存储在指定值中的数据类型的代码。有关可能的类型代码的列表，请参阅注册表值类型。如果不需要类型代码， 则 lpType 参数可以为 NULL 。

[out, optional] lpData

指向接收值数据的缓冲区的指针。如果不需要数据，此参数可以为 NULL 。

[in, out, optional] lpcbData

指向变量的指针，该变量指定 lpData 参数指向的缓冲区的大小（以字节为单位）。当函数返回时，此变量包含复制到 lpData 的数据的大小。

仅当 lpData 为 NULL 时，lData 参数才能为 NULL。

如果数据具有REG_SZ、REG_MULTI_SZ或REG_EXPAND_SZ类型，则此大小包括任何终止 null 字符或字符，除非数据存储时没有它们。有关详细信息，请参阅“备注”。

如果 lpData 参数指定的缓冲区不够大，无法保存数据，则函数将返回ERROR_MORE_DATA并将所需的缓冲区大小存储在 l ERROR_MORE_DATA Data 指向的变量中。在这种情况下， lpData 缓冲区的内容未定义。

如果 lpData 为 NULL，且 lData 为非 NULL，则该函数返回ERROR_SUCCESS，并将数据的大小（以字节为单位）存储在 l ERROR_SUCCESS Data 指向的变量中。这使应用程序能够确定为值的数据分配缓冲区的最佳方式。

如果 hKey 指定 HKEY_PERFORMANCE_DATA 并且 lpData 缓冲区不够大，无法包含所有返回的数据， 则 RegQueryValueEx 将返回ERROR_MORE_DATA，并且通过 lusbData 参数返回的值未定义。这是因为性能数据的大小可能会从一次调用更改为下一个调用。在这种情况下，必须增加缓冲区大小，并再次调用 RegQueryValueEx ，并在 lusbData 参数中传递更新的缓冲区大小。重复此操作，直到函数成功。你需要保留一个单独的变量来跟踪缓冲区大小，因为 lData 返回的值不可预知。

如果 lpValueName 注册表值不存在， 则 RegQueryValueEx 将返回ERROR_FILE_NOT_FOUND，并且通过 lusbData 参数返回的值未定义。

返回值

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

如果函数失败，则返回值为系统错误代码。

如果 lpData 缓冲区太小而无法接收数据，则函数将返回ERROR_MORE_DATA。

如果 lpValueName 注册表值不存在，该函数将返回ERROR_FILE_NOT_FOUND。

注解

应用程序通常调用 RegEnumValue 来确定值名称，然后 调用 RegQueryValueEx 来检索名称的数据。

如果数据具有REG_SZ、REG_MULTI_SZ或REG_EXPAND_SZ类型，则字符串可能未使用正确的终止 null 字符进行存储。因此，即使函数返回ERROR_SUCCESS，应用程序也应该确保字符串在使用前正确终止;否则，它可能会覆盖缓冲区。 (请注意，REG_MULTI_SZ字符串应具有两个终止 null 字符。) 应用程序可以确保字符串正确终止的一种方法是使用 RegGetValue，这将根据需要添加终止 null 字符。

如果数据具有REG_SZ、REG_MULTI_SZ或REG_EXPAND_SZ类型，并且此函数的 ANSI 版本通过显式调用 RegQueryValueExA 或在将 Windows.h 文件) 之前未定义 UNICODE 来 (使用，则此函数会将存储的 Unicode 字符串转换为 ANSI 字符串，然后再将其复制到 lpData 指向的缓冲区。

调用 RegQueryValueEx 函数时，将 hKey 设置为 HKEY_PERFORMANCE_DATA 句柄和指定对象的值字符串时，返回的数据结构有时具有未请求的对象。不要感到惊讶：这是正常行为。调用 RegQueryValueEx 函数时，应始终希望遍历返回的数据结构以查找请求的对象。

请注意，将重定向访问某些注册表项的操作。有关详细信息，请参阅注册表虚拟化和注册表中的 32 位和 64 位应用程序数据。

示例

请确保在每次调用此函数时，重新初始化 由 l++Data 参数指向的值。在循环中调用此函数时，这一点非常重要，如下面的代码示例所示。

#include <windows.h>
#include <malloc.h>
#include <stdio.h>

#define TOTALBYTES    8192
#define BYTEINCREMENT 4096

void main()
{
    DWORD BufferSize = TOTALBYTES;
    DWORD cbData;
    DWORD dwRet;

    PPERF_DATA_BLOCK PerfData = (PPERF_DATA_BLOCK) malloc( BufferSize );
    cbData = BufferSize;

    printf("\nRetrieving the data...");

    dwRet = RegQueryValueEx( HKEY_PERFORMANCE_DATA,
                             TEXT("Global"),
                             NULL,
                             NULL,
                             (LPBYTE) PerfData,
                             &cbData );
    while( dwRet == ERROR_MORE_DATA )
    {
        // Get a buffer that is big enough.

        BufferSize += BYTEINCREMENT;
        PerfData = (PPERF_DATA_BLOCK) realloc( PerfData, BufferSize );
        cbData = BufferSize;

        printf(".");
        dwRet = RegQueryValueEx( HKEY_PERFORMANCE_DATA,
                         TEXT("Global"),
                         NULL,
                         NULL,
                         (LPBYTE) PerfData,
                         &cbData );
    }
    if( dwRet == ERROR_SUCCESS )
        printf("\n\nFinal buffer size is %d\n", BufferSize);
    else printf("\nRegQueryValueEx failed (%d)\n", dwRet);
}

注意

winreg.h 标头将 RegQueryValueEx 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求


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