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
- 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 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>
Topik terkait