SHGetValue

This function gets a value from an open registry key or optionally from a named subkey.

Declaration

DWORD
SHGetValue (
    HKEY hKey,
    LPCTSTR pszSubKey,
    LPCTSTR pszValue,
    LPDWORD pdwType,
    LPVOID pvData,
    LPDWORD pcbData);

The function exists in ANSI and Unicode forms.

Parameters

The hKey argument provides a handle to an open key.

The pszSubKey argument provides the address of a null-terminated string that names a subkey. If this argument is NULL or if the string it addresses is empty, there is no subkey.

The pszValue argument provides the address of a null-terminated string that names the value to query within the subkey, or is NULL to query the subkey’s default value. If no subkey is given, the value is sought within the open key instead.

The pdwType argument provides the address of a variable that is to receive the data type, e.g., REG_SZ or REG_DWORD. This argument can be NULL to mean that the data type is not wanted.

The pvData argument provides the address of a buffer that is to receive the data. This argument can be NULL to mean that there is no buffer and that the data is not wanted.

The pcbData argument provides the address of a variable that plays different roles on input and output. On input, the variable provides the size of the buffer, in bytes. This size is ignored if pvData is NULL, because there is then no buffer. On output, the variable receives the size of the data, in bytes. This argument can be NULL to mean that the size of the buffer is zero (if a buffer is even given) and that the size of the data is not wanted.

Return Value

The function returns zero for success, else an error code.

Of particular interest are the cases in which the value is accessible but has more data than can fit in the given buffer, including because there is no buffer:

• If pvData is NULL, the caller did not ask for data and is not denied anything that was asked for. The function therefore succeeds. If pcbData is not NULL, the variable at pcbData receives the size of the data.
• If pvData is not NULL, the caller asked for data, which the function cannot deliver. The function therefore fails. The error code is ERROR_MORE_DATA. The contents of the buffer at pvData are undefined. If pcbData is not NULL, the variable at pcbData receives the size of the data.

Behaviour

If not given a subkey, the function is essentially SHQueryValueEx. Otherwise, the function

• opens the subkey, asking just for KEY_QUERY_VALUE access,
• calls SHQueryValueEx to query the value in this subkey,
• and closes the subkey.

To have these steps in one function is convenient when no reason exists to keep the subkey open for longer, and can make for a useful saving of space.

Availability

The SHGetValue function is exported by name (in both ANSI and Unicode versions) from SHLWAPI version 4.70 and higher.

The function has long been documented, though tersely, and with the claim that it is available only from version 4.71.