SHRestricted

This function gets the value of a shell restriction.

Declaration

DWORD SHRestricted (RESTRICTIONS rest);

Parameters

The rest argument selects the restriction whose
value is wanted. The supported values in the RESTRICTIONS enumeration are listed separately,
since there are many members and also some awkward variations with the SHELL32 version.

Return Value

The function returns the value of the selected restriction, else zero.

Behaviour

The shell restrictions are defined as a set in the sense supported by the SHLWAPI
function SHRestrictionLookup.
Each restriction is implemented as a registry value in some subkey of
Software\Microsoft\Windows\CurrentVersion\Policies 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.

Part of the SHLWAPI support is that SHELL32 provides memory for caching the values
of the restrictions. SHELL32 expects to be notified through its
SHSettingsChanged
function if any restrictions have their values changed in the registry. The
SHRestricted function checks whether any such notifications
have been received since the previous call to SHRestricted.
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.

Old Behaviour

Until version 5.00, SHELL32 implemented this function itself instead of by providing
a table to the SHRestrictionLookup function in SHLWAPI.
In versions 4.71 and 4.72, this implementation did not differ very much from what
got moved to SHLWAPI in version 5.00. Earlier versions were not so settled.

In the very earliest implementations of version 4.0, for both Windows 95 releases
and for at least the original NT 4.0, restrictions are sought only in
HKEY_CURRENT_USER.

In the Windows 95 releases and all NT 4.0 releases as late as Service Pack 5
(but specifically not as late as Service Pack 6), the rest
argument is interpreted as a combination of bit flags. The function attempts to
get the value of each restriction that corresponds to a set bit in the
rest argument, and returns the first non-zero value
it encounters. Since the order of testing is surely an implementation detail, the
intention may have been that one call can test whether any of multiple restrictions
has a non-zero value.

The Windows 95 implementations do not cache the values of any restrictions and
they ignore restrictions when running in a clean-boot configuration.

Availability

The SHRestricted function is exported from SHELL32
as ordinal 100 in version 4.0 and higher. In version 6.0 and higher, starting from
Windows XP SP1, the function is also exported by name.

Though the function dates from the original release of Windows 95, it was left
undocumented by Microsoft until 2002 when it got listed among the
Settlement
Program Interfaces. Even then, the function is said to require “version 5.0
or later”.

This page was created on 12th September 2004 and was last modified
on 16th December 2009.