Fonction SymLoadModuleEx (dbghelp.h)

Article
08/23/2023

Charge la table de symboles pour le module spécifié.

Syntaxe

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
);

Paramètres

[in] hProcess

Handle du processus qui a été passé à l’origine à la fonction SymInitialize .

[in] hFile

Handle du fichier pour l’image exécutable. Cet argument est principalement utilisé par les débogueurs, où le débogueur transmet le handle de fichier obtenu à partir d’un événement de débogage. La valeur NULL indique que hFile n’est pas utilisé.

[in] ImageName

Nom de l’image exécutable. Ce nom peut contenir un chemin d’accès partiel, un chemin complet ou aucun chemin du tout. Si le fichier ne peut pas être localisé par le nom fourni, le chemin de recherche du symbole est utilisé.

[in] ModuleName

Nom de raccourci pour le module. Si la valeur du pointeur est NULL, la bibliothèque crée un nom à l’aide du nom de base du fichier de symboles.

[in] BaseOfDll

Adresse de chargement du module. Si la valeur est égale à zéro, la bibliothèque obtient l’adresse de chargement à partir du fichier de symboles. L’adresse de chargement contenue dans le fichier de symboles n’est pas nécessairement l’adresse de charge réelle. Les débogueurs et les autres applications ayant une adresse de charge réelle doivent utiliser l’adresse de charge réelle lors de l’appel de cette fonction.

Si l’image est un fichier .pdb, ce paramètre ne peut pas être égal à zéro.

[in] DllSize

Taille du module, en octets. Si la valeur est zéro, la bibliothèque obtient la taille du fichier de symboles. La taille contenue dans le fichier de symboles n’est pas nécessairement la taille réelle. Les débogueurs et les autres applications ayant une taille réelle doivent utiliser la taille réelle lors de l’appel de cette fonction.

Si l’image est un fichier .pdb, ce paramètre ne peut pas être égal à zéro.

[in] Data

Pointeur vers une structure MODLOAD_DATA qui représente des en-têtes autres que l’en-tête PE standard. Ce paramètre est facultatif et peut être NULL.

[in] Flags

Ce paramètre peut être égal à zéro ou à une ou plusieurs des valeurs suivantes. Si ce paramètre est égal à zéro, la fonction charge les modules et les symboles du module.

Valeur	Signification
SLMFLAG_NO_SYMBOLS 0x4	Charge le module, mais pas les symboles du module.
SLMFLAG_VIRTUAL 0x1	Crée un module virtuel nommé ModuleName à l’adresse spécifiée dans BaseOfDll. Pour ajouter des symboles à ce module, appelez la fonction SymAddSymbol .

Valeur retournée

Si la fonction réussit, la valeur de retour est l’adresse de base du module chargé.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour récupérer des informations d’erreur étendues, appelez GetLastError.

Si le module est déjà chargé, la valeur de retour est zéro et GetLastError retourne ERROR_SUCCESS.

Remarques

Le gestionnaire de symboles crée une entrée pour le module et si l’option de chargement différé des symboles est désactivée, une tentative de chargement des symboles est effectuée. Si le chargement différé des symboles est activé, le module est marqué comme différé et les symboles ne sont pas chargés tant qu’une référence à un symbole n’est pas effectuée dans le module. Par conséquent, vous devez toujours appeler la fonction SymGetModuleInfo64 après avoir appelé SymLoadModuleEx.

Pour décharger la table de symboles, utilisez la fonction SymUnloadModule64 .

Toutes les fonctions DbgHelp, telles que celle-ci, sont à thread unique. Par conséquent, les appels de plusieurs threads à cette fonction entraîneront probablement un comportement inattendu ou une altération de la mémoire. Pour éviter cela, vous devez synchroniser tous les appels simultanés de plusieurs threads vers cette fonction.

Pour appeler la version Unicode de cette fonction, définissez DBGHELP_TRANSLATE_TCHAR.

Exemples

Pour obtenir un exemple, consultez Chargement d’un module de symboles.

Configuration requise

Condition requise	Valeur
Plateforme cible	Windows
En-tête	dbghelp.h
Bibliothèque	Dbghelp.lib
DLL	Dbghelp.dll
Composant redistribuable	DbgHelp.dll 6.0 ou version ultérieure

Voir aussi