Common Control Versions
This topic lists the available versions of the Common Control library (ComCtl32.dll), describes how to identify the version that your application is using, and explains how to target your application for a specific version.
This topic contains the following sections.
- Common Control DLL Versions Numbers
- Structure Sizes for Different Common Control Versions
- Using DllGetVersion to Determine the Version Number
- Project Versions
- Related topics
Common Control DLL Versions Numbers
Support for common controls is provided by ComCtl32.dll, which all 32-bit and 64-bit versions of Windows include. Each successive version of the DLL supports the features and API of earlier versions and adds new features.
Because various versions of ComCtl32.dll were distributed with Internet Explorer, the version that is active is sometimes different from the version that was shipped with the operating system. Therefore, your application must directly determine which version of ComCtl32.dll is present.
In the common controls reference documentation, many programming elements specify a minimum supported DLL version number. This version number indicates that the programming element is implemented in that version and subsequent versions of the DLL unless otherwise specified. If no version number is specified, the programming element is implemented in all existing versions of the DLL.
The following table outlines the different DLL versions and how they were distributed on supported OSes.
ComCtl32.dll
Version
Distribution Platform
5.81
Microsoft Internet Explorer 5.01, Microsoft Internet Explorer 5.5, and Microsoft Internet Explorer 6
5.82
Windows Server 2003, Windows Vista, Windows Server 2008, and Windows 7
6.0
Windows Server 2003
6.10
Windows Vista, Windows Server 2008, and Windows 7
Structure Sizes for Different Common Control Versions
Ongoing enhancements to common controls have resulted in the need to extend many of the structures. For this reason, the size of the structures has changed between different versions of Commctrl.h. Because most of the common control structures take a structure size as one of the parameters, a message or function can fail if the size is not recognized. To remedy this, structure size constants have been defined to aid in targeting different version of ComCtl32.dll. The following list defines the structure size constants.
| Structure Size Constant | Definition |
|---|---|
| HDITEM_V1_SIZE | The size of the HDITEM structure in version 4.0. |
| IMAGELISTDRAWPARAMS_V3_SIZE | The size of the IMAGELISTDRAWPARAMS structure in version 5.9. |
| LVCOLUMN_V1_SIZE | The size of the LVCOLUMN structure in version 4.0. |
| LVGROUP_V5_SIZE | The size of the LVGROUP structure in version 6.0. |
| LVHITTESTINFO_V1_SIZE | The size of the LVHITTESTINFO structure in version 4.0. |
| LVITEM_V1_SIZE | The size of the LVITEM structure in version 4.0. |
| LVITEM_V5_SIZE | The size of the LVITEM structure in version 6.0. |
| LVTILEINFO_V5_SIZE | The size of the LVTILEINFO structure in version 6.0. |
| MCHITTESTINFO_V1_SIZE | The size of the MCHITTESTINFO structure in version 4.0. |
| NMLVCUSTOMDRAW_V3_SIZE | The size of the NMLVCUSTOMDRAW structure in version 4.7. |
| NMTTDISPINFO_V1_SIZE | The size of the NMTTDISPINFO structure in version 4.0. |
| NMTVCUSTOMDRAW_V3_SIZE | The size of the NMTVCUSTOMDRAW structure in version 4.7. |
| PROPSHEETHEADER_V1_SIZE | The size of the PROPSHEETHEADER structure in version 4.0. |
| PROPSHEETPAGE_V1_SIZE | The size of the PROPSHEETPAGE structure in version 4.0. |
| REBARBANDINFO_V3_SIZE | The size of the REBARBANDINFO structure in version 4.7. |
| REBARBANDINFO_V6_SIZE | The size of the REBARBANDINFO structure in version 6.0. |
| TTTOOLINFO_V1_SIZE | The size of the TOOLINFO structure in version 4.0. |
| TTTOOLINFO_V2_SIZE | The size of the TOOLINFO structure in version 4.7. |
| TTTOOLINFO_V3_SIZE | The size of the TOOLINFO structure in version 6.0. |
| TVINSERTSTRUCT_V1_SIZE | The size of the TVINSERTSTRUCT structure in version 4.0. |
Using DllGetVersion to Determine the Version Number
The DllGetVersion function can be called by an application to determine which DLL version is present on the system.
DllGetVersion returns a DLLVERSIONINFO2 structure. In addition to the information provided through DLLVERSIONINFO, DLLVERSIONINFO2 also provides the hotfix number that identifies the latest installed service pack, which provides a more robust way to compare version numbers. Because the first member of DLLVERSIONINFO2 is a DLLVERSIONINFO structure, the later structure is backward-compatible.
The following sample function GetVersion loads a specified DLL and attempts to call its DllGetVersion function. If successful, it uses a macro to pack the major and minor version numbers from the DLLVERSIONINFO structure into a DWORD that is returned to the calling application. If the DLL does not export DllGetVersion, the function returns zero. You can modify the function to handle the possibility that DllGetVersion returns a DLLVERSIONINFO2 structure. If so, use the information in that DLLVERSIONINFO2 structure's ullVersion member to compare versions, build numbers, and service pack releases. The MAKEDLLVERULL macro simplifies the task of comparing these values to those in ullVersion.
Note
Using LoadLibrary incorrectly can pose security risks. Refer to the LoadLibrary documentation for information on how to correctly load DLLs with different versions of Windows.
#include "stdafx.h"
#include "windows.h"
#include "windef.h"
#include "winbase.h"
#include "shlwapi.h"
#define PACKVERSION(major,minor) MAKELONG(minor,major)
DWORD GetVersion(LPCTSTR lpszDllName)
{
HINSTANCE hinstDll;
DWORD dwVersion = 0;
// For security purposes, LoadLibrary should be provided with a fully qualified
// path to the DLL. The lpszDllName variable should be tested to ensure that it
// is a fully qualified path before it is used.
hinstDll = LoadLibrary(lpszDllName);
if(hinstDll)
{
DLLGETVERSIONPROC pDllGetVersion;
pDllGetVersion = (DLLGETVERSIONPROC)GetProcAddress(hinstDll, "DllGetVersion");
// Because some DLLs might not implement this function, you must test for
// it explicitly. Depending on the particular DLL, the lack of a DllGetVersion
// function can be a useful indicator of the version.
if(pDllGetVersion)
{
DLLVERSIONINFO dvi;
HRESULT hr;
ZeroMemory(&dvi, sizeof(dvi));
dvi.info1.cbSize = sizeof(dvi);
hr = (*pDllGetVersion)(&dvi);
if(SUCCEEDED(hr))
{
dwVersion = PACKVERSION(dvi.info1.dwMajorVersion, dvi.info1.dwMinorVersion);
}
}
FreeLibrary(hinstDll);
}
return dwVersion;
}
The following code example shows how you can use GetVersion to test whether ComCtl32.dll is version 6.0 or later.
LPCTSTR lpszDllName = L"C:\\Windows\\System32\\ComCtl32.dll";
DWORD dwVer = GetVersion(lpszDllName);
DWORD dwTarget = PACKVERSION(6,0);
if(dwVer >= dwTarget)
{
// This version of ComCtl32.dll is version 6.0 or later.
}
else
{
// Proceed knowing that version 6.0 or later additions are not available.
// Use an alternate approach for older the DLL version.
}
Project Versions
To ensure that your application is compatible with different targeted versions of a .dll file, version macros are present in the header files. These macros are used to define, exclude, or redefine certain definitions for different versions of the DLL. See Using the Windows Headers for an in-depth description of these macros.
For example, the macro name _WIN32_IE is commonly found in older headers. You are responsible for defining the macro as a hexadecimal number. This version number defines the target version of the application that is using the DLL. The following table shows the available version numbers and the effect each has on your application.
| Version | Description |
|---|---|
| 0x0300 | The application is compatible with ComCtl32.dll version 4.70 and later. The application cannot implement features that were added after version 4.70. |
| 0x0400 | The application is compatible with ComCtl32.dll version 4.71 and later. The application cannot implement features that were added after version 4.71. |
| 0x0401 | The application is compatible with ComCtl32.dll version 4.72 and later. The application cannot implement features that were added after version 4.72. |
| 0x0500 | The application is compatible with ComCtl32.dll version 5.80 and later. The application cannot implement features that were added after version 5.80. |
| 0x0501 | The application is compatible with ComCtl32.dll version 5.81 and later. The application cannot implement features that were added after version 5.81. |
| 0x0600 | The application is compatible with ComCtl32.dll version 6.0 and later. The application cannot implement features that were added after version 6.0. |
If you do not define the _WIN32_IE macro in your project, it is automatically defined as 0x0500. To define a different value, you can add the following to the compiler directives in your make file; substitute the desired version number for 0x0400.
/D _WIN32_IE=0x0400
Another method is to add a line similar to the following in your source code before you include the Shell header files. Substitute the desired version number for 0x0400.
#define _WIN32_IE 0x0400
#include <commctrl.h>
Related topics