CTaskCondition

The CTaskCondition class is one of many that SHELL32 exposes through its exported DllGetClass function. Instances can therefore be created using such well-documented COM functions as CoCreateInstance, by anyone who knows the CLSID:

CLSID_CTaskCondition {EE8E4870-A889-4DC4-969F-F38F707F4AC2}

The CTaskCondition class implements the following interfaces (in the SHELL32 version 6.00 from Windows Vista):

Though the CTaskCondition class may have been written solely to support the Control Panel, the conditions it can test are surely useful for many purposes. Each instance of the class tests one condition which can be specified through either method of the ITaskConditionInit interface. The Init method provides for the condition to be named, for its test to be inverted, and for some number of name-value pairs to be set for the condition. The InitFromXML method provides for the same, but with the specification to be drawn from an XML DOM node. Once the condition has been primed, it may be evaluated any number of times by calling the Eval method of the ITaskCondition interface.

The point to the XML DOM node is apparent from inspection of SHELL32’s own task XML file (number 21 in the SHELL32 resources, if only for the version 6.00 from Windows Vista). Though Microsoft does present annotated examples of task XML files such as may be followed by non-Microsoft programmers of Control Panel items, the examples have no <sh:conditions> blocks and thus don’t demonstrate how to make display of a Control Panel item conditional on some expected hardware or software support.

Supported Conditions

The following conditions are supported by the SHELL32 version 6.00 from Windows Vista:

Condition Properties
shcond://v1#IsAuxDisplayConnected  
shcond://v1#IsAuxDisplayConnectedAndAutoWakeEnabled  
shcond://v1#IsBrightnessAvailable  
shcond://v1#IsConnectedToInternet  
shcond://v1#IsDateInRange Before
After
shcond://v1#IsGlassOn  
shcond://v1#IsMachineOnDomain  
shcond://v1#IsMachineNotOnDomainAndDomainIsAvail  
shcond://v1#IsMobilePC  
shcond://v1#IsMuiEnabled  
shcond://v1#IsOfflineFilesEnabled  
shcond://v1#IsPenAvailable  
shcond://v1#IsPresentationSettingsEnabled  
shcond://v1#IsServer  
shcond://v1#IsSlapiEnabled ValueName
shcond://v1#IsTabletPC  
shcond://v1#IsTouchAvailable  
shcond://v1#IsUserAdmin  
shcond://v1#RegkeyExists Regkey
shcond://v1#RegvalEquals Regkey
Regval
RegvalExpected
shcond://v1#RegvalExists Regkey
Regval
shcond://v1#SkuEquals Sku

The condition “shcond://v1#IsDateInRange” requires at least one Before or After property. It evaluates as many as given, answering for whether all constraints are true of the current date and time. For all other conditions where more than one property is shown, all are required.

Some of the tested conditions are very much the sort of thing on which programmers can spend a lot of time with little certainty of having coded a reliable test. So, how nice of the shell to provide a standardisation!

Detailed documentation of all conditions is left for another time, not least for the trouble of deciding the most suitable format for presenting them. Some are nearly trivial and many are not substantial enough to justify separate pages. Yet others involve enough code that the descriptions would be too complex for inclusion just as a section on this page. If only for now, a selection is documented immediately below.

IsAuxDisplayConnected

The “shcond://v1#IsAuxDisplayConnected” condition evaluates as true if a Windows SideShow-compatible device is connected.

The test is to ask SETUPAPI whether it has at least some device information for the SideShow device class. The SetupDiGetClassDevsEx function is called with GUID_DEVCLASS_SIDESHOW as its first argument and with nothing for all other arguments. If this succeeds, then the returned handle is passed to the SetupDiEnumDeviceInfo function to obtain the first device information element. If this function succeeds and the last error code is not ERROR_NO_MORE_ITEMS, then the condition evaluates as true.

IsAuxDisplayConnectedAndAutoWakeEnabled

The “shcond://v1#IsAuxDisplayConnectedAndAutoWakeEnabled” condition adds to the basic “shcond://v1#IsAuxDisplayConnected” condition by also testing for whether automatic waking is allowed.

Automatic waking of SideShow devices is subject to administrative policy, through the following registry setting in either of two keys (listed in decreasing order of precedence):

Key: HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\SideShow
HKEY_CURRENT_USER\Software\Policies\Microsoft\Windows\SideShow
Value: AutoWakeDisabled
Default: 0

Any four bytes of data are accepted. Any non-zero value means that automatic waking is disabled and the condition evaluates as false.

This registry setting has user-interface support through the Group Policy Object Editor, as “Turn off automatic wake” in the Windows SideShow administrative template (shown under Windows Components).

IsMobilePC

The “shcond://v1#IsMobilePC” condition evaluates as true if Windows is running on a mobile PC (or is configured as if running on a mobile PC). The Control Panel uses this condition to decide whether to show the Mobile PC category of Control Panel items.

The test has two parts. The condition is true if either part succeeds.

The first determination is of whether the machine has the power configuration of a laptop. If the POWRPROF function PowerDeterminePlatformRole returns PlatformRoleMobile (2), then the condition evaluates as true. If it returns PlatformRoleDesktop (1), then refinement is sought from another POWRPROF function, GetPwrCapabilities. If the returned data has the SystemBatteriesPresent member as true but the BatteriesAreShortTerm member as false, then the condition evaluates as true.

The other part to the test is a registry setting:

Key: HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Explorer\ControlPanel
Value: ShowCategoryMobilePC
Type: boolean
Default: false

Data of various types is accepted (following the rules for the documented SHRegGetBoolUSValue function). The setting, and thence the condition, evaluates as true if REG_DWORD data is non-zero, if any of the first four bytes of REG_BINARY data is non-zero, or if case-insensitive REG_SZ or REG_EXPAND_SZ data is any of YES, TRUE or 1. No user-interface support is known for this setting.

IsPenAvailable

The “shcond://v1#IsTouchAvailable” condition evaluates as true if a pen device is usable. Evaluation is wholly dependent on one registry setting:

Key: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\Tablet PC
Value: DeviceKind
Type: REG_DWORD

The condition evaluates as true if the 0x80000000 and 0x00000004 bits are both set in the dword of data.

IsPresentationSettingsEnabled

The “shcond://v1#IsPresentationSettingsEnabled” condition evaluates as true if running on a mobile PC that is allowed Presentation Settings.

Evaluation is in three parts. All must be true for the condition to evaluate as true. First, the “shcond://v1#IsMobilePC” condition must evaluate as true. Second, Presentation Settings must be licensed. The DWORD data for the license value MobilePCPresentationSettings-EnablePresentationSettings must be non-zero (which is true only for the Home Premium, Business and Ultimate editions of WIndows Vista and for no editions of Windows Server 2008.) Finally, Presentation Settings must not be disabled by policy. This means that the following registry value in either of two keys (listed in decreasing order of precedence) must not be non-zero:

Key: HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Policies\PresentationSettings
HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Policies\PresentationSettings
Value: NoPresentationSettings
Type: boolean
Default: false

This setting has user-interface support through the Group Policy Object Editor, as “Turn off Windows presentation settings” in the Presentation Settings administrative template (shown under Windows Components).

IsTouchAvailable

The “shcond://v1#IsTouchAvailable” condition evaluates as true if a touch-screen device is usable. Evaluation is wholly dependent on one registry setting:

Key: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\Tablet PC
Value: DeviceKind
Type: REG_DWORD

The condition evaluates as true if the 0x80000000 and 0x00000001 bits are both set in the dword of data.

IsUserAdmin

The “shcond://v1#IsUserAdmin” condition evaluates as true if the current user has administrative privilege (whether currently elevated or not).

Evaluation involves as many as three queries for information about the access token for the current thread, if available, else the current process, but only the first two queries actually matter to the result. If a query for the TokenElevationType information class succeeds and reports the type as TokenElevationTypeFull, then the user is elevated and the condition evaluates as true. If the type is TokenElevationTypeLimited, then the user at least has the means to be elevated and the condition evaluates as true. If the type is TokenElevationTypeDefault, then the token is queried for the TokenElevation information class. If this succeeds and the token is elevated, then the condition evaluates as true. In all other cases, the condition evaluates as false. The redundant query is for the TokenUIAccess information class.

Note that this test is very different from that of the documented IsUserAnAdmin function (which tests for membership of the Administrators group).

SkuEquals

The “shcond://v1#SkuEquals” condition evaluates as true if executing on the given Windows product type.

The INamedPropertyStore given to the Eval method must provide a property named Sku whose case-insensitive string value is to be tested against the product type obtained from the GetProductInfo function. The following are supported by the SHELL32 version 6.00 from Windows Vista (original and SP1):

Sku Matching Product Types
anybusiness PRODUCT_BUSINESS
PRODUCT_SMALLBUSINESS_SERVER
PRODUCT_BUSINESS_N
anyhome PRODUCT_HOME_BASIC
PRODUCT_HOME_PREMIUM
PRODUCT_HOME_BASIC_N
PRODUCT_STARTER
PRODUCT_HOME_PREMIUM_N
anyn PRODUCT_HOME_BASIC_N
PRODUCT_BUSINESS_N
PRODUCT_HOME_PREMIUM_N
PRODUCT_ENTERPRISE_N
PRODUCT_ULTIMATE_N
business PRODUCT_BUSINESS
businessn PRODUCT_BUSINESS_N
enterprise PRODUCT_ENTERPRISE
PRODUCT_ENTERPRISE_SERVER
PRODUCT_ENTERPRISE_SERVER_CORE
PRODUCT_ENTERPRISE_SERVER_IA64
PRODUCT_ENTERPRISE_N
enterprisen PRODUCT_ENTERPRISE_N
homebasic PRODUCT_HOME_BASIC
homen PRODUCT_HOME_BASIC_N
homepremium PRODUCT_HOME_PREMIUM
homepremiumn PRODUCT_HOME_PREMIUM_N
smallbusiness PRODUCT_SMALLBUSINESS_SERVER
starter PRODUCT_STARTER
ultimate PRODUCT_ULTIMATE
ultimaten PRODUCT_ULTIMATE_N

The properties “anyn”, “enterprisen”, “homepremiumn” and “ultimaten” are not recognised before Windows Vista SP1 and Windows Server 2008.

Availability

The CTaskCondition class is implemented in the SHELL32 version 6.00 from Windows Vista, and higher.

Though new for Windows Vista, this class is not documented by Microsoft in the January 2007 edition of the Software Development Kit (SDK) for Windows Vista.