RegQueryValueA function (winreg.h)

Retrieves the data associated with the default or unnamed value of a specified registry key. The data must be a null-terminated string.

Syntax

LSTATUS RegQueryValueA(
  [in]                HKEY   hKey,
  [in, optional]      LPCSTR lpSubKey,
  [out, optional]     LPSTR  lpData,
  [in, out, optional] PLONG  lpcbData
);

Parameters

[in] hKey

A handle to an open registry key. The key must have been opened with the KEY_QUERY_VALUE access right. For more information, see Registry Key Security and Access Rights.

This handle is returned by the RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyEx, or RegOpenKeyTransacted function. It can also be one of the following predefined keys:

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

[in, optional] lpSubKey

The name of the subkey of the hKey parameter for which the default value is retrieved.

Key names are not case sensitive.

If this parameter is NULL or points to an empty string, the function retrieves the default value for the key identified by hKey.

For more information, see Registry Element Size Limits.

[out, optional] lpData

A pointer to a buffer that receives the default value of the specified key.

If lpValue is NULL, and lpcbValue is non-NULL, the function returns ERROR_SUCCESS, and stores the size of the data, in bytes, in the variable pointed to by lpcbValue. This enables an application to determine the best way to allocate a buffer for the value's data.

[in, out, optional] lpcbData

A pointer to a variable that specifies the size of the buffer pointed to by the lpValue parameter, in bytes. When the function returns, this variable contains the size of the data copied to lpValue, including any terminating null characters.

If the data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, this size includes any terminating null character or characters. For more information, see Remarks.

If the buffer specified lpValue is not large enough to hold the data, the function returns ERROR_MORE_DATA and stores the required buffer size in the variable pointed to by lpcbValue. In this case, the contents of the lpValue buffer are undefined.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a system error code.

If the lpValue buffer is too small to receive the value, the function returns ERROR_MORE_DATA.

Remarks

If the ANSI version of this function is used (either by explicitly calling RegQueryValueA or by not defining UNICODE before including the Windows.h file), this function converts the stored Unicode string to an ANSI string before copying it to the buffer specified by the lpValue parameter.

If the data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, the string may not have been stored with the proper null-terminating characters. Therefore, even if the function returns ERROR_SUCCESS, the application should ensure that the string is properly terminated before using it; otherwise, it may overwrite a buffer. (Note that REG_MULTI_SZ strings should have two null-terminating characters.)

Note that operations that access certain registry keys are redirected. For more information, see Registry Virtualization and 32-bit and 64-bit Application Data in the Registry.

Requirements

See also

RegEnumKeyEx

RegEnumValue

RegQueryInfoKey

RegQueryValueEx

RegSetValueEx

Registry Functions

Registry Overview