Versões de controle comuns
Este tópico lista as versões disponíveis da biblioteca controle comum (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 seções a seguir.
- números de versões de DLL de controle comum
- tamanhos de estrutura para diferentes versões de controle comum
- 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 por ComCtl32.dll, que incluem todas as versões de 32 bits e 64 bits do Windows. Cada versão sucessiva da DLL dá suporte aos recursos e à API de versões anteriores e adiciona novos recursos.
Como várias versões de ComCtl32.dll foram distribuídas com o Internet Explorer, a versão que está ativa às vezes é diferente da versão que foi enviada 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 com suporte. 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 OSes com suporte.
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 comum
Aprimoramentos contínuos em controles comuns resultaram na necessidade de estender muitas das estruturas. Por esse motivo, o tamanho das estruturas foi alterado entre diferentes versões do Commctrl.h. Como a maioria das estruturas de controle comuns assume um tamanho de estrutura como um dos parâmetros, uma mensagem ou função pode falhar se o tamanho não for reconhecido. Para corrigir isso, as constantes de tamanho da estrutura foram definidas para ajudar a direcionar diferentes versões de ComCtl32.dll. A lista a seguir define as constantes de tamanho da estrutura.
| Constante de tamanho da estrutura | Definição |
|---|---|
| HDITEM_V1_SIZE | O tamanho da estruturaHDITEM na versão 4.0. |
| IMAGELISTDRAWPARAMS_V3_SIZE | O tamanho da estrutura deIMAGELISTDRAWPARAMSna versão 5.9. |
| LVCOLUMN_V1_SIZE | O tamanho da estrutura deLVCOLUMNna versão 4.0. |
| LVGROUP_V5_SIZE | O tamanho da estrutura deLVGROUPna versão 6.0. |
| LVHITTESTINFO_V1_SIZE | O tamanho da estrutura deLVHITTESTINFOna versão 4.0. |
| LVITEM_V1_SIZE | O tamanho da estruturaLVITEMna versão 4.0. |
| LVITEM_V5_SIZE | O tamanho da estrutura deLVITEMna versão 6.0. |
| LVTILEINFO_V5_SIZE | O tamanho da estrutura deLVTILEINFOna versão 6.0. |
| MCHITTESTINFO_V1_SIZE | O tamanho da estrutura deMCHITTESTINFO na versão 4.0. |
| NMLVCUSTOMDRAW_V3_SIZE | O tamanho da estrutura deNMLVCUSTOMDRAWna versão 4.7. |
| NMTTDISPINFO_V1_SIZE | O tamanho da estruturaNMTTDISPINFOna versão 4.0. |
| NMTVCUSTOMDRAW_V3_SIZE | O tamanho da estruturaNMTVCUSTOMDRAWna versão 4.7. |
| PROPSHEETHEADER_V1_SIZE | O tamanho da estruturaPROPSHEETHEADERna versão 4.0. |
| PROPSHEETPAGE_V1_SIZE | O tamanho da estruturaPROPSHEETPAGEna versão 4.0. |
| REBARBANDINFO_V3_SIZE | O tamanho da estruturaREBARBANDINFOna versão 4.7. |
| REBARBANDINFO_V6_SIZE | O tamanho da estruturaREBARBANDINFOna versão 6.0. |
| TTTOOLINFO_V1_SIZE | O tamanho da estruturaTOOLINFOna versão 4.0. |
| TTTOOLINFO_V2_SIZE | O tamanho da estruturaTOOLINFOna versão 4.7. |
| TTTOOLINFO_V3_SIZE | O tamanho da estruturaTOOLINFOna versão 6.0. |
| TVINSERTSTRUCT_V1_SIZE | O tamanho da estruturaTVINSERTSTRUCTna versão 4.0. |
Usando DllGetVersion para determinar o número de versão
A funçãoDllGetVersionpode ser chamada por um aplicativo para determinar qual versão de DLL está presente no sistema.
DllGetVersion retorna uma estrutura DLLVERSIONINFO2. Além das informações fornecidas por meio 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 é uma estrutura de DLLVERSIONINFO, 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 tiver êxito, ele usará uma macro para empacotar os números de versão principal e secundária da estrutura deDLLVERSIONINFOem um DWORD que é retornado ao aplicativo de chamada. Se a DLL não exportar DllGetVersion, a função retornará zero. Você pode modificar a função para lidar com a possibilidade de que DllGetVersion retorne uma estrutura DLLVERSIONINFO2. Nesse caso, use as informações nesse membro ullVersion da estrutura DLLVERSIONINFO2 para comparar versões, números de build e versões do service pack. A macroMAKEDLLVERULL simplifica a tarefa de comparar esses valores com aqueles em ullVersion.
Nota
Usar LoadLibrary incorretamente pode representar riscos à segurança. Consulte a documentação do LoadLibrary para obter informações sobre como carregar corretamente DLLs com diferentes versões do 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;
}
O exemplo de código a seguir mostra como você pode usar GetVersion para testar se ComCtl32.dll é a 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 direcionadas de um arquivo .dll, as 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 versões diferentes da DLL. Consulte Usando os cabeçalhos do Windows para obter uma descrição detalhada dessas macros.
Por exemplo, o nome da macro _WIN32_IE geralmente é 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.
| Versão | Descrição |
|---|---|
| 0x0300 | O aplicativo é compatível com ComCtl32.dll versão 4.70 e posterior. O aplicativo não pode implementar recursos que foram adicionados após a versão 4.70. |
| 0x0400 | O aplicativo é compatível com ComCtl32.dll versão 4.71 e posterior. O aplicativo não pode implementar recursos que foram adicionados após a versão 4.71. |
| 0x0401 | O aplicativo é compatível com ComCtl32.dll versão 4.72 e posterior. O aplicativo não pode implementar recursos que foram adicionados após a versão 4.72. |
| 0x0500 | O aplicativo é compatível com ComCtl32.dll versão 5.80 e posterior. O aplicativo não pode implementar recursos que foram adicionados após a versão 5.80. |
| 0x0501 | O aplicativo é compatível com ComCtl32.dll versão 5.81 e posterior. O aplicativo não pode implementar recursos que foram adicionados após a versão 5.81. |
| 0x0600 | O aplicativo é compatível com ComCtl32.dll versão 6.0 e posterior. O aplicativo não pode implementar recursos que foram adicionados após a versão 6.0. |
Se você não definir a macro _WIN32_IE em seu projeto, ela será definida automaticamente como 0x0500. Para definir um valor diferente, você pode adicionar o seguinte às diretivas do compilador no 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