URLSubLoadString

This function loads a URL as a resource string and resolves various substitutable parameters.

Declaration

HRESULT 
URLSubLoadString (
    HINSTANCE hInstance, 
    UINT uID, 
    PWSTR lpBuffer, 
    DWORD cchBuffer, 
    DWORD dwFlags);

Parameters

The hInstance argument provides the handle to an instance of the module from which to load the resource string, or is NULL to load from SHDOCVW’s or IEFRAME’s resources.

The uID argument provides the integer identifier of the desired resource string.

The lpBuffer and cchBuffer arguments describe a buffer (by address and capacity in Unicode 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 loads the indicated resource string into a buffer on the stack, resolves the indicated substitutable parameters, and copies the result to the given buffer.

Failure to load the resource string is failure for the function. The error code is E_FAIL. 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).

Use by Microsoft

The most conspicuous use of this function by Microsoft is the internal matter of where Internet Explorer navigates in response to selections from the browser’s main menu, especially for on-line help. The target URLs are configurable through the registry, but the defaults are loaded from SHDOCVW’s resources, using URLSubLoadString.

A less obvious use, not continued into Windows Vista, is by SHELL32, to support the Visit Gallery button in the New Desktop Item dialog. The URL for the Microsoft Desktop Gallery is in SHELL32’s resources and is loaded using URLSubLoadString.

Availability

The URLSubLoadString function is exported from SHDOCVW as ordinal 138 in version 5.0 and higher.

An ANSI form of this function exists in SHDOCVW as early as version 4.71, but is not exported. This early form does not make a special case of hInstance being NULL.

A very slightly different coding of this function exists in IEFRAME but is not exported. It seems to have this copy only because the browser’s code for handling WM_COMMAND messages has moved to IEFRAME from BROWSEUI. The implementation of URLSubLoadString in SHDOCVW continues to be exported, but quick inspection of Microsoft’s symbol files for Windows Vista suggests that no Windows (or Internet Explorer) executable now imports the function.

SHDOCVW version 6.1 retires this function: it continues to be exported but only as a forward to SHUNIMPL for certain failure.

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