GetContextStackTrace

The GetContextStackTrace 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.

HRESULT
  IDebugControl4::GetContextStackTrace(
    IN OPTIONAL PVOID  StartContext,
    IN ULONG  StartContextSize,
    OUT OPTIONAL PDEBUG_STACK_FRAME  Frames,
    IN ULONG  FramesSize,
    OUT OPTIONAL PVOID  FrameContexts,
    IN ULONG  FrameContextsSize,
    IN ULONG  FrameContextsEntrySize,
    OUT OPTIONAL PULONG  FramesFilled
    );

Parameters

StartContext

Specifies the register context for the top of the stack.

StartContextSize

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

Frames

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

FramesSize

Specifies the number of items in the array Frames.

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.

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.

FrameContextsEntrySize

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

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

S_OK

The method was successful.

This method may also return error values. See Return Values for more details.

Interface Version

GetContextStackTrace is available in IDebugControl4 and later versions.

Comments

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

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

Headers: Defined in Dbgeng.h. Include Dbgeng.h. CONTEXT is defined in Ntddk.h.

See Also

GetStackTrace, k, kb, kd, kp, kP, kv (Display Stack Backtrace), OutputContextStackTrace,