Fungsi LoadLibraryExA (libloaderapi.h)
Memuat modul yang ditentukan ke ruang alamat proses panggilan. Modul yang ditentukan dapat menyebabkan modul lain dimuat.
Sintaksis
HMODULE LoadLibraryExA(
[in] LPCSTR lpLibFileName,
HANDLE hFile,
[in] DWORD dwFlags
);
Parameter
[in] lpLibFileName
String yang menentukan nama file modul yang akan dimuat. Nama ini tidak terkait dengan nama yang disimpan dalam modul pustaka itu sendiri, seperti yang ditentukan oleh LIBRARY kata kunci dalam file module-definition (.def).
Modul dapat menjadi modul pustaka (file .dll) atau modul yang dapat dieksekusi (file .exe). Jika modul yang ditentukan adalah modul yang dapat dieksekusi, impor statis tidak dimuat; sebagai gantinya, modul dimuat seolah-olah DONT_RESOLVE_DLL_REFERENCES ditentukan. Lihat parameter
Jika string menentukan nama modul tanpa jalur dan ekstensi nama file dihilangkan, fungsi menambahkan ekstensi pustaka default ".DLL" ke nama modul. Untuk mencegah fungsi menambahkan ".DLL" ke nama modul, sertakan karakter titik berikutnya (.) dalam string nama modul.
Jika string menentukan jalur yang sepenuhnya memenuhi syarat, fungsi hanya mencari jalur tersebut untuk modul. Saat menentukan jalur, pastikan untuk menggunakan garis miring terbalik (\), bukan garis miring (/). Untuk informasi selengkapnya tentang jalur, lihat Penamaan File, Jalur, dan Namespace.
Jika string menentukan nama modul tanpa jalur dan lebih dari satu modul yang dimuat memiliki nama dasar dan ekstensi yang sama, fungsi mengembalikan handel ke modul yang dimuat terlebih dahulu.
Jika string menentukan nama modul tanpa jalur dan modul dengan nama yang sama belum dimuat, atau jika string menentukan nama modul dengan jalur relatif, fungsi akan mencari modul yang ditentukan. Fungsi ini juga mencari modul jika memuat modul yang ditentukan menyebabkan sistem memuat modul terkait lainnya (yaitu, jika modul memiliki dependensi). Direktori yang dicari dan urutan pencariannya bergantung pada jalur yang ditentukan dan parameter dwFlags. Untuk informasi selengkapnya, lihat Keterangan.
Jika fungsi tidak dapat menemukan modul atau salah satu dependensinya, fungsi gagal.
hFile
Parameter ini dicadangkan untuk digunakan di masa mendatang. Ini harus null.
[in] dwFlags
Tindakan yang akan diambil saat memuat modul. Jika tidak ada bendera yang ditentukan, perilaku fungsi ini identik dengan fungsi LoadLibrary. Parameter ini bisa menjadi salah satu nilai berikut.
Nilai | Arti |
---|---|
|
Jika nilai ini digunakan, dan modul yang dapat dieksekusi adalah DLL, sistem tidak memanggil DllMain untuk proses dan inisialisasi dan penghentian utas. Selain itu, sistem tidak memuat modul eksekusi tambahan yang dirujuk oleh modul yang ditentukan.
Catatan Jangan gunakan nilai ini; hanya disediakan untuk kompatibilitas mundur. Jika Anda hanya berencana mengakses data atau sumber daya di DLL, gunakan LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE atau LOAD_LIBRARY_AS_IMAGE_RESOURCE atau keduanya. Jika tidak, muat pustaka sebagai DLL atau modul yang dapat dieksekusi menggunakan fungsi LoadLibrary
|
|
Jika nilai ini digunakan, sistem tidak memeriksa aturan AppLocker atau menerapkan Kebijakan Pembatasan Perangkat Lunak untuk DLL. Tindakan ini hanya berlaku untuk DLL yang dimuat dan bukan ke dependensinya. Nilai ini direkomendasikan untuk digunakan dalam program penyiapan yang harus menjalankan DLL yang diekstrak selama penginstalan.
Windows Server 2008 R2 dan Windows 7: Pada sistem dengan KB2532445 diinstal, pemanggil harus berjalan sebagai "LocalSystem" atau "TrustedInstaller"; jika tidak, sistem mengabaikan bendera ini. Untuk informasi selengkapnya, lihat "Anda dapat menghindari aturan AppLocker dengan menggunakan makro Office di komputer yang menjalankan Windows 7 atau Windows Server 2008 R2" di Pangkalan Pengetahuan Bantuan dan Dukungan di https://support.microsoft.com/kb/2532445. Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: AppLocker diperkenalkan di Windows 7 dan Windows Server 2008 R2. |
|
Jika nilai ini digunakan, sistem memetakan file ke ruang alamat virtual proses panggilan seolah-olah itu adalah file data. Tidak ada yang dilakukan untuk mengeksekusi atau mempersiapkan untuk menjalankan file yang dipetakan. Oleh karena itu, Anda tidak dapat memanggil fungsi seperti GetModuleFileName, GetModuleHandle atau GetProcAddress dengan DLL ini. Menggunakan nilai ini menyebabkan penulisan ke memori baca-saja untuk meningkatkan pelanggaran akses. Gunakan bendera ini saat Anda ingin memuat DLL hanya untuk mengekstrak pesan atau sumber daya darinya.
Nilai ini dapat digunakan dengan LOAD_LIBRARY_AS_IMAGE_RESOURCE. Untuk informasi selengkapnya, lihat Keterangan. |
|
Mirip dengan LOAD_LIBRARY_AS_DATAFILE, kecuali bahwa file DLL dibuka dengan akses tulis eksklusif untuk proses panggilan. Proses lain tidak dapat membuka file DLL untuk akses tulis saat sedang digunakan. Namun, DLL masih dapat dibuka oleh proses lain.
Nilai ini dapat digunakan dengan LOAD_LIBRARY_AS_IMAGE_RESOURCE. Untuk informasi selengkapnya, lihat Keterangan. Windows Server 2003 dan Windows XP: Nilai ini tidak didukung hingga Windows Vista. |
|
Jika nilai ini digunakan, sistem memetakan file ke ruang alamat virtual proses sebagai file gambar.
Namun, loader tidak memuat impor statis atau melakukan langkah-langkah inisialisasi biasa lainnya. Gunakan bendera ini saat Anda ingin memuat DLL hanya untuk mengekstrak pesan atau sumber daya darinya.
Kecuali aplikasi tergantung pada file yang memiliki tata letak dalam memori gambar, nilai ini harus digunakan dengan LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE atau LOAD_LIBRARY_AS_DATAFILE. Untuk informasi selengkapnya, lihat bagian Keterangan. Windows Server 2003 dan Windows XP: Nilai ini tidak didukung hingga Windows Vista. |
|
Jika nilai ini digunakan, direktori penginstalan aplikasi dicari untuk DLL dan dependensinya. Direktori di jalur pencarian standar tidak dicari. Nilai ini tidak dapat dikombinasikan dengan LOAD_WITH_ALTERED_SEARCH_PATH.
Windows 7, Windows Server 2008 R2, Windows Vista, dan Windows Server 2008: Nilai ini memerlukan KB2533623 untuk diinstal. Windows Server 2003 dan Windows XP: Nilai ini tidak didukung. |
|
Nilai ini adalah kombinasi dari LOAD_LIBRARY_SEARCH_APPLICATION_DIR, LOAD_LIBRARY_SEARCH_SYSTEM32, dan LOAD_LIBRARY_SEARCH_USER_DIRS. Direktori di jalur pencarian standar tidak dicari. Nilai ini tidak dapat dikombinasikan dengan LOAD_WITH_ALTERED_SEARCH_PATH.
Nilai ini menunjukkan jumlah maksimum direktori yang direkomendasikan yang harus disertakan aplikasi dalam jalur pencarian DLL-nya. Windows 7, Windows Server 2008 R2, Windows Vista, dan Windows Server 2008: Nilai ini memerlukan KB2533623 untuk diinstal. Windows Server 2003 dan Windows XP: Nilai ini tidak didukung. |
|
Jika nilai ini digunakan, direktori yang berisi DLL untuk sementara ditambahkan ke awal daftar direktori yang dicari untuk dependensi DLL. Direktori di jalur pencarian standar tidak dicari.
Parameter lpFileName Misalnya, jika Lib2.dll adalah dependensi C:\Dir1\Lib1.dll, loading Lib1.dll with this value causes the system to search for Lib2.dll hanya di C:\Dir1. Untuk mencari Lib2.dll di C:\Dir1 dan semua direktori di jalur pencarian DLL, gabungkan nilai ini dengan LOAD_LIBRARY_SEARCH_DEFAULT_DIRS. Windows 7, Windows Server 2008 R2, Windows Vista, dan Windows Server 2008: Nilai ini memerlukan KB2533623 untuk diinstal. Windows Server 2003 dan Windows XP: Nilai ini tidak didukung. |
|
Jika nilai ini digunakan, %windows%\system32 dicari untuk DLL dan dependensinya.
Direktori di jalur pencarian standar tidak dicari. Nilai ini tidak dapat dikombinasikan dengan LOAD_WITH_ALTERED_SEARCH_PATH.
Windows 7, Windows Server 2008 R2, Windows Vista, dan Windows Server 2008: Nilai ini memerlukan KB2533623 untuk diinstal. Windows Server 2003 dan Windows XP: Nilai ini tidak didukung. |
|
Jika nilai ini digunakan, direktori yang ditambahkan menggunakan AddDllDirectory Windows 7, Windows Server 2008 R2, Windows Vista, dan Windows Server 2008: Nilai ini memerlukan KB2533623 untuk diinstal. Windows Server 2003 dan Windows XP: Nilai ini tidak didukung. |
|
Jika nilai ini digunakan dan lpFileName menentukan jalur absolut, sistem menggunakan strategi pencarian file alternatif yang dibahas di bagian Keterangan untuk menemukan modul yang dapat dieksekusi terkait yang menyebabkan modul yang ditentukan dimuat. Jika nilai ini digunakan dan lpFileName menentukan jalur relatif, perilaku tidak terdefinisi.
Jika nilai ini tidak digunakan, atau jika lpFileName tidak menentukan jalur, sistem menggunakan strategi pencarian standar yang dibahas di bagian Keterangan untuk menemukan modul yang dapat dieksekusi terkait yang menyebabkan modul yang ditentukan dimuat. Nilai ini tidak dapat digabungkan dengan bendera LOAD_LIBRARY_SEARCH apa pun. |
|
Menentukan bahwa tanda tangan digital gambar biner harus diperiksa pada waktu pemuatan.
Nilai ini memerlukan Windows 8.1, Windows 10 atau yang lebih baru. |
|
Jika nilai ini digunakan, memuat DLL untuk eksekusi dari direktori saat ini hanya diperbolehkan jika berada di bawah direktori dalam daftar Beban aman. |
Mengembalikan nilai
Jika fungsi berhasil, nilai pengembalian adalah handel ke modul yang dimuat.
Jika fungsi gagal, nilai yang dikembalikan adalah NULL. Untuk mendapatkan informasi kesalahan yang diperluas, panggil GetLastError.
Komentar
Fungsi
- LoadLibraryEx dapat memuat modul DLL tanpa memanggil fungsi DllMain DLL.
- LoadLibraryEx dapat memuat modul dengan cara yang dioptimalkan untuk kasus di mana modul tidak akan pernah dijalankan, memuat modul seolah-olah itu adalah file data.
- LoadLibraryEx dapat menemukan modul dan modul terkait dengan menggunakan salah satu dari dua strategi pencarian atau dapat mencari serangkaian direktori khusus proses.
Proses panggilan dapat menggunakan handel yang dikembalikan oleh LoadLibraryEx untuk mengidentifikasi modul dalam panggilan ke getProcAddress, FungsiFindResource , dan LoadResource.
Untuk mengaktifkan atau menonaktifkan pesan kesalahan yang ditampilkan oleh loader selama pemuatan DLL, gunakan fungsi SetErrorMode.
Tidak aman untuk memanggil LoadLibraryEx dari DllMain. Untuk informasi selengkapnya, lihat bagian Keterangan di DllMain.
Visual C++: Kompilator Visual C++ mendukung sintaks yang memungkinkan Anda mendeklarasikan variabel thread-local: _declspec(thread). Jika Anda menggunakan sintaksis ini dalam DLL, Anda tidak akan dapat memuat DLL secara eksplisit menggunakan LoadLibraryEx pada versi Windows sebelum Windows Vista. Jika DLL Anda akan dimuat secara eksplisit, Anda harus menggunakan fungsi penyimpanan lokal utas alih-alih _declspec(utas). Misalnya, lihat Menggunakan Penyimpanan Lokal Utas di Pustaka Dynamic Link.
Memuat DLL sebagai File Data atau Sumber Daya Gambar
Nilai LOAD_LIBRARY_AS_DATAFILE, LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE, dan LOAD_LIBRARY_AS_IMAGE_RESOURCE memengaruhi jumlah referensi per proses dan pemuatan modul yang ditentukan. Jika salah satu nilai ini ditentukan untuk parameterJika LoadLibraryEx dipanggil dua kali untuk file yang sama dengan LOAD_LIBRARY_AS_DATAFILE, LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE, atau LOAD_LIBRARY_AS_IMAGE_RESOURCE, dua pemetaan terpisah dibuat untuk file tersebut.
Saat nilai LOAD_LIBRARY_AS_IMAGE_RESOURCE digunakan, modul dimuat sebagai gambar menggunakan ekspansi penyelarasan bagian portable executable (PE). Alamat virtual relatif (RVA) tidak harus dipetakan ke alamat disk, sehingga sumber daya dapat lebih cepat diambil dari modul. Menentukan LOAD_LIBRARY_AS_IMAGE_RESOURCE mencegah proses lain mengubah modul saat dimuat.
Kecuali aplikasi bergantung pada karakteristik pemetaan gambar tertentu, nilai LOAD_LIBRARY_AS_IMAGE_RESOURCE harus digunakan dengan LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE atau LOAD_LIBRARY_AS_DATAFILE. Ini memungkinkan loader untuk memilih apakah akan memuat modul sebagai sumber daya gambar atau file data, memilih opsi mana pun yang memungkinkan sistem untuk berbagi halaman secara lebih efektif. Fungsi sumber daya seperti FindResource dapat menggunakan pemetaan.
Untuk menentukan bagaimana modul dimuat, gunakan salah satu makro berikut untuk menguji handel yang dikembalikan oleh LoadLibraryEx.
#define LDR_IS_DATAFILE(handle) (((ULONG_PTR)(handle)) & (ULONG_PTR)1)
#define LDR_IS_IMAGEMAPPING(handle) (((ULONG_PTR)(handle)) & (ULONG_PTR)2)
#define LDR_IS_RESOURCE(handle) (LDR_IS_IMAGEMAPPING(handle) || LDR_IS_DATAFILE(handle))
Tabel berikut ini menjelaskan makro ini.
Makro | Deskripsi |
---|---|
LDR_IS_DATAFILE(menangani) | Jika makro ini mengembalikan TRUE, modul dimuat sebagai file data (LOAD_LIBRARY_AS_DATAFILE atau LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE). |
LDR_IS_IMAGEMAPPING(menangani) | Jika makro ini mengembalikan TRUE, modul dimuat sebagai file gambar (LOAD_LIBRARY_AS_IMAGE_RESOURCE). |
LDR_IS_RESOURCE(menangani) | Jika makro ini mengembalikan TRUE, modul dimuat sebagai file data atau file gambar. |
Gunakan fungsi FreeLibrary
Mencari DLL dan Dependensi
Jalur pencarian adalah kumpulan direktori yang dicari untuk DLL. FungsiFungsi
- Nama file ditentukan tanpa jalur dan nama file dasar tidak cocok dengan nama file dasar modul yang dimuat, dan tidak ada bendera LOAD_LIBRARY_SEARCH yang digunakan.
- Jalur ditentukan tetapi LOAD_WITH_ALTERED_SEARCH_PATH tidak digunakan.
- Aplikasi belum menentukan jalur pencarian DLL default untuk proses menggunakan SetDefaultDllDirectories.
Jika lpFileName menentukan jalur relatif, seluruh jalur relatif ditambahkan ke setiap token di jalur pencarian DLL. Untuk memuat modul dari jalur relatif tanpa mencari jalur lain, gunakan GetFullPathName untuk mendapatkan jalur nonrelatif dan memanggil LoadLibraryEx dengan jalur nonrelatif. Jika modul sedang dimuat sebagai datafile dan jalur relatif dimulai dengan "." atau "..", jalur relatif diperlakukan sebagai jalur absolut.
Jika lpFileName menentukan jalur absolut dan dwFlags diatur ke LOAD_WITH_ALTERED_SEARCH_PATH, LoadLibraryEx menggunakan jalur pencarian yang diubah. Perilaku tidak terdefinisi saat bendera LOAD_WITH_ALTERED_SEARCH_PATH diatur, dan lpFileName menentukan jalur relatif.
Fungsi SetDllDirectory
Aplikasi dapat menentukan direktori untuk mencari satu panggilan
- Direktori yang berisi DLL (LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR). Direktori ini hanya dicari untuk dependensi DLL yang akan dimuat.
- Direktori aplikasi (LOAD_LIBRARY_SEARCH_APPLICATION_DIR).
- Jalur secara eksplisit ditambahkan ke jalur pencarian aplikasi dengan fungsi
AddDllDirectory ( LOAD_LIBRARY_SEARCH_USER_DIRS ) atau fungsi SetDllDirectory. Jika lebih dari satu jalur telah ditambahkan, urutan di mana jalur dicari tidak ditentukan. - Direktori System32 (LOAD_LIBRARY_SEARCH_SYSTEM32).
Windows 7, Windows Server 2008 R2, Windows Vista, dan Windows Server 2008: Bendera LOAD_LIBRARY_SEARCH_ tersedia pada sistem yang telah KB2533623 diinstal. Untuk menentukan apakah bendera tersedia, gunakan GetProcAddress
Jika aplikasi telah menggunakan
Jika jalur ditentukan dan ada file pengalihan yang terkait dengan aplikasi, fungsi LoadLibraryEx mencari modul di direktori aplikasi. Jika modul ada di direktori aplikasi, LoadLibraryEx mengabaikan spesifikasi jalur dan memuat modul dari direktori aplikasi. Jika modul tidak ada di direktori aplikasi, fungsi memuat modul dari direktori yang ditentukan. Untuk informasi selengkapnya, lihat Pengalihan Pustaka Dynamic Link.
Jika Anda memanggil LoadLibraryEx dengan nama rakitan tanpa spesifikasi jalur dan rakitan tercantum dalam manifes yang kompatibel dengan sistem, panggilan secara otomatis dialihkan ke rakitan berdampingan.
Keterangan Keamanan
LOAD_LIBRARY_AS_DATAFILE tidak mencegah proses lain mengubah modul saat dimuat. Karena ini dapat membuat aplikasi Anda kurang aman, Anda harus menggunakan LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE alih-alih LOAD_LIBRARY_AS_DATAFILE saat memuat modul sebagai file data, kecuali Anda secara khusus perlu menggunakan LOAD_LIBRARY_AS_DATAFILE. Menentukan LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE mencegah proses lain mengubah modul saat dimuat. Jangan tentukan LOAD_LIBRARY_AS_DATAFILE dan LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE dalam panggilan yang sama.Jangan gunakan fungsi
Jangan membuat asumsi tentang versi sistem operasi berdasarkan panggilan LoadLibraryEx yang mencari DLL. Jika aplikasi berjalan di lingkungan di mana DLL secara sah tidak ada tetapi versi DLL berbahaya ada di jalur pencarian, versi berbahaya DLL dapat dimuat. Sebagai gantinya, gunakan teknik yang direkomendasikan yang dijelaskan dalam Mendapatkan Versi Sistem.
Untuk diskusi umum tentang masalah keamanan DLL, lihatKeamanan Pustaka
Contoh
Contoh kode berikut menunjukkan panggilan ke LoadLibraryExA.
//Load the FMAPI DLL
hLib = ::LoadLibraryEx(L"fmapi.dll", NULL, NULL);
if ( !hLib )
{
wprintf(L"Could not load fmapi.dll, Error #%d.\n", GetLastError());
return;
}
Untuk contoh tambahan, lihat Mencari Teks untuk Nomor Kode Kesalahan.
Nota
Header libloaderapi.h mendefinisikan LoadLibraryEx sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praproscesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.
Persyaratan
Syarat | Nilai |
---|---|
klien minimum yang didukung | Windows XP [hanya aplikasi desktop] |
server minimum yang didukung |
Windows Server 2003 [hanya aplikasi desktop] |
Platform Target |
Windows |
Header |
libloaderapi.h (termasuk Windows.h) |
Pustaka |
Kernel32.lib |
DLL |
Kernel32.dll |
Lihat juga
Fungsi Pustaka
Urutan Pencarian Pustaka
Keamanan Pustaka
FindResource
FreeLibrary
Penautan Dinamis