Функция GetModuleHandleExA (libloaderapi.h)

Статья
08/24/2023

Извлекает дескриптор модуля для указанного модуля и увеличивает число ссылок на модуль, если не указано GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT. Модуль должен быть загружен вызывающим процессом.

Синтаксис

BOOL GetModuleHandleExA(
  [in]           DWORD   dwFlags,
  [in, optional] LPCSTR  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 не содержит пути и существует несколько загруженных модулей с одинаковыми базовыми именами и расширениями, вы не сможете предсказать, какой дескриптор модуля будет возвращен. Чтобы обойти эту проблему, можно указать путь, использовать параллельные сборки или указать расположение памяти, а не имя библиотеки DLL в параметре lpModuleName .

Если 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 в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования


Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	libloaderapi.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll