Función GetModuleBaseNameA (psapi.h)

Artículo
08/25/2023

Recupera el nombre base del módulo especificado.

Sintaxis

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

Parámetros

[in] hProcess

Identificador del proceso que contiene el módulo.

El identificador debe tener los derechos de acceso PROCESS_QUERY_INFORMATION y PROCESS_VM_READ . Para obtener más información, consulte Derechos de acceso y seguridad de procesos.

[in, optional] hModule

Identificador del módulo. Si este parámetro es NULL, esta función devuelve el nombre del archivo utilizado para crear el proceso de llamada.

[out] lpBaseName

Puntero al búfer que recibe el nombre base del módulo. Si el nombre base es mayor que el número máximo de caracteres especificado por el parámetro nSize , el nombre base se trunca.

[in] nSize

Tamaño del búfer lpBaseName , en caracteres.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto especifica la longitud de la cadena copiada en el búfer, en caracteres.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

La función GetModuleBaseName está diseñada principalmente para que la usen los depuradores y aplicaciones similares que deben extraer información del módulo de otro proceso. Si la lista de módulos del proceso de destino está dañada o aún no se ha inicializado, o si la lista de módulos cambia durante la llamada de función como resultado de que los archivos DLL se cargan o se descargan, GetModuleBaseName puede producir un error o devolver información incorrecta.

Para recuperar el nombre base de un módulo en el proceso actual, use la función GetModuleFileName para recuperar el nombre completo del módulo y, a continuación, use una llamada de función como strrchr(szmodulename, '\') para examinar hasta el principio del nombre base dentro de la cadena de nombre del módulo. Esto es más eficaz y más confiable que llamar a GetModuleBaseName con un identificador para el proceso actual.

Para recuperar el nombre base del módulo ejecutable principal para un proceso remoto, use la función GetProcessImageFileName o QueryFullProcessImageName para recuperar el nombre del módulo y, a continuación, use la strrchr función como se describe en el párrafo anterior. Esto es más eficaz y más confiable que llamar a GetModuleBaseName con un identificador de módulo NULL.

La función GetModuleBaseName no recupera el nombre base de los módulos cargados con la marca LOAD_LIBRARY_AS_DATAFILE . Para obtener más información, consulte LoadLibraryEx.

A partir de Windows 7 y Windows Server 2008 R2, Psapi.h establece números de versión para las funciones psapi. El número de versión de PSAPI afecta al nombre usado para llamar a la función y la biblioteca que debe cargar un programa.

Si PSAPI_VERSION es 2 o superior, esta función se define como K32GetModuleBaseName en Psapi.h y exportada en Kernel32.lib y Kernel32.dll. Si PSAPI_VERSION es 1, esta función se define como GetModuleBaseName en Psapi.h y exportada en Psapi.lib y Psapi.dll como contenedor que llama a K32GetModuleBaseName.

Los programas que se deben ejecutar en versiones anteriores de Windows, así como Windows 7 y versiones posteriores siempre deben llamar a esta función como GetModuleBaseName. Para garantizar la resolución correcta de símbolos, agregue Psapi.lib a la macro TARGETLIBS y compile el programa con -DPSAPI_VERSION=1. Para usar la vinculación dinámica en tiempo de ejecución, cargue Psapi.dll.

Ejemplos

Para obtener un ejemplo, vea Enumerar todos los procesos.

Nota:

El encabezado psapi.h define GetModuleBaseName como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos


Cliente mínimo compatible	Windows XP [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	psapi.h
Library	Kernel32.lib en Windows 7 y Windows Server 2008 R2; Psapi.lib (si PSAPI_VERSION=1) en Windows 7 y Windows Server 2008 R2; Psapi.lib en Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP
Archivo DLL	Kernel32.dll en Windows 7 y Windows Server 2008 R2; Psapi.dll (si PSAPI_VERSION=1) en Windows 7 y Windows Server 2008 R2; Psapi.dll en Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP