Geoff Chappell - Software Analyst
This function gets the value of an Internet Explorer restriction.
DWORD
SHRestricted2 (
RESTRICTIONS2 rest,
LPCTSTR url,
DWORD reserved);
The function exists in ANSI and Unicode forms.
The rest argument selects the restriction whose value is wanted. The supported values in the RESTRICTIONS2 enumeration are listed separately. (This name for the enumeration is invented, no record of Microsoft’s name being known.)
The url argument, if not NULL, supplies a URL to evaluate the restriction for, most notably with respect to the URL’s security zone.
The reserved argument must be zero.
The function returns the value of the selected restriction, else zero.
The Internet Explorer restrictions are defined as a set in the sense supported by the SHLWAPI function SHRestrictionLookup. Each restriction is implemented as a registry value to be sought in either the HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER branch, with precedence given to the former. Though many restrictions are booleans that specify whether a corresponding feature is restricted, typically as an administrative policy, the general scheme is that a restriction can evaluate to any DWORD, defaulting to zero.
The function fails if reserved is not zero or if rest is unsupported.
When a URL is given, applicable restrictions (presently 0x50000002 to 0x50000008 inclusive) are evaluated first with respect to the security zone, if any, that applies to the URL. The ordinary registry value for the restriction applies only if no URL is given or if querying for the URL policy permission does not succeed.
Part of the SHLWAPI support is that SHDOCVW provides memory for caching the values of the restrictions. It then depends on SHELL32 to be notified through its SHSettingsChanged function if any restrictions have their values changed in the registry. SHELL32 records the notification by incrementing a global counter, which is also a SHLWAPI feature. The SHRestricted2 function consults the counter (using the undocumented SHLWAPI function SHGlobalCounterGetValue) to learn whether any settings are known to have changed since the previous call to SHRestricted2. If any have, the function resets its cached values of all restrictions before proceeding to ask SHLWAPI for the lookup.
To versions 4.71 and 4.72, any rest less than 0x50000001 cannot be an Internet Explorer restriction but may be a shell restriction and is passed unchanged to the SHELL32 function SHRestricted. Also in these versions, SHDOCVW does its own caching and its own lookup.
For the version 6.0 from Windows Vista, the preceding explanation of behaviour remains true of the implementation in SHDOCVW, but this is not the implementation that is accessed by importing SHRestricted2 from SHDOCVW. The function is not-quite duplicated in a new DLL, named IEFRAME, and is exported from there. SHDOCVW forwards all import requests to the copy that is exported from IEFRAME. The implementation in SHDOCVW still gets a little use, but only internally (and even this may be due to oversight or to some difficulty in shedding it completely). In version 6.1, the implementation in SHDOCVW is eliminated entirely.
The preceding explanation of behaviour also is true of the implementation in IEFRAME, except that SHLWAPI is reduced just to providing the sense and meaning of what a restriction is and of how one is implemented. IEFRAME does not actually call the undocumented function SHRestrictionLookup as implemented in SHLWAPI. Instead, IEFRAME has its own copy of the SHLWAPI code. Microsoft’s symbol files indicate that this copying of code from SHLWAPI is done at source-level, not by linking from a library.
Similar games apply to the global counter, but with more convolution. The SHLWAPI support for global counters was reworked for Windows Vista. The old functions are retired, but not because the functionality wasn’t wanted. There are new functions, arguably improving on the old, not that Microsoft cares to document them. Again, it should be stressed that the IEFRAME implementation of SHRestricted2 does not get its global counters by calling any code in SHLWAPI. It gets them instead from a copy of the code. This time, however, the copy is not in IEFRAME: it is in another new DLL, named IERTUTIL, and IEFRAME imports its global-counter functionality from there (under the new name IEGlobalCounterGetValue) rather than from SHLWAPI.
All this looks for all the world like a ruse to evade any accusation that IEFRAME calls undocumented SHLWAPI functions. Such calls would be problematic with respect to a legal settlement in which components of Internet Explorer are not to call undocumented functions in components of Windows. Just from its name, IEFRAME is surely an Internet Explorer component, and many might think SHLWAPI is just as surely a Windows component. Internet Explorer no longer calls SHLWAPI to help with the functionality of SHRestricted2. It just calls its own internal copy of the SHLWAPI code instead. Microsoft’s lawyers must be beside themselves with delight at their cleverness.
This “separation” of Internet Explorer functionality from Windows seems to have been prepared some years in advance of Windows Vista. Starting with the version 6.0 from Windows XP SP2 and from Windows Server 2003 SP1, including builds from the Internet Explorer 7 and 8 packages for Windows XP and Windows Server 2003, the SHDOCVW implementation of SHRestricted2 is aware that an IEFRAME implementation may be present from installation of Internet Explorer 7 or 8. The exported function is not actually SHRestricted2W itself but SHRestricted2W_IeframeProxy (and similarly for the ANSI version). The proxy may have been intended to redirect the function to the IEFRAME implementation when IEFRAME is indeed present. As actually coded however, all the proxy does is save the address of the IEFRAME implementation before proceeding anyway to execute the rest of the SHDOCVW implementation.
The SHRestricted2 function is exported in ANSI and Unicode forms from:
In version 6.0 from Windows Vista, and higher, SHDOCVW continues to export both forms of the function but only as forwards 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).