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:

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

• ITaskCondition
• ITaskConditionInit

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:

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):

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:

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:

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:

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:

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):

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.