Versions courantes du contrôle

Cette rubrique répertorie les versions disponibles de la bibliothèque Common Control (ComCtl32.dll), explique comment identifier la version utilisée par votre application et explique comment cibler votre application pour une version spécifique.

Cette rubrique contient les sections suivantes.

• numéros de versions de DLL de contrôle commun
• tailles de structure pour différentes versions de contrôle courantes
• à l’aide de DllGetVersion pour déterminer le numéro de version
• versions de projet
• rubriques connexes

Numéros de versions de DLL de contrôle commun

La prise en charge des contrôles courants est fournie par ComCtl32.dll, que toutes les versions 32 bits et 64 bits de Windows incluent. Chaque version successive de la DLL prend en charge les fonctionnalités et l’API des versions antérieures et ajoute de nouvelles fonctionnalités.

Étant donné que différentes versions de ComCtl32.dll ont été distribuées avec Internet Explorer, la version active est parfois différente de la version fournie avec le système d’exploitation. Par conséquent, votre application doit déterminer directement la version de ComCtl32.dll présente.

Dans la documentation de référence des contrôles courants, de nombreux éléments de programmation spécifient un numéro de version DE DLL minimum pris en charge. Ce numéro de version indique que l’élément de programmation est implémenté dans cette version et les versions ultérieures de la DLL, sauf indication contraire. Si aucun numéro de version n’est spécifié, l’élément de programmation est implémenté dans toutes les versions existantes de la DLL.

Le tableau suivant présente les différentes versions de DLL et la façon dont elles ont été distribuées sur les systèmes d’exploitation pris en charge.

ComCtl32.dll

Version

Plateforme de distribution

5.81

Microsoft Internet Explorer 5.01, Microsoft Internet Explorer 5.5 et Microsoft Internet Explorer 6

5.82

Windows Server 2003, Windows Vista, Windows Server 2008 et Windows 7

6.0

Windows Server 2003

6.10

Windows Vista, Windows Server 2008 et Windows 7

Tailles de structure pour différentes versions de contrôle courantes

Des améliorations continues apportées aux contrôles communs ont entraîné la nécessité d’étendre la plupart des structures. Pour cette raison, la taille des structures a changé entre différentes versions de Commctrl.h. Étant donné que la plupart des structures de contrôle courantes prennent une taille de structure comme l’un des paramètres, un message ou une fonction peut échouer si la taille n’est pas reconnue. Pour remédier à cela, des constantes de taille de structure ont été définies pour aider à cibler différentes versions de ComCtl32.dll. La liste suivante définit les constantes de taille de structure.

Utilisation de DllGetVersion pour déterminer le numéro de version

La fonction DllGetVersion peut être appelée par une application pour déterminer quelle version DLL est présente sur le système.

DllGetVersion retourne une structure de DLLVERSIONINFO2. En plus des informations fournies via DLLVERSIONINFO, DLLVERSIONINFO2 fournit également le numéro de correctif logiciel qui identifie le dernier Service Pack installé, qui offre un moyen plus robuste de comparer les numéros de version. Étant donné que le premier membre de DLLVERSIONINFO2 est une structure DLLVERSIONINFO, la structure ultérieure est rétrocompatible.

L’exemple de fonction suivant GetVersion charge une DLL spécifiée et tente d’appeler sa fonction DllGetVersion. Si elle réussit, elle utilise une macro pour packer les numéros de version principaux et secondaires de la structure DLLVERSIONINFOdans une DWORD retournée à l’application appelante. Si la DLL n’exporte pas DllGetVersion, la fonction retourne zéro. Vous pouvez modifier la fonction pour gérer la possibilité que DllGetVersion retourne une structure DLLVERSIONINFO2. Si c’est le cas, utilisez les informations de cette structure DLLVERSIONINFO2membre ullVersion pour comparer les versions, les numéros de build et les versions de Service Pack. La macro MAKEDLLVERULL simplifie la tâche de comparer ces valeurs à celles de ullVersion.

#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;
}

L’exemple de code suivant montre comment utiliser GetVersion pour tester si ComCtl32.dll est version 6.0 ou ultérieure.

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

Versions de projet

Pour vous assurer que votre application est compatible avec différentes versions ciblées d’un fichier .dll, les macros de version sont présentes dans les fichiers d’en-tête. Ces macros sont utilisées pour définir, exclure ou redéfinir certaines définitions pour différentes versions de la DLL. Consultez Utilisation des en-têtes Windows pour obtenir une description détaillée de ces macros.

Par exemple, le nom de macro _WIN32_IE est généralement trouvé dans les en-têtes plus anciens. Vous êtes responsable de la définition de la macro en tant que nombre hexadécimal. Ce numéro de version définit la version cible de l’application qui utilise la DLL. Le tableau suivant présente les numéros de version disponibles et l’effet que chacun a sur votre application.

Si vous ne définissez pas la macro _WIN32_IE dans votre projet, elle est automatiquement définie comme 0x0500. Pour définir une valeur différente, vous pouvez ajouter les instructions suivantes aux directives du compilateur dans votre fichier make ; remplacez le numéro de version souhaité par 0x0400.

/D _WIN32_IE=0x0400

Une autre méthode consiste à ajouter une ligne similaire à ce qui suit dans votre code source avant d’inclure les fichiers d’en-tête Shell. Remplacez le numéro de version souhaité par 0x0400.

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

Rubriques connexes

À propos des contrôles courants