///////////////////////////////////////////////////////////////////////////////
// Name:        wx/msw/debughlp.h
// Purpose:     wraps dbghelp.h standard file
// Author:      Vadim Zeitlin, Suzumizaki-kimitaka
// Created:     2005-01-08 (extracted from msw/crashrpt.cpp)
// Copyright:   (c) 2003-2005 Vadim Zeitlin <vadim@wxwidgets.org>
// Licence:     wxWindows licence
///////////////////////////////////////////////////////////////////////////////

#ifndef _WX_MSW_DEBUGHLPH_H_
#define _WX_MSW_DEBUGHLPH_H_

#include "wx/defs.h"

#if wxUSE_DBGHELP

#include "wx/dynlib.h"
#include "wx/msw/wrapwin.h"

#ifdef __VISUALC__
    // Disable a warning that we can do nothing about: we get it at least for
    // imagehlp.h from 8.1 Windows kit when using VC14.
    #pragma warning(push)

    // 'typedef ': ignored on left of '' when no variable is declared
    #pragma warning(disable:4091)
#endif

#include <imagehlp.h>

#ifdef __VISUALC__
  #pragma warning(pop)
#endif

#include "wx/msw/private.h"

/*

The table below shows which functions are exported by dbghelp.dll.

On 64 bit Windows, there seems to be no difference between 32bit dll and 64bit
one. Vista-64 and Win8-64 look the same, but "Ex" and "ExW" versions exist only
in Windows 8.

Note that SymGetLineFromAddrW and EnumerateLoadedModulesW DON'T exist at all.

function | Windows     | XP-32 Vista-64 Win8-64
SymEnumSymbolsW            n/a     v       v
SymFromAddrW               n/a     v       v
SymInitializeW             n/a     v       v

SymEnumSymbols              v      v       v
SymFromAddr                 v      v       v
SymInitialize               v      v       v

SymGetLineFromAddrW64      n/a     v       v
SymGetLineFromAddr64        v      v       v
SymGetLineFromAddrW        n/a    n/a     n/a
SymGetLineFromAddr          v      v       v

EnumerateLoadedModulesW64  n/a     v       v
EnumerateLoadedModules64    v      v       v
EnumerateLoadedModulesW    n/a    n/a     n/a
EnumerateLoadedModules      v      v       v

*/

// It's not really clear whether API v10 is used by anything as VC8 still used
// v9, just as MSVC7.1, while VC9 already used v11, but provide support for it
// just in case.
#if API_VERSION_NUMBER < 10/*{{{*/

typedef BOOL
(CALLBACK *PENUMLOADED_MODULES_CALLBACKW64)(PWSTR ModuleName,
                                            DWORD64 ModuleBase,
                                            ULONG ModuleSize,
                                            PVOID UserContext);

typedef struct _IMAGEHLP_LINEW64
{
    DWORD    SizeOfStruct;
    PVOID    Key;
    DWORD    LineNumber;
    PWSTR    FileName;
    DWORD64  Address;
} IMAGEHLP_LINEW64, *PIMAGEHLP_LINEW64;

typedef struct _SYMBOL_INFOW
{
    ULONG       SizeOfStruct;
    ULONG       TypeIndex;
    ULONG64     Reserved[2];
    ULONG       Index;
    ULONG       Size;
    ULONG64     ModBase;
    ULONG       Flags;
    ULONG64     Value;
    ULONG64     Address;
    ULONG       Register;
    ULONG       Scope;
    ULONG       Tag;
    ULONG       NameLen;
    ULONG       MaxNameLen;
    WCHAR       Name[1];
} SYMBOL_INFOW, *PSYMBOL_INFOW;

typedef BOOL
(CALLBACK *PSYM_ENUMERATESYMBOLS_CALLBACKW)(PSYMBOL_INFOW pSymInfo,
                                            ULONG SymbolSize,
                                            PVOID UserContext);

