Versi Kontrol Umum

Topik ini mencantumkan versi pustaka Common Control yang tersedia (ComCtl32.dll), 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
• Ukuran Struktur untuk Versi Kontrol Umum yang Berbeda
• Menggunakan DllGetVersion untuk Menentukan Nomor Versi
• Versi Proyek
• Topik terkait

Nomor Versi DLL Kontrol Umum

Dukungan untuk kontrol umum disediakan oleh ComCtl32.dll, yang mencakup semua 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.dllyang berbeda. Daftar berikut mendefinisikan konstanta ukuran struktur.

Menggunakan DllGetVersion untuk Menentukan Nomor Versi

FungsiDllGetVersion dapat dipanggil oleh aplikasi untuk menentukan versi DLL mana yang ada di 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 sampel berikut GetVersion memuat DLL tertentu dan mencoba memanggil fungsidllGetVersion. Jika berhasil, ia menggunakan makro untuk mengemas nomor versi utama dan minor dari strukturDLLVERSIONINFO 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 struktur DLLVERSIONINFO2 anggota ullVersion untuk membandingkan versi, nomor build, dan rilis paket layanan. MakroMAKEDLLVERULL menyederhanakan tugas membandingkan nilai-nilai ini dengan yang ada di 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;
}

Contoh kode berikut menunjukkan bagaimana Anda dapat menggunakan GetVersion untuk menguji apakah ComCtl32.dll adalah 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.

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>

Topik terkait

Tentang Kontrol Umum