Fungsi LoadLibraryW (libloaderapi.h)
Memuat modul yang ditentukan ke ruang alamat proses panggilan. Modul yang ditentukan dapat menyebabkan modul lain dimuat.
Untuk opsi beban tambahan, gunakan fungsi LoadLibraryEx .
Sintaks
HMODULE LoadLibraryW(
[in] LPCWSTR lpLibFileName
);
Parameter
[in] lpLibFileName
Nama modul. Ini dapat berupa modul pustaka (file .dll) atau modul yang dapat dieksekusi (file .exe).
Jika modul yang ditentukan adalah modul yang dapat dieksekusi, impor statis tidak dimuat; sebaliknya, modul dimuat seolah-olah oleh LoadLibraryEx dengan DONT_RESOLVE_DLL_REFERENCES bendera .
Nama yang ditentukan adalah nama file modul dan tidak terkait dengan nama yang disimpan dalam modul pustaka itu sendiri, seperti yang ditentukan oleh kata kunci LIBRARY dalam file module-definition (.def).
Jika string menentukan jalur lengkap, fungsi hanya mencari jalur tersebut untuk modul.
Jika string menentukan jalur relatif atau nama modul tanpa jalur, fungsi menggunakan strategi pencarian standar untuk menemukan modul; untuk informasi selengkapnya, lihat Keterangan.
Jika fungsi tidak dapat menemukan modul, fungsi gagal. Saat menentukan jalur, pastikan untuk menggunakan garis miring terbalik (\), bukan garis miring (/). Untuk informasi selengkapnya tentang jalur, lihat Penamaan File atau Direktori.
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.
Nilai kembali
Jika fungsi berhasil, nilai yang dikembalikan adalah handel ke modul.
Jika fungsi gagal, nilai yang dikembalikan adalah NULL. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.
Keterangan
Untuk mengaktifkan atau menonaktifkan pesan kesalahan yang ditampilkan oleh pemuat selama pemuatan DLL, gunakan fungsi SetErrorMode .
LoadLibrary dapat digunakan untuk memuat modul pustaka ke ruang alamat proses dan mengembalikan handel yang dapat digunakan di GetProcAddress untuk mendapatkan alamat fungsi DLL. LoadLibrary juga dapat digunakan untuk memuat modul lain yang dapat dieksekusi. Misalnya, fungsi dapat menentukan file .exe untuk mendapatkan handel yang dapat digunakan di FindResource atau LoadResource. Namun, jangan gunakan LoadLibrary untuk menjalankan file .exe. Sebagai gantinya, gunakan fungsi CreateProcess .
Jika modul yang ditentukan adalah DLL yang belum dimuat untuk proses panggilan, sistem memanggil fungsi DllMain DLL dengan nilai DLL_PROCESS_ATTACH . Jika DllMain mengembalikan TRUE, LoadLibrary mengembalikan handel ke modul. Jika DllMain mengembalikan FALSE, sistem akan membongkar DLL dari ruang alamat proses dan LoadLibrary mengembalikan NULL. Tidak aman untuk memanggil LoadLibrary dari DllMain. Untuk informasi selengkapnya, lihat bagian Keterangan di DllMain.
Handel modul tidak global atau dapat diwariskan. Panggilan ke LoadLibrary oleh satu proses tidak menghasilkan handel yang dapat digunakan proses lain — misalnya, dalam memanggil GetProcAddress. Proses lain harus melakukan panggilannya sendiri ke LoadLibrary untuk modul sebelum memanggil GetProcAddress.
Jika lpFileName tidak menyertakan jalur dan ada lebih dari satu modul yang dimuat dengan nama dasar dan ekstensi yang sama, fungsi mengembalikan handel ke modul yang dimuat terlebih dahulu.
Jika tidak ada ekstensi nama file yang ditentukan dalam parameter lpFileName , ekstensi pustaka default .dll ditambahkan. Namun, string nama file dapat menyertakan karakter titik berikutnya (.) untuk menunjukkan bahwa nama modul tidak memiliki ekstensi. Ketika tidak ada jalur yang ditentukan, fungsi mencari modul yang dimuat yang nama dasarnya cocok dengan nama dasar modul yang akan dimuat. Jika namanya cocok, beban berhasil. Jika tidak, fungsi akan mencari file.
Direktori pertama yang dicari adalah direktori yang berisi file gambar yang digunakan untuk membuat proses panggilan (untuk informasi selengkapnya, lihat fungsi CreateProcess ). Melakukan ini memungkinkan file pustaka tautan dinamis privat (DLL) yang terkait dengan proses untuk ditemukan tanpa menambahkan direktori yang diinstal proses ke variabel lingkungan PATH. Jika jalur relatif ditentukan, seluruh jalur relatif ditambahkan ke setiap token dalam daftar jalur pencarian DLL. Untuk memuat modul dari jalur relatif tanpa mencari jalur lain, gunakan GetFullPathName untuk mendapatkan jalur nonrelatif dan memanggil LoadLibrary dengan jalur nonrelatif. Untuk informasi selengkapnya tentang urutan pencarian DLL, lihat Urutan Pencarian Pustaka Dynamic-Link.
Jalur pencarian dapat diubah menggunakan fungsi SetDllDirectory . Solusi ini direkomendasikan alih-alih menggunakan SetCurrentDirectory atau hard-coding jalur lengkap ke DLL.
Jika jalur ditentukan dan ada file pengalihan untuk aplikasi, fungsi mencari modul di direktori aplikasi. Jika modul ada di direktori aplikasi, LoadLibrary mengabaikan jalur yang ditentukan dan memuat modul dari direktori aplikasi. Jika modul tidak ada di direktori aplikasi, LoadLibrary memuat modul dari direktori yang ditentukan. Untuk informasi selengkapnya, lihat Pengalihan Pustaka Dynamic Link.
Jika Anda memanggil LoadLibrary dengan nama perakitan tanpa spesifikasi jalur dan perakitan tercantum dalam manifes yang kompatibel dengan sistem, panggilan secara otomatis dialihkan ke rakitan berdampingan.
Sistem mempertahankan jumlah referensi per proses pada semua modul yang dimuat. Memanggil LoadLibrary meningkatkan jumlah referensi. Memanggil fungsi FreeLibrary atau FreeLibraryAndExitThread mengurangi jumlah referensi. Sistem membongkar modul ketika jumlah referensinya mencapai nol atau ketika proses berakhir (terlepas dari jumlah referensi).
Windows Server 2003 dan Windows XP: Pengkompilasi Visual C++ mendukung sintaksis yang memungkinkan Anda mendeklarasikan variabel thread-local: _declspec(thread). Jika Anda menggunakan sintaks ini dalam DLL, Anda tidak akan dapat memuat DLL secara eksplisit menggunakan LoadLibrary 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 Tautan Dinamis.
Keterangan Keamanan
Jangan gunakan fungsi SearchPath untuk mengambil jalur ke DLL untuk panggilan LoadLibrary berikutnya. Fungsi SearchPath menggunakan urutan pencarian yang berbeda dari LoadLibrary dan tidak menggunakan mode pencarian proses yang aman kecuali ini diaktifkan secara eksplisit dengan memanggil SetSearchPathMode dengan BASE_SEARCH_PATH_ENABLE_SAFE_SEARCHMODE. Oleh karena itu, SearchPath kemungkinan akan terlebih dahulu mencari direktori kerja pengguna saat ini untuk DLL yang ditentukan. Jika penyerang telah menyalin versi BERBAHAYA DLL ke direktori kerja saat ini, jalur yang diambil oleh SearchPath akan menunjuk ke DLL berbahaya, yang kemudian akan dimuat LoadLibrary .Jangan membuat asumsi tentang versi sistem operasi berdasarkan panggilan LoadLibrary yang mencari DLL. Jika aplikasi berjalan di lingkungan di mana DLL secara sah tidak ada tetapi versi berbahaya DLL berada di jalur pencarian, versi berbahaya DLL dapat dimuat. Sebagai gantinya, gunakan teknik yang direkomendasikan yang dijelaskan dalam Mendapatkan Versi Sistem.
Contoh
Misalnya, lihat Menggunakan Run-Time Dynamic Linking.
Catatan
Header libloaderapi.h mendefinisikan LoadLibrary sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor 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
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows XP [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2003 [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | libloaderapi.h (termasuk Windows.h) |
| Pustaka | Kernel32.lib |
| DLL | Kernel32.dll |