Export (0) Print
Expand All

RegQueryValue function

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

Note  This function is provided only for compatibility with 16-bit versions of Windows. Applications should use the RegQueryValueEx function.

Syntax


LONG WINAPI RegQueryValue(
  _In_         HKEY hKey,
  _In_opt_     LPCTSTR lpSubKey,
  _Out_opt_    LPTSTR lpValue,
  _Inout_opt_  PLONG lpcbValue
);

Parameters

hKey [in]

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
lpSubKey [in, optional]

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.

lpValue [out, optional]

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.

lpcbValue [in, out, optional]

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

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Winreg.h (include Windows.h)

Library

Advapi32.lib

DLL

Advapi32.dll

Unicode and ANSI names

RegQueryValueW (Unicode) and RegQueryValueA (ANSI)

See also

RegEnumKeyEx
RegEnumValue
Registry Functions
Registry Overview
RegQueryInfoKey
RegQueryValueEx
RegSetValueEx

 

 

Community Additions

ADD
Show:
© 2014 Microsoft