/*!

\page architecture_overview Architecture Overview

\section crashrpt_mission CrashRpt Mission

<i> The mission</i> is to provide a set of tools for:
 - handling exceptions (critical errors) in a client software
 - automatically collecting necessary error info and generating error reports 
 - deliverying error reports over the internet
 - and simplifying error report postprocessing

\section crashrpt_stackholders CrashRpt Stakeholders

<i>Stakeholders</i> are the individuals or groups that have their concerns in CrashRpt architecture:
 - Developers that are interested in improving their software by analyzing user
   feedback on critical errors
 - Software end-users that are interested in better quality of programs
   they install and use
 - CrashRpt development team members that are interested in providing a set of convenient
   crash reporting tools that are widely used

\section nonfunctional_requirements Non-functional Requirements

\b Usability. CrashRpt end-users should be provided with a user-friendly, clean and
   intuitive GUI. GUI should be localizable to end-user's favourite language.

\b Compatibility. CrashRpt should support Windows operating system. 32-bit and 64-bit platforms
   should be supported. Visual C++ development environment should be supported.

\b Rubustness. CrashRpt should provide crash reporting services not depending of client
   application state. Client application may be unstable, heap-corrupted, stack-corrupted and so on.

\b Testability. The main features should be covered by automated tests to 
   guarantee expected behavior.

\section crashrpt_structure CrashRpt Structure Overview

CrashRpt consists of two kinds of functionality: error reporting functionality 
and error report analyzis functionality. Error reporting functionality is distributed with
a client software and responsible for handling exceptions in the client software and 
deliverying error reports to the developer.

Error report analyzis functionality is designed to help the developer to extract data
contained in error reports and to simplify error report analyzis. It is usually located
at the side of the developer and not distributed with the client software.

\image html architecture.png "CrashRpt Architecture"

\subsection error_reporting_functionality Error Reporting Functionality

Error reporting functionality consists of two core modules: \b CrashRpt.dll and \b CrashSender.exe.
- \b CrashRpt.dll contains functionality for handling exceptions in the client software.
- \b CrashSender.exe contains functionality for sending error reports to the software's support team.

Two modules are needed to be able to close the application 
that crashes and to continue sending error report through \b CrashSender.exe 
in background.

Typically a process (executable file) loads \b CrashRpt.dll 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 
\ref CrashRptAPI to set exception handlers in the process once, typically 
in its \b main() function. In a multi-threaded program, client additionally 
sets exception handlers in the beginning of thread procedure of each worker thread.
For additional info, see \ref using_crashrpt_api.

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. For more information, see \ref exception_handling.

In Visual C++, some exceptions related to security can't be intercepted. For example, 
since CRT v8.0 you can not handle security errors. 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.


\subsection error_report_analyzis_functionality Error Report Analyzis Functionality

Error report analyzis functionality consists of two modules:

- \b CrashRptProbe.dll implements API that can be used to access error report data.
- \b crprober.exe is a console tool that helps to extract error report data and
   write the summary in a human-readable form.

When you receive many error reports from users of your software, you 
would have to spend a lot of time to open each report, analyze its contents and
write some summary about the report. There may be many reports related to the same 
problem, so opening such reports doesn't tell anything new. The error report analyzis
functionality is designed to address these problems. For additional information, 
see \ref analyzing_error_reports.

\section architecture_faq FAQ

<b>My software is not an EXE, but DLL. Can I use crashrpt in such case?</b>

Well, you can install exception handlers in your \b DllMain() function, but typically 
you can't guarantee that the client process (EXE) won't install its own exception 
handlers above yours. And there might be some problems if the client process uses 
several worker threads that call functions from your DLL. In such case you would 
have to install per-thread exception handlers too. It would be better if 
the client process take care of exception handling instead of your DLL.

<b>How do I use crashrpt across process boundaries?</b>

Each process loads its own copy of \c CrashRpt.dll. It is difficult to imagine 
how you can share single loaded instance of CrashRpt.dll between several processes. 
Currently CrashRpt doesn't support such possibility.  


<b>Does using crashrpt affect performance of my application?</b>

No, using CrashRpt doesn't affect performance of your application. CrashRpt doesn't 
perform any tasks in background and doesn't use additional memory. CrashRpt code is 
executed just when an exception is raised.

<b>Does using crashrpt make it easier for somebody to reverse engineer my code?</b>

No, actually not. In order to use CrashRpt, you enable program database generation 
in Release configuration (/Zi compiler flag and /DEBUG linker flag) and this generates 
.PDB file for your project. PDB files contain information which can be used to reverse 
engineer your code, however you typically store such information locally and do not 
distribute it with your software release package. So, using CrashRpt doesn't affect 
the difficulty of reverse engineering your code. 

*/

