Fungsi GetModuleHandleA (libloaderapi.h)

Artikel
03/11/2023

Mengambil handel modul untuk modul yang ditentukan. Modul harus dimuat oleh proses panggilan.

Untuk menghindari kondisi balapan yang dijelaskan di bagian Keterangan, gunakan fungsi GetModuleHandleEx .

Sintaks

HMODULE GetModuleHandleA(
  [in, optional] LPCSTR lpModuleName
);

Parameter

[in, optional] lpModuleName

Nama modul yang dimuat (baik file .dll atau .exe). Jika ekstensi nama file dihilangkan, ekstensi pustaka default .dll ditambahkan. String nama file dapat menyertakan karakter titik berikutnya (.) untuk menunjukkan bahwa nama modul tidak memiliki ekstensi. String tidak harus menentukan jalur. Saat menentukan jalur, pastikan untuk menggunakan garis miring terbalik (\), bukan garis miring (/). Nama ini dibandingkan (kasus secara independen) dengan nama modul yang saat ini dipetakan ke ruang alamat proses panggilan.

Jika parameter ini NULL, GetModuleHandle mengembalikan handel ke file yang digunakan untuk membuat proses panggilan (file .exe).

Fungsi GetModuleHandle tidak mengambil handel untuk modul yang dimuat menggunakan bendera LOAD_LIBRARY_AS_DATAFILE . Untuk informasi selengkapnya, lihat LoadLibraryEx.

Menampilkan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah handel ke modul yang ditentukan.

Jika fungsi gagal, nilai yang dikembalikan adalah NULL. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Handel yang dikembalikan tidak global atau dapat diwariskan. Ini tidak dapat diduplikasi atau digunakan oleh proses lain.

Jika lpModuleName tidak menyertakan jalur dan ada lebih dari satu modul yang dimuat dengan nama dasar dan ekstensi yang sama, Anda tidak dapat memprediksi handel modul mana yang akan dikembalikan. Untuk mengatasi masalah ini, Anda dapat menentukan jalur, menggunakan rakitan berdampingan, atau menggunakan GetModuleHandleEx untuk menentukan lokasi memori daripada nama DLL.

Fungsi GetModuleHandle mengembalikan handel ke modul yang dipetakan tanpa menambah jumlah referensinya. Namun, jika handel ini diteruskan ke fungsi FreeLibrary , jumlah referensi modul yang dipetakan akan diturunkan. Oleh karena itu, jangan meneruskan handel yang dikembalikan oleh GetModuleHandle ke fungsi FreeLibrary . Melakukannya dapat menyebabkan modul DLL tidak dipetakan sebelum waktunya.

Fungsi ini harus digunakan dengan hati-hati dalam aplikasi multithreaded. Tidak ada jaminan bahwa handel modul tetap valid antara waktu fungsi ini mengembalikan handel dan waktu penggunaannya. Misalnya, anggaplah bahwa utas mengambil handel modul, tetapi sebelum menggunakan handel, utas kedua membebaskan modul. Jika sistem memuat modul lain, sistem dapat menggunakan kembali handel modul yang baru-baru ini dikosongkan. Oleh karena itu, utas pertama akan memiliki handel ke modul yang berbeda dari yang dimaksudkan.

Contoh

Misalnya, lihat Menggunakan Brushes.

Catatan

Header libloaderapi.h mendefinisikan GetModuleHandle 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


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