GetModuleHandleExA 函式 (libloaderapi.h)

發行項
08/24/2023

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

語法

BOOL GetModuleHandleExA(
  [in]           DWORD   dwFlags,
  [in, optional] LPCSTR  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 標頭會將 GetModuleHandleEx 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程式碼，可能會導致編譯或執行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

需求


最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平台	Windows
標頭	libloaderapi.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll