RegQueryValueExW 函数（winreg.h）

项目
11/20/2024

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

警告

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

语法

LSTATUS RegQueryValueExW(
  [in]                HKEY    hKey,
  [in, optional]      LPCWSTR 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

注册表值的名称。

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

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

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

lpReserved

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

[out, optional] lpType

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

[out, optional] lpData

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

[in, out, optional] lpcbData

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

仅当 lpDataNULL时，l 参数才能 NULL。

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

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

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

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

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

返回值

如果函数成功，则返回值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 [仅限桌面应用]
目标平台	窗户
标头	winreg.h （包括 Windows.h）
库	Advapi32.lib
DLL	Advapi32.dll