URLSubstitution

This function resolves various substitutable parameters in a URL.

Declaration

HRESULT 
URLSubstitution (
    LPCWSTR lpUrl, 
    LPWSTR lpBuffer, 
    DWORD cchBuffer, 
    DWORD dwFlags);

The function has ANSI and Unicode forms, but not together in one version, and apparently not with an A or W suffix. The Unicode form is given above since the ANSI form is long obsolete.

Parameters

The lpUrl argument provides the address of a Unicode string to process.

The lpBuffer and cchBuffer 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

For each substitutable parameter that is enabled by the given dwFlags, the function replaces that parameter’s first occurrence with an evaluation (including to replace with nothing, i.e., remove).

The replacement is done in buffers on the stack, which allows that the output buffer may overlap the input. These buffers have capacity for INTERNET_MAX_URL_LENGTH (0x0824) characters. Exceeding this capacity does not cause the function to fail. Instead, the function 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).

Availability

The URLSubstitution function is exported from:

• SHDOCVW.DLL as ordinal 150 in versions 4.71 and 4.72;
• SHDOCVW.DLL as ordinal 165 in version 5.0 and higher;
• IEFRAME.DLL as ordinal 165 in version 7.0 and higher.

Beware that as ordinal 150, the function operates on ANSI strings, not Unicode. With the change to Unicode for version 5.0, ordinal 150 is reused for the _GetStdLocation function.

In version 6.0 from Windows Vista, and higher, SHDOCVW continues to export the function but only by forwarding to IEFRAME.

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).

Unexported Implementations

The transfer of URLSubstitution from SHDOCVW to IEFRAME is not as clean as might be imagined. Although attempts to import the function from SHDOCVW are forwarded to IEFRAME, SHDOCVW retains an implementation for internal use (specifically, as a helper for the function URLSubLoadString, which SHDOCVW continues to export even though IEFRAME also has a copy which it doesn’t export).

Two more modules from Windows Vista, namely IEXPLORE.EXE and INETCPL.CPL, reproduce the coding from IEFRAME rather than import the function. Microsoft’s published symbol files confirm that all three acquire this code from the same source file via a library, named STOCK_IE.LIB, and strongly suggest that SHDOCVW’s implementation is from what may have been the original source file.

The URLMON.DLL from Windows Vista has yet another coding of this function, apparently from yet another source file. This implementation does not support as many parameters, only {SUB_OLCID} and {SUB_CLCID}, and has C++ linkage. It appears to have been copied from SHDOCVW, rather than imported, so that URLMON version 6.0 could, by editing or possibly by conditional compilation, avoid converting to and from Unicode when resolving substitutable parameters in an ANSI string. Yet for the version 6.0 from Windows Vista, and higher, this copy in URLMON is natively Unicode and would surely be just as well imported from IEFRAME.

One more implementation appears to have been copied from SHDOCVW even longer ago and to have been edited substantially (even to acquire an extra argument). It is in MSOE.DLL, i.e., the main component of Outlook Express, later named Windows Mail.