Fonction HeapWalk (heapapi.h)

Article
08/24/2023

Énumère les blocs de mémoire dans le tas spécifié.

Syntaxe

BOOL HeapWalk(
  [in]      HANDLE               hHeap,
  [in, out] LPPROCESS_HEAP_ENTRY lpEntry
);

Paramètres

[in] hHeap

Une poignée au tas. Ce handle est retourné par la fonction HeapCreate ou GetProcessHeap .

[in, out] lpEntry

Pointeur vers une structure PROCESS_HEAP_ENTRY qui conserve les informations d’état d’une énumération de tas particulière.

Si la fonction HeapWalk réussit, en retournant la valeur TRUE, les membres de cette structure contiennent des informations sur le bloc de mémoire suivant dans le tas.

Pour lancer une énumération de tas, définissez le champ lpData de la structure PROCESS_HEAP_ENTRY sur NULL. Pour poursuivre une énumération de tas particulière, appelez la fonction HeapWalk à plusieurs reprises, sans aucune modification apportée à hHeap, lpEntry ou à l’un des membres de la structure PROCESS_HEAP_ENTRY .

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Si l’énumération du tas se termine correctement en atteignant la fin du tas, la fonction retourne FALSE et GetLastError retourne le code d’erreur ERROR_NO_MORE_ITEMS.

Notes

La fonction HeapWalk est principalement utile pour le débogage, car l’énumération d’un tas est une opération potentiellement chronophage. Le verrouillage du tas pendant l’énumération empêche d’autres threads d’accéder au tas et peut dégrader les performances, en particulier sur les ordinateurs multitraitement symétriques (SMP). Les effets secondaires peuvent durer jusqu’à ce que le tas soit déverrouillé. Utilisez les fonctions HeapLock et HeapUnlock pour contrôler le verrouillage du tas pendant l’énumération du tas.

Pour lancer une énumération de tas, appelez HeapWalk avec le champ lpData de la structure PROCESS_HEAP_ENTRY pointée vers lpEntry définie sur NULL.

Pour continuer une énumération de tas, appelez HeapWalk avec les mêmes valeurs hHeap et lpEntry , et avec la structure PROCESS_HEAP_ENTRY inchangée par rapport à l’appel précédent à HeapWalk. Répétez ce processus jusqu’à ce que vous n’ayez pas besoin d’énumération supplémentaire, ou jusqu’à ce que la fonction retourne FALSE et Que GetLastError retourne ERROR_NO_MORE_ITEMS, ce qui indique que tous les blocs de mémoire du tas ont été énumérés.

Aucun appel spécial de HeapWalk n’est nécessaire pour mettre fin à l’énumération du tas, car aucune donnée d’état d’énumération n’est conservée en dehors du contenu de la structure PROCESS_HEAP_ENTRY .

HeapWalk peut échouer dans une application multithread si le tas n’est pas verrouillé pendant l’énumération du tas.

Exemples

Énumération d’un tas

Configuration requise


Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	heapapi.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll