SKAllocValueW

This function retrieves the data for a value in a subkey of a shell key.

Declaration

HRESULT
SKAllocValueW (
    SHELLKEY nShellKey,
    LPCWSTR pszSubKey,
    LPCWSTR pszValue,
    LPDWORD pdwType,
    LPVOID *ppvData,
    LPDWORD pcbData);

Parameters

The nShellKey argument specifies the shell key as a constant from the SHELLKEY enumeration.

The pszSubKey argument provides the address of a null-terminated string that names the subkey, or is NULL for the shell key itself.

The pszValue argument provides the address of a null-terminated string that names the value, or is NULL for the default value.

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 ppvData argument provides the address of a variable that is to receive the address of the data.

The pcbData argument provides the address of a variable that is to receive the size of the data, in bytes. This argument can be NULL to mean that the data size is not wanted.

Return Value

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

Behaviour

The function opens the given subkey of the specified shell key (using SHGetShellKeyEx, asking for read access), queries the given value for its size, seeks memory to hold that size of data (plus two bytes), and then queries the value for its data and closes the subkey. The memory is obtained through LocalAlloc and may be freed through LocalFree when the caller is done with it.

The registry queries are done through SHQueryValueExW. The first query is done with no buffer, just to get the size of data that is available for the given value. The detail of adding two bytes to this size is explainable by knowledge that when SHQueryValueExW is called to get data into a buffer, it corrects for improperly terminated string data and may need as many as two bytes spare in the buffer.

Variations

In builds before Windows Vista, the subkey is opened by using SHGetShellKey.

Availability

The SKAllocValueW function is exported from SHLWAPI as ordinal 519 in version 6.00 and higher.

Though this function dates from 2001, it was still not documented by Microsoft as late as the January 2007 edition of the Windows Vista Software Development Kit (SDK).