IsOS

Declaration

BOOL IsOS (DWORD dwOS);

Parameters

The dwOS argument selects a question about the operating system, or at least about the current process’s relationship with the operating system. Not all questions are supported in all SHLWAPI versions. Not all values of dwOS select the same question in all SHLWAPI versions.

Return Value

The function returns a non-zero value to indicate that the tested condition is satisfied, else the function returns FALSE. The non-zero value is not necessarily TRUE.

Behaviour

The function depends heavily, as might anyone, on the version information reported by the standard API function GetVersionEx. In versions before 6.1, this information is sought only the first time that the IsOS function is called. The IsOS function asks first to have an OSVERSIONINFOEXA structure filled, and failing that, an OSVERSIONINFOA structure. Success at getting one or the other is assumed. Having got (or already having) this version information, the function sets about interpreting it for the question implied by the dwOS argument. In version 6.1 and higher, the function asks for version information only when needed for the particular question, and only then as an OSVERSIONINFOEXW structure, and the function fails (returns FALSE) if this version information is not available.

The function fails if dwOS is not one of the supported constants.

Rather than attempt a description of which versions, editions and other variations of Microsoft’s operating systems satisfy which questions, the following table summarises what the function tests to answer the question. The descriptions in terms of platform, version, build, product type and suite, as obtained from GetVersionEx, are common to many cases, as are the descriptions in terms of system metrics, and are explained in the section on Behaviour. Such descriptions are complete for most values of dwOS. Other cases are elaborated on separate pages. The table is regrettably wide, mostly to account for variations in what is tested by which SHLWAPI versions.

Version Information

To save space in the preceding table, and throughout this article, some shorthands are used for the members of the version information structure and the values they can take. None should be unclear, but they are all listed below for definiteness:

• “major version” is the dwMajorVersion member
• “minor version” is the dwMinorVersion member
• “version” is a standard composition of the dwMajorVersion and dwMinorVersion members
• “build” is the dwBuildNumber member
• “platform” is the dwPlatformId member
  • “Windows” is VER_PLATFORM_WIN32_WINDOWS
  • “NT” is VER_PLATFORM_WIN32_NT
• “suite” is the wSuiteMask member, understood in terms of bit flags, so that it is whichever bits are set and it is not whichever bits are clear
  • “small business” is VER_SUITE_SMALLBUSINESS
  • “enterprise” is VER_SUITE_ENTERPRISE
  • “terminal” is VER_SUITE_TERMINAL
  • “small business restricted” is VER_SUITE_SMALLBUSINESS_RESTRICTED
  • “embedded” is VER_SUITE_EMBEDDEDNT
  • “data center” is VER_SUITE_DATACENTER
  • “single user” is VER_SUITE_SINGLEUSERTS
  • “personal” is VER_SUITE_PERSONAL
  • “blade” is VER_SUITE_BLADE
  • “storage server” is VER_SUITE_STORAGE_SERVER
  • “compute server” is VER_SUITE_COMPUTE_SERVER
  • “home server” is VER_SUITE_WH_SERVER
• “product type” is the wProductType member
  • “workstation” is VER_NT_WORKSTATION
  • “domain controller” is VER_NT_DOMAIN_CONTROLLER
  • “server” is VER_NT_SERVER

Suite

The wSuiteMask member lies in the extension from OSVERSIONINFO to OSVERSIONINFOEX, and even though the extended structure is sought by all exported implementations of IsOS, this member is not interpreted until the builds of version 5.0 from Windows 2000. Earlier builds work instead with a registry value:

The string data Enterprise and DataCenter are then treated as equivalent to “suite is enterprise” and “suite is data center” respectively. As with the version information, the function seeks this registry value only when first called (per-process).

In the following cases, which all involve testing the wSuiteMask member for a single flag, the function does not return TRUE if the flag is set, but instead returns the flag:

• OS_EMBEDDED
• OS_WEBSERVER
• OS_SMALLBUSINESSSERVER
• undocumented case 0x28, only in variation for Windows Server 2003
• undocumented case 0x29, only in variation for Windows Server 2003
• undocumented case 0x2B, only in variation for Windows Server 2003

Variations

The change in OS_WIN2000ORGREATER (0x07) for version 6.0 makes it an alias for the undocumented case 0x04. The latter is in fact the original, dating from versions 4.71 and 4.72 when IsOS was coded in both SHLWAPI and SHDOCVW but not exported from either. The documented case 0x07 does have the merit of a better fit with the chronology of releases: case 0x04 was being used, e.g., by SHDOCVW in Internet Explorer 4.0, to distinguish “Windows 2000 or greater” some two years before Windows 2000 was released.

The change in OS_WIN95_GOLD is presumably a bug fix, the earlier coding having picked an incorrect build number.

Note that the early test for OS_WIN2000TERMINAL was not discarded: it got reused as OS_TERMINALCLIENT.

Hard Coding

For some values of dwOS, version 6.1 returns a hard-coded result that is consistent with the question as understood by previous versions:

It is not known why the function takes for granted that it is running on Windows XP or greater but still tests whether it is running on Windows 2000 or greater.

System Metrics

A handful of cases are answered by calling the standard API function GetSystemMetrics to obtain a particular system metric. Where such cases are described in the preceding table as “evaluation of system metric”, the function returns exactly whatever is returned by GetSystemMetrics, without regard for whether this is TRUE or FALSE.

Availability

The IsOS function is exported from SHLWAPI as ordinal 437 in version 5.0 and higher. Starting with version 6.0 from Windows Vista, the function is also exported by name.

It exists earlier, in both SHLWAPI and SHDOCVW from Internet Explorer 4.0 in 1997, but only as an internal routine.

Documentation Status

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.

However, the function did eventually get documented, apparently later in 2004. This article now conforms to Microsoft’s nomenclature.

Note that Microsoft is hardly rushing to keep its new documentation up to date. The several new cases of dwOS that are supported in Windows XP SP2, Windows Server 2003 SP1 and Windows Vista were not yet documented by Microsoft in the Windows Vista SDK dated January 2007. Some names for these undocumented cases are inferred from the names of subroutines in version 6.1.

A substantial revision of the SDK documentation, apparently done some time during 2008 or 2009, seems intended to describe the function as it behaves in SHLWAPI version 6.1, but notes that “Values are not provided for Windows Vista and Windows 7.” An alternative is suggested. This is just as well. As shown above, some of the “values” introduced since Windows XP SP2 are interpreted very differently depending on which SHLWAPI version is asked. This is no problem for Microsoft’s own use of IsOS in Internet Explorer, since SHLWAPI is linked statically into the IEFRAME executable and Microsoft therefore has complete control of which version of the SHLWAPI code is called. The situation is different for programs that import from SHLWAPI. These may find themselves calling any of a wide variety of SHLWAPI versions. They are therefore exposed to such problems as getting a false positive from OS_WIN7ORGREATER if they happen to be running on certain editions of certain builds of Windows Server 2003. For such reasons, many of these new dwOS values really would be much better left alone. Whether this is why Microsoft does not update its documentation to cover these new values is, of course, not known.