carb::crashreporter::ICrashReporter

Defined in carb/crashreporter/ICrashReporter.h

struct ICrashReporter

ICrashReporter is the interface to implement a plugin that catches and reports information about the crash to either a local file, a server, or both.

ICrashReporter is an optional plugin that is automatically loaded by the framework and doesn’t need to be specifically listed in the configuration. If an ICrashReporter plugin is found, it’s enabled. Only one ICrashReporter instance is supported at a time.

The crash report itself consists of multiple parts. Some parts are only present on certain supported platforms. All generated crash dump files will appear in the directory named by the “/crashreporter/dumpDir” setting. If no value is provided, the current working directory is used instead. The following parts could be expected:

A minidump file. This is only generated on Windows. This file will contain the state of the process’s threads, stack memory, global memory space, register values, etc at the time of the crash. This file will end in ‘.dmp’.
A stack trace of the crash point file. This could be produced on all platforms. This file will end in ‘.txt’.
A metadata file. This is a TOML formatted file that contains all the metadata values that were known by the crash reporter at the time of the crash. This file will end in ‘.toml’.

The crash reporter may have any number of arbitrary metadata values associated with it. These values are defined as key/value pair strings. There are two ways a metadata value can be defined:

Add a value to the /crashreporter/data/ branch of the settings registry. This can be done directly through the ISettings interface, adding a value to one of the app’s config files, or by using the addCrashMetadata() utility function. These values should be set once and either never or very rarely modified. There is a non-trivial amount of work related to collecting a new metadata value in this manner that could lead to an overall performance impact if done too frequently.
Add a key and data callback to collect the current value of a metadata key for something that changes frequently. This type of metadata value is added with addVolatileMetadata() on this interface. These values may change as frequently as needed. The current value will only ever be collected when a crash does occur or when the callback is removed.

Once a metadata value has been added to the crash reporter, it cannot be removed. The value will remain even if the key is removed from /crashreporter/data/ or its value callback is removed. This is intentional so that as much data as possible can be collected to be sent with the crash report as is possible.

If a metadata key is registered as a volatile value, it will always override a key of the same name that is found under the /crashreporter/data/ branch of the settings registry. Even if the volatile metadata value is removed or unregistered, it will still override any key of the same name found in the settings registry.

Metadata key names may or may not be case sensitive depending on their origin. If a metadata value comes from the settings registry, its name is case sensitive since the settings registry is also case sensitive. Metadata values that are registered as volatile metadata values do not have case sensitive names. Attempting to register a new value under the same key but with different casing will fail since it would overwrite an existing name. This difference is intentional to avoid confusion in the metadata output. When adding metadata values through the settings registry, care should be taken to use consistent casing to avoid confusion in the output.

Public Functions

inline MetadataId addVolatileMetadata(const char *keyName, OnGetMetadataIntegerFn callback, void *context)

Adds a new volatile metadata value to the crash report.

Remark

This registers a new volatile metadata value with the crash reporter. This new value includes a callback that will be used to acquire the most recent value of the metadata key when a crash does occur. The value may be provided as either a signed or unsigned integer (64 bit), a floating point value (64 bit), or a string of arbitrary length. Callback types are intentionally provided for each type to discourage the implementations from doing their own string conversions that could be dangerous while handling a crash event.

Remark

Because the process may be in an unstable or delicate state when the callback is performed to retrieve the metadata values, there are several restrictions on what the callback function can and cannot do. In general, the callback function should provide the metadata value as quickly and simply as possible. An ideal case would be just to return the current value of a local, global, or member variable. Some guidelines are:

Do not perform any allocations or call into anything that may perform an allocation. At the time of a crash, many things could have gone wrong and allocations could fail or hang for various reasons.
Do not use any STL container classes other than to retrieve a current value. Many STL container class operations can implicitly perform an allocation to resize a buffer, array, new node, etc. If a resize, copy, or assign operation is unavoidable, try to use a container class that provides the possibility to reserve space for expected operations early (ie: string, vector, etc).
Avoid doing anything that may use a mutex or other locking primitive that is not in a strictly known state at the time. During a crash, the state of any lock could be undefined leading to a hang if an attempt is made to acquire it. If thread safety is a concern around accessing the value, try using an atomic variable instead of depending on a lock.
Do not make any calls into ICrashReporter from the callback function. This will result in a deadlock.
Under no circumstances should a new thread be created by the callback.
Do not assert or throw an exception for any reason through any method (ie: assert(), CARB_ASSERT(), CARB_CHECK(), etc). If an assertion fails, it will interrupt the crash report handling and cause a potential recursion loop. proper error handling must be used at all times.

Thread Safety: This call is thread safe.

Parameters

keyName – [in] The name of the metadata key to set. This must only contain printable ASCII characters except for a double quote (‘”’), slash (‘/’), or whitespace. It is the caller’s responsibility to ensure the key name will not be overwriting another system’s metadata value. One way to do this is to prefix the key name with the name of the extension or plugin (sanitized to follow the above formatting rules). Volatile metadata key names are not case sensitive. This may not be nullptr or an empty string.
callback – [in] The callback function that will provide the value for the new metadata key. This may not be a nullptr callback function. See below for notes on what the callback function may and may not do.
context – [in] An opaque context pointer that will be passed to the callback function when called. This will not be accessed or evaluated in any way, but must remain valid for the entire duration that the callback is registered here.

Return values

kMetadataFailBadParameter – if an invalid parameter is passed in.
kMetadataFailKeyAlreadyUsed – if the given key name is already in use or is a reserved name.
kInvalidMetadataId – if a crash dump is currently in progress during this call.

Returns

An identifier that can be used to unregister the callback in the event that the owning module needs to be unloaded. It is the caller’s responsibility to ensure that the metadata callback is properly unregistered with a call to removeVolatileMetadataValue() before it unloads.

inline MetadataId addVolatileMetadata(const char *keyName, OnGetMetadataUIntegerFn callback, void *context)

Adds a new volatile metadata value to the crash report.

Remark

This registers a new volatile metadata value with the crash reporter. This new value includes a callback that will be used to acquire the most recent value of the metadata key when a crash does occur. The value may be provided as either a signed or unsigned integer (64 bit), a floating point value (64 bit), or a string of arbitrary length. Callback types are intentionally provided for each type to discourage the implementations from doing their own string conversions that could be dangerous while handling a crash event.

Remark

Because the process may be in an unstable or delicate state when the callback is performed to retrieve the metadata values, there are several restrictions on what the callback function can and cannot do. In general, the callback function should provide the metadata value as quickly and simply as possible. An ideal case would be just to return the current value of a local, global, or member variable. Some guidelines are:

Do not perform any allocations or call into anything that may perform an allocation. At the time of a crash, many things could have gone wrong and allocations could fail or hang for various reasons.
Do not use any STL container classes other than to retrieve a current value. Many STL container class operations can implicitly perform an allocation to resize a buffer, array, new node, etc. If a resize, copy, or assign operation is unavoidable, try to use a container class that provides the possibility to reserve space for expected operations early (ie: string, vector, etc).
Avoid doing anything that may use a mutex or other locking primitive that is not in a strictly known state at the time. During a crash, the state of any lock could be undefined leading to a hang if an attempt is made to acquire it. If thread safety is a concern around accessing the value, try using an atomic variable instead of depending on a lock.
Do not make any calls into ICrashReporter from the callback function. This will result in a deadlock.
Under no circumstances should a new thread be created by the callback.
Do not assert or throw an exception for any reason through any method (ie: assert(), CARB_ASSERT(), CARB_CHECK(), etc). If an assertion fails, it will interrupt the crash report handling and cause a potential recursion loop. proper error handling must be used at all times.

Thread Safety: This call is thread safe.

Parameters

keyName – [in] The name of the metadata key to set. This must only contain printable ASCII characters except for a double quote (‘”’), slash (‘/’), or whitespace. It is the caller’s responsibility to ensure the key name will not be overwriting another system’s metadata value. One way to do this is to prefix the key name with the name of the extension or plugin (sanitized to follow the above formatting rules). Volatile metadata key names are not case sensitive. This may not be nullptr or an empty string.
callback – [in] The callback function that will provide the value for the new metadata key. This may not be a nullptr callback function. See below for notes on what the callback function may and may not do.
context – [in] An opaque context pointer that will be passed to the callback function when called. This will not be accessed or evaluated in any way, but must remain valid for the entire duration that the callback is registered here.

Return values

kMetadataFailBadParameter – if an invalid parameter is passed in.
kMetadataFailKeyAlreadyUsed – if the given key name is already in use or is a reserved name.
kInvalidMetadataId – if a crash dump is currently in progress during this call.

Returns

An identifier that can be used to unregister the callback in the event that the owning module needs to be unloaded. It is the caller’s responsibility to ensure that the metadata callback is properly unregistered with a call to removeVolatileMetadataValue() before it unloads.

inline MetadataId addVolatileMetadata(const char *keyName, OnGetMetadataFloatFn callback, void *context)

Adds a new volatile metadata value to the crash report.

Remark

This registers a new volatile metadata value with the crash reporter. This new value includes a callback that will be used to acquire the most recent value of the metadata key when a crash does occur. The value may be provided as either a signed or unsigned integer (64 bit), a floating point value (64 bit), or a string of arbitrary length. Callback types are intentionally provided for each type to discourage the implementations from doing their own string conversions that could be dangerous while handling a crash event.

Remark

Because the process may be in an unstable or delicate state when the callback is performed to retrieve the metadata values, there are several restrictions on what the callback function can and cannot do. In general, the callback function should provide the metadata value as quickly and simply as possible. An ideal case would be just to return the current value of a local, global, or member variable. Some guidelines are:

Do not perform any allocations or call into anything that may perform an allocation. At the time of a crash, many things could have gone wrong and allocations could fail or hang for various reasons.
Do not use any STL container classes other than to retrieve a current value. Many STL container class operations can implicitly perform an allocation to resize a buffer, array, new node, etc. If a resize, copy, or assign operation is unavoidable, try to use a container class that provides the possibility to reserve space for expected operations early (ie: string, vector, etc).
Avoid doing anything that may use a mutex or other locking primitive that is not in a strictly known state at the time. During a crash, the state of any lock could be undefined leading to a hang if an attempt is made to acquire it. If thread safety is a concern around accessing the value, try using an atomic variable instead of depending on a lock.
Do not make any calls into ICrashReporter from the callback function. This will result in a deadlock.
Under no circumstances should a new thread be created by the callback.
Do not assert or throw an exception for any reason through any method (ie: assert(), CARB_ASSERT(), CARB_CHECK(), etc). If an assertion fails, it will interrupt the crash report handling and cause a potential recursion loop. proper error handling must be used at all times.

Thread Safety: This call is thread safe.

Parameters

keyName – [in] The name of the metadata key to set. This must only contain printable ASCII characters except for a double quote (‘”’), slash (‘/’), or whitespace. It is the caller’s responsibility to ensure the key name will not be overwriting another system’s metadata value. One way to do this is to prefix the key name with the name of the extension or plugin (sanitized to follow the above formatting rules). Volatile metadata key names are not case sensitive. This may not be nullptr or an empty string.
callback – [in] The callback function that will provide the value for the new metadata key. This may not be a nullptr callback function. See below for notes on what the callback function may and may not do.
context – [in] An opaque context pointer that will be passed to the callback function when called. This will not be accessed or evaluated in any way, but must remain valid for the entire duration that the callback is registered here.

Return values

kMetadataFailBadParameter – if an invalid parameter is passed in.
kMetadataFailKeyAlreadyUsed – if the given key name is already in use or is a reserved name.
kInvalidMetadataId – if a crash dump is currently in progress during this call.

Returns

An identifier that can be used to unregister the callback in the event that the owning module needs to be unloaded. It is the caller’s responsibility to ensure that the metadata callback is properly unregistered with a call to removeVolatileMetadataValue() before it unloads.

inline MetadataId addVolatileMetadata(const char *keyName, size_t maxLength, OnGetMetadataStringFn callback, void *context)

Adds a new volatile metadata value to the crash report.

Remark

This registers a new volatile metadata value with the crash reporter. This new value includes a callback that will be used to acquire the most recent value of the metadata key when a crash does occur. The value may be provided as either a signed or unsigned integer (64 bit), a floating point value (64 bit), or a string of arbitrary length. Callback types are intentionally provided for each type to discourage the implementations from doing their own string conversions that could be dangerous while handling a crash event.

Remark

Because the process may be in an unstable or delicate state when the callback is performed to retrieve the metadata values, there are several restrictions on what the callback function can and cannot do. In general, the callback function should provide the metadata value as quickly and simply as possible. An ideal case would be just to return the current value of a local, global, or member variable. Some guidelines are:

Do not perform any allocations or call into anything that may perform an allocation. At the time of a crash, many things could have gone wrong and allocations could fail or hang for various reasons.
Do not use any STL container classes other than to retrieve a current value. Many STL container class operations can implicitly perform an allocation to resize a buffer, array, new node, etc. If a resize, copy, or assign operation is unavoidable, try to use a container class that provides the possibility to reserve space for expected operations early (ie: string, vector, etc).
Avoid doing anything that may use a mutex or other locking primitive that is not in a strictly known state at the time. During a crash, the state of any lock could be undefined leading to a hang if an attempt is made to acquire it. If thread safety is a concern around accessing the value, try using an atomic variable instead of depending on a lock.
Do not make any calls into ICrashReporter from the callback function. This will result in a deadlock.
Under no circumstances should a new thread be created by the callback.
Do not assert or throw an exception for any reason through any method (ie: assert(), CARB_ASSERT(), CARB_CHECK(), etc). If an assertion fails, it will interrupt the crash report handling and cause a potential recursion loop. proper error handling must be used at all times.

Thread Safety: This call is thread safe.

Parameters

keyName – [in] The name of the metadata key to set. This must only contain printable ASCII characters except for a double quote (‘”’), slash (‘/’), or whitespace. It is the caller’s responsibility to ensure the key name will not be overwriting another system’s metadata value. One way to do this is to prefix the key name with the name of the extension or plugin (sanitized to follow the above formatting rules). Volatile metadata key names are not case sensitive. This may not be nullptr or an empty string.
callback – [in] The callback function that will provide the value for the new metadata key. This may not be a nullptr callback function. See below for notes on what the callback function may and may not do.
context – [in] An opaque context pointer that will be passed to the callback function when called. This will not be accessed or evaluated in any way, but must remain valid for the entire duration that the callback is registered here.
maxLength – [in] The maximum number of characters, including the null terminator, that the metadata’s value will occupy when its value is retrieved. When retrieved, if the value is longer than this limit, this new metadata value will be truncated. There may be an arbitrary amount of extra space added internally. This is often done for padding or alignment purposes. Callers should however neither count on this space being present nor expect any strings to always be truncated at an exact length.

Return values

kMetadataFailBadParameter – if an invalid parameter is passed in.
kMetadataFailKeyAlreadyUsed – if the given key name is already in use or is a reserved name.
kInvalidMetadataId – if a crash dump is currently in progress during this call.

Returns

An identifier that can be used to unregister the callback in the event that the owning module needs to be unloaded. It is the caller’s responsibility to ensure that the metadata callback is properly unregistered with a call to removeVolatileMetadataValue() before it unloads.

inline MetadataId addVolatileMetadata(const char *keyName, size_t maxLength, OnGetMetadataWideStringFn callback, void *context)

Adds a new volatile metadata value to the crash report.

Remark

This registers a new volatile metadata value with the crash reporter. This new value includes a callback that will be used to acquire the most recent value of the metadata key when a crash does occur. The value may be provided as either a signed or unsigned integer (64 bit), a floating point value (64 bit), or a string of arbitrary length. Callback types are intentionally provided for each type to discourage the implementations from doing their own string conversions that could be dangerous while handling a crash event.

Remark

Because the process may be in an unstable or delicate state when the callback is performed to retrieve the metadata values, there are several restrictions on what the callback function can and cannot do. In general, the callback function should provide the metadata value as quickly and simply as possible. An ideal case would be just to return the current value of a local, global, or member variable. Some guidelines are:

Do not perform any allocations or call into anything that may perform an allocation. At the time of a crash, many things could have gone wrong and allocations could fail or hang for various reasons.
Do not use any STL container classes other than to retrieve a current value. Many STL container class operations can implicitly perform an allocation to resize a buffer, array, new node, etc. If a resize, copy, or assign operation is unavoidable, try to use a container class that provides the possibility to reserve space for expected operations early (ie: string, vector, etc).
Avoid doing anything that may use a mutex or other locking primitive that is not in a strictly known state at the time. During a crash, the state of any lock could be undefined leading to a hang if an attempt is made to acquire it. If thread safety is a concern around accessing the value, try using an atomic variable instead of depending on a lock.
Do not make any calls into ICrashReporter from the callback function. This will result in a deadlock.
Under no circumstances should a new thread be created by the callback.
Do not assert or throw an exception for any reason through any method (ie: assert(), CARB_ASSERT(), CARB_CHECK(), etc). If an assertion fails, it will interrupt the crash report handling and cause a potential recursion loop. proper error handling must be used at all times.

Thread Safety: This call is thread safe.

Parameters

keyName – [in] The name of the metadata key to set. This must only contain printable ASCII characters except for a double quote (‘”’), slash (‘/’), or whitespace. It is the caller’s responsibility to ensure the key name will not be overwriting another system’s metadata value. One way to do this is to prefix the key name with the name of the extension or plugin (sanitized to follow the above formatting rules). Volatile metadata key names are not case sensitive. This may not be nullptr or an empty string.
callback – [in] The callback function that will provide the value for the new metadata key. This may not be a nullptr callback function. See below for notes on what the callback function may and may not do.
context – [in] An opaque context pointer that will be passed to the callback function when called. This will not be accessed or evaluated in any way, but must remain valid for the entire duration that the callback is registered here.
maxLength – [in] The maximum number of characters, including the null terminator, that the metadata’s value will occupy when its value is retrieved. When retrieved, if the value is longer than this limit, this new metadata value will be truncated. There may be an arbitrary amount of extra space added internally. This is often done for padding or alignment purposes. Callers should however neither count on this space being present nor expect any strings to always be truncated at an exact length.

Return values

kMetadataFailBadParameter – if an invalid parameter is passed in.
kMetadataFailKeyAlreadyUsed – if the given key name is already in use or is a reserved name.
kInvalidMetadataId – if a crash dump is currently in progress during this call.

Returns

An identifier that can be used to unregister the callback in the event that the owning module needs to be unloaded. It is the caller’s responsibility to ensure that the metadata callback is properly unregistered with a call to removeVolatileMetadataValue() before it unloads.

Public Members

void (*sendAndRemoveLeftOverDumpsAsync)(OnDumpSubmittedFn onDumpSubmitted, void *userData)

Upon crash, a crash dump is written to disk, uploaded, and then removed.

However, due to settings or because the application is in an undefined state, the upload may fail. This method can be used on subsequent runs of the application to attempt to upload/cleanup previous failed uploads.

This method returns immediately, performing all uploads/removals asynchronously. Supply an optional callback to be notified when the uploads/removals have been completed. The callback will be performed regardless of whether the upload is successful. However, each crash dump file will only be removed from the local file system if its upload was successful and the “/crashreporter/preserveDump” setting is false. A future call to this function will try the upload again on failed crash dumps.

The callback will be performed on the calling thread before return if there is no upload task to perform or if the crash reporter is currently disabled. In all other cases, the callback will be performed in the context of another thread. It is the caller’s responsibility to ensure all accesses made in the callback are thread safe. The supplied callback may neither directly nor indirectly access this instance of ICrashReporter.

Thread Safety: This method is thread safe and can be called concurrently.

Param onDumpSubmitted: The callback function to be called when the dumps are uploaded and deleted.
Param userData: The user data to be passed to the callback function.

CrashSentCallbackId *(*addCrashSentCallback)(OnCrashSentFn onCrashSent, void *userData)

Adds a new callback that is called after sending (successfully or not) a crash dump to a server.

Registration of multiple callbacks is allowed and all registered callbacks will be called serially (the order in which callbacks are called is undefined). It is allowed to use the same callback function (and userData) multiple times.

This method is thread safe and can be called concurrently.

The supplied callback may neither directly nor indirectly access this instance of ICrashReporter.

Param onCrashSent: The new callback to register, must not be nullptr.
Param userData: The user data to be passed to the callback function, can be nullptr.
Return: Not null if the provided callback was successfully registered, nullptr otherwise.

void (*removeCrashSentCallback)(CrashSentCallbackId *callbackId)

Removes previously registered callback.

This method is thread safe and can be called concurrently.

The given parameter is the id returned from addCrashSentCallback.

The given callback id can be nullptr or an invalid id.

Param callbackId: The callback to remove. A null or invalid pointer is accepted (though may produce an error message).

void (*resolveSymbol)(const void *address, ResolveSymbolFn func, void *user)

Attempts to resolve a given address to a symbolic name using debugging features available to the system.

If symbol resolution fails or is not available, func is called with a nullptr name.

Thread Safety: The callback function is always performed synchronously to this call. It is the callee’s responsibility to ensure safe access to both the user pointer and any global resources.

Note

This function can be extremely slow. Use for debugging only.

Param address: The address to attempt to resolve.
Param func: The func to call upon resolution
Param user: User-specific data to be passed to func

void (*removeVolatileMetadataValue)(MetadataId id)

Removes a previously registered volatile metadata value.

Remark

This removes a volatile metadata value from the crash reporter. The value will be retrieved from the callback and stored internally before it is removed from the crash reporter. The given identifier will be invalid upon return.