The global object in charge of setting up and controlling crash reporting. More...

#include <CrashHandler.h>

Inherits QObject.

Public Slots
void	setPath (const QString &path)
	Set the directory for the crash reports. More...

bool	start ()
	Start the crash handler. More...

void	startMonitor (QCoreApplication *app)
	Starts the unhandled exception monitor. More...

bool	isStarted () const
	Whether the crash monitor has been successfully started. More...

bool	isEnabled () const
	Whether the crash monitor will report crashes if they occur. More...

void	setEnabled (bool enabled)
	Set whether we want to submit crash reports to the report server. More...

void	setUrl (const QString &url)
	Set the URL where to send crash reports to. More...

void	setToken (const QString &token)
	Set the token for the crash reporter. More...

void	setAnnotation (const std::string &key, const char *value)
	Set an annotation to be added to a crash. More...

void	setAnnotation (const std::string &key, const QString &value)
	Set an annotation to be added to a crash. More...

void	setAnnotation (const std::string &key, const std::string &value)
	Set an annotation to be added to a crash. More...

Signals
void	enabledChanged (bool enabled)
	Emitted when the enabled/disabled state of the crash handler changes. More...

Detailed Description

The global object in charge of setting up and controlling crash reporting.

This object initializes and talks to crash reporting backends. For those, see CrashHandlerBackend.h and the .cpp files that implement that interface.

The crash URL and token can only be passed to the underlying system on start, so things should be set up in such a way that startup is only done after those are set.

start() will be automatically called when setEnabled() is called with true. setAnnotation() can only be called after start.

To use, follow this general pattern in an application:

auto &ch = CrashHandler::getInstance();
ch.setPath(...);
ch.setUrl("https://server.com/crash-reports");
ch.setToken("1.2beta");
ch.setEnabled(true);
ch.setAnnotation("version", "1.3"); // Needs a started handler to work

For an assignment client, there are two potential ways to start, through the command-line and through the settings system. Since the path, URL and token only apply on startup, the code must be written such that if command arguments are not given, setEnabled() or start() are not called until receiving the settings from the domain.

Member Function Documentation

◆ enabledChanged

void CrashHandler::enabledChanged ( bool enabled )

signal

Emitted when the enabled/disabled state of the crash handler changes.

This can be used to store it as a setting.

Parameters

enabled Whether the crash handler is now enabled

◆ isEnabled

bool CrashHandler::isEnabled ( ) const

inlineslot

Whether the crash monitor will report crashes if they occur.

This setting is independent of isCrashMonitorStarted() – crash reporting may be enabled but fail to work due to the crash reporting component being missing or failing to initialize.

Returns: true Crashes will be reported to CMAKE_BACKTRACE_URL; false Crashes will not be reported

◆ isStarted

bool CrashHandler::isStarted ( ) const

inlineslot

Whether the crash monitor has been successfully started.

Reasons for it failing to start include:

Not having a crash reporter for the platform
Crash reporter not being configured with reporting URLs (CMAKE_BACKTRACE_TOKEN and CMAKE_BACKTRACE_URL)
Crash reporter is present and configured, but failed to initialize for some reason

Returns: true Crash reporter is present, configured and working.; false Crash reporter has not been started for one of the above reasons.

◆ setAnnotation [1/3]

void CrashHandler::setAnnotation	(	const std::string &	key,
		const char *	value
	)

slot

Set an annotation to be added to a crash.

Annotations add extra information, such as the application's version number, the current user, or any other information of interest.

Note: Annotations made before the crash handler are remembered, and sent to the crash handler as soon as it's initialized.

Parameters

key	Key
value	Value

◆ setAnnotation [2/3]

void CrashHandler::setAnnotation	(	const std::string &	key,
		const QString &	value
	)

slot

Set an annotation to be added to a crash.

Annotations add extra information, such as the application's version number, the current user, or any other information of interest.

Note: Annotations made before the crash handler are remembered, and sent to the crash handler as soon as it's initialized.

Parameters

key	Key
value	Value

◆ setAnnotation [3/3]

void CrashHandler::setAnnotation	(	const std::string &	key,
		const std::string &	value
	)

slot

Set an annotation to be added to a crash.

Annotations add extra information, such as the application's version number, the current user, or any other information of interest.

Note: Annotations made before the crash handler are remembered, and sent to the crash handler as soon as it's initialized.

Parameters

key	Key
value	Value

◆ setEnabled

void CrashHandler::setEnabled ( bool enabled )

slot

Set whether we want to submit crash reports to the report server.

The report server is configured with CMAKE_BACKTRACE_URL. Emits crashReportingEnabledChanged signal.

Note: This automatically calls start(), so it should be called after setPath(), setUrl() and setToken()

Parameters

enabled Whether it's enabled.

◆ setPath

void CrashHandler::setPath ( const QString & path )

slot

Set the directory for the crash reports.

This sets the path for writing crash reports. This should be done on application startup.

Parameters

path	Directory where to store crash reports. It's allowed to set this to argv[0], if the path is a filename, then the base directory will be automatically used.

◆ setToken

void CrashHandler::setToken ( const QString & token )

slot

Set the token for the crash reporter.

This is an identifier in the crash collection service, such as Sentry, and may contain a branch name or a version number.

If not set, a predefined token specified at compile time via CMAKE_BACKTRACE_TOKEN will be used.

Parameters

token Token

◆ setUrl

void CrashHandler::setUrl ( const QString & url )

slot

Set the URL where to send crash reports to.

If not set, a predefined URL specified at compile time via CMAKE_BACKTRACE_URL will be used.

Parameters

url URL

◆ start

bool CrashHandler::start ( )

slot

Start the crash handler.

This is called automatically if it wasn't started yet when setEnabled() is called.

Parameters

path	Path where to store the crash database

Returns: true Started successfully; false Failed to start

◆ startMonitor

void CrashHandler::startMonitor ( QCoreApplication * app )

slot

Starts the unhandled exception monitor.

On Windows, it's possible for the unhandled exception handler to be reset. This starts a timer to periodically set it back.

On non-Windows systems this has no effect.

Parameters

app	Main application

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

CrashHandler.h
CrashHandler.cpp

Public Slots

Signals

Detailed Description

Member Function Documentation

◆ enabledChanged

◆ isEnabled

◆ isStarted

◆ setAnnotation [1/3]

◆ setAnnotation [2/3]

◆ setAnnotation [3/3]

◆ setEnabled

◆ setPath

◆ setToken

◆ setUrl

◆ start

◆ startMonitor