Fonction StackWalkEx (dbghelp.h)
Obtient une trace de pile.
Syntaxe
BOOL IMAGEAPI StackWalkEx(
[in] DWORD MachineType,
[in] HANDLE hProcess,
[in] HANDLE hThread,
[in, out] LPSTACKFRAME_EX StackFrame,
[in, out] PVOID ContextRecord,
[in, optional] PREAD_PROCESS_MEMORY_ROUTINE64 ReadMemoryRoutine,
[in, optional] PFUNCTION_TABLE_ACCESS_ROUTINE64 FunctionTableAccessRoutine,
[in, optional] PGET_MODULE_BASE_ROUTINE64 GetModuleBaseRoutine,
[in, optional] PTRANSLATE_ADDRESS_ROUTINE64 TranslateAddress,
[in] DWORD Flags
);
Paramètres
[in] MachineType
Type d’architecture de l’ordinateur pour lequel la trace de pile est générée. Ce paramètre peut prendre les valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Intel x86 |
|
Intel Itanium |
|
x64 (AMD64 ou EM64T) |
[in] hProcess
Handle du processus pour lequel la trace de pile est générée. Si l’appelant fournit un pointeur de rappel valide pour le paramètre ReadMemoryRoutine , cette valeur ne doit pas être un handle de processus valide. Il peut s’agir d’un jeton unique et cohérent pour tous les appels à la fonction StackWalkEx . Si le gestionnaire de symboles est utilisé avec StackWalkEx, utilisez les mêmes handles de processus pour les appels à chaque fonction.
[in] hThread
Handle pour le thread pour lequel la trace de pile est générée. Si l’appelant fournit un pointeur de rappel valide pour le paramètre ReadMemoryRoutine , cette valeur n’a pas besoin d’être un handle de thread valide. Il peut s’agir d’un jeton unique et cohérent pour tous les appels à la fonction StackWalkEx .
[in, out] StackFrame
Pointeur vers une structure STACKFRAME_EX . Cette structure reçoit des informations pour l’image suivante, si l’appel de fonction réussit.
[in, out] ContextRecord
Pointeur vers une structure CONTEXT . Ce paramètre est requis uniquement lorsque le paramètre MachineType n’est pas IMAGE_FILE_MACHINE_I386. Toutefois, il est recommandé que ce paramètre contienne un enregistrement de contexte valide. Cela permet à StackWalkEx de gérer une plus grande variété de situations.
Ce contexte peut être modifié. Par conséquent, ne passez pas d’enregistrement de contexte qui ne doit pas être modifié.
[in, optional] ReadMemoryRoutine
Routine de rappel qui fournit des services de lecture de mémoire. Lorsque la fonction StackWalkEx doit lire la mémoire à partir de l’espace d’adressage du processus, le rappel ReadProcessMemoryProc64 est utilisé.
Si ce paramètre a la valeur NULL, la fonction utilise une routine par défaut. Dans ce cas, le paramètre hProcess doit être un handle de processus valide.
Si ce paramètre n’est pas NULL, l’application doit implémenter et inscrire une fonction de rappel de gestionnaire de symboles qui gère CBA_READ_MEMORY.
[in, optional] FunctionTableAccessRoutine
Routine de rappel qui fournit l’accès à la table de fonctions d’exécution pour le processus. Ce paramètre est obligatoire, car la fonction StackWalkEx n’a pas accès à la table de fonctions d’exécution du processus. Pour plus d’informations, consultez FunctionTableAccessProc64.
Le gestionnaire de symboles fournit des fonctions qui chargent et accèdent à la table d’exécution. Si ces fonctions sont utilisées, SymFunctionTableAccess64 peut être passé en tant que paramètre valide.
[in, optional] GetModuleBaseRoutine
Routine de rappel qui fournit une base de module pour une adresse virtuelle donnée. Ce paramètre est obligatoire. Pour plus d’informations, consultez GetModuleBaseProc64.
Le gestionnaire de symboles fournit des fonctions qui chargent et gèrent les informations de module. Si ces fonctions sont utilisées, SymGetModuleBase64 peut être passé en tant que paramètre valide.
[in, optional] TranslateAddress
Routine de rappel qui fournit la traduction d’adresses pour les adresses 16 bits. Pour plus d’informations, consultez TranslateAddressProc64.
La plupart des appelants de StackWalkEx peuvent passer en toute sécurité null pour ce paramètre.
[in] Flags
Combinaison de zéro ou plusieurs indicateurs.
SYM_STKWALK_DEFAULT (0)
SYM_STKWALK_FORCE_FRAMEPTR (1)
Valeur retournée
Si la fonction réussit, la valeur de retour est TRUE.
Si la fonction échoue, la valeur de retour est FALSE. Notez que StackWalkEx ne définit généralement pas le dernier code d’erreur.
Remarques
La fonction StackWalkEx fournit une méthode portable pour obtenir une trace de pile. L’utilisation de la fonction StackWalkEx est recommandée plutôt que l’écriture de votre propre fonction en raison de toutes les complexités associées à la marche de la pile sur les plateformes. En outre, il existe des options de compilateur qui entraînent l’affichage de la pile différemment, selon la façon dont le module est compilé. En utilisant cette fonction, votre application dispose d’une trace de pile portable qui continue de fonctionner en tant que modification du compilateur et du système d’exploitation.
Le premier appel à cette fonction échoue si addrPC,
Les membres AddrFrame et AddrStack de la structure STACKFRAME64 passées dans le paramètre StackFrame ne sont pas initialisés.
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.
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.2 ou version ultérieure |