CrashSight Windows SDK

1 SDK Introduction

CrashSight is a crash report SDK which works on Windows.

2 Path Requirement

Files and directory given by CrashSight is listed as follows:
root_path/xxgame.exe
root_path/GbSpy64.dll
root_path/GameBabyConfig64.dat
root_path/TQM64
root_path/TQM64/TQMCenter.exe
root_path/TQM64/GameBabyConfig64.dat

Example：

3 Step In Using CrashSight

1. Get the app id and app key from website (Project Details -> Setting -> Information -> App ID & App Key).

2. Path given sdk files into required path as “Path Requirement”.

3. Load “GbSpy64.dll” by Windows sdk function(in Windows.h) “LoadLibrary”(Only work for C++, loading function is different for other programing language).

4. Declare exported functions, typedef void(*SetTQMConfig)(const char* id, const char* version, const char* key).

5. Get function address by (SetTQMConfig)GetProcAddress(dll_handle, “SetTQMConfig”).

6. Call function “SetTQMConfig” to init CrashSight.

7. Edit GameBabyConfig64.dat especially the app id.

<GameBabyConfig __version="1">
	<GameName>Test-Game.exe</GameName>  <!--Process name-->
	<LobbyName></LobbyName>
	<IgnoreDllCnt>2</IgnoreDllCnt>      <!--Number of ignored Dll.-->
	<IgnoreDlls>TenSLX.dll</IgnoreDlls>   <!--Name of each ignored Dll-->
	<IgnoreDlls>Tensafe.dll</IgnoreDlls>   <!--Name of each ignored Dll-->
	<AppId>0620edc732</AppId>        <!--App Id given by CrashSight website-->
	<DomainUrl>windows.crashsight.qq.com</DomainUrl> <!-- Upload URL-->
</GameBabyConfig>

8. Test whether CrashSight Dll is loaded and crashed is reported to CrashSight server(display on website).

4 SDK APIs

4.1 Initialize CrashSight

Function Definition ``` typedef void(*SetTQMConfig)(const char* id, const char* version, const char* key); ```

4.2 Error Report

Function Definition

typedef void(*reportException)(int type, const char* name, const char* message, const char* stackTrace, const char * extras);

Each parameter is display on CrashSight website as follow picture.
The expName is exception name, and the expMessage is simple statement of exception. (Especially,expName/expMessage should encode by utf-8 within 128 byte.) The stackTrace is the stack about where error happened which should be limited in 2 Mb. The extras is a reserve parameter which should be filled with .

4.3 Set Crash Callback Function

Function Definition

	typedef void(*SetCrashCallback)(CrashCallbackFuncPtr callback);
	SetCrashCallback theCallBack = NULL;
	theCallBack = (SetCrashCallback)GetProcAddress(dllDemo, "SetCrashCallback");

4.4 Callback Function Example

Function Definition

	typedef void(*CrashCallbackFuncPtr)(int type, const char* guid);

The type is the callback type, and only 1 is given now. The guid is a 64 bytes string for identifying each upload. https://{WEBSITE_URL}/crash-reporting/client-report-id/{APP_ID}/{GID}?pid=10

4.5 Single Process Mode(Extra monitor is unable)

Minimum support version 2.0.11

Extra monitor process is not work at single process model.

Function Definition

typedef bool (*MonitorEnable)(bool enable);
MonitorEnable monitor_enable = NULL;
monitor_enable = (MonitorEnable)GetProcAddress(dllDemo, "MonitorEnable");

4.6 Manually Upload Crash

Upload a crash in some situation. For example, upload UE Fatal exception.

Minimum support version 2.0.11

Function Definition

typedef void (*CsReportCrash)();
CsReportCrash cs_report_crash = NULL;
cs_report_crash = (CsReportCrash)GetProcAddress(dllDemo, "CsReportCrash");

FCoreDelegates::OnShutdownAfterError.AddStatic(cs_report_crash);

4.7 Custom Log File Directory

Edit default log file directory, but only works when use single process mode.

Minimum support version 2.0.11

Function Definition

typedef int (*SetCustomLogDir)(const char* log_path);
SetCustomLogDir theSetCustomLogDir = NULL;
theSetCustomLogDir = (SetCustomLogDir)GetProcAddress(dllDemo, "SetCustomLogDir");

5 Code Sample

C++ Code:

typedef void(*SetTQMConfig)(const char* id, const char* version, const char* key);
typedef void(*reportException)(int type, const char* name, const char* message, const char* stackTrace, const char * extras);
int main()
{
	// Load dll
	HINSTANCE dllDemo = LoadLibraryA("GbSpy64.dll");
	// Execute initialization
	if (dllDemo)
	{
		SetTQMConfig theSetTQMConfig = NULL;
		theSetTQMConfig = (SetTQMConfig)GetProcAddress(dllDemo, "SetTQMConfig");
		if (theSetTQMConfig != NULL)
		{
			theSetTQMConfig("userid", "version", "key");
		}
	}
	// Upload a custom error
	if (dllDemo)
	{
		reportException theReportException = NULL;
		theReportException = (reportException)GetProcAddress(dllDemo, "reportException");
		if (theReportException != NULL)
		{
			int type = 1;
			theReportException(type, "exp name", "exp message", "stack", "extras");
		}
	}
	return 1;
}

C# Code：

Function Definition:
[DllImport("GbSpy64.dll")] 
static extern void SetTQMConfig([MarshalAs(UnmanagedType.LPUTF8Str)]string userId, [MarshalAs(UnmanagedType.LPUTF8Str)]string version, [MarshalAs(UnmanagedType.LPUTF8Str)]string key);

[DllImport("GbSpy64.dll")] 
static extern void reportException (int type, [MarshalAs(UnmanagedType.LPUTF8Str)]string name, [MarshalAs(UnmanagedType.LPUTF8Str)]string message, [MarshalAs(UnmanagedType.LPUTF8Str)]string stackTrace, [MarshalAs(UnmanagedType.LPUTF8Str)]string extras);

Call Function:
SetTQMConfig("userId", "version", "key");
reportException(1, "name", "message","stackTrace", "extras");

6 Appendix

1. Supported exception by CrashSight. [Exception definition by Microsoft](https://docs.microsoft.com/en-us/windows/win32/debug/getexceptioncode)

#define STATUS_ACCESS_VIOLATION          ((DWORD   )0xC0000005L)    
#define STATUS_IN_PAGE_ERROR             ((DWORD   )0xC0000006L)    
#define STATUS_INVALID_HANDLE            ((DWORD   )0xC0000008L)    
#define STATUS_INVALID_PARAMETER         ((DWORD   )0xC000000DL)    
#define STATUS_NO_MEMORY                 ((DWORD   )0xC0000017L)    
#define STATUS_ILLEGAL_INSTRUCTION       ((DWORD   )0xC000001DL)    
#define STATUS_NONCONTINUABLE_EXCEPTION  ((DWORD   )0xC0000025L)    
#define STATUS_INVALID_DISPOSITION       ((DWORD   )0xC0000026L)    
#define STATUS_ARRAY_BOUNDS_EXCEEDED     ((DWORD   )0xC000008CL)    
#define STATUS_FLOAT_DENORMAL_OPERAND    ((DWORD   )0xC000008DL)    
#define STATUS_FLOAT_DIVIDE_BY_ZERO      ((DWORD   )0xC000008EL)    
#define STATUS_FLOAT_INEXACT_RESULT      ((DWORD   )0xC000008FL)    
#define STATUS_FLOAT_INVALID_OPERATION   ((DWORD   )0xC0000090L)    
#define STATUS_FLOAT_OVERFLOW            ((DWORD   )0xC0000091L)    
#define STATUS_FLOAT_STACK_CHECK         ((DWORD   )0xC0000092L)    
#define STATUS_FLOAT_UNDERFLOW           ((DWORD   )0xC0000093L)    
#define STATUS_INTEGER_DIVIDE_BY_ZERO    ((DWORD   )0xC0000094L)    
#define STATUS_INTEGER_OVERFLOW          ((DWORD   )0xC0000095L)    
#define STATUS_PRIVILEGED_INSTRUCTION    ((DWORD   )0xC0000096L)    
#define STATUS_STACK_OVERFLOW            ((DWORD   )0xC00000FDL)    
#define STATUS_DLL_NOT_FOUND             ((DWORD   )0xC0000135L)    
#define STATUS_ORDINAL_NOT_FOUND         ((DWORD   )0xC0000138L)    
#define STATUS_ENTRYPOINT_NOT_FOUND      ((DWORD   )0xC0000139L)    
#define STATUS_CONTROL_C_EXIT            ((DWORD   )0xC000013AL)    
#define STATUS_DLL_INIT_FAILED           ((DWORD   )0xC0000142L)    
#define STATUS_FLOAT_MULTIPLE_FAULTS     ((DWORD   )0xC00002B4L)    
#define STATUS_FLOAT_MULTIPLE_TRAPS      ((DWORD   )0xC00002B5L)    
#define STATUS_REG_NAT_CONSUMPTION       ((DWORD   )0xC00002C9L)    
#define STATUS_HEAP_CORRUPTION           ((DWORD   )0xC0000374L)    
#define STATUS_STACK_BUFFER_OVERRUN      ((DWORD   )0xC0000409L)    
#define STATUS_INVALID_CRUNTIME_PARAMETER ((DWORD   )0xC0000417L)    
#define STATUS_ASSERTION_FAILURE         ((DWORD   )0xC0000420L)    
#define STATUS_ENCLAVE_VIOLATION         ((DWORD   )0xC00004A2L)    
#if defined(STATUS_SUCCESS) || (_WIN32_WINNT > 0x0500) || (_WIN32_FUSION >= 0x0100) 
#define STATUS_SXS_EARLY_DEACTIVATION    ((DWORD   )0xC015000FL)    
#define STATUS_SXS_INVALID_DEACTIVATION  ((DWORD   )0xC0150010L)