Detailed Description

A collection of functions used to report information about a crash.

#include <utility/YiCrashHandler.h>

Classes
class	PostData
	A container for information required to make a POST request. More...

Static Public Member Functions
static void	AddAppDataValue (const CYIString &key, const CYIString &value)

static CYIString	GetAppDataValue (const CYIString &key)

static void	ClearAppData ()

static void	PreallocateMinidumpFilenameStorage ()

static void	ReplacePlaceholderWithMinidumpFilename (CYIStringView filename, CYIString *pJSON)

static void	ReplacePlaceholderWithTimestamp (CYIString *pJSON)

static void	ReplacePlaceholders (CYIStringView minidumpFilename, CYIString *pJSON)

static const CYIString &	GetCrashReport ()

static void	ReportFatalError (const CYIString &callStack)

static CYIString	GetCallStack ()

static void	SetCrashReportPostData (const PostData &data)

static const PostData &	GetCrashReportPostData ()

static void	SetMinidumpPostData (const PostData &data)

static const PostData &	GetMinidumpPostData ()

static void	SetEngineInformation ()

static void	SetDeviceInformation ()

static void	UpdateRenderingSurfaceData (const CYIRenderingSurfaceInfo &surface)

Static Public Attributes
static const CYIStringView	s_quotedUnixTimestampMsPlaceholder

static CYISignal	CrashReportChanged

static CYISignal	CrashReportPostDataChanged

static CYISignal	MinidumpPostDataChanged

static CYISignal	FatalErrorOccurred

Static Protected Member Functions
static void	ResetCrashReportForTesting ()

Static Protected Attributes
static const CYIStringView	s_quotedUnixTimestampMsForReplacement

static constexpr const char *	s_pMinidumpFilenameKey = "minidump_filename"

Friends
class	CYICrashHandlerPlatform

Member Function Documentation

◆ AddAppDataValue()

static void CYICrashHandler::AddAppDataValue	(	const CYIString &	key,
		const CYIString &	value
	)

static

Adds app data as a key-value pair. This data will be available as part of the JSON document returned by CYICrashHandler::GetCrashReport.

If key already exists in the stored app data, the current value associated with key will be overwritten with value.

See also: CYICrashHandler::GetCrashReport

◆ ClearAppData()

static void CYICrashHandler::ClearAppData ( )

static

Removes all stored app data values.

◆ GetAppDataValue()

static CYIString CYICrashHandler::GetAppDataValue ( const CYIString & key )

static

Returns the value associated with key.

Warning: This function may allocate memory and is not safe to call during or after a crash. If you need to retrieve values after a crash, CYICrashHandler::GetCrashReport should be used.

See also: CYICrashHandler::GetCrashReport

◆ GetCallStack()

static CYIString CYICrashHandler::GetCallStack ( )

static

Returns the call stack included when a fatal error is manually triggered using CYICrashHandler::ReportFatalError.

Warning: This function may allocate memory and is not safe to call during or after a crash. If you need to retrieve the call stack after a crash, CYICrashHandler::GetCrashReport should be used.

See also: CYICrashHandler::ReportFatalError; CYICrashHandler::GetCrashReport

◆ GetCrashReport()

static const CYIString& CYICrashHandler::GetCrashReport ( )

static

Returns the crash report which contains relevant data for the crash. This function does not allocate memory and is safe to call during or after a crash.

See also: CYICrashHandler::AddAppDataValue; CYICrashHandler::ReportFatalError; CYICrashHandler::SetEngineInformation; CYICrashHandler::SetDeviceInformation; CYICrashHandler::UpdateRenderingSurfaceData

◆ GetCrashReportPostData()

static const PostData& CYICrashHandler::GetCrashReportPostData ( )

static

Returns the crash report PostData which contains specific data required to upload the crash payload.

◆ GetMinidumpPostData()

static const PostData& CYICrashHandler::GetMinidumpPostData ( )

static

Returns the minidump post request data which contains specific data required to upload the crash minidump.

◆ PreallocateMinidumpFilenameStorage()

static void CYICrashHandler::PreallocateMinidumpFilenameStorage ( )

static

Pre-allocates memory to store a minidump filename. This function is called internally by the crash handler.

See also: CYICrashHandler::ReplacePlaceholderWithMinidumpFilename

◆ ReplacePlaceholders()

static void CYICrashHandler::ReplacePlaceholders	(	CYIStringView	minidumpFilename,
		CYIString *	pJSON
	)

static

Given the JSON string pJSON, replaces all known placeholders with their appropriate values.

See also: ReplacePlaceholderWithMinidumpFilename; ReplacePlaceholderWithTimestamp

◆ ReplacePlaceholderWithMinidumpFilename()

static void CYICrashHandler::ReplacePlaceholderWithMinidumpFilename	(	CYIStringView	filename,
		CYIString *	pJSON
	)

static

Given the JSON string pJSON, replaces the minidump filename placeholder with filename. The path portion of the filename is stripped out, if it exists.

Note: The length of the minidump filename is limited to 64 characters and may not contain any control characters, double quotes or backslashes. Longer filenames are truncated to 64 characters.

◆ ReplacePlaceholderWithTimestamp()

static void CYICrashHandler::ReplacePlaceholderWithTimestamp ( CYIString * pJSON )

static

Given the JSON string pJSON, replaces the timestamp placeholders with the current time. The format used for the time depends on the placeholder used. If timestamp placeholders cannot be found in pJSON, this function does nothing.

See also: CYICrashHandler::s_quotedUnixTimestampMsPlaceholder

◆ ReportFatalError()

static void CYICrashHandler::ReportFatalError ( const CYIString & callStack )

static

Triggers crash handling for a fatal error in the app that does not result in a crash. The argument callStack is available as part of the JSON document returned by CYICrashHandler::GetCrashReport.

See also: CYICrashHandler::GetCrashReport

◆ ResetCrashReportForTesting()

static void CYICrashHandler::ResetCrashReportForTesting ( )

staticprotected

Resets crash report values for the purposes of automated testing.

Note: This function is used in automated testing, and is not intended for use in normal app execution.

◆ SetCrashReportPostData()

static void CYICrashHandler::SetCrashReportPostData ( const PostData & data )

static

◆ SetDeviceInformation()

static void CYICrashHandler::SetDeviceInformation ( )

static

Adds device information to the crash report. This data will be available as part of the JSON document returned by CYICrashHandler::GetCrashReport.

Note: There is no need for this function to be called by platform or app code. It is called automatically by the engine.

See also: CYICrashHandler::GetCrashReport

◆ SetEngineInformation()

static void CYICrashHandler::SetEngineInformation ( )

static

Adds engine information to the crash report. This data will be available as part of the JSON document returned by CYICrashHandler::GetCrashReport.

Note: This function should be called once by the platform implementation, as early as possible. It should not be called by app code.

See also: CYICrashHandler::GetCrashReport

◆ SetMinidumpPostData()

static void CYICrashHandler::SetMinidumpPostData ( const PostData & data )

static

Sets minidump POST request data. data is available as CYICrashHandler::GetMinidumpPostData.

Example usage:

auto postData = CYICrashHandler::GetMinidumpPostData();
postData.SetUrl("www.example.com");
postData.AddHeader("name", "value");
CYICrashHandler::SetMinidumpPostData(postData);

Note: Calling this function will trigger CYICrashHandler::CrashReportPostDataChanged signal after changing the data.

◆ UpdateRenderingSurfaceData()

static void CYICrashHandler::UpdateRenderingSurfaceData ( const CYIRenderingSurfaceInfo & surface )

static

Updates rendering surface data in the crash report. If the data does not exist in the crash report, it is added for the first time. This data will be available as part of the JSON document returned by CYICrashHandler::GetCrashReport.

Note: There is no need for this function to be called by platform or app code. It is called automatically by the engine.

See also: CYICrashHandler::GetCrashReport

Friends And Related Function Documentation

◆ CYICrashHandlerPlatform

friend class CYICrashHandlerPlatform

friend

Member Data Documentation

◆ CrashReportChanged

CYISignal CYICrashHandler::CrashReportChanged

static

A signal called whenever any of the crash report data changes.

◆ CrashReportPostDataChanged

CYISignal CYICrashHandler::CrashReportPostDataChanged

static

A signal called whenever a crash report's PostData changes.

◆ FatalErrorOccurred

CYISignal CYICrashHandler::FatalErrorOccurred

static

A signal called whenever a fatal error is reported by app or platform code.

See also: CYICrashHandler::ReportFatalError

◆ MinidumpPostDataChanged

CYISignal CYICrashHandler::MinidumpPostDataChanged

static

A signal called whenever a crash minidump's PostData changes.

◆ s_pMinidumpFilenameKey

constexpr const char* CYICrashHandler::s_pMinidumpFilenameKey = "minidump_filename"

staticprotected

The minidump filename key

◆ s_quotedUnixTimestampMsForReplacement

const CYIStringView CYICrashHandler::s_quotedUnixTimestampMsForReplacement

staticprotected

A placeholder string that can be inserted into JSON payloads. At crash-time, it will be replaced with the unix epoch (in milliseconds).

◆ s_quotedUnixTimestampMsPlaceholder

const CYIStringView CYICrashHandler::s_quotedUnixTimestampMsPlaceholder

static

A placeholder string that can be inserted into JSON payloads. At crash-time, it will be replaced with the unix epoch (in milliseconds). Quotes around the placeholder will be removed.

For example, given the following payload:

...
"timestampMs": "(contents of s_quotedUnixTimestampMsPlaceholder)",
...

the payload will be modified at crash time to include the current unix epoch time (in milliseconds):

...
"timestampMs": 123456789000,
...

The documentation for this class was generated from the following file:

utility/YiCrashHandler.h

Detailed Description

Classes

Static Public Member Functions

Static Public Attributes

Static Protected Member Functions

Static Protected Attributes

Friends

Member Function Documentation

◆ AddAppDataValue()

◆ ClearAppData()

◆ GetAppDataValue()

◆ GetCallStack()

◆ GetCrashReport()

◆ GetCrashReportPostData()

◆ GetMinidumpPostData()

◆ PreallocateMinidumpFilenameStorage()

◆ ReplacePlaceholders()

◆ ReplacePlaceholderWithMinidumpFilename()

◆ ReplacePlaceholderWithTimestamp()

◆ ReportFatalError()

◆ ResetCrashReportForTesting()

◆ SetCrashReportPostData()

◆ SetDeviceInformation()

◆ SetEngineInformation()

◆ SetMinidumpPostData()

◆ UpdateRenderingSurfaceData()

Friends And Related Function Documentation

◆ CYICrashHandlerPlatform

Member Data Documentation

◆ CrashReportChanged

◆ CrashReportPostDataChanged

◆ FatalErrorOccurred

◆ MinidumpPostDataChanged

◆ s_pMinidumpFilenameKey

◆ s_quotedUnixTimestampMsForReplacement

◆ s_quotedUnixTimestampMsPlaceholder