Share via


GetModuleHandleExW 函式 (libloaderapi.h)

擷取指定模組的模組句柄,並遞增模組的參考計數,除非指定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

另請參閱

動態連結庫函式

FreeLibrary

GetModuleFileName

LoadLibrary

LoadLibraryEx

VBS 記憶體保護區中可用的 Vertdll API