Função HeapWalk (heapapi.h)

Artigo
08/24/2023

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

Enumerando um heap

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