Funzione HeapWalk (heapapi.h)

Articolo
08/24/2023

Enumera i blocchi di memoria nell'heap specificato.

Sintassi

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

Parametri

[in] hHeap

Handle all'heap. Questo handle viene restituito dalla funzione HeapCreate o GetProcessHeap .

[in, out] lpEntry

Puntatore a una struttura PROCESS_HEAP_ENTRY che gestisce le informazioni sullo stato per un'enumerazione heap specifica.

Se la funzione HeapWalk ha esito positivo, restituisce il valore TRUE, i membri di questa struttura contengono informazioni sul blocco di memoria successivo nell'heap.

Per avviare un'enumerazione heap, impostare il campo lpData della struttura PROCESS_HEAP_ENTRY su NULL. Per continuare un'enumerazione heap specifica, chiamare ripetutamente la funzione HeapWalk , senza modifiche a hHeap, lpEntry o uno dei membri della struttura PROCESS_HEAP_ENTRY .

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Se l'enumerazione heap termina correttamente raggiungendo la fine dell'heap, la funzione restituisce FALSE e GetLastError restituisce il codice di errore ERROR_NO_MORE_ITEMS.

Commenti

La funzione HeapWalk è principalmente utile per il debug perché l'enumerazione di un heap è un'operazione potenzialmente dispendiosa. Il blocco dell'heap durante l'enumerazione blocca altri thread dall'accesso all'heap e può ridurre le prestazioni, in particolare nei computer SMP (simmetrici). Gli effetti collaterali possono durare fino a quando l'heap non viene sbloccato. Usare le funzioni HeapLock e HeapUnlock per controllare il blocco heap durante l'enumerazione heap.

Per avviare un'enumerazione heap, chiamare HeapWalk con il campo lpData della struttura PROCESS_HEAP_ENTRY a cui punta lpEntry impostato su NULL.

Per continuare un'enumerazione heap, chiamare HeapWalk con gli stessi valori hHeap e lpEntry e con la struttura PROCESS_HEAP_ENTRY invariata dalla chiamata precedente a HeapWalk. Ripetere questo processo fino a quando non è necessaria ulteriore enumerazione o finché la funzione restituisce FALSE e GetLastError restituisce ERROR_NO_MORE_ITEMS, indicando che tutti i blocchi di memoria dell'heap sono stati enumerati.

Non è necessaria alcuna chiamata speciale di HeapWalk per terminare l'enumerazione heap, poiché non vengono mantenuti dati di stato di enumerazione all'esterno del contenuto della struttura PROCESS_HEAP_ENTRY.

HeapWalk può non riuscire in un'applicazione multithreaded se l'heap non è bloccato durante l'enumerazione heap.

Esempio

Enumerazione di un heap

Requisiti


Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	heapapi.h (includere Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll