// Copyright (c) 1997-1999 Microsoft Corporation
//
// stack backtracing stuff
//
// 22-Nov-1999 sburns (refactored)



namespace Burnslib
{
   
namespace StackTrace
{
   const size_t MODULE_NAME_MAX = 32;
   const size_t SYMBOL_NAME_MAX = 256;



   // This should be called when stack tracing facilities are no longer
   // needed.

   void
   Cleanup();



   // Fill the provided array with a stack backtrace, starting with the
   // code address indicated by the context structure supplied.
   // 
   // This version is suited for use in an SEH exception handler to determine
   // the call stack at the point at which an exception was raised.
   //
   // Example:
   //
   // DWORD64 stackTrace[TRACE_MAX];
   // size_t traceMax = TRACE_MAX;
   // 
   // __try
   // {
   //    // call some code that might raise an SEH exception
   // }
   // __except(
   //    Burnslib::StackTrace::TraceFilter(
   //       stackTrace,
   //       traceMax,
   //       (GetExceptionInformation())->ContextRecord))
   // {
   //    // for each element in stackTrace, call
   //    // Burnslib::StackTrace::LookupAddress
   // }      
   //
   // Each element is an address that can be used to obtain a corresponding
   // module, function name, line number and source file name (or a subset of
   // that information, depending on the debugging symbol information
   // available), from the LookupAddress function.
   // Returns EXCEPTION_EXECUTE_HANDLER
   //
   // stackTrace - the array to receive the addresses.
   // 
   // traceMax - the maximum number of stack frames to traverse.  The
   // stackTrace array must be able to hold at least this many elements.
   // If the depth of the call stack is less than traceMax, then the
   // remaining elements are 0.

   DWORD
   TraceFilter(
      DWORD64  stackTrace[],
      size_t   traceMax,    
      CONTEXT* context);    



   // Fill the provided array with a stack backtrace, starting with the
   // invoker of this function.
   //
   // Each element is an address that can be used to obtain a corresponding
   // module, function name, line number and source file name (or a subset of
   // that information, depending on the debugging symbol information
   // available), from the LookupAddress function.
   // 
   // stackTrace - the array to receive the addresses.
   // 
   // traceMax - the maximum number of stack frames to traverse.  The
   // stackTrace array must be able to hold at least this many elements.
   // If the depth of the call stack is less than traceMax, then the
   // remaining elements are 0.

   void
   Trace(DWORD64 stackTrace[], size_t traceMax);



   // Resolves an address obtained by Trace.  ::SymSetOptions and
   // ::SymInitialize must have been called at some point before this
   // function is called.
   // 
   // traceAddress - the address to resolve.
   // 
   // moduleName - address of an array of char to receieve the name of the
   // module to which the address originates, or 0.  The array must be able
   // to hold MODULE_NAME_MAX bytes.
   // 
   // fullImageName - address of an array of char to receive the full path
   // name of the binary file from which the module was loaded, or 0.  The
   // array must be able to hold MAX_PATH bytes.
   // 
   // symbolName - address of an array of char to receive the undecorated
   // name of the function corresponding to the address, or 0.  The array
   // must be able to hold SYMBOL_NAME_MAX bytes.
   // 
   // displacement - address of a DWORD to receive the byte offset from the
   // beginning of the function that corresponds to the address, or 0.
   // 
   // line - address of a DWORD to receive the line number in the source of
   // the code that corresponds to the instruction at the displacement
   // offset of the function, or 0.
   // 
   // fullpath - address of an array of char to receive the full name of
   // the source code file that defines the function corresponding to the
   // address, or 0.  The array must be able to hold MAX_PATH bytes.

   void
   LookupAddress(
      DWORD64  traceAddress,   
      char     moduleName[],   
      char     fullImageName[],
      char     symbolName[],    // must be SYMBOL_NAME_MAX bytes
      DWORD64* displacement,   
      DWORD*   line,           
      char     fullpath[]);     // must be MAX_PATH bytes



   // Calls LookupAddress and fills in the blanks
   //
   // %1 - module name
   // %2 - symbol name
   // %3 - source full path
   // %4 - line number

   String
   LookupAddress(
      DWORD64 traceAddress,
      const wchar_t* format = L"%1%!%2 %3(%4!d!)");

}  // namespace StackTrace



}  // namespace Burnslib