Función SymLoadModuleEx (dbghelp.h)

Artículo
08/23/2023

Carga la tabla de símbolos para el módulo especificado.

Sintaxis

DWORD64 IMAGEAPI SymLoadModuleEx(
  [in] HANDLE        hProcess,
  [in] HANDLE        hFile,
  [in] PCSTR         ImageName,
  [in] PCSTR         ModuleName,
  [in] DWORD64       BaseOfDll,
  [in] DWORD         DllSize,
  [in] PMODLOAD_DATA Data,
  [in] DWORD         Flags
);

Parámetros

[in] hProcess

Identificador del proceso que se pasó originalmente a la función SymInitialize .

[in] hFile

Identificador del archivo para la imagen ejecutable. Este argumento se usa principalmente por los depuradores, donde el depurador pasa el identificador de archivo obtenido de un evento de depuración. Un valor de NULL indica que no se usa hFile .

[in] ImageName

Nombre de la imagen ejecutable. Este nombre puede contener una ruta de acceso parcial, una ruta de acceso completa o ninguna ruta de acceso. Si el archivo no se encuentra por el nombre proporcionado, se usa la ruta de acceso de búsqueda de símbolos.

[in] ModuleName

Un nombre de acceso directo para el módulo. Si el valor del puntero es NULL, la biblioteca crea un nombre con el nombre base del archivo de símbolos.

[in] BaseOfDll

La dirección de carga del módulo. Si el valor es cero, la biblioteca obtiene la dirección de carga del archivo de símbolos. La dirección de carga contenida en el archivo de símbolos no es necesariamente la dirección de carga real. Los depuradores y otras aplicaciones que tienen una dirección de carga real deben usar la dirección de carga real al llamar a esta función.

Si la imagen es un archivo .pdb, este parámetro no puede ser cero.

[in] DllSize

Tamaño del módulo, en bytes. Si el valor es cero, la biblioteca obtiene el tamaño del archivo de símbolos. El tamaño contenido en el archivo de símbolos no es necesariamente el tamaño real. Los depuradores y otras aplicaciones que tienen un tamaño real deben usar el tamaño real al llamar a esta función.

Si la imagen es un archivo .pdb, este parámetro no puede ser cero.

[in] Data

Puntero a una estructura de MODLOAD_DATA que representa encabezados distintos del encabezado PE estándar. Este parámetro es opcional y puede ser NULL.

[in] Flags

Este parámetro puede ser cero o uno o varios de los valores siguientes. Si este parámetro es cero, la función carga los módulos y los símbolos del módulo.

Valor	Significado
SLMFLAG_NO_SYMBOLS 0x4	Carga el módulo, pero no los símbolos del módulo.
SLMFLAG_VIRTUAL 0x1	Crea un módulo virtual denominado ModuleName en la dirección especificada en BaseOfDll. Para agregar símbolos a este módulo, llame a la función SymAddSymbol .

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es la dirección base del módulo cargado.

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

Si el módulo ya está cargado, el valor devuelto es cero y GetLastError devuelve ERROR_SUCCESS.

Comentarios

El controlador de símbolos crea una entrada para el módulo y, si la opción de carga de símbolos diferida está desactivada, se intenta cargar los símbolos. Si la carga de símbolos diferida está habilitada, el módulo se marca como diferido y los símbolos no se cargan hasta que se realiza una referencia a un símbolo del módulo. Por lo tanto, siempre debe llamar a la función SymGetModuleInfo64 después de llamar a SymLoadModuleEx.

Para descargar la tabla de símbolos, use la función SymUnloadModule64 .

Todas las funciones DbgHelp, como esta, son un único subproceso. Por lo tanto, es probable que las llamadas desde más de un subproceso a esta función producirán un comportamiento inesperado o daños en la memoria. Para evitarlo, debe sincronizar todas las llamadas simultáneas de más de un subproceso a esta función.

Para llamar a la versión Unicode de esta función, defina DBGHELP_TRANSLATE_TCHAR.