GetModuleHandleExW 函式（libloaderapi.h）

發行項
11/20/2024

擷取指定模組的模組句柄，並遞增模組的參考計數，除非指定GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT。呼叫進程必須已載入模組。

語法

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

參數

[in] dwFlags

此參數可以是零或一或多個下列值。如果模組的參考計數遞增，呼叫端必須使用 FreeLibrary 函式，在不再需要模組句柄時遞減參考計數。

GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS （0x00000004）

lpModuleName 參數是模組中的位址。

GET_MODULE_HANDLE_EX_FLAG_PIN （0x00000001）

不論呼叫 FreeLibrary 多少次，模組都會保持載入，直到進程終止為止。

此選項無法與 GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT 搭配使用。

GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT （0x00000002）

模組的參考計數不會遞增。此選項相當於 GetModuleHandle的行為。請勿將擷取的模組句柄傳遞至 FreeLibrary 函式;這樣做可能會導致 DLL 過早地取消對應。如需詳細資訊，請參閱。

此選項無法與GET_MODULE_HANDLE_EX_FLAG_PIN搭配使用。

[in, optional] lpModuleName

載入的模組名稱（.dll 或 .exe 檔案），或模組中的位址（如果 dwFlags 為GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS）。

針對模組名稱，如果省略擴展名，則會附加默認連結庫擴展名 .dll。檔名字串可以包含尾端點字元（.），表示模組名稱沒有擴展名。字串不需要指定路徑。指定路徑時，請務必使用反斜杠（\），而不是正斜線（/）。名稱會與目前對應至呼叫進程位址空間的模組名稱進行比較（個別大小寫）。

如果此參數為 NULL，函式會傳回用來建立呼叫進程之檔案的句柄（.exe 檔案）。

[out] phModule

指定模組的句柄。如果函式失敗，此參數會 NULL。

GetModuleHandleEx 函式不會擷取使用 LOAD_LIBRARY_AS_DATAFILE 旗標載入之模組的句柄。如需詳細資訊，請參閱 LoadLibraryEx。

傳回值

如果函式成功，則傳回值為非零值。

如果函式失敗，傳回值為零。若要取得擴充的錯誤資訊，請參閱 GetLastError。

言論

傳回的句柄不是全域或可繼承的。它不能由另一個進程複製或使用。

如果 lpModuleName 不包含路徑，而且有多個載入的模組具有相同基底名稱和擴充功能，則您無法預測將傳回哪個模組句柄。若要解決此問題，您可以指定路徑、使用並存元件，或在 lpModuleName 參數中指定記憶體位置，而不是 DLL 名稱。

如果 dwFlags 包含GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT ，則 GetModuleHandleEx 函式會傳回對應模組的句柄，而不會遞增其參考計數。不過，如果這個句柄傳遞至 FreeLibrary 函式，對應的模塊參考計數將會遞減。因此，請勿將 getModuleHandleEx 傳回的句柄傳遞至 freeLibrary 函式 GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT。這樣做可能會導致 DLL 模組過早地取消對應。

如果 dwFlags 包含GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT，則必須在多線程應用程式中小心使用此函式。不保證模組句柄在函式傳回句柄和使用句柄的時間之間保持有效。例如，線程會擷取模組句柄，但在它使用句柄之前，第二個線程會釋放模組。如果系統載入另一個模組，它可以重複使用最近釋放的模組句柄。因此，第一個線程的句柄與預期的模組不同。

若要編譯使用此函式的應用程式，請將_WIN32_WINNT定義為0x0501或更新版本。如需詳細資訊，請參閱使用 Windows 標頭。

注意

libloaderapi.h 標頭 會根據 UNICODE 預處理器常數的定義，將 GetModuleHandleEx 定義為自動選取此函式 ANSI 或 Unicode 版本的別名。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

要求

要求	價值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
支援的最低伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平臺	窗戶
標頭	libloaderapi.h （包括 Windows.h）
連結庫	Kernel32.lib
DLL	Kernel32.dll