StackWalkEx 函式 (dbghelp.h)

發行項
02/26/2024

取得堆疊追蹤。

語法

BOOL IMAGEAPI StackWalkEx(
  [in]           DWORD                            MachineType,
  [in]           HANDLE                           hProcess,
  [in]           HANDLE                           hThread,
  [in, out]      LPSTACKFRAME_EX                  StackFrame,
  [in, out]      PVOID                            ContextRecord,
  [in, optional] PREAD_PROCESS_MEMORY_ROUTINE64   ReadMemoryRoutine,
  [in, optional] PFUNCTION_TABLE_ACCESS_ROUTINE64 FunctionTableAccessRoutine,
  [in, optional] PGET_MODULE_BASE_ROUTINE64       GetModuleBaseRoutine,
  [in, optional] PTRANSLATE_ADDRESS_ROUTINE64     TranslateAddress,
  [in]           DWORD                            Flags
);

參數

[in] MachineType

產生堆疊追蹤之電腦的架構類型。此參數可以是下列其中一個值。

值	意義
IMAGE_FILE_MACHINE_I386 0x014c	Intel x86
IMAGE_FILE_MACHINE_IA64 0x0200	Intel Itanium
IMAGE_FILE_MACHINE_AMD64 0x8664	x64 (AMD64 或 EM64T)

[in] hProcess

產生堆疊追蹤之進程的句柄。如果呼叫端為 ReadMemoryRoutine 參數提供有效的回呼指標，則這個值不需要是有效的進程句柄。它可以是唯一且一致地對 StackWalkEx 函 式的所有呼叫相同的令牌。如果符號處理程式與 StackWalkEx 搭配使用，請針對每個函式的呼叫使用相同的進程句柄。

[in] hThread

產生堆疊追蹤之線程的句柄。如果呼叫端為 ReadMemoryRoutine 參數提供有效的回呼指標，則這個值不需要是有效的線程句柄。它可以是唯一且一致地對 StackWalkEx 函 式的所有呼叫相同的令牌。

[in, out] StackFrame

STACKFRAME_EX 結構的指標。如果函數調用成功，這個結構就會接收下一個框架的資訊。

[in, out] ContextRecord

CONTEXT 結構的指標。只有在 MachineType 參數未 IMAGE_FILE_MACHINE_I386時，才需要此參數。不過，建議此參數包含有效的內容記錄。這可讓 StackWalkEx 處理各種情況。

此內容可以修改，因此不要傳遞不應修改的內容記錄。

[in, optional] ReadMemoryRoutine

提供記憶體讀取服務的回呼例程。當 StackWalkEx 函式需要從進程的位址空間讀取記憶體時，會使用 ReadProcessMemoryProc64 回呼。

如果此參數為 NULL，則函式會使用預設例程。在此情況下， hProcess 參數必須是有效的進程句柄。

如果此參數不是 NULL，應用程式應該實作並註冊可處理 CBA_READ_MEMORY的符號處理程式回呼函式。

[in, optional] FunctionTableAccessRoutine

回呼例程，提供進程運行時間函式數據表的存取權。這是必要參數，因為 StackWalkEx 函式無法存取進程的運行時間函式數據表。如需詳細資訊，請參閱 FunctionTableAccessProc64。

符號處理程式提供載入和存取運行時間數據表的函式。如果使用這些函式，則 SymFunctionTableAccess64 可以傳遞為有效的參數。

[in, optional] GetModuleBaseRoutine

回呼例程，提供任何指定虛擬位址的模組基底。此為必要參數。如需詳細資訊，請參閱 GetModuleBaseProc64。

符號處理程式會提供載入和維護模組資訊的函式。如果使用這些函式，則 SymGetModuleBase64 可以傳遞為有效的參數。

[in, optional] TranslateAddress

回呼例程，提供16位位址的位址轉譯。如需詳細資訊，請參閱 TranslateAddressProc64。

StackWalkEx 的大部分呼叫端都可以安全地傳遞此參數的 NULL。

[in] Flags

零個或多個旗標的組合。

SYM_STKWALK_DEFAULT (0)

SYM_STKWALK_FORCE_FRAMEPTR (1)

傳回值

如果函式成功，則傳回值為 TRUE。

如果函式失敗，傳回值為 FALSE。請注意， StackWalkEx 通常不會設定最後一個錯誤碼。

備註

StackWalkEx 函式提供可攜式方法來取得堆棧追蹤。建議使用 StackWalkEx 函式來撰寫您自己的函式，因為與平臺上的堆疊逐步執行相關聯的所有複雜度。此外，還有一些編譯程式選項會根據模組的編譯方式，以不同的方式顯示堆疊。藉由使用此函式，您的應用程式具有可攜式堆疊追蹤，可在編譯程式和操作系統變更時繼續運作。

如果 AddrPC，第一次呼叫此函式將會失敗，
不會初始化 StackFrame 參數中所傳遞STACKFRAME64結構的 AddrFrame 和 AddrStack 成員。

所有 DbgHelp 函式，例如此函式都是單個線程。因此，從一個以上的線程呼叫此函式可能會導致非預期的行為或記憶體損毀。若要避免這種情況，您必須將所有並行呼叫從一個以上的線程同步至此函式。