Função HeapWalk (heapapi.h)
Enumera os blocos de memória no heap especificado.
Sintaxe
BOOL HeapWalk(
[in] HANDLE hHeap,
[in, out] LPPROCESS_HEAP_ENTRY lpEntry
);
Parâmetros
[in] hHeap
Um identificador para o heap. Esse identificador é retornado pela função HeapCreate ou GetProcessHeap .
[in, out] lpEntry
Um ponteiro para uma estrutura PROCESS_HEAP_ENTRY que mantém informações de estado para uma enumeração de heap específica.
Se a função HeapWalk for bem-sucedida, retornando o valor TRUE, os membros dessa estrutura contêm informações sobre o próximo bloco de memória no heap.
Para iniciar uma enumeração de heap, defina o campo lpData da estrutura PROCESS_HEAP_ENTRY como NULL. Para continuar uma enumeração de heap específica, chame a função HeapWalk repetidamente, sem alterações em hHeap, lpEntry ou qualquer um dos membros da estrutura PROCESS_HEAP_ENTRY .
Valor retornado
Se a função for bem-sucedida, o valor retornado será diferente de zero.
Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.
Se a enumeração heap for encerrada com êxito ao chegar ao final do heap, a função retornará FALSE e GetLastError retornará o código de erro ERROR_NO_MORE_ITEMS.
Comentários
A função HeapWalk é útil principalmente para depuração porque enumerar um heap é uma operação potencialmente demorada. Bloquear o heap durante a enumeração impede que outros threads acessem o heap e podem degradar o desempenho, especialmente em computadores SMP (multiprocessamento simétrico). Os efeitos colaterais podem durar até que o heap seja desbloqueado. Use as funções HeapLock e HeapUnlock para controlar o bloqueio de heap durante a enumeração de heap.
Para iniciar uma enumeração de heap, chame HeapWalk com o campo lpData da estrutura PROCESS_HEAP_ENTRY apontada por lpEntry definido como NULL.
Para continuar uma enumeração de heap, chame HeapWalk com os mesmos valores hHeap e lpEntry e com a estrutura PROCESS_HEAP_ENTRY inalterada da chamada anterior para HeapWalk. Repita esse processo até que você não precise de mais enumeração ou até que a função retorne FALSE e GetLastError retorne ERROR_NO_MORE_ITEMS, indicando que todos os blocos de memória do heap foram enumerados.
Nenhuma chamada especial do HeapWalk é necessária para encerrar a enumeração de heap, pois nenhum dado de estado de enumeração é mantido fora do conteúdo da estrutura de PROCESS_HEAP_ENTRY .
O HeapWalk poderá falhar em um aplicativo multithread se o heap não estiver bloqueado durante a enumeração de heap.
Exemplos
Requisitos
| Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | heapapi.h (inclua Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |