This section describes how to determine which version of the Shell or Common Controls DLLs your application is running on and how to target your application for a specific version.
All but a handful of the programming elements discussed in the Shell and Common Controls documentation are contained in three DLLs: Comctl32.dll, Shell32.dll, and Shlwapi.dll. Because of ongoing enhancements, different versions of these DLLs implement different features. Throughout this document, programming elements are marked with a version number. This version number indicates that the programming element was first implemented in that version and will also be found in all subsequent versions of the DLL. If no version number is specified, the programming element is implemented in all versions. The following table outlines the different DLL versions, and how they were distributed.
| Version | DLL | Distribution Platform |
|---|---|---|
| 4.00 | All | Microsoft® Windows® 95/Windows NT® 4.0. |
| 4.70 | All | Microsoft® Internet Explorer 3.x. |
| 4.71 | All | Microsoft® Internet Explorer 4.0 (see note 2). |
| 4.72 | All | Microsoft® Internet Explorer 4.01 and Windows® 98 (see note 2). |
| 5.00 | Shlwapi.dll | Microsoft® Internet Explorer 5 (see note 3). |
| 5.00 | Shell32.dll | Microsoft® Windows® 2000. (see note 3). |
| 5.80 | Comctl32.dll | Microsoft® Internet Explorer 5 (see note 3). |
| 5.81 | Comctl32.dll | Microsoft® Windows 2000(see note 3). |
Note 1: The 4.00 versions of Shell32.dll and Comctl32.dll are found on the original versions of Windows 95 and Windows NT 4. New versions of Commctl.dll were shipped with all Internet Explorer releases. Shlwapi.dll first shipped with Internet Explorer 4.0, so its first version number is 4.71. The Shell was not updated with the Internet Explorer 3.0 release, so Shell32.dll does not have a version 4.70. While Shell32.dll versions 4.71 and 4.72 were shipped with the corresponding Internet Explorer releases, they were not necessarily installed (see Note 2). For subsequent releases, the version numbers for the three DLLs are not identical. In general, you should assume that all three DLLs may have different version numbers, and test each one separately.
Note 2: All systems with Internet Explorer 4.0 or 4.01 will have the associated version of Comctl32.dll and Shlwapi.dll (4.71 or 4.72, respectively). However, for systems prior to Windows 98, Internet Explorer 4.0 and 4.01 can be installed with or without the integrated shell. If they are installed with the integrated shell, the associated version of Shell32.dll will be installed. If they are installed without the integrated shell, Shell32.dll is not updated. In other words, the presence of version 4.71 or 4.72 of Comctl32.dll or Shlwapi.dll on a system does not guarantee that Shell32.dll has the same version number. All Windows 98 systems have version 4.72 of Shell32.dll.
Note 3:Version 5.80 of Comctl32.dll and version 5.0 of Shlwapi.dll are distributed with Internet Explorer 5. They will be found on all systems on which Internet Explorer 5 is installed, except Windows 2000. Internet Explorer 5 does not update the Shell, so version 5.0 of Shell32.dll will not be found on Windows NT, Windows 95, or Windows 98 systems. Version 5.0 of Shell32.dll will be distributed with Windows 2000, along with version 5.0 of Shlwapi.dll, and version 5.81 of Comctl32.dll.
Starting with version 4.71, the Shell and Common Controls DLLs, among others, began exporting DllGetVersion. This function can be called by an application to determine which DLL version is present on the system. It returns a structure that contains version information.
Note: DLL's do not necessarily export DllGetVersion. Always test for it before attempting to use it.
For systems earlier than Windows 2000, DllGetVersion returns a DLLVERSIONINFO structure that contains the major and minor version numbers, the build number, and a platform ID. For Windows 2000 and later systems, DllGetVersion may instead return a DLLVERSIONINFO2 structure. This structure contains the QFE number that identifies the service pack and provides a more robust way to compare version numbers than DLLVERSIONINFO. Since the first member of DLLVERSIONINFO2 is a DLLVERSIONINFO structure, the new structure is backward-compatible.
The following sample function 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. With Window 2000 and later systems, you can modify the function to handle the possibility that DllGetVersion returns a DLLVERSIONINFO2 structure. If so, use the information contained in the ullVersion member to compare versions, build numbers, and service pack releases. The MAKEDLLVERULL macro is designed to simplify the task of comparing these values to those contained in ullVersion.
#define PACKVERSION(major,minor) MAKELONG(minor,major)
DWORD GetDllVersion(LPCTSTR lpszDllName)
{
HINSTANCE hinstDll;
DWORD dwVersion = 0;
hinstDll = LoadLibrary(lpszDllName);
if(hinstDll)
{
DLLGETVERSIONPROC pDllGetVersion;
pDllGetVersion = (DLLGETVERSIONPROC) GetProcAddress(hinstDll, "DllGetVersion");
/*Because some DLLs may not implement this function, you
*must test for it explicitly. Depending on the particular
*DLL, the lack of a DllGetVersion function may
*be a useful indicator of the version.
*/
if(pDllGetVersion)
{
DLLVERSIONINFO dvi;
HRESULT hr;
ZeroMemory(&dvi, sizeof(dvi));
dvi.cbSize = sizeof(dvi);
hr = (*pDllGetVersion)(&dvi);
if(SUCCEEDED(hr))
{
dwVersion = PACKVERSION(dvi.dwMajorVersion, dvi.dwMinorVersion);
}
}
FreeLibrary(hinstDll);
}
return dwVersion;
}
The following code fragment illustrates how you can use GetDllVersion to test if Comctl32.dll is version 4.71 or later.
if(GetDllVersion(TEXT("comctl32.dll")) >= PACKVERSION(4,71))
{
//Proceed
}
else
{
//Use an alternate approach for older DLL versions
}
To ensure that your application is compatible with different targeted versions of Comctl32.dll and Shell32.dll, a version macro was added to the header files. This macro is used to define, exclude, or redefine certain definitions for different versions of the DLL. The macro name is _WIN32_IE and you, the developer, 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 are the currently available version numbers and the effect each has on your application.
| Version | Description |
|---|---|
| 0x0200 | The application will be compatible with Comctl32.dll and Shell32.dll version 4.00 and later. The application will not be able to implement features that were added after version 4.00 of Comctl32.dll. |
| 0x0300 | The application will be compatible with Comctl32.dll and Shell32.dll version 4.70 and later. The application will not be able to implement features that were added after version 4.70 of Comctl32.dll. |
| 0x0400 | The application will be compatible with Comctl32.dll and Shell32.dll version 4.71 and later. The application will not be able to implement features that were added after version 4.71 of Comctl32.dll. |
| 0x0401 | The application will be compatible with Comctl32.dll and Shell32.dll version 4.72 and later. The application will not be able to implement features that were added after version 4.72 of Comctl32.dll. |
| 0x0500 | The application will be compatible with Comctl32.dll version 5.80 and later, and Shell32.dll and Shlwapi.dll version 5.0 and later. The application will not be able to implement features that were added after version 5.80 of Comctl32.dll or version 5.0 of Shell32.dll and Shlwapi.dll. |
| 0x0501 | The application will be compatible with Comctl32.dll version 5.81 and later and Shell32.dll and Shlwapi.dll version 5.0 and later. The application will not be able to implement features that were added after version 5.81 of Comctl32.dll or version 5.0 of Shell32.dll and Shlwapi.dll. |
If you do not define this macro in your project, it will automatically be 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 including the Shell and Common Control header files (substitute the desired version number for 0x0400). For example:
#define _WIN32_IE 0x0400 #include <commctrl.h>
To get the most recent version of the Shell and Common Controls DLLs, download and install Internet Explorer.