SHRegGetValueA function (shlwapi.h)
[SHRegGetValue may be altered or unavailable in subsequent versions of the operating system or product. Use RegGetValue in its place.]
Retrieves a registry value.
LSTATUS SHRegGetValueA( [in] HKEY hkey, [in] LPCSTR pszSubKey, [in] LPCSTR pszValue, [in] SRRF srrfFlags, [in, out] DWORD *pdwType, [out] void *pvData, [in, out] DWORD *pcbData );
A handle to the currently open key, or any of the following predefined values.
A pointer to a null-terminated string that specifies the relative path from hkey to the subkey to retrieve the value from. This parameter can be NULL or an empty string, in which case the data is retrieved from the hkey location.
A pointer to a null-terminated string that contains the name of the value. This parameter can be NULL or an empty string, in which case the data is retrieved from the Default value.
One or more of the SRRF flags that restricts the data to be retrieved. At least one type restriction (SRRF_RT) value must be specified.
[in, out] pdwType
A pointer to a DWORD that receives the type of data stored in the retrieved value. When using default values, the input pdwType is the type of the default value. For possible values, see Registry Data Types. If the SRRF_NOEXPAND flag is not set, REG_EXPAND_SZ types are automatically expanded and returned as REG_SZ. If type information is not required, this parameter can be NULL.
A pointer to a buffer that receives the value's data. This parameter can be NULL if the data is not needed. For example, if you were testing only for a value's existence, the specific value data would be superfluous.
[in, out] pcbData
A pointer to a DWORD that, on entry, contains the size of the destination data buffer pvData, in bytes. This value can be NULL only if pvData is NULL. On exit, pcbData points to one of these values.
|NULL||ERROR_SUCCESS||Size in bytes sufficient to hold the registry data. Note that this is not guaranteed to be the precise size, but only a sufficient size.|
|Non-NULL||ERROR_SUCCESS||Exact number of bytes written to pvData.|
|Non-NULL||ERROR_MORE_DATA||Size in bytes needed to hold the entire data. Note that this is not guaranteed to be the precise size, but only a sufficient size.|
Returns ERROR_SUCCESS if successful, or a nonzero error code defined in Winerror.h otherwise. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a generic description of the error.
SHRegGetValue provides data type checking, boot mode checking, auto-expansion of REG_EXPAND_SZ data, and guaranteed null-termination of REG_SZ, REG_EXPAND_SZ, and REG_MULTI_SZ data.
The key identified by hkey must have been opened with KEY_QUERY_VALUE security access. If pszSubKey is not NULL or an empty string, that key also must be able to be opened with KEY_QUERY_VALUE security access in the current calling context.
If the data's type is REG_SZ, REG_EXPAND_SZ or REG_MULTI_SZ, then any returned data includes or takes into account the string's null-termination. For example, if pvData is not NULL, the data returned in that buffer is null-terminated. If pcbData is not NULL, the buffer size that it points to includes the bytes required to hold the terminating null character.
Unless the SRRF_NOEXPAND flag is set, string data of type REG_EXPAND_SZ is automatically expanded before being returned. The expanded string's type is reported in pdwType as REG_SZ, the pcbData parameter points to the number of bytes written for the expanded string, and the buffer pointed to by pvData holds the expanded version of the string.RegOpenKeyEx before calling SHRegGetValue. Use the key returned in the phkResult parameter of RegOpenKeyEx as the hkey parameter in this function, with pszSubKey set to NULL.
The potential for an additional call to the registry to read or re-read the data exists when the data type is REG_EXPAND_SZ and the SRRF_NOEXPAND flag has not been set. The following conditions result in that additional call.
- pvData is NULL, pcbData is not NULL. Though the data is not retrieved, the registry must be read to get the string and that string expanded to determine the required size of the data buffer.
- pvData is not NULL, but is too small to hold the data. The data is re-read to get the full string, the string is expanded, and the total required size is determined.
The shlwapi.h header defines SHRegGetValue as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
|Minimum supported client||Windows XP with SP2 [desktop apps only]|
|Minimum supported server||Windows Server 2003 [desktop apps only]|
|DLL||Shlwapi.dll (version 6.0 or later)|