SymLoadModuleExW, fonction (dbghelp.h)

Article
11/20/2024

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

Syntaxe

DWORD64 IMAGEAPI SymLoadModuleExW(
  [in] HANDLE        hProcess,
  [in] HANDLE        hFile,
  [in] PCWSTR        ImageName,
  [in] PCWSTR        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 vers le fichier de 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. Une valeur de 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 d’accès complet ou aucun chemin d’accès. Si le fichier ne peut pas être localisé par le nom fourni, le chemin de recherche des symboles est utilisé.

[in] ModuleName

Nom du 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 chargement réelle. Les débogueurs et d’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 égale à 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 d’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 de retour

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 égale à 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 de symbole différée est désactivée, une tentative est effectuée pour charger les symboles. Si le chargement des symboles différés est activé, le module est marqué comme différé et les symboles ne sont pas chargés tant qu’une référence n’est pas faite à un symbole 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, comme celle-ci, sont monothread. Par conséquent, les appels de plusieurs threads à cette fonction entraîneront probablement une altération inattendue du comportement ou 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.

Note

L’en-tête dbghelp.h définit SymLoadModuleEx comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.