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

Статья
11/20/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 файла) или адрес модуля (если 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 [только классические приложения]
целевая платформа	Виндоус
заголовка	libloaderapi.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll