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.

• DLL Version Numbers
• Using DllGetVersion to Determine the Version Number
  • Using DllGetVersion
• Project Versions

DLL Version Numbers

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 the Shell and common controls reference documentation, each programming element is given 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 dating back to Microsoft Internet Explorer 3.0, Microsoft Windows 95, and Microsoft Windows NT 4.0.

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.0. New versions of Commctl.dll were shipped with all Internet Explorer releases. Shlwapi.dll shipped with Internet Explorer 4.0, so its initial version number here 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. No other versions of Internet Explorer update Shell32.dll. 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 and Windows Me, along with version 5.0 of Shlwapi.dll, and version 5.81 of Comctl32.dll.

Note 4: ComCtl32.dll version 6 is not redistributable. If you want your application to use ComCtl32.dll version 6, you must add an application manifest that indicates that version 6 should be used if it is available.

Using DllGetVersion to Determine the Version Number

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.

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 might instead return a DLLVERSIONINFO2 structure. This structure contains the hotfix number that identifies the service pack and provides a more robust way to compare version numbers than DLLVERSIONINFO. Because the first member of DLLVERSIONINFO2 is a DLLVERSIONINFO structure, the new structure is backward-compatible.

Using DllGetVersion

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 Windows 2000 and later systems, you can modify the function to handle the possibility that DllGetVersion returns a DLLVERSIONINFO2 structure. If so, use the information in the 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.

#define PACKVERSION(major,minor) MAKELONG(minor,major)
DWORD GetDllVersion(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.cbSize = sizeof(dvi);

            hr = (*pDllGetVersion)(&dvi);

            if(SUCCEEDED(hr))
            {
               dwVersion = PACKVERSION(dvi.dwMajorVersion, dvi.dwMinorVersion);
            }
        }

        FreeLibrary(hinstDll);
    }
    return dwVersion;
}

The following code example 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.
}

Project 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 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.

If you do not define this 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 including the Shell and Common Control header files; substitute the desired version number for 0x0400.

#define _WIN32_IE 0x0400
#include <commctrl.h>