typedef BOOL
(CALLBACK *PSYM_ENUMERATESYMBOLS_CALLBACK)(PSYMBOL_INFO pSymInfo,
                                           ULONG SymbolSize,
                                           PVOID UserContext);

#endif // API_VERSION_NUMBER < 10/*}}}*/

// wx-prefixed types map to either the ANSI or Unicode ("W") version depending
// on the build of wx itself.
#ifdef UNICODE
    #define wxPSYM_ENUMERATESYMBOLS_CALLBACK PSYM_ENUMERATESYMBOLS_CALLBACKW
#else // !UNICODE
    #define wxPSYM_ENUMERATESYMBOLS_CALLBACK PSYM_ENUMERATESYMBOLS_CALLBACK
#endif // UNICODE/!UNICODE

// This one could be already defined by wx/msw/stackwalk.h
#ifndef wxSYMBOL_INFO
    #ifdef UNICODE
        #define wxSYMBOL_INFO SYMBOL_INFOW
    #else // !UNICODE
        #define wxSYMBOL_INFO SYMBOL_INFO
    #endif // UNICODE/!UNICODE
#endif // !defined(wxSYMBOL_INFO)

typedef wxSYMBOL_INFO* wxPSYMBOL_INFO;

// This differs from PENUMLOADED_MODULES_CALLBACK[W]64 in that it always uses
// "const" for its first argument when the SDK used to pass a non-const string
// here until API_VERSION_NUMBER==11, so we can't just define it as an existing
// typedef.
typedef BOOL
(CALLBACK *wxPENUMLOADED_MODULES_CALLBACK)(const wxChar* moduleName,
                                           DWORD64 moduleBase,
                                           ULONG moduleSize,
                                           void *userContext);

// ----------------------------------------------------------------------------
// wxDbgHelpDLL: dynamically load dbghelp.dll functions
// ----------------------------------------------------------------------------

// wrapper for some functions from dbghelp.dll
//
// MT note: this class is not MT safe and should be only used from a single
//          thread at a time (this is so because dbghelp.dll is not MT-safe
//          itself anyhow)
class wxDbgHelpDLL
{
public:
    // some useful constants not present in debughlp.h (stolen from DIA SDK)
    enum BasicType
    {
        BASICTYPE_NOTYPE = 0,
        BASICTYPE_VOID = 1,
        BASICTYPE_CHAR = 2,
        BASICTYPE_WCHAR = 3,
        BASICTYPE_INT = 6,
        BASICTYPE_UINT = 7,
        BASICTYPE_FLOAT = 8,
        BASICTYPE_BCD = 9,
        BASICTYPE_BOOL = 10,
        BASICTYPE_LONG = 13,
        BASICTYPE_ULONG = 14,
        BASICTYPE_CURRENCY = 25,
        BASICTYPE_DATE = 26,
        BASICTYPE_VARIANT = 27,
        BASICTYPE_COMPLEX = 28,
        BASICTYPE_BIT = 29,
        BASICTYPE_BSTR = 30,
        BASICTYPE_HRESULT = 31,
        BASICTYPE_MAX
    };

    enum SymbolTag
    {
        SYMBOL_TAG_NULL,
        SYMBOL_TAG_EXE,
        SYMBOL_TAG_COMPILAND,
        SYMBOL_TAG_COMPILAND_DETAILS,
        SYMBOL_TAG_COMPILAND_ENV,
        SYMBOL_TAG_FUNCTION,
        SYMBOL_TAG_BLOCK,
        SYMBOL_TAG_DATA,
        SYMBOL_TAG_ANNOTATION,
        SYMBOL_TAG_LABEL,
        SYMBOL_TAG_PUBLIC_SYMBOL,
        SYMBOL_TAG_UDT,
        SYMBOL_TAG_ENUM,
        SYMBOL_TAG_FUNCTION_TYPE,
        SYMBOL_TAG_POINTER_TYPE,
        SYMBOL_TAG_ARRAY_TYPE,
        SYMBOL_TAG_BASE_TYPE,
        SYMBOL_TAG_TYPEDEF,
        SYMBOL_TAG_BASE_CLASS,
        SYMBOL_TAG_FRIEND,
        SYMBOL_TAG_FUNCTION_ARG_TYPE,
        SYMBOL_TAG_FUNC_DEBUG_START,
        SYMBOL_TAG_FUNC_DEBUG_END,
        SYMBOL_TAG_USING_NAMESPACE,
        SYMBOL_TAG_VTABLE_SHAPE,
        SYMBOL_TAG_VTABLE,
        SYMBOL_TAG_CUSTOM,
        SYMBOL_TAG_THUNK,
        SYMBOL_TAG_CUSTOM_TYPE,
        SYMBOL_TAG_MANAGED_TYPE,
        SYMBOL_TAG_DIMENSION,
        SYMBOL_TAG_MAX
    };

    enum DataKind
    {
        DATA_UNKNOWN,
        DATA_LOCAL,
        DATA_STATIC_LOCAL,
        DATA_PARAM,
        DATA_OBJECT_PTR,                    // "this" pointer
        DATA_FILE_STATIC,
        DATA_GLOBAL,
        DATA_MEMBER,
        DATA_STATIC_MEMBER,
        DATA_CONSTANT,
        DATA_MAX
    };

    enum UdtKind
    {
        UDT_STRUCT,
        UDT_CLASS,
        UDT_UNION,
        UDT_MAX
    };


    // function types
    typedef DWORD (WINAPI *SymGetOptions_t)();
    typedef DWORD (WINAPI *SymSetOptions_t)(DWORD);
    typedef BOOL (WINAPI *SymInitialize_t)(HANDLE, LPCSTR, BOOL);
    typedef BOOL (WINAPI *SymInitializeW_t)(HANDLE, LPCWSTR, BOOL);
    typedef BOOL (WINAPI *StackWalk_t)(DWORD, HANDLE, HANDLE, LPSTACKFRAME,
                                       LPVOID, PREAD_PROCESS_MEMORY_ROUTINE,
                                       PFUNCTION_TABLE_ACCESS_ROUTINE,
                                       PGET_MODULE_BASE_ROUTINE,
                                       PTRANSLATE_ADDRESS_ROUTINE);
    typedef BOOL (WINAPI *SymFromAddr_t)(HANDLE, DWORD64, PDWORD64, PSYMBOL_INFO);
    typedef BOOL (WINAPI *SymFromAddrW_t)(HANDLE, DWORD64, PDWORD64, PSYMBOL_INFOW);
    typedef LPVOID (WINAPI *SymFunctionTableAccess_t)(HANDLE, DWORD_PTR);
    typedef DWORD_PTR (WINAPI *SymGetModuleBase_t)(HANDLE, DWORD_PTR);
    typedef BOOL (WINAPI *SymGetLineFromAddr_t)(HANDLE, DWORD,
                                                PDWORD, PIMAGEHLP_LINE);
    typedef BOOL (WINAPI *SymGetLineFromAddr64_t)(HANDLE, DWORD64,
                                                  PDWORD, PIMAGEHLP_LINE64);
    typedef BOOL (WINAPI *SymGetLineFromAddrW64_t)(HANDLE, DWORD64,
                                                   PDWORD, PIMAGEHLP_LINEW64);
    typedef BOOL (WINAPI *SymSetContext_t)(HANDLE, PIMAGEHLP_STACK_FRAME,
                                           PIMAGEHLP_CONTEXT);
    typedef BOOL (WINAPI *SymEnumSymbols_t)(HANDLE, ULONG64, PCSTR,
                                            PSYM_ENUMERATESYMBOLS_CALLBACK,
                                            const PVOID);
    typedef BOOL (WINAPI *SymEnumSymbolsW_t)(HANDLE, ULONG64, PCWSTR,
                                             PSYM_ENUMERATESYMBOLS_CALLBACKW,
                                             const PVOID);
    typedef BOOL (WINAPI *SymGetTypeInfo_t)(HANDLE, DWORD64, ULONG,
                                            IMAGEHLP_SYMBOL_TYPE_INFO, PVOID);
    typedef BOOL (WINAPI *SymCleanup_t)(HANDLE);
    typedef BOOL (WINAPI *EnumerateLoadedModules_t)(HANDLE, PENUMLOADED_MODULES_CALLBACK, PVOID);
    typedef BOOL (WINAPI *EnumerateLoadedModules64_t)(HANDLE, PENUMLOADED_MODULES_CALLBACK64, PVOID);
    typedef BOOL (WINAPI *EnumerateLoadedModulesW64_t)(HANDLE, PENUMLOADED_MODULES_CALLBACKW64, PVOID);
    typedef BOOL (WINAPI *MiniDumpWriteDump_t)(HANDLE, DWORD, HANDLE,
                                               MINIDUMP_TYPE,
                                               CONST PMINIDUMP_EXCEPTION_INFORMATION,
                                               CONST PMINIDUMP_USER_STREAM_INFORMATION,
                                               CONST PMINIDUMP_CALLBACK_INFORMATION);

    // Higher level functions selecting the right debug help library function
    // to call: for CallFoo(), it can be Foo(), Foo64(), FooW() or FooW64()
    // depending on the build options and function availability.
    //
    // They also provide more convenient to use wx-specific API, e.g. work with
    // wxString instead of char/wchar_t pointers and omit the arguments we
    // don't need.
    static BOOL CallSymInitialize(HANDLE, BOOL);
    static BOOL CallEnumerateLoadedModules(HANDLE, wxPENUMLOADED_MODULES_CALLBACK, PVOID);
    static BOOL CallSymFromAddr(HANDLE, DWORD64,
                                size_t* offset, wxString* name);
    static BOOL CallSymGetLineFromAddr(HANDLE, DWORD64,
                                       wxString* fileName, size_t* line);
    static BOOL CallSymEnumSymbols(HANDLE hProcess,
                                   ULONG64 baseOfDll,
                                   wxPSYM_ENUMERATESYMBOLS_CALLBACK callback,
                                   const PVOID callbackParam);

    // The macro called by wxDO_FOR_ALL_SYM_FUNCS() below takes 2 arguments:
    // the name of the function in the program code, which never has "64"
    // suffix, and the name of the function in the DLL which can have "64"
    // suffix in some cases. These 2 helper macros call the macro with the
    // correct arguments in both cases.
    #define wxSYM_CALL(what, name)  what(name, name)
#if defined(_M_AMD64) || defined(_M_ARM64)
    #define wxSYM_CALL_64(what, name)  what(name, name ## 64)

    // Also undo all the "helpful" definitions done by imagehlp.h that map 32
    // bit functions to 64 bit ones, we don't need this as we do it ourselves.
    #undef StackWalk
    #undef SymFunctionTableAccess
    #undef SymGetModuleBase
    #undef SymGetLineFromAddr
    #undef EnumerateLoadedModules
#else
    #define wxSYM_CALL_64(what, name)  what(name, name)
#endif

    #define wxSYM_CALL_ALWAYS_W(what, name)  what(name ## W, name ## W)

    #define wxSYM_CALL_ALTERNATIVES(what, name)                \
        what(name, name);                                      \
        what(name ## 64, name ## 64);                          \
        what(name ## W64, name ## W64)

    #define wxDO_FOR_ALL_SYM_FUNCS_REQUIRED_PUBLIC(what)       \
        wxSYM_CALL_64(what, StackWalk);                        \
        wxSYM_CALL_64(what, SymFunctionTableAccess);           \
        wxSYM_CALL_64(what, SymGetModuleBase);                 \
                                                               \
        wxSYM_CALL(what, SymGetOptions);                       \
        wxSYM_CALL(what, SymSetOptions);                       \
        wxSYM_CALL(what, SymSetContext);                       \
        wxSYM_CALL(what, SymGetTypeInfo);                      \
        wxSYM_CALL(what, SymCleanup);                          \
        wxSYM_CALL(what, MiniDumpWriteDump)

    #define wxDO_FOR_ALL_SYM_FUNCS_REQUIRED_PRIVATE(what)      \
        wxSYM_CALL(what, SymInitialize);                       \
        wxSYM_CALL(what, SymFromAddr);                         \
        wxSYM_CALL(what, SymEnumSymbols)

    #define wxDO_FOR_ALL_SYM_FUNCS_REQUIRED(what)              \
        wxDO_FOR_ALL_SYM_FUNCS_REQUIRED_PRIVATE(what);         \
        wxDO_FOR_ALL_SYM_FUNCS_REQUIRED_PUBLIC(what)

    // Alternation will work when the following functions are not found,
    // therefore they are not included in REQUIRED version.
    #define wxDO_FOR_ALL_SYM_FUNCS_OPTIONAL(what)              \
        wxSYM_CALL_ALTERNATIVES(what, SymGetLineFromAddr);     \
        wxSYM_CALL_ALTERNATIVES(what, EnumerateLoadedModules); \
        wxSYM_CALL_ALWAYS_W(what, SymInitialize);              \
        wxSYM_CALL_ALWAYS_W(what, SymFromAddr);                \
        wxSYM_CALL_ALWAYS_W(what, SymEnumSymbols)

    #define wxDO_FOR_ALL_SYM_FUNCS(what)                       \
        wxDO_FOR_ALL_SYM_FUNCS_REQUIRED(what);                 \
        wxDO_FOR_ALL_SYM_FUNCS_OPTIONAL(what)

    #define wxDECLARE_SYM_FUNCTION(func, name) static func ## _t func

    wxDO_FOR_ALL_SYM_FUNCS_REQUIRED_PUBLIC(wxDECLARE_SYM_FUNCTION);

private:
    wxDO_FOR_ALL_SYM_FUNCS_REQUIRED_PRIVATE(wxDECLARE_SYM_FUNCTION);
    wxDO_FOR_ALL_SYM_FUNCS_OPTIONAL(wxDECLARE_SYM_FUNCTION);

public:

    #undef wxDECLARE_SYM_FUNCTION

    // load all functions from DLL, return true if ok
    static bool Init();

    // return the string with the error message explaining why Init() failed
    static const wxString& GetErrorMessage();

    // log error returned by the given function to debug output
    static void LogError(const wxChar *func);

    // return textual representation of the value of given symbol
    static wxString DumpSymbol(wxPSYMBOL_INFO pSymInfo, void *pVariable);

    // return the name of the symbol with given type index
    static wxString GetSymbolName(wxPSYMBOL_INFO pSymInfo);

private:
    // dereference the given symbol, i.e. return symbol which is not a
    // pointer/reference any more
    //
    // if ppData != NULL, dereference the pointer as many times as we
    // dereferenced the symbol
    //
    // return the tag of the dereferenced symbol
    static SymbolTag DereferenceSymbol(wxPSYMBOL_INFO pSymInfo, void **ppData);

    static wxString DumpField(wxPSYMBOL_INFO pSymInfo,
                              void *pVariable,
                              unsigned level);

    static wxString DumpBaseType(BasicType bt, DWORD64 length, void *pVariable);

    static wxString DumpUDT(wxPSYMBOL_INFO pSymInfo,
                            void *pVariable,
                            unsigned level = 0);

    static bool BindDbgHelpFunctions(const wxDynamicLibrary& dllDbgHelp);
    static bool DoInit();
};

#endif // wxUSE_DBGHELP

#endif // _WX_MSW_DEBUGHLPH_H_