heapWalk 函式 (heapapi.h)

發行項
08/24/2023

列舉指定堆積中的記憶體區塊。

語法

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

參數

[in] hHeap

堆積的控制碼。 HeapCreate或GetProcessHeap函式會傳回此控制碼。

[in, out] lpEntry

PROCESS_HEAP_ENTRY結構的指標，可維護特定堆積列舉的狀態資訊。

如果 HeapWalk 函式成功，傳回 TRUE值，這個結構的成員會包含堆積中下一個記憶體區塊的相關資訊。

若要起始堆積列舉，請將PROCESS_HEAP_ENTRY結構的lpData欄位設定為Null。若要繼續特定的堆積列舉，請重複呼叫 HeapWalk 函式，不變更 hHeap、 lpEntry或 PROCESS_HEAP_ENTRY 結構的任何成員。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

如果堆積列舉藉由到達堆積的結尾成功終止，函式會傳回 FALSE，而 GetLastError 會傳回錯誤碼 ERROR_NO_MORE_ITEMS。

備註

HeapWalk函式主要用於偵錯，因為列舉堆積是可能耗時的作業。在列舉期間鎖定堆積會封鎖其他執行緒存取堆積，而且可能會降低效能，特別是在對稱式多處理 (SMP) 電腦上。副作用可以持續到堆積解除鎖定為止。使用 HeapLock 和 HeapUnlock 函式來控制堆積列舉期間的堆積鎖定。

若要起始堆積列舉，請使用lpEntry設定為Null所指向之PROCESS_HEAP_ENTRY結構的lpData欄位呼叫HeapWalk。

若要繼續堆積列舉，請使用相同的hHeap和lpEntry值呼叫HeapWalk，並使用與先前對HeapWalk呼叫相同的PROCESS_HEAP_ENTRY結構來呼叫 HeapWalk。重複此程式，直到您不需要進一步列舉，或直到函式傳回 FALSE 且 GetLastError 傳回 ERROR_NO_MORE_ITEMS為止，指出已列舉所有堆積的記憶體區塊。

不需要任何特殊的 HeapWalk 呼叫即可終止堆積列舉，因為不會在 PROCESS_HEAP_ENTRY 結構的內容之外維護列舉狀態資料。

如果堆積列舉期間未鎖定堆積，HeapWalk在多執行緒應用程式中可能會失敗。

範例

列舉堆積

需求


最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限桌面應用程式]
目標平台	Windows
標頭	heapapi.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll