| Home | Table of Contents | Please view with Internet Explorer (version 5.00 or higher) and enable scripting. For reasons, see Browsing This Web Site. |
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.
When a URL is given, restrictions 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. By consulting the counter, the SHRestricted2 function checks whether any settings are known to have changed since the previous call to SHRestricted2. If they have, then the function resets its cached values of all restrictions. For every restriction, the next time that SHLWAPI is asked for a lookup, including for this call, it must refresh the cache from the registry.
It is perhaps very important to someone at Microsoft that something be spelt out here about the role of SHLWAPI in supporting these Internet Explorer restrictions. In 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 has been 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 code that is left 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).
For the IEFRAME implementation, 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 rather than from SHLWAPI.
All this looks for all the world like a ruse to evade any accusation that IEFRAME calls undocumented functions in SHLWAPI. This 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 as much a Windows component (and not just because Microsoft once upon a time described it as a core Windows component). True, IEFRAME does not call 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.
To versions 4.71 and all but the latest builds of version 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.
In all versions before 5.00, SHDOCVW does its own caching.
The SHRestricted2 function is exported in ANSI and Unicode forms from SHDOCVW as ordinals 158 and 159 respectively in version 4.71 and higher.
In Windows Vista, the exported implementation of this function is in IEFRAME, again as ordinals 158 and 159 for the ANSI and Unicode forms. SHDOCVW continues to export both forms of the function but only by forwarding them 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).