User:Mikolardos/CrashRpt

Introduction
CrashRpt library is a light-weight open source error handling framework for applications created in Microsoft Visual C++ and running under Windows. The library is distributed under New BSD License.

CrashRpt project page is hosted on Google Code website, an older version of the library also can be found on CodeProject site.

The library can intercept Win32 structured exceptions and C++ typed exceptions generated by a user-mode application.

CrashRpt dynamic library (DLL) works like Dr. Watson utility that ships with Windows XP, or like Windows Error Reporting in Windows Vista.

CrashRpt intercepts unhandled exceptions, creates a crash minidump file, builds a crash descriptor in XML format, presents an interface to allow user to review the crash report, and finally it compresses and sends the crash report to the software support team.

Analogous Software
An analogous open-source library is BreakPad which is used, for example, in popular open-source web browsers Mozilla Firefox and Google Chrome. Breakpad supports Windows (x86), Linux (x86) and Mac OS X (x86, PowerPC) platforms.

Requirements
CrashRpt can be compiled and used in Visual C++ .NET 2003, Visual C++ 2005, Visual C++ 2008 and in Visual C++ Express Edition.

To compile CrashRpt in Visual C++ Express, Microsoft Platform SDK for Windows Server 2003 is additionally required.

Dependencies
CrashRpt depends on the following libraries:
 * Windows Template Library (WTL)
 * Microsoft Debug Help Library
 * ZLib
 * TinyXml

Architecture
CrashRpt consists of two core modules:  and.


 * contains functionality for intercepting exceptions in a client software.


 * contains functionality for sending error reports to the software's support team.

CrashRpt is separated into these modules to be able to close the application which crashes and to continue sending error report through  in background.

Typically a process (executable file) loads  into its address space when process starts. This single instance of CrashRpt is shared between all DLL modules that are loaded into the process' address space. Client application uses CrashRpt API functions to set exception handlers in the process once, typically in  function. In a multi-theraded program, client additionally set exception handlers in the beginning of thread procedure of each worker thread.

CrashRpt is designed to use C runtime libraries (CRT) as a Multi-threaded DLL (/MD compiler flag). All modules in the client application must be linked to the same version of CRT DLL in order to use CrashRpt. If some dependent module of the application uses different version of CRT or is statically linked to CRT, exceptions are not intercepted in that module.

In Visual C++, some exceptions related to security can't be intercepted. Since CRT v8.0 security errors can't be intercepted. When buffer overrun is detected, CRT invokes Dr. Watson directly instead of calling unhandled exception filter. This is done because of security reasons and Microsoft doesn't plan to change this behavior.

Error Reports
An error report refers to a collection of files intended to help developers diagnose the cause of a crash.

The error report is a ZIP archive file. The archive contains crash minidump file, which includes operating system version, processor type, CPU registers state, local variables and stack trace for each execution thread. The minidump in most cases can be used on developer's side to determine the reason of the crash and try to fix the problem.

In addition, CrashRpt generates an XML crash descriptor file. The file contains various information that might be useful for crash analyzis.

Custom files, for example, application log files, can be included into crash report by client application using callback function.

Error Report Delivery
CrashRpt sends error reports back to your software support team using any of the following ways:


 * via HTTP request to a server-side script
 * via connection to an SMTP server
 * via Simple MAPI programming interface (the user's default E-mail client application)

If one of these ways fails, CrashRpt tries others in turn. The preferred order of ways used to send reports can be manually defined.

Error Report Analyzis
When a software release is made and CrashRpt support is enabled in a client software, sooner or later the software vendor starts receiving crash reports. Count of received crash reports may depend on robustness of the software to various exceptional situations and on how much the software is popular. If there are many incoming error reports, the vendor can monitor and analyse them for the first few days after release, and prepare a hot fix release.

The purpose of an error report is to help the developer determine the reason of the problem and try to fix it. Usually the developer can't reproduce the error on his machine, and can't guarantee it is fixed. The only way to check if the error is fixed is to release a new version of software. The normal scenario is that the software becomes more and more stable with each release and less and less error reports are received.