Funzione HeapWalk (heapapi.h)
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
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 |