GetModuleHandleExA 函数 (libloaderapi.h)

检索指定模块的模块句柄,并递增模块的引用计数,除非指定了GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT。 模块必须已由调用进程加载。

语法

BOOL GetModuleHandleExA(
  [in]           DWORD   dwFlags,
  [in, optional] LPCSTR  lpModuleName,
  [out]          HMODULE *phModule
);

parameters

[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

另请参阅

动态链接库函数

FreeLibrary

GetModuleFileName

LoadLibrary

LoadLibraryEx