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

Статья
11/20/2024

Извлекает базовое имя указанного модуля.

Синтаксис

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

Параметры

[in] hProcess

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

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

[in, optional] hModule

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

[out] lpBaseName

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

[in] nSize

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

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

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

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

Замечания

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

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

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

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

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

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

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

Примеры

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

Заметка

Заголовок psapi.h определяет GetModuleBaseName как псевдоним, который автоматически выбирает версию 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