Retrieves the type and data for the specified registry value.
LONG WINAPI RegGetValue( _In_ HKEY hkey, _In_opt_ LPCTSTR lpSubKey, _In_opt_ LPCTSTR lpValue, _In_opt_ DWORD dwFlags, _Out_opt_ LPDWORD pdwType, _Out_opt_ PVOID pvData, _Inout_opt_ LPDWORD pcbData );
- 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.
- lpSubKey [in, optional]
The name of the registry key. This key must be a subkey of the key specified by the hkey parameter.
Key names are not case sensitive.
- lpValue [in, optional]
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.
For more information, see Registry Element Size Limits.
Keys do not automatically have an unnamed or default value. Unnamed values can be of any type.
- dwFlags [in, optional]
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.
Do not automatically expand environment strings if the value is of type REG_EXPAND_SZ.
If pvData is not NULL, set the contents of the buffer to zeroes on failure.
- pdwType [out, optional]
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.
- pvData [out, optional]
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.
- pcbData [in, out, optional]
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 undefined.
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.
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.
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.
Minimum supported client
|Windows Vista, Windows XP Professional x64 Edition [desktop apps only]|
Minimum supported server
|Windows Server 2008, Windows Server 2003 with SP1 [desktop apps only]|
Unicode and ANSI names
|RegGetValueW (Unicode) and RegGetValueA (ANSI)|
- Registry Functions
- Registry Overview
Build date: 10/26/2012