HeapWalk 関数 (heapapi.h)
指定したヒープ内のメモリ ブロックを列挙します。
構文
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 構造体のメンバーは変更されません。
戻り値
関数が成功すると、戻り値は 0 以外になります。
関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。
ヒープの末尾に達してヒープ列挙が正常に終了した場合、関数は FALSE を返し、GetLastError はエラー コード ERROR_NO_MORE_ITEMSを返します。
解説
HeapWalk 関数は、ヒープの列挙が時間のかかる可能性があるため、デバッグに主に役立ちます。 列挙中にヒープをロックすると、他のスレッドがヒープにアクセスできなくなります。特に、対称マルチプロセッシング (SMP) コンピューターではパフォーマンスが低下する可能性があります。 副作用は、ヒープのロックが解除されるまで続く可能性があります。 ヒープ列挙中にヒープ ロックを制御するには、 HeapLock 関数と HeapUnlock 関数を使用します。
ヒープ列挙を開始するには、lpEntry が指すPROCESS_HEAP_ENTRY構造体の lpData フィールドを NULL に設定して HeapWalk を呼び出します。
ヒープ列挙を続行するには、同じ hHeap 値と lpEntry 値を使用して 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 を含む) |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |