GetModuleHandleA 函式 (libloaderapi.h)

發行項
08/24/2023

擷取指定模組的模組控制碼。呼叫進程必須已載入模組。

若要避免一節中所述的競爭條件，請使用 GetModuleHandleEx 函式。

語法

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

參數

[in, optional] lpModuleName

載入的模組名稱 (.dll 或 .exe 檔案) 。如果省略副檔名，則會附加預設程式庫副檔名 .dll。檔案名字串可以包含尾端點字元 (.) ，表示模組名稱沒有副檔名。字串不需要指定路徑。指定路徑時，請務必使用反斜線 (\) ，而不是正斜線 (/) 。名稱會獨立比較 (大小寫，) 目前對應至呼叫進程的位址空間的模組名稱。

如果此參數為 Null， GetModuleHandle 會傳回用來建立呼叫進程 (.exe 檔案之檔案的控制碼) 。

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

傳回值

如果函式成功，則傳回值是指定模組的控制碼。

如果函式失敗，則傳回值為 Null。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

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

如果 lpModuleName 不包含路徑，而且有多個載入的模組具有相同基底名稱和延伸模組，則您無法預測將傳回哪一個模組控制碼。若要解決此問題，您可以指定路徑、並存元件，或使用 GetModuleHandleEx 來指定記憶體位置，而不是 DLL 名稱。

GetModuleHandle函式會傳回對應模組的控制碼，而不會遞增其參考計數。不過，如果這個控制碼傳遞至 FreeLibrary 函式，對應模組的參考計數將會遞減。因此，請勿將 GetModuleHandle 傳回的控制碼傳遞至 FreeLibrary 函式 。這樣做可能會導致 DLL 模組提前取消對應。

此函式必須在多執行緒應用程式中謹慎使用。不保證模組控制碼在函式傳回控制碼和使用控制碼的時間之間保持有效。例如，假設執行緒會擷取模組控制碼，但在使用控制碼之前，第二個執行緒會釋放模組。如果系統載入另一個模組，它可以重複使用最近釋放的模組控制碼。因此，第一個執行緒的控制碼會與預期的模組不同。

範例

如需範例，請參閱使用筆刷。

注意

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

需求


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