SHRegGetUSValueA function (shlwapi.h)

Article
11/20/2024

Retrieves a value from a registry subkey in a user-specific subtree (HKEY_CURRENT_USER or HKEY_LOCAL_MACHINE).

Syntax

LSTATUS SHRegGetUSValueA(
  [in]                LPCSTR pszSubKey,
  [in, optional]      LPCSTR pszValue,
  [in, out, optional] DWORD  *pdwType,
  [out, optional]     void   *pvData,
  [in, out, optional] DWORD  *pcbData,
  [in]                BOOL   fIgnoreHKCU,
  [in, optional]      void   *pvDefaultData,
  [in]                DWORD  dwDefaultDataSize
);

Parameters

[in] pszSubKey

Type: LPCTSTR

A pointer to a null-terminated string with the name of the subkey relative to HKEY_LOCAL_MACHINE and HKEY_CURRENT_USER. For example: "Software\MyCompany\MyProduct".

[in, optional] pszValue

Type: LPCTSTR

A pointer to a null-terminated string with the name of the value. This value can be NULL.

[in, out, optional] pdwType

Type: DWORD*

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 type information is not required, this parameter can be NULL.

[out, optional] pvData

Type: void*

A pointer to a buffer that receives the value's data.

[in, out, optional] pcbData

Type: DWORD*

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

[in] fIgnoreHKCU

Type: BOOL

A variable that specifies which key to look under. When set to TRUE, SHRegGetUSValue ignores HKEY_CURRENT_USER and returns the value from the key under HKEY_LOCAL_MACHINE.

[in, optional] pvDefaultData

Type: void*

A pointer to a buffer that receives the value's default data.

[in] dwDefaultDataSize

Type: DWORD

The length, in bytes, of the buffer pointed to by pvDefaultData.

Return value

Type: LSTATUS

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.

Remarks

When fIgnoreHKCU is set to TRUE, SHRegGetUSValue returns the value from the key under HKEY_LOCAL_MACHINE. When set to FALSE, SHRegGetUSValue first tries to return the value from the key under HKEY_CURRENT_USER. However, if the key is not found under HKEY_CURRENT_USER, the value is returned from the key under HKEY_LOCAL_MACHINE. If neither key is present, or if an error occurred and dwDefaultDataSize is nonzero, then the default data is copied to pvData and ERROR_SUCCESS returns. ERROR_SUCCESS returns for both default and non-default data, and there is no way of distinguishing which value copies to pvData. To prevent the use of default data, set pvDefaultData to NULL and dwDefaultDataSize to zero.

This function opens the key each time it is used. If your code involves getting a series of values from the same key, it is more efficient to open the key once with SHRegOpenUSKey and then use SHRegQueryUSValue to retrieve the data.

Note

The shlwapi.h header defines SHRegGetUSValue as an alias that 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 is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional, Windows XP [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	shlwapi.h
Library	Shlwapi.lib
DLL	Shlwapi.dll (version 4.71 or later)

Share via