 |
crashrpt | |
| A crash reporting system for Windows applications | ||
|
crashrpt | |
| A crash reporting system for Windows applications | ||
Data Fields | |
| WORD | cb |
| Size of this structure in bytes; must be initialized before using! | |
| LPCWSTR | pszAppName |
| Name of application. | |
| LPCWSTR | pszAppVersion |
| Application version. | |
| LPCWSTR | pszEmailTo |
| E-mail address of crash reports recipient. | |
| LPCWSTR | pszEmailSubject |
| Subject of crash report e-mail. | |
| LPCWSTR | pszUrl |
| URL of server-side script (used in HTTP connection). | |
| LPCWSTR | pszCrashSenderPath |
| Directory name where CrashSender.exe is located. | |
| LPGETLOGFILE | pfnCrashCallback |
| Deprecated, do not use. | |
| UINT | uPriorities [5] |
| Array of error sending transport priorities. | |
| DWORD | dwFlags |
| Flags. | |
| LPCWSTR | pszPrivacyPolicyURL |
| URL of privacy policy agreement. | |
| LPCWSTR | pszDebugHelpDLL |
| File name or folder of Debug help DLL. | |
| MINIDUMP_TYPE | uMiniDumpType |
| Minidump type. | |
| LPCWSTR | pszErrorReportSaveDir |
| Directory where to save error reports. | |
| LPCWSTR | pszRestartCmdLine |
| Command line for application restart (without executable name). | |
| LPCWSTR | pszLangFilePath |
| Path to the language file (including file name). | |
| LPCWSTR | pszEmailText |
| Custom E-mail text (used when deliverying report as E-mail). | |
| LPCWSTR | pszSmtpProxy |
| Network address and port to be used as SMTP proxy. | |
| LPCWSTR | pszCustomSenderIcon |
| Custom icon used for Error Report dialog. | |
| LPCWSTR | pszSmtpLogin |
| Login name used for SMTP authentication when sending error report as E-mail. | |
| LPCWSTR | pszSmtpPassword |
| Password used for SMTP authentication when sending error report as E-mail. | |
| int | nRestartTimeout |
| Timeout for application restart. | |
Below, structure members are described in details. Required parameters must always be specified, while optional ones may be set with 0 (zero) or NULL. Most of parameters are optional.
cb [in, required]
This must contain the size of this structure in bytes.
pszAppName [in, optional]
This is the friendly name of the client application. The application name is displayed in the Error Report dialog. If this parameter is NULL, the name of EXE file that was used to start caller process becomes the application name.
pszAppVersion [in, optional]
Should be the application version. Example: "1.0.1".
If this equals to NULL, product version is extracted from the executable file which started the caller process, and this product version is used as application version. If the executable file doesn's have a version info resource, the crInstall() function will fail.
pszEmailTo [in, optional]
This is the email address of the recipient of error reports (or several E-mail adresses separated with semicolon), for example "name@example.com" or "person1@example.com;person2@someserver.com". If several E-mail addresses are specified, error report will be delivered to each of them. If this parameter equals to NULL, the crash report won't be sent using E-mail client.
Keep this NULL if you plan to use large error reports (more than several MB in size), because large emails may be rejected by the mail server.
pszEmailSubject [in, optional]
This is the subject of the email message. If this parameter is NULL, the default subject of form '[app_name] [app_version] Error Report' is generated.
pszUrl is the URL of a server-side script that would receive crash report data via HTTP or HTTPS connection. If this parmeter is NULL, HTTP(S) connection won't be used to send crash reports. For example of a server-side script that can receive crash reports, see Sending Error Reports.
HTTP(S) transport is the recommended way of sending large error reports (more than several MB in size). To define a custom port for HTTP(S) connection, use the following URL format: "http://example.com[:port]/crashrpt.php" or "https://example.com[:port]/crashrpt.php", where optional port is the placeholder for the port number.
pszCrashSenderPath [in, optional]
This is the absolute path to the directory where CrashSender.exe is located. The crash sender process is responsible for letting end user know about the crash and sending the error report. If this is NULL, it is assumed that CrashSender.exe is located in the same directory as CrashRpt.dll.
uPriorities [in, optional]
This is an array that defines the preferred methods of sending error reports. The available methods are: HTTP (or HTTPS) connection, SMTP connection or simple MAPI (default mail client).
A priority is a non-negative integer number or special constant CR_NEGATIVE_PRIORITY. The greater positive number defines the greater priority. Specify the CR_NEGATIVE_PRIORITY to skip the given delivery method.
The element having index CR_HTTP defines priority for using HTML connection. The element having index CR_SMTP defines priority for using SMTP connection. The element having index CR_SMAPI defines priority for using the default mail client.
The methods having greater priority will be tried first. If priorities are equal to each other, HTTP (or HTTPS) connection will be tried the first, SMTP connection will be tried the second and simple MAPI will be tried the last.
dwFlags [in, optional]
Since v1.1.2, dwFlags can be used to define behavior parameters. This can be a combination of the following values:
| Use the combination of the following constants to specify what exception handlers to install: | |
| CR_INST_ALL_POSSIBLE_HANDLERS | Install all available exception handlers. |
| CR_INST_SEH_EXCEPTION_HANDLER | Install SEH exception handler. |
| CR_INST_PURE_CALL_HANDLER | Install pure call handler (VS .NET and later). |
| CR_INST_NEW_OPERATOR_ERROR_HANDLER | Install new operator error handler (VS .NET and later). |
| CR_INST_SECURITY_ERROR_HANDLER | Install security errror handler (VS .NET and later). |
| CR_INST_INVALID_PARAMETER_HANDLER | Install invalid parameter handler (VS 2005 and later). |
| CR_INST_SIGABRT_HANDLER | Install SIGABRT signal handler. |
| CR_INST_SIGINT_HANDLER | Install SIGINT signal handler. |
| CR_INST_SIGTERM_HANDLER | Install SIGTERM signal handler. |
| Use the combination of the following constants to define behavior parameters: | |
| CR_INST_NO_GUI | Available since v.1.2.2 Do not show GUI. It is not recommended to use this flag for regular GUI-based applications. Use this only for services that have no GUI. |
| CR_INST_DONT_SEND_REPORT | Available since v.1.2.2 This parameter means 'do not send error report immediately on crash, just save it locally'. Use this if you have direct access to the machine where crash happens and do not need to send report over the Internet. You can use this in couple with CR_INST_STORE_ZIP_ARCHIVES flag to store zipped error reports along with uncompressed error report files. |
| CR_INST_APP_RESTART | Available since v.1.2.4 This parameter allows to automatically restart the application on crash. The command line for the application is taken from pszRestartCmdLine parameter. To avoid cyclic restarts of an application which crashes on startup, the application is restarted only if at least 60 seconds elapsed since its start. |
| CR_INST_NO_MINIDUMP | Available since v.1.2.4 Specify this parameter if you want minidump file not to be included into crash report. The default behavior is to include the minidump file.
|
| CR_INST_SEND_QUEUED_REPORTS | Available since v.1.2.5 Specify this parameter to send all queued reports. Those report files are by default stored in LOCAL_APPDATA%\CrashRpt\UnsentCrashReports\AppName_AppVersion% folder. If this is specified, CrashRpt checks if it's time to remind user about recent errors in the application and offers to send all queued error reports.
|
| CR_INST_STORE_ZIP_ARCHIVES | Available since v.1.2.7 This parameter can be used in couple with CR_INST_DONT_SEND_REPORT flag to store not only uncompressed error report files, but also ZIP archives. By default (if this flag omitted) CrashRpt stores all error report files in uncompressed state.
|
| CR_INST_SEND_MANDATORY | Available since v.1.3.1 This parameter makes sending procedure mandatory by removing the "Close" button and "Other actions..." button from the Error Report dialog. Typically, it is not recommended to use this flag, unless you intentionally want users to always send error reports for your application. |
| CR_INST_SHOW_ADDITIONAL_INFO_FIELDS | Available since v.1.3.1 This parameter makes "Your E-mail" and "Describe what you were doing when the problem occurred" fields of Error Report dialog always visible. 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.
|
| CR_INST_ALLOW_ATTACH_MORE_FILES | Available since v.1.3.1 Adds an ability for user to attach more files to crash report by choosing "Attach More File(s)" item from context menu of Error Report Details dialog. By default this feature is disabled.
|
| CR_INST_AUTO_THREAD_HANDLERS | Available since v.1.4.2 Specifying this flag results in automatic installation of all available exception handlers to all threads that will be created in the future. This flag only works if CrashRpt is compiled as a DLL, it does not work if you compile CrashRpt as static library. |
pszPrivacyPolicyURL [in, optional]
This parameter defines the URL for the Privacy Policy hyperlink of the Error Report dialog. If this parameter is NULL, the link is not displayed. For information on the Privacy Policy, see About an Error Report. This parameter is available since v1.1.2.
pszDebugHelpDLL [in, optional]
This parameter defines the location of the dbghelp.dll to load. If this parameter is NULL, the dbghelp.dll is searched using the default search sequence. This parameter is available since v1.2.1.
uMiniDumpType [in, optional]
This parameter defines the minidump type. For the list of available minidump types, see the documentation for the MiniDumpWriteDump() function in MSDN. Parameter is available since v.1.2.1.
It is recommended to set this parameter with zero (equivalent of MiniDumpNormal constant). Other values may increase the minidump size significantly.
pszErrorReportSaveDir [in, optional]
This parameter defines the directory where to save the error reports. If this is NULL, the default directory is used (%LOCAL_APP_DATA%\CrashRpt\UnsentCrashReports\%AppName%_%AppVersion%). This parameter is available since v.1.2.2.
pszRestartCmdLine [in, optional]
This parameter defines the string that specifies the command-line arguments for the application when it is restarted (when using CR_INST_APP_RESTART flag). Do not include the name of the executable in the command line; it is added automatically. This parameter can be NULL. Available since v.1.2.4.
pszLangFilePath [in, optional]
This parameter defines the absolute path (including file name) for language file. If this is NULL, the lang file is assumed to be located in the same dir as CrashSender.exe file and have the name crashrpt_lang.ini. This parameter is available since v.1.2.4.
pszEmailText [in, optional]
This parameter defines the custom E-mail text that is used when deliverying error report as E-mail. If this is NULL, the default E-mail text is used. It is recommended to set this parameter with NULL. This parameter is available since v.1.2.4.
pszSmtpProxy [in, optional]
This parameter defines the network address (IP or domain) and, optionally, port formatted as "address[:port]" of SMTP server. Examples: "192.168.1.1:2525", "mail.example.com:25". If this parameter is NULL, the SMTP server address is resolved using the MX record of recipient's mailbox. You should typically set this parameter with NULL, except in the case when your software is a server and custom SMTP configuration is required. This parameter is available since v.1.2.4.
pszCustomSenderIcon [in, optional]
This parameter can be used to define a custom icon for Error Report dialog. This parameter is available since v.1.2.8.
The value of this parameter should be absolute path to the module containing the icon resource, followed by resource identifier separated by comma. You can set this parameter with NULL to use the default icon.
The resource identifier is a zero-based index of the icon to retrieve. For example, if this value is 0, the first icon in the specified file is used. If the identifier is a negative number not equal to -1, the icon in the specified file whose resource identifier is equal to the absolute value of the resource identifier is used. Example: "D:\MyApp\Resources.dll, -128".
pszSmtpLogin [in, optional]
This parameter defines the login name for SMTP authentication. It is typically used together with pszSmtpProxy and pszSmtpPassword parameter. If this parameter is ommitted (NULL), no SMTP autentication is used. This parameter is available since v.1.3.1.
pszSmtpPassword [in, optional]
This parameter defines the password for SMTP authentication. It is used in pair with pszSmtpLogin parameter. This parameter is available since v.1.3.1.
nRestartTimeout [in, optional]
This parameter defines the timeout (in seconds) for the application restart (when using CR_INST_APP_RESTART flag). It is recommended to set this with zero (in such a case, the default restart timeout of 60 seconds is applied). Available since v.1.4.3.
1.5.9