URLSubRegQuery

This function loads a URL from the registry and resolves various substitutable parameters.

Declaration

HRESULT 
URLSubRegQuery (
    LPCTSTR pszKey, 
    LPCTSTR pszValue, 
    BOOL fUseHKCU, 
    LPTSTR lpBuffer,
    DWORD nBufferMax,
    DWORD dwFlags);

The function exists in ANSI and Unicode forms.

Parameters

The pszSubKey and pszValue arguments name a registry key and registry value, respectively.

The fUseHKCU argument is non-zero to query the registry key relative to HKEY_CURRENT_USER in preference to HKEY_LOCAL_MACHINE. If the argument is zero, the key is relative to HKEY_LOCAL_MACHINE only.

The lpBuffer and nBufferMax arguments describe a buffer (by address and capacity in characters, respectively) that is to receive the processed string.

The dwFlags argument provides bit flags that specify the desired URL substitutions.

Return Value

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

Behaviour

The function reads data from the indicated registry value to a buffer on the stack, resolves the indicated substitutable parameters, and copies the result to the given buffer.

Failure to read the given registry value, including because there is too much data or it is the wrong type, is failure for the function. The error code is E_FAIL. IEFRAME implementations query the registry value using SHRegGetValueFromHKCUHKLM (if fUseHKCU is non-zero) else SHRegGetValue. Either way, the function insists on string data  (including REG_EXPAND_SZ with environment variables already expanded).

For loading the resource string and performing the substitutions, the function uses buffers on the stack with capacity for INTERNET_MAX_URL_LENGTH (0x0824) characters. Exceeding this capacity while resolving substitutable parameters does not cause the function to fail: the function instead does what it can but with truncation, so that the results are perhaps better regarded as undefined (not that the function provides any formal indication that truncation has occurred).

Old Behaviour

All SHDOCVW implementations query the registry value using SHRegGetUSValue (specifying no default data). Although REG_SZ data is surely expected, the function does nothing to require it. Data of any other type is treated as a Unicode string in version 5.0 and higher or an ANSI string in earlier versions.

Availability

The URLSubRegQuery function is exported:

• in an ANSI form from SHDOCVW as ordinal 151 in version 4.71 and higher;
• in ANSI and Unicode forms from IEFRAME as ordinals 151 and 238 in version 7.0 and higher.

This function is retired in the SHDOCVW version 6.0 from Windows Vista, and higher: it continues to be exported but only as a forward to SHUNIMPL for certain failure.

A Unicode form exists in SHDOCVW from as early as version 5.0, but is not exported. It is used internally, including to support the ANSI form which is exported.

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