GetModuleHandleA 函数 (libloaderapi.h)

项目
08/24/2023

检索指定模块的模块句柄。模块必须已由调用进程加载。

若要避免“备注”部分所述的争用条件，请使用 GetModuleHandleEx 函数。

语法

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

parameters

[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)
Library	Kernel32.lib
DLL	Kernel32.dll