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

Статья
08/24/2023

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

Чтобы избежать условий гонки, описанных в разделе Примечания, используйте функцию GetModuleHandleEx .

Синтаксис

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

Параметры

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

Требования


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