Fungsi GetModuleHandleExW (libloaderapi.h)

Artikel
02/05/2024

Mengambil handel modul untuk modul yang ditentukan dan menaikkan jumlah referensi modul kecuali GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT ditentukan. Modul harus dimuat oleh proses panggilan.

Sintaks

BOOL GetModuleHandleExW(
  [in]           DWORD   dwFlags,
  [in, optional] LPCWSTR lpModuleName,
  [out]          HMODULE *phModule
);

Parameter

[in] dwFlags

Parameter ini bisa nol atau satu atau beberapa nilai berikut. Jika jumlah referensi modul bertambah, pemanggil harus menggunakan fungsi FreeLibrary untuk mengurangi jumlah referensi saat handel modul tidak lagi diperlukan.

GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS (0x00000004)

Parameter lpModuleName adalah alamat dalam modul.

GET_MODULE_HANDLE_EX_FLAG_PIN (0x00000001)

Modul tetap dimuat sampai proses dihentikan, tidak peduli berapa kali FreeLibrary dipanggil.

Opsi ini tidak dapat digunakan dengan GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT.

GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT (0x00000002)

Jumlah referensi untuk modul tidak bertambah. Opsi ini setara dengan perilaku GetModuleHandle. Jangan meneruskan handel modul yang diambil ke fungsi FreeLibrary ; melakukannya dapat menyebabkan DLL tidak dipetakan sebelum waktunya. Untuk informasi selengkapnya, lihat Keterangan.

Opsi ini tidak dapat digunakan dengan GET_MODULE_HANDLE_EX_FLAG_PIN.

[in, optional] lpModuleName

Nama modul yang dimuat (baik file .dll atau .exe), atau alamat dalam modul (jika dwFlags GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS).

Untuk nama modul, 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 dibandingkan (kasus secara independen) dengan nama modul yang saat ini dipetakan ke ruang alamat proses panggilan.

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

[out] phModule

Handel ke modul yang ditentukan. Jika fungsi gagal, parameter ini adalah NULL.

Fungsi GetModuleHandleEx 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 bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, lihat 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 menentukan lokasi memori daripada nama DLL di parameter lpModuleName .

Jika dwFlags berisi GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT, fungsi GetModuleHandleEx mengembalikan handel ke modul yang dipetakan tanpa meningkatkan 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 GetModuleHandleEx dengan GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT ke fungsi FreeLibrary . Melakukannya dapat menyebabkan modul DLL tidak dipetakan sebelum waktunya.

Jika dwFlags berisi GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT, 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, 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 dibebaskan. Oleh karena itu, utas pertama akan memiliki pegangan ke modul yang berbeda dari yang dimaksudkan.

Untuk mengkompilasi aplikasi yang menggunakan fungsi ini, tentukan _WIN32_WINNT sebagai 0x0501 atau yang lebih baru. Untuk informasi selengkapnya, lihat Menggunakan Header Windows.

Catatan

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