Bagikan melalui


Versi Kontrol Umum

Topik ini mencantumkan versi pustaka Common Control (ComCtl32.dll) yang tersedia, menjelaskan cara mengidentifikasi versi yang digunakan aplikasi Anda, dan menjelaskan cara menargetkan aplikasi Anda untuk versi tertentu.

Topik ini berisi bagian berikut.

Nomor Versi DLL Kontrol Umum

Dukungan untuk kontrol umum disediakan oleh ComCtl32.dll, yang mencakup windows versi 32-bit dan 64-bit. Setiap versi DLL berturut-turut mendukung fitur dan API dari versi sebelumnya dan menambahkan fitur baru.

Karena berbagai versi ComCtl32.dll didistribusikan dengan Internet Explorer, versi yang aktif terkadang berbeda dari versi yang dikirim dengan sistem operasi. Oleh karena itu, aplikasi Anda harus secara langsung menentukan versi ComCtl32.dll mana yang ada.

Dalam dokumentasi referensi kontrol umum, banyak elemen pemrograman menentukan nomor versi DLL minimum yang didukung. Nomor versi ini menunjukkan bahwa elemen pemrograman diimplementasikan dalam versi tersebut dan versi DLL berikutnya kecuali ditentukan lain. Jika tidak ada nomor versi yang ditentukan, elemen pemrograman diimplementasikan di semua versi DLL yang ada.

Tabel berikut menguraikan versi DLL yang berbeda dan bagaimana mereka didistribusikan pada OS yang didukung.

ComCtl32.dll

Versi

Platform Distribusi

5.81

Microsoft Internet Explorer 5.01, Microsoft Internet Explorer 5.5, dan Microsoft Internet Explorer 6

5.82

Windows Server 2003, Windows Vista, Windows Server 2008, dan Windows 7

6.0

Windows Server 2003

6.10

Windows Vista, Windows Server 2008, dan Windows 7

 

Ukuran Struktur untuk Versi Kontrol Umum yang Berbeda

Penyempurnaan yang sedang berlangsung pada kontrol umum telah mengakibatkan kebutuhan untuk memperluas banyak struktur. Untuk alasan ini, ukuran struktur telah berubah antara versi Commctrl.h yang berbeda. Karena sebagian besar struktur kontrol umum mengambil ukuran struktur sebagai salah satu parameter, pesan atau fungsi dapat gagal jika ukurannya tidak dikenali. Untuk memperbaiki hal ini, konstanta ukuran struktur telah didefinisikan untuk membantu menargetkan versi ComCtl32.dll yang berbeda. Daftar berikut mendefinisikan konstanta ukuran struktur.

Konstanta Ukuran Struktur Definisi
HDITEM_V1_SIZE Ukuran struktur HDITEM dalam versi 4.0.
IMAGELISTDRAWPARAMS_V3_SIZE Ukuran struktur IMAGELISTDRAWPARAMS dalam versi 5.9.
LVCOLUMN_V1_SIZE Ukuran struktur LVCOLUMN dalam versi 4.0.
LVGROUP_V5_SIZE Ukuran struktur LVGROUP dalam versi 6.0.
LVHITTESTINFO_V1_SIZE Ukuran struktur LVHITTESTINFO dalam versi 4.0.
LVITEM_V1_SIZE Ukuran struktur LVITEM dalam versi 4.0.
LVITEM_V5_SIZE Ukuran struktur LVITEM dalam versi 6.0.
LVTILEINFO_V5_SIZE Ukuran struktur LVTILEINFO dalam versi 6.0.
MCHITTESTINFO_V1_SIZE Ukuran struktur MCHITTESTINFO dalam versi 4.0.
NMLVCUSTOMDRAW_V3_SIZE Ukuran struktur NMLVCUSTOMDRAW dalam versi 4.7.
NMTTDISPINFO_V1_SIZE Ukuran struktur NMTTDISPINFO dalam versi 4.0.
NMTVCUSTOMDRAW_V3_SIZE Ukuran struktur NMTVCUSTOMDRAW dalam versi 4.7.
PROPSHEETHEADER_V1_SIZE Ukuran struktur PROPSHEETHEADER dalam versi 4.0.
PROPSHEETPAGE_V1_SIZE Ukuran struktur PROPSHEETPAGE dalam versi 4.0.
REBARBANDINFO_V3_SIZE Ukuran struktur REBARBANDINFO dalam versi 4.7.
REBARBANDINFO_V6_SIZE Ukuran struktur REBARBANDINFO dalam versi 6.0.
TTTOOLINFO_V1_SIZE Ukuran struktur TOOLINFO dalam versi 4.0.
TTTOOLINFO_V2_SIZE Ukuran struktur TOOLINFO dalam versi 4.7.
TTTOOLINFO_V3_SIZE Ukuran struktur TOOLINFO dalam versi 6.0.
TVINSERTSTRUCT_V1_SIZE Ukuran struktur TVINSERTSTRUCT dalam versi 4.0.

 

Menggunakan DllGetVersion untuk Menentukan Nomor Versi

Fungsi DllGetVersion dapat dipanggil oleh aplikasi untuk menentukan versi DLL mana yang ada pada sistem.

DllGetVersion mengembalikan struktur DLLVERSIONINFO2 . Selain informasi yang diberikan melalui DLLVERSIONINFO, DLLVERSIONINFO2 juga menyediakan nomor perbaikan yang mengidentifikasi paket layanan terbaru yang diinstal, yang menyediakan cara yang lebih kuat untuk membandingkan nomor versi. Karena anggota pertama DLLVERSIONINFO2 adalah struktur DLLVERSIONINFO , struktur yang lebih baru kompatibel mundur.

Fungsi GetVersion sampel berikut memuat DLL tertentu dan mencoba memanggil fungsi DllGetVersion-nya. Jika berhasil, ia menggunakan makro untuk mengemas nomor versi utama dan minor dari struktur DLLVERSIONINFO ke dalam DWORD yang dikembalikan ke aplikasi panggilan. Jika DLL tidak mengekspor DllGetVersion, fungsi mengembalikan nol. Anda dapat memodifikasi fungsi untuk menangani kemungkinan DllGetVersion mengembalikan struktur DLLVERSIONINFO2. Jika demikian, gunakan informasi dalam anggota ullVersion struktur DLLVERSIONINFO2 tersebut untuk membandingkan versi, nomor build, dan rilis paket layanan. Makro MAKEDLLVERULL menyederhanakan tugas membandingkan nilai-nilai ini dengan yang ada di ullVersion.

Catatan

Menggunakan LoadLibrary salah dapat menimbulkan risiko keamanan. Lihat dokumentasi LoadLibrary untuk informasi tentang cara memuat DLL dengan benar dengan versi Windows yang berbeda.

 

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

Contoh kode berikut menunjukkan bagaimana Anda dapat menggunakan GetVersion untuk menguji apakah ComCtl32.dll versi 6.0 atau yang lebih baru.

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

Versi Proyek

Untuk memastikan bahwa aplikasi Anda kompatibel dengan versi file .dll yang ditargetkan yang berbeda, makro versi ada di file header. Makro ini digunakan untuk menentukan, mengecualikan, atau menentukan ulang definisi tertentu untuk versi DLL yang berbeda. Lihat Menggunakan Header Windows untuk deskripsi mendalam tentang makro ini.

Misalnya, nama makro _WIN32_IE umumnya ditemukan di header yang lebih lama. Anda bertanggung jawab untuk mendefinisikan makro sebagai angka heksadesimal. Nomor versi ini menentukan versi target aplikasi yang menggunakan DLL. Tabel berikut menunjukkan nomor versi yang tersedia dan efek yang dimiliki masing-masing pada aplikasi Anda.

Versi Deskripsi
0x0300 Aplikasi ini kompatibel dengan ComCtl32.dll versi 4.70 dan yang lebih baru. Aplikasi tidak dapat menerapkan fitur yang ditambahkan setelah versi 4.70.
0x0400 Aplikasi ini kompatibel dengan ComCtl32.dll versi 4.71 dan yang lebih baru. Aplikasi tidak dapat menerapkan fitur yang ditambahkan setelah versi 4.71.
0x0401 Aplikasi ini kompatibel dengan ComCtl32.dll versi 4.72 dan yang lebih baru. Aplikasi tidak dapat menerapkan fitur yang ditambahkan setelah versi 4.72.
0x0500 Aplikasi ini kompatibel dengan ComCtl32.dll versi 5.80 dan yang lebih baru. Aplikasi tidak dapat menerapkan fitur yang ditambahkan setelah versi 5.80.
0x0501 Aplikasi ini kompatibel dengan ComCtl32.dll versi 5.81 dan yang lebih baru. Aplikasi tidak dapat menerapkan fitur yang ditambahkan setelah versi 5.81.
0x0600 Aplikasi ini kompatibel dengan ComCtl32.dll versi 6.0 dan yang lebih baru. Aplikasi tidak dapat menerapkan fitur yang ditambahkan setelah versi 6.0.

 

Jika Anda tidak menentukan makro _WIN32_IE dalam proyek Anda, makro tersebut secara otomatis didefinisikan sebagai 0x0500. Untuk menentukan nilai yang berbeda, Anda dapat menambahkan yang berikut ini ke arahan kompilator dalam file buatan Anda; ganti nomor versi yang diinginkan untuk 0x0400.

/D _WIN32_IE=0x0400

Metode lain adalah menambahkan baris yang mirip dengan yang berikut ini dalam kode sumber Anda sebelum Anda menyertakan file header Shell. Ganti nomor versi yang diinginkan untuk 0x0400.

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

Tentang Kontrol Umum