WPC_InstallState

This function assesses whether the Windows Parental Controls (WPC) are installed.

Declaration

HRESULT WPC_InstallState (DWORD *pdwState);

Parameters

The pdwState argument is the address of a variable that is to receive an indicator of the WPC install state:

0 if installed and allowed;
1 if not installed;
2 if disabled by Safe Mode or by Control Panel policy;
3 if disabled by domain policy.

Return Value

The function returns zero for success, else an error code.

Behaviour

If the pdwState argument is NULL, there is no install state to return, and the function fails (returning E_INVALIDARG). Except for this, the function always succeeds. It tests for cases 1, 2 and 3 in turn (as described below). If none apply, the function sets the variable at pdwState to 0.

Installed

If WPC is installed, there should be meaningful values in the registry key that defines the WPC Control Panel item. The function tests specifically for whether the friendly name is readable. This is stored in the following registry value:

Key:	HKEY_CLASSES_ROOT\CLSID\{96AE8D84-A250-4520-95A5-A47A7E3C548B}
Value:	LocalizedString

else in the default value of this same key. Data for the value may be an indirect string (in the sense of the SHLoadRegUIString function), to name a string resource in a resource library or executable. If the function cannot read a friendly name from either value, then WPC is not installed and the variable at pdwState is set to 1.

Safe Mode

WPC is disabled in any type of Safe Mode. The function sets the variable at pdwState to 2.

Control Panel Policy

Like any other Control Panel item, WPC is subject to administrative policy for specifying which items are allowed or which are disallowed. The mechanisms are well known. They are activated by setting the following registry values, which may each be in either of two keys (listed in decreasing order of precedence):

Key:	HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer
Value:	RestrictCpl DisallowCpl
Type:	boolean
Default:	false

Each setting activates a list of Control Panel items as values in another key:

HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer\RestrictCpl
HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer\DisallowCpl

A Control Panel item is listed in the subkey if there exists any value whose string data is the item’s friendly name or filename. The string data is case insensitive. If it is an indirect string (in the sense of the SHLoadIndirectString function) and the indicated string resource can be loaded, then the comparison is with the string resource. Otherwise, the comparison is with the string data itself.

If data for the RestrictCpl value is non-zero, then Control Panel items are disallowed unless they are listed specifically in the RestrictCpl subkey. If data for the DisallowCpl value is non-zero, then Control Panel items are disallowed if they are listed specifically in the DisallowCpl subkey.

These registry settings for Control Panel policy have user-interface support through the Group Policy Object Editor, as “Show only specified Control Panel items” and “Hide specified Control Panel items”, respectively, in the Control Panel template (in the User Configuration branch only).

If the Parental Controls item is disallowed through either setting (though only by being listed under its friendly name, not the filename), then the function sets the variable at pdwState to 2.

Domain Policy

For machines that are joined to a domain, WPC is ordinarily not enabled but can be enabled by administrative policy:

Key:	HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Policies\ParentalControls HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Policies\ParentalControls
Value:	WPCEnableOnDomain
Type:	boolean
Default:	false

If the machine is joined to a domain and this setting evaluates as zero, then WPC is disabled and the function sets the variable at pdwState to 3.

This registry setting has user-interface support through the Group Policy Object Editor, as “Make Parental Controls control panel visible on a Domain” in the Parental Controls administrative template (displayed under Windows Components in the Computer Configuration branch only).

Availability

The WPC_InstallState function is exported from SHELL32.DLL as ordinal 859 in the version 6.00 from Windows Vista, and higher.

This function was not documented by Microsoft for the January 2007 edition of the Windows Vista Software Development Kit (SDK).