Función HeapWalk (heapapi.h)

Artículo
08/24/2023

Enumera los bloques de memoria del montón especificado.

Sintaxis

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

Parámetros

[in] hHeap

Identificador del montón. La función HeapCreate o GetProcessHeap devuelve este identificador.

[in, out] lpEntry

Puntero a una estructura PROCESS_HEAP_ENTRY que mantiene información de estado para una enumeración de montón determinada.

Si la función HeapWalk se realiza correctamente, devolviendo el valor TRUE, los miembros de esta estructura contienen información sobre el siguiente bloque de memoria del montón.

Para iniciar una enumeración de montón, establezca el campo lpData de la estructura PROCESS_HEAP_ENTRY en NULL. Para continuar con una enumeración de montón determinada, llame repetidamente a la función HeapWalk , sin cambios en hHeap, lpEntry o ninguno de los miembros de la estructura de PROCESS_HEAP_ENTRY .

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Si la enumeración del montón finaliza correctamente llegando al final del montón, la función devuelve FALSE y GetLastError devuelve el código de error ERROR_NO_MORE_ITEMS.

Comentarios

La función HeapWalk es principalmente útil para la depuración, ya que la enumeración de un montón es una operación potencialmente lenta. Bloquear el montón durante la enumeración impide que otros subprocesos accedan al montón y pueden degradar el rendimiento, especialmente en equipos de multiprocesamiento simétrico (SMP). Los efectos secundarios pueden durar hasta que se desbloquea el montón. Use las funciones HeapLock y HeapUnlock para controlar el bloqueo del montón durante la enumeración del montón.

Para iniciar una enumeración de montón, llame a HeapWalk con el campo lpData de la estructura de PROCESS_HEAP_ENTRY a la que apunta lpEntry establecido en NULL.

Para continuar con una enumeración de montón, llame a HeapWalk con los mismos valores hHeap y lpEntry , y con la estructura PROCESS_HEAP_ENTRY sin cambios de la llamada anterior a HeapWalk. Repita este proceso hasta que no necesite enumeración adicional o hasta que la función devuelva FALSE y GetLastError devuelva ERROR_NO_MORE_ITEMS, lo que indica que se han enumerado todos los bloques de memoria del montón.

No se necesita ninguna llamada especial de HeapWalk para finalizar la enumeración del montón, ya que no se mantienen datos de estado de enumeración fuera del contenido de la estructura PROCESS_HEAP_ENTRY .

HeapWalk puede producir un error en una aplicación multiproceso si el montón no está bloqueado durante la enumeración del montón.

Ejemplos

Enumeración de un montón

Requisitos


Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	heapapi.h (incluya Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll