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 文件) ，或者GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS) dwFlags 时模块 (中的地址。

对于模块名称，如果省略文件扩展名，则会追加默认库扩展名 .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 返回的句柄与GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT传递给 FreeLibrary 函数。这样做可能会导致 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)
Library	Kernel32.lib
DLL	Kernel32.dll