GetThreadCallStack (Compact 2013)

3/28/2014

This function obtains the call stack of a thread in the system.

Syntax

ULONG GetThreadCallStack(
  HANDLE hThrd,
  ULONG dwMaxFrames,
  LPVOID lpFrames[],
  DWORD dwFlags,
  DWORD dwSkip
);

Parameters

• hThrd
  [in] Handle to the thread.

• dwMaxFrames
  [in] Maximum number of frames.

• lpFrames
  [in] Array of CallSnapshot, CallSnapshotEx, or CallSnapshot3 structures to receive the stack frames.

• dwFlags
  [in] Bit flag to indicate what operation is to be performed.

  The following table shows possible values. These values can be used together in any combination.

  Value	Description
  STACKSNAP_EXTENDED_INFO	Enables the function to return additional stack information, such as the frame pointer, current process, and function parameters. See the Remarks section for more information about this flag.
  STACKSNAP_FAIL_IF_INCOMPLETE	Indicates that the function fails if dwMaxFrames is less than the number of frames.
  STACKSNAP_INPROC_ONLY	Causes the function to return only the stack frames that are within the thread's owner process. It does not include stack frames that are outside the thread's owner process.
  STACKSNAP_NEW_VM	Enables the function to return additional call stack information, such as the frame pointer, the current process, the current process whose VM is active, and function parameters.
  STACKSNAP_RETURN_FRAMES_ON_ERROR	Returns the number of frames found, even if an error occurs. The SetLastError function is set. If this flag is on, the last error is always set, even when there is no error.

• dwSkip
  [in] Number of frames to be skipped.

Return Value

The number of frames copied into lpFrames array indicates success. Zero indicates failure. Call GetLastError to get extended error information.

Remarks

Keep the following points in mind when using GetThreadCallStack:

• The priority of the caller thread of this function might be temporarily boosted to a higher priority than the priority of hThrd. This prevents hThrd from running while looking into its context. Calling this function can have an impact on the real-time behavior of hThrd.

• The number of frames is dynamic. However, by using dwSkip, you can use the following loop to retrieve the full call stacks of a thread:

  CallSnapshot lpFrames[MAX_FRAMES];
  DWORD dwCnt, dwSkip = 0;
  do
  {
     dwCnt = GetThreadCallStack (hThread, MAX_FRAMES, lpFrames, 0, dwSkip);
     if (dwCnt)
     {
        // Process the frames retrieved so far
        MyProcessFrames (dwCnt, lpFrames);
        dwSkip += dwCnt;
     }
  }
  while (MAX_FRAMES == dwCnt);
  

• An untrusted application can obtain the call stack of only threads within its own process.**

Keep the following points in mind when passing the STACKSNAP_EXTENDED_INFO or STACKSNAP_NEW_VM flags:

• If passing STACKSNAP_EXTENDED_INFO, Windows Embedded Compact treats the lpFrames passed in as a CallSnapshotEx structure and passes back extended information for each frame, including the frame pointer, current process, four parameters, and return address.
• If passing STACKSNAP_NEW_VM, Windows Embedded Compact treats the lpFrames passed in as a CallSnapshot3structure and passes back extended information for each frame, including the frame pointer, current process, four parameters, return address, and the process whose VM is active
• If neither flag is passed, Windows Embedded Compact treats lpFrames as a CallSnapshot structure and passes back only the return addresses.

Requirements

See Also

Reference

Kernel Functions
CallSnapshot
CallSnapshotEx
SetLastError