GetModuleHandleExW 函式 (libloaderapi.h)

發行項
02/07/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 [僅限傳統型應用程式]
目標平台	Windows
標頭	libloaderapi.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll