Versões de controle comuns

Este tópico lista as versões disponíveis da biblioteca Common Control (ComCtl32.dll), descreve como identificar a versão que seu aplicativo está usando e explica como direcionar seu aplicativo para uma versão específica.

Este tópico contém as seguintes seções.

• números de versões de DLL de controle comum
• tamanhos de estrutura para diferentes versões de controle comuns
• usando DllGetVersion para determinar o número de versão
• versões do projeto
• Tópicos relacionados

Números de versões de DLL de controle comum

O suporte para controles comuns é fornecido pelo ComCtl32.dll, que todas as versões de 32 bits e 64 bits do Windows incluem. Cada versão sucessiva da DLL suporta os recursos e a API de versões anteriores e adiciona novos recursos.

Como várias versões do ComCtl32.dll foram distribuídas com o Internet Explorer, a versão ativa às vezes é diferente da versão fornecida com o sistema operacional. Portanto, seu aplicativo deve determinar diretamente qual versão do ComCtl32.dll está presente.

Na documentação de referência de controles comuns, muitos elementos de programação especificam um número mínimo de versão de DLL suportado. Esse número de versão indica que o elemento de programação é implementado nessa versão e nas versões subsequentes da DLL, a menos que especificado de outra forma. Se nenhum número de versão for especificado, o elemento de programação será implementado em todas as versões existentes da DLL.

A tabela a seguir descreve as diferentes versões de DLL e como elas foram distribuídas em sistemas operacionais suportados.

ComCtl32.dll

Versão

Plataforma de Distribuição

5.81

Microsoft Internet Explorer 5.01, Microsoft Internet Explorer 5.5 e Microsoft Internet Explorer 6

5.82

Windows Server 2003, Windows Vista, Windows Server 2008 e Windows 7

6.0

Windows Server 2003

6.10

Windows Vista, Windows Server 2008 e Windows 7

Tamanhos de estrutura para diferentes versões de controle comuns

As melhorias em curso dos controlos comuns resultaram na necessidade de alargar muitas das estruturas. Por esta razão, o tamanho das estruturas mudou entre as diferentes versões do Commctrl.h. Como a maioria das estruturas de controle comuns tem um tamanho de estrutura como um dos parâmetros, uma mensagem ou função pode falhar se o tamanho não for reconhecido. Para remediar esta situação, foram definidas constantes de tamanho da estrutura para ajudar a visar diferentes versões do ComCtl32.dll. A lista a seguir define as constantes de tamanho da estrutura.

Usando DllGetVersion para determinar o número da versão

A função DllGetVersion pode ser chamada por um aplicativo para determinar qual versão DLL está presente no sistema.

DllGetVersion retorna uma estrutura DLLVERSIONINFO2. Além das informações fornecidas através DLLVERSIONINFO, DLLVERSIONINFO2 também fornece o número de hotfix que identifica o service pack instalado mais recente, que fornece uma maneira mais robusta de comparar números de versão. Como o primeiro membro do DLLVERSIONINFO2 é um DLLVERSIONINFO estrutura, a estrutura posterior é compatível com versões anteriores.

A função de exemplo a seguir GetVersion carrega uma DLL especificada e tenta chamar sua funçãoDllGetVersion. Se for bem-sucedido, ele usa uma macro para empacotar os números de versão principal e secundária da estruturaDLLVERSIONINFOem um DWORD que é retornado para o aplicativo de chamada. Se a DLL não exportar DllGetVersion, a função retornará zero. Você pode modificar a função para manipular a possibilidade de que DllGetVersion retorna uma estrutura DLLVERSIONINFO2. Em caso afirmativo, use as informações no membro do ullVersion da estrutura de DLLVERSIONINFO2 para comparar versões, números de compilação e versões de service pack. O macro MAKEDLLVERULL simplifica a tarefa de comparar esses valores com aqueles em 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;
}

O exemplo de código a seguir mostra como você pode usar GetVersion para testar se ComCtl32.dll é versão 6.0 ou posterior.

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

Versões do projeto

Para garantir que seu aplicativo seja compatível com diferentes versões de destino de um arquivo .dll, macros de versão estão presentes nos arquivos de cabeçalho. Essas macros são usadas para definir, excluir ou redefinir determinadas definições para diferentes versões da DLL. Consulte Usando o de Cabeçalhos do Windows para obter uma descrição detalhada dessas macros.

Por exemplo, o nome da macro _WIN32_IE é comumente encontrado em cabeçalhos mais antigos. Você é responsável por definir a macro como um número hexadecimal. Esse número de versão define a versão de destino do aplicativo que está usando a DLL. A tabela a seguir mostra os números de versão disponíveis e o efeito que cada um tem em seu aplicativo.

Se você não definir a macro _WIN32_IE em seu projeto, ela será automaticamente definida como 0x0500. Para definir um valor diferente, você pode adicionar o seguinte às diretivas do compilador em seu arquivo make; Substitua o número de versão desejado por 0x0400.

/D _WIN32_IE=0x0400

Outro método é adicionar uma linha semelhante à seguinte no código-fonte antes de incluir os arquivos de cabeçalho do Shell. Substitua o número de versão desejado por 0x0400.

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

Tópicos relacionados

Sobre controles comuns