Miscellaneous API Features

This page covers miscellaneous API features not mentioned in previous two pages.

Generating Error Report Manually

Typically CrashRpt generates error reports automatically, when a critical error occurs. But sometimes it is required to generate error report manually, on user demand.

Assume it is required to remotely debug some application logics error. Such an error, for example, infinite loop in a worker thread, may not cause program crash. To collect the information about error that doesn't cause crash, a software developer might provide an ability to generate error report manually on user demand, for example on a key combination press.

The crGenerateErrorReport() function allows to generate an error report manually. When you generate an error report manually, the caller process is not terminated and continues its execution. To send the error report, CrashRpt creates another process named CrashSender.exe.

Catching Structured Exceptions in a Block of Code

Sometimes it may be required to catch a SEH exception inside of a block of code (using __try/__except construction) and generate error report when an exception happens. CrashRpt provides a conveniense function crExceptionFilter() for this purpose.

For additional information on SEH exceptions, please refer to About Exceptions and Exception Handling page.

Silent (non-GUI) Mode

CrashRpt can function in silent (non-GUI) mode. In this mode, Error Report window is not displayed on crash and no interaction with user is performed. The silent mode is enabled by specifying the CR_INST_NO_GUI flag for CR_INSTALL_INFO::dwFlags structure member.

The silent mode is designed for server applications or services that do not need to interact with user on crash. The silent mode should not be used for regular GUI applications. For regular interactive applications, a user should provide his/her consent to allow sending the error report.

Automatic Application Restart

You can tell CrashRpt to restart your application automatically when crash occurs. This can be done by specifying the CR_INST_APP_RESTART flag for the CR_INSTALL_INFO::dwFlags structure member.

You can pass command line parameters to the executable being restarted using CR_INSTALL_INFO::pszRestartCmdLine, but can't specify another executable for restart. Only the same executable can be restarted that was used to start the current process.

By default, the application is restarted only if at least 60 seconds have elapsed since its start up. This is done to avoid cyclic restarts of an application that crashes right on its start up. (Also, the application is restarted only if the user does provide his/her consent.) You can override the default restart timeout (in seconds) using the CR_INSTALL_INFO::nRestartTimeout structure field.

If you generate an error report manually with automatic restart feature enabled, the caller process is not terminated automatically and another instance of client application is launched. If you want to avoid starting the second instance of the client application, specify the CR_EXCEPTION_INFO::bManual flag.

Customizing CrashRpt User Interface

CrashRpt provides several options for customizing look and feel of its UI (Error Report Dialog and other dialogs).

You can specify custom icon for CrashRpt dialogs by specifying CR_INSTALL_INFO::pszCustomSenderIcon structure member. The value of this parameter should be absolute path to the module containing the icon resource, followed by resource identifier separated by comma. For example, specifying this with "C:\\WINDOWS\\System32\\user32.dll, 1" results in the following appearance (see the figure below).

Custom Icon

By default, CrashRpt allows user to choose, whether to send error report (user clicks the "Send report" button) or exit the application (user clicks the "Exit the program" button). Hovewer, for some applications it may be useful to make sending error reports mandatory. Specifying CR_INST_SEND_MANDATORY flag for CR_INSTALL_INFO::dwFlags structure member makes sending procedure mandatory by removing the "Close" button and "Close the program" button from the Error Report dialog (as shown in the figure below). Typically, it is not recommended to use this flag, unless you intentionally want users to always send error reports for your application.

Sending Error Report Mandatory

Specifying the CR_INST_SHOW_ADDITIONAL_INFO_FIELDS flag for CR_INSTALL_INFO::dwFlags structure member makes "Your E-mail" and "Describe what you were doing when the problem occurred" fields of Error Report dialog always visible (see the figure below). By default (when this parameter not specified), these fields are hidden and user needs to click the "Provide additional info (recommended)" link to show them. You can specify this flag if you need to attract user's attention to those fields.

Showing User E-mail and Problem Description Fields

CrashSender.exe Command-line Options

The following is not a real "API feature", but a useful command-line option for CrashSender.exe executable.

As of v.1.3.1, CrashRpt allows to specify a command line parameter /terminate for CrashSender.exe. This resolves a problem with installers that will want to update or remove the EXE file during software installation process. Earlier, there was no way to programmatically tell the CrashSender.exe program to exit immediatelly.

Launching "CrashSender.exe /terminate" from command shell would look for all open CrashSender.exe processes and terminate them immediately (without sending crash reports or waiting for completion). Terminating the process is acomplished with TerminateProcess() function.

Further reading: An Example of Using CrashRpt API.