IDebugControl5::GetContextStackTraceEx method (dbgeng.h)

Article
10/21/2021

The GetContextStackTraceEx method returns the frames at the top of the call stack, starting with an arbitrary register context and returning the reconstructed register context for each stack frame. The GetContextStackTraceEx method provides inline frame support. For more information about working with inline functions, see Debugging Optimized Code and Inline Functions.

Syntax

HRESULT GetContextStackTraceEx(
  [in, optional]  PVOID                 StartContext,
  [in]            ULONG                 StartContextSize,
  [out, optional] PDEBUG_STACK_FRAME_EX Frames,
  [in]            ULONG                 FramesSize,
  [out, optional] PVOID                 FrameContexts,
  [in]            ULONG                 FrameContextsSize,
  [in]            ULONG                 FrameContextsEntrySize,
  [out, optional] PULONG                FramesFilled
);

Parameters

[in, optional] StartContext

Specifies the register context for the top of the stack.

[in] StartContextSize

Specifies the size, in bytes, of the StartContext register context.

[out, optional] Frames

Receives the stack frames. The number of elements this array holds is FrameSize. If Frames is NULL, this information is not returned.

[in] FramesSize

Specifies the number of items in the array Frames.

[out, optional] FrameContexts

Receives the reconstructed register context for each frame in the stack. The entries in this array correspond to the entries in the Frames array. The type of the thread context is the CONTEXT structure for the target's effective processor. If FrameContexts is NULL, this information is not returned.

[in] FrameContextsSize

Specifies the size, in bytes, of the memory pointed to by FrameContexts. The number of stack frames returned equals the number of contexts returned, and FrameContextsSize must equal FramesSize times FrameContextsEntrySize.

[in] FrameContextsEntrySize

Specifies the size, in bytes, of each frame context in FrameContexts.

[out, optional] FramesFilled

Receives the number of frames that were placed in the array Frames and contexts in FrameContexts. If FramesFilled is NULL, this information is not returned.

Return value

Return code	Description
S_OK	The method was successful.

This method can also return error values. For more information, see Return Values.

Remarks

The stack trace returned to Frames and FrameContexts can be printed using OutputContextStackTraceEx.

It is common for stack unwinds to restore only a subset of the registers. For example, stack unwinds will not always restore the volatile register state because the volatile registers are scratch registers and code does not need to preserve them. Registers that are not restored on unwind are left as the last value restored, so care should be taken when using the register state that might not be restored by an unwind.

Requirements

Requirement	Value
Target Platform	Desktop
Header	dbgeng.h (include Dbgeng.h, Ntddk.h)