Функция GetModuleFileNameExA (psapi.h)

Статья
11/20/2024

Извлекает полный путь для файла, содержащего указанный модуль.

Синтаксис

DWORD GetModuleFileNameExA(
  [in]           HANDLE  hProcess,
  [in, optional] HMODULE hModule,
  [out]          LPSTR   lpFilename,
  [in]           DWORD   nSize
);

Параметры

[in] hProcess

Дескриптор процесса, содержащего модуль.

Дескриптор должен иметь PROCESS_QUERY_INFORMATION и PROCESS_VM_READ права доступа. Дополнительные сведения см. в "Безопасность процессов и доступ".

Windows 10 и более поздних версий Windows Server 2016 и более позднихверсий: если параметр hModule имеет значение NULL, то для дескриптора требуется только PROCESS_QUERY_LIMITED_INFORMATION права доступа.

Функция GetModuleFileNameEx не извлекает путь для модулей, загруженных с помощью флага LOAD_LIBRARY_AS_DATAFILE. Дополнительные сведения см. в разделе LoadLibraryEx.

[in, optional] hModule

Дескриптор модуля. Если этот параметр имеет значение NULL, GetModuleFileNameEx возвращает путь исполняемого файла процесса, указанного в hProcess.

[out] lpFilename

Указатель на буфер, получающий полный путь к модулю. Если размер имени файла превышает значение параметра nSize, функция завершается успешно, но имя файла усечено и завершается значением NULL.

[in] nSize

Размер буфера lpFilename в символах.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение указывает длину строки, скопированной в буфер.

Если функция завершается ошибкой, возвращаемое значение равно нулю. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.

Замечания

Функция getModuleFileNameEx в основном предназначена для использования отладчиками и аналогичными приложениями, которые должны извлекать сведения о модуле из другого процесса. Если список модулей в целевом процессе поврежден или еще не инициализирован, или если список модулей изменяется во время вызова функции в результате загрузки или выгрузки БИБЛИОТЕК DLL, GetModuleFileNameEx может завершиться ошибкой или вернуть неверные сведения.

Чтобы получить имя модуля в текущем процессе, используйте функцию GetModuleFileName. Это более эффективно и надежнее, чем вызов GetModuleFileNameEx с дескриптором текущего процесса.

Чтобы получить имя основного исполняемого модуля для удаленного процесса, используйте функцию GetProcessImageFileName или QueryFullProcessImageName. Это более эффективно и надежнее, чем вызов функции GetModuleFileNameEx с дескриптором модуля NULL.

Начиная с Windows 7 и Windows Server 2008 R2, Psapi.h устанавливает номера версий для функций PSAPI. Номер версии PSAPI влияет на имя, используемое для вызова функции и библиотеки, которую должна загрузить программа.

Если значение PSAPI_VERSION равно 2 или больше, эта функция определяется как K32GetModuleFileNameEx в Psapi.h и экспортируется в Kernel32.lib и Kernel32.dll. Если PSAPI_VERSION равно 1, эта функция определяется как GetModuleFileNameEx в Psapi.h и экспортируется в Psapi.lib и Psapi.dll как оболочка, которая вызывает K32GetModuleFileNameEx.

Программы, которые должны выполняться в более ранних версиях Windows, а также Windows 7 и более поздних версиях, всегда должны вызывать эту функцию как GetModuleFileNameEx. Чтобы обеспечить правильное разрешение символов, добавьте Psapi.lib в макрос TARGETLIBS и скомпилируйте программу с помощью -DPSAPI_VERSION=1. Чтобы использовать динамическую компоновку во время выполнения, загрузите Psapi.dll.

Примеры

Пример см. в разделе Перечисление всех модулей дляпроцесса.

Заметка

Заголовок psapi.h определяет GetModuleFileNameEx как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2003 [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	psapi.h
библиотеки	Kernel32.lib в Windows 7 и Windows Server 2008 R2; Psapi.lib (если PSAPI_VERSION=1) в Windows 7 и Windows Server 2008 R2; Psapi.lib в Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP
DLL	Kernel32.dll в Windows 7 и Windows Server 2008 R2; Psapi.dll (если PSAPI_VERSION=1) в Windows 7 и Windows Server 2008 R2; Psapi.dll в Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP