HeapWalk-Funktion (heapapi.h)

Artikel
08/24/2023

Listet die Speicherblöcke im angegebenen Heap auf.

Syntax

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

Parameter

[in] hHeap

Ein Handle für den Heap. Dieses Handle wird entweder von der HeapCreate- oder getProcessHeap-Funktion zurückgegeben.

[in, out] lpEntry

Ein Zeiger auf eine PROCESS_HEAP_ENTRY-Struktur , die Zustandsinformationen für eine bestimmte Heapaufzählung verwaltet.

Wenn die HeapWalk-Funktion erfolgreich ist und der Wert TRUE zurückgegeben wird, enthalten die Member dieser Struktur Informationen zum nächsten Speicherblock im Heap.

Um eine Heapaufzählung zu initiieren, legen Sie das LpData-Feld der PROCESS_HEAP_ENTRY-Struktur auf NULL fest. Um eine bestimmte Heapaufzählung fortzusetzen, rufen Sie die HeapWalk-Funktion wiederholt auf, ohne Änderungen an hHeap, lpEntry oder einem der Member der PROCESS_HEAP_ENTRY-Struktur vorzunehmen.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Wenn die Heapaufzählung erfolgreich beendet wird, indem sie das Ende des Heaps erreicht, gibt die Funktion FALSE zurück, und GetLastError gibt den Fehlercode ERROR_NO_MORE_ITEMS zurück.

Hinweise

Die HeapWalk-Funktion ist in erster Linie für das Debuggen nützlich, da das Aufzählen eines Heaps möglicherweise zeitaufwendig ist. Das Sperren des Heaps während der Enumeration hindert andere Threads am Zugriff auf den Heap und kann die Leistung beeinträchtigen, insbesondere auf SMP-Computern (Symmetric Multiprocessing). Die Nebenwirkungen können anhalten, bis der Heap entsperrt ist. Verwenden Sie die Funktionen HeapLock und HeapUnlock , um die Heapsperre während der Heapaufzählung zu steuern.

Um eine Heapaufzählung zu initiieren, rufen Sie HeapWalk auf, wobei das LpData-Feld der PROCESS_HEAP_ENTRY-Struktur verweist, auf die von lpEntry auf NULL festgelegt ist.

Um eine Heapaufzählung fortzusetzen, rufen Sie HeapWalk mit den gleichen hHeap - und lpEntry-Werten und mit der PROCESS_HEAP_ENTRY-Struktur auf, die gegenüber dem vorherigen Aufruf von HeapWalk unverändert ist. Wiederholen Sie diesen Vorgang, bis Sie keine weitere Enumeration benötigen oder bis die Funktion FALSE zurückgibt und GetLastErrorERROR_NO_MORE_ITEMS zurückgibt. Dies bedeutet, dass alle Speicherblöcke des Heaps aufgelistet wurden.

Es ist kein spezieller Aufruf von HeapWalk erforderlich, um die Heapaufzählung zu beenden, da keine Enumerationszustandsdaten außerhalb des Inhalts der PROCESS_HEAP_ENTRY-Struktur verwaltet werden.

HeapWalk kann in einer Multithreadanwendung fehlschlagen, wenn der Heap während der Heapaufzählung nicht gesperrt ist.

Beispiele

Auflisten eines Heaps

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	heapapi.h (windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll