RegGetValueA function (winreg.h)

Retrieves the type and data for the specified registry value.

Syntax

LSTATUS RegGetValueA(
  [in]                HKEY    hkey,
  [in, optional]      LPCSTR  lpSubKey,
  [in, optional]      LPCSTR  lpValue,
  [in, optional]      DWORD   dwFlags,
  [out, optional]     LPDWORD pdwType,
  [out, optional]     PVOID   pvData,
  [in, out, optional] LPDWORD pcbData
);

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_PERFORMANCE_DATA

HKEY_PERFORMANCE_NLSTEXT

HKEY_PERFORMANCE_TEXT

HKEY_USERS

[in, optional] lpSubKey

The path of a registry key relative to the key specified by the hkey parameter. The registry value will be retrieved from this subkey.

The path is not case sensitive.

If this parameter is NULL or an empty string, "", the value will be read from the key specified by hkey itself.

[in, optional] lpValue

The name of the registry value.

If this parameter is NULL or an empty string, "", the function retrieves the type and data for the key's unnamed or default value, if any. Keys do not automatically have an unnamed or default value, and unnamed values can be of any type.

For more information, see Registry Element Size Limits.

[in, optional] dwFlags

The flags that restrict the data type of value to be queried. If the data type of the value does not meet this criteria, the function fails. This parameter can be one or more of the following values.

This parameter can also include one or more of the following values.

[out, optional] pdwType

A pointer to a variable that receives a code indicating the type of data stored in the specified value. For a list of the possible type codes, see Registry Value Types. This parameter can be NULL if the type is not required.

[out, optional] pvData

A pointer to a buffer that receives the value's data. This parameter can be NULL if the data is not required.

If the data is a string, the function checks for a terminating null character. If one is not found, the string is stored with a null terminator if the buffer is large enough to accommodate the extra character. Otherwise, the function fails and returns ERROR_MORE_DATA.

[in, out, optional] pcbData

A pointer to a variable that specifies the size of the buffer pointed to by the pvData parameter, in bytes. When the function returns, this variable contains the size of the data copied to pvData.

The pcbData parameter can be NULL only if pvData is NULL.

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 by pvData parameter 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 pcbData. In this case, the contents of the pvData buffer are zeroes if dwFlags specifies RRF_ZEROONFAILURE and undefined otherwise.

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

If hKey specifies HKEY_PERFORMANCE_DATA and the pvData buffer is not large enough to contain all of the returned data, the function returns ERROR_MORE_DATA and the value returned through the pcbData parameter is undefined. This is because the size of the performance data can change from one call to the next. In this case, you must increase the buffer size and call RegGetValue again passing the updated buffer size in the pcbData parameter. Repeat this until the function succeeds. You need to maintain a separate variable to keep track of the buffer size, because the value returned by pcbData is unpredictable.

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 pvData buffer is too small to receive the value, the function returns ERROR_MORE_DATA.

If the lpValue registry value does not exist, the function returns ERROR_FILE_NOT_FOUND.

If dwFlags specifies a combination of both RRF_SUBKEY_WOW6464KEY and RRF_SUBKEY_WOW6432KEY, the function returns ERROR_INVALID_PARAMETER.

Remarks

An application typically calls RegEnumValue to determine the value names and then RegGetValue to retrieve the data for the names.

If the data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, and the ANSI version of this function is used (either by explicitly calling RegGetValueA 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 pointed to by pvData.

When calling this function with hkey set to the HKEY_PERFORMANCE_DATA handle and a value string of a specified object, the returned data structure sometimes has unrequested objects. Do not be surprised; this is normal behavior. You should always expect to walk the returned data structure to look for the requested object.

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.

To compile an application that uses this function, define _WIN32_WINNT as 0x0600 or later. For more information, see Using the Windows Headers.

Requirements

See also

RegCreateKeyEx

RegEnumKeyEx

RegEnumValue

RegOpenKeyEx

RegQueryInfoKey

Registry Functions

Registry Overview