SHRestrictionLookup

This function gets the value of a shell restriction given by its ID within a table of supported restrictions.

Declaration

DWORD
SHRestrictionLookup (
    DWORD dwRestrictionId,
    LPCWSTR lpKey,
    const struct RESTRICTION_ITEM *lpRestrictionItems,
    LPDWORD lpRestrictionItemValues);

Since the RESTRICTION_ITEM structure appears to be used only for this function, its format is as well given here. (The names for this structure and for its members are invented, no record of Microsoft’s names being yet known.)

struct RESTRICTION_ITEM {
    DWORD dwRestrictionId;
    LPCWSTR lpSubKey;
    LPCWSTR lpValue;
};

Parameters

The dwRestrictionId argument identifies which restriction to look up.

The lpKey argument provides a null-terminated string that names a registry key, to be interpreted relative to HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER. This argument may be NULL to stand for Software\Microsoft\Windows\CurrentVersion\Policies.

The lpRestrictionItems argument provides the address of an array of structures that describe the supported restrictions. A structure whose lpSubKey member is NULL is treated as terminating the array and as not describing a restriction.

The lpRestrictionItemValues argument provides the address of an array of values for the supported restrictions, in the order set by the descriptive array. This array of values acts as a cache. A value of 0xFFFFFFFF is treated as invalid, as if it has not yet been looked up.

Return Value

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

Behaviour

The dwRestrictionId argument is meaningful only if it matches a dwRestrictionId member of some structure in the array at lpRestrictionItems. The value of the restriction is then the DWORD of data for the registry value named by lpValue in the subkey named by lpSubKey in the key named by lpKey in the HKEY_LOCAL_MACHINE branch of the registry, else in the HKEY_CURRENT_USER branch.

If dwRestrictionId does not match a dwRestrictionId member of some structure in the array at lpRestrictionItems, the function returns zero. If the corresponding entry in the lpRestrictionItemValues array is not 0xFFFFFFFF, it is accepted as the value of the restriction, without needing to query the registry. If the registry must be queried, then whatever value the function gets (including zero if the query fails), the function caches it in the lpRestrictionItemValues array.

Availability

The SHRestrictionLookup function is exported from SHLWAPI as ordinal 266 in version 5.00 and higher.

Though this function dates from as long ago as 1999, it was still not documented by Microsoft in the MSDN Library at least as late as the CD edition dated January 2004.

Use by Microsoft

The SHRestrictionLookup function is used by SHELL32 to support the SHRestricted function, which has been documented by Microsoft among the Settlement Program Interfaces.

Another user is SHDOCVW—and, in Windows Vista, IEFRAME—to support the SHRestricted2 function, which was still not documented in the Software Development Kit (SDK) dated January 2007.

The SHRestrictionLookup function is also used by COMDLG32 for a set of its own restrictions, just as it could be by any module written by any programmer who wants to provide for a set of configurable parameters that all default to zero.