DoctorDumpSDK
Public Member Functions | Static Public Attributes | List of all members
crash_rpt::CrashRpt Class Reference

To enable crash processing you should create an instance of this class. More...

#include <CrashRpt.h>

Public Member Functions

 CrashRpt (LPCSTR applicationGUID, LPCWSTR appName, LPCWSTR company) throw ()
 
 CrashRpt (LPCSTR applicationGUID, LPCSTR prefix, LPCWSTR appName, LPCWSTR company, BOOL ownProcess=TRUE) throw ()
 
 CrashRpt (LPCWSTR crashrptPath, LPCSTR applicationGUID, LPCSTR prefix, LPCWSTR appName, LPCWSTR company, BOOL ownProcess=TRUE) throw ()
 
 CrashRpt (ApplicationInfo *applicationInfo, HandlerSettings *handlerSettings, BOOL ownProcess=TRUE) throw ()
 
 CrashRpt (LPCWSTR crashrptPath, ApplicationInfo *applicationInfo, HandlerSettings *handlerSettings, BOOL ownProcess=TRUE) throw ()
 
 CrashRpt (LPCWSTR crashrptPath=NULL) throw ()
 
 ~CrashRpt ()
 
bool IsCrashHandlingEnabled () const
 
bool InitCrashRpt (ApplicationInfo *applicationInfo, HandlerSettings *handlerSettings, BOOL ownProcess=TRUE) throw ()
 
bool InitCrashHandler (ApplicationInfo *applicationInfo, HandlerSettings *handlerSettings, BOOL ownProcess=TRUE) throw ()
 
bool InitCrashRpt (LPCSTR applicationGUID, LPCSTR prefix, LPCWSTR appName, LPCWSTR company, BOOL ownProcess=TRUE) throw ()
 
bool SetCustomInfo (LPCWSTR text)
 
bool AddUserInfoToReport (LPCWSTR key, LPCWSTR value) throw ()
 
bool RemoveUserInfoFromReport (LPCWSTR key)
 
bool AddFileToReport (LPCWSTR path, LPCWSTR reportFileName) throw ()
 
bool RemoveFileFromReport (LPCWSTR path) throw ()
 
bool GetVersionFromApp (ApplicationInfo *appInfo) throw ()
 
bool GetVersionFromFile (LPCWSTR path, ApplicationInfo *appInfo) throw ()
 
LONG SendReport (EXCEPTION_POINTERS *exceptionPointers)
 
void SkipDoctorDump_SendAssertionViolated (LPCSTR dumpGroup=NULL) const
 

Static Public Attributes

static const DWORD ExceptionAssertionViolated = ((DWORD)0xCCE17000)
 
static const DWORD ExceptionCppTerminate = ((DWORD)0xCCE17001)
 Exception code for Terminate()/SIGABRT call in crash callback.
 
static const DWORD ExceptionPureCall = ((DWORD)0xCCE17002)
 Exception code for pure virtual call in crash callback.
 
static const DWORD ExceptionInvalidParameter = ((DWORD)0xCCE17003)
 Exception code for CRT invalid parameter call in crash callback.
 

Detailed Description

To enable crash processing you should create an instance of this class.

It should be created as global static object and correctly initialized. Also you may instantiate it in your main() or WinMain() function as soon as possible.

Examples:
Sample.cpp.

Constructor & Destructor Documentation

crash_rpt::CrashRpt::CrashRpt ( LPCSTR  applicationGUID,
LPCWSTR  appName,
LPCWSTR  company 
)
throw (
)
inline

CrashRpt constructor. Loads crashrpt.dll and initializes crash handling.

Note
The crashrpt.dll is allowed to be missing. In that case there will be no crash handling.
Parameters
[in]applicationGUIDGUID assigned to this application.
[in]appNameApplication name that will be shown in message box.
[in]companyCompany name that will be shown in message box.
crash_rpt::CrashRpt::CrashRpt ( LPCSTR  applicationGUID,
LPCSTR  prefix,
LPCWSTR  appName,
LPCWSTR  company,
BOOL  ownProcess = TRUE 
)
throw (
)
inline

CrashRpt constructor. Loads crashrpt.dll and initializes crash handling.

Note
The crashrpt.dll is allowed to be missing. In that case there will be no crash handling.
Parameters
[in]applicationGUIDGUID assigned to this application.
[in]prefixPrefix that will be used with the dump name: YourPrefix_v1.v2.v3.v4_YYYYMMDD_HHMMSS.mini.dmp.
[in]appNameApplication name that will be shown in message box.
[in]companyCompany name that will be shown in message box.
[in]ownProcessIf you own the process your code running in set this option to TRUE. If don't (for example you write a plugin to some external application) set this option to FALSE. In that case you need to explicitly catch exceptions. See SendReport for more information.
crash_rpt::CrashRpt::CrashRpt ( LPCWSTR  crashrptPath,
LPCSTR  applicationGUID,
LPCSTR  prefix,
LPCWSTR  appName,
LPCWSTR  company,
BOOL  ownProcess = TRUE 
)
throw (
)
inline

CrashRpt constructor. Loads crashrpt.dll and initializes crash handling.

Note
The crashrpt.dll is allowed to be missing. In that case there will be no crash handling.
Parameters
[in]crashrptPathPath to crashrpt.dll file. File may be renamed.
[in]applicationGUIDGUID assigned to this application.
[in]prefixPrefix that will be used with the dump name: YourPrefix_v1.v2.v3.v4_YYYYMMDD_HHMMSS.mini.dmp.
[in]appNameApplication name that will be shown in message box.
[in]companyCompany name that will be shown in message box.
[in]ownProcessIf you own the process your code running in set this option to TRUE. If don't (for example you write a plugin to some external application) set this option to FALSE. In that case you need to explicitly catch exceptions. See SendReport for more information.
crash_rpt::CrashRpt::CrashRpt ( ApplicationInfo applicationInfo,
HandlerSettings handlerSettings,
BOOL  ownProcess = TRUE 
)
throw (
)
inline

CrashRpt constructor. Loads crashrpt.dll and initializes crash handling.

Note
The crashrpt.dll is allowed to be missing. In that case there will be no crash handling.
Parameters
[in]applicationInfoPointer to the ApplicationInfo structure that identifies your application.
[in]handlerSettingsPointer to the HandlerSettings structure that customizes crash handling behavior. This parameter can be NULL.
[in]ownProcessIf you own the process your code running in set this option to TRUE. If don't (for example you write a plugin to some external application) set this option to FALSE. In that case you need to explicitly catch exceptions. See SendReport for more information.
crash_rpt::CrashRpt::CrashRpt ( LPCWSTR  crashrptPath,
ApplicationInfo applicationInfo,
HandlerSettings handlerSettings,
BOOL  ownProcess = TRUE 
)
throw (
)
inline

CrashRpt constructor. Loads crashrpt.dll and initializes crash handling.

Note
The crashrpt.dll is allowed to be missing. In that case there will be no crash handling.
Parameters
[in]crashrptPathPath to crashrpt.dll file. File may be renamed.
[in]applicationInfoPointer to the ApplicationInfo structure that identifies your application.
[in]handlerSettingsPointer to the HandlerSettings structure that customizes crash handling behavior. This parameter can be NULL.
[in]ownProcessIf you own the process your code running in set this option to TRUE. If don't (for example you write a plugin to some external application) set this option to FALSE. In that case you need to explicitly catch exceptions. See SendReport for more information.
crash_rpt::CrashRpt::CrashRpt ( LPCWSTR  crashrptPath = NULL)
throw (
)
inline

CrashRpt constructor. Loads crashrpt.dll. You should call InitCrashRpt to turn on crash handling.

Note
The crashrpt.dll is allowed to be missing. In that case there will be no crash handling.
Parameters
[in]crashrptPathPath to crashrpt.dll file. File may be renamed.
crash_rpt::CrashRpt::~CrashRpt ( )
inline

CrashRpt destructor.

Note
It doesn't unload crashrpt.dll and doesn't disable crash handling since crash may appear on very late phase of application exit. For example destructor of some static variable that is called after return from main() may crash.

Member Function Documentation

bool crash_rpt::CrashRpt::AddFileToReport ( LPCWSTR  path,
LPCWSTR  reportFileName 
)
throw (
)
inline

You may add any file to crash report. This file will be read when crash appears and will be sent within the report. Multiple files may be added. Filename of the file in the report may be changed to any name.

Returns
If the function succeeds, the return value is true.
Note
This function is thread safe.
Parameters
[in]pathPath to the file, that will be added to the report.
[in]reportFileNameFilename that will be used in report for this file. If parameter is NULL, original name from path will be used.
bool crash_rpt::CrashRpt::AddUserInfoToReport ( LPCWSTR  key,
LPCWSTR  value 
)
throw (
)
inline

You may add any key/value pair to crash report.

Returns
If the function succeeds, the return value is true.
Note
This function is thread safe.
Parameters
[in]keykey string that will be added to the report.
[in]valuevalue for the key.
bool crash_rpt::CrashRpt::GetVersionFromApp ( ApplicationInfo appInfo)
throw (
)
inline

Fills version field (V) of ApplicationInfo with product version found in the executable file of the current process.

Returns
If the function succeeds, the return value is true.
Parameters
[out]appInfoPointer to ApplicationInfo structure. Its version field (V) will be set to product version.
bool crash_rpt::CrashRpt::GetVersionFromFile ( LPCWSTR  path,
ApplicationInfo appInfo 
)
throw (
)
inline

Fill version field (V) of ApplicationInfo with product version found in the file specified.

Returns
If the function succeeds, the return value is true.
Parameters
[in]pathPath to the file product version will be extracted from.
[out]appInfoPointer to ApplicationInfo structure. Its version field (V) will be set to product version.
bool crash_rpt::CrashRpt::InitCrashHandler ( ApplicationInfo applicationInfo,
HandlerSettings handlerSettings,
BOOL  ownProcess = TRUE 
)
throw (
)
inline

Initializes crash handler.

Returns
Return true if crash handling was enabled.
Warning
This method is deprecated. Use InitCrashRpt instead.
Parameters
[in]applicationInfoPointer to the ApplicationInfo structure that identifies your application.
[in]handlerSettingsPointer to the HandlerSettings structure that customizes crash handling behavior. This parameter can be NULL.
[in]ownProcessIf you own the process your code running in set this option to TRUE. If don't (for example you write a plugin to some external application) set this option to FALSE. In that case you need to explicitly catch exceptions. See SendReport for more information.
bool crash_rpt::CrashRpt::InitCrashRpt ( ApplicationInfo applicationInfo,
HandlerSettings handlerSettings,
BOOL  ownProcess = TRUE 
)
throw (
)
inline

Initializes crash handler.

Note
You may call this function multiple times if some data has changed.
Returns
Return true if crash handling was enabled.
Parameters
[in]applicationInfoPointer to the ApplicationInfo structure that identifies your application.
[in]handlerSettingsPointer to the HandlerSettings structure that customizes crash handling behavior. This parameter can be NULL.
[in]ownProcessIf you own the process your code running in set this option to TRUE. If don't (for example you write a plugin to some external application) set this option to FALSE. In that case you need to explicitly catch exceptions. See SendReport for more information.
bool crash_rpt::CrashRpt::InitCrashRpt ( LPCSTR  applicationGUID,
LPCSTR  prefix,
LPCWSTR  appName,
LPCWSTR  company,
BOOL  ownProcess = TRUE 
)
throw (
)
inline

Initializes crash handler.

Note
You may call this function multiple times if some data has changed.
Returns
Return true if crash handling was enabled.
Parameters
[in]applicationGUIDGUID assigned to this application.
[in]prefixPrefix that will be used with the dump name: YourPrefix_v1.v2.v3.v4_YYYYMMDD_HHMMSS.mini.dmp.
[in]appNameApplication name that will be shown in message box.
[in]companyCompany name that will be shown in message box.
[in]ownProcessIf you own the process your code running in set this option to TRUE. If don't (for example you write a plugin to some external application) set this option to FALSE. In that case you need to explicitly catch exceptions. See SendReport for more information.
bool crash_rpt::CrashRpt::IsCrashHandlingEnabled ( ) const
inline

Checks that crash handling was enabled.

Returns
Return true if crash handling was enabled.
bool crash_rpt::CrashRpt::RemoveFileFromReport ( LPCWSTR  path)
throw (
)
inline

Remove from report the file that was registered earlier to be sent within report.

Returns
If the function succeeds, the return value is true.
Note
This function is thread safe.
Parameters
[in]pathPath to the file, that will be removed from the report.
bool crash_rpt::CrashRpt::RemoveUserInfoFromReport ( LPCWSTR  key)
inline

You may remove any key that was added previously to crash report by AddUserInfoToReport.

Returns
If the function succeeds, the return value is true.
Note
This function is thread safe.
Parameters
[in]keykey string that will be removed from the report.
LONG crash_rpt::CrashRpt::SendReport ( EXCEPTION_POINTERS *  exceptionPointers)
inline

If you do not own the process your code running in (for example you write a plugin to some external application) you need to properly initialize CrashRpt using ownProcess option. Also you need to explicitly catch all exceptions in all entry points to your code and in all threads you create. To do so use this construction:

bool SomeEntryPoint(PARAM p)
{
__try
{
return YouCode(p);
}
__except (CrashRpt::SendReport(GetExceptionInformation()))
{
::ExitProcess(0); // It is better to stop the process here or else corrupted data may incomprehensibly crash it later.
return false;
}
}
Parameters
[in]exceptionPointersPointer to EXCEPTION_POINTERS structure. You should get it using GetExceptionInformation() function inside __except keyword.
bool crash_rpt::CrashRpt::SetCustomInfo ( LPCWSTR  text)
inline
Note
This function is experimental and may not be available and may not be support by Doctor Dump in the future. You may set custom information for your possible report. This text will be available on Doctor Dump dumps page. The text should not contain private information.
Returns
If the function succeeds, the return value is true.
Parameters
[in]textcustom info for the report. The text will be cut to 100 characters.
void crash_rpt::CrashRpt::SkipDoctorDump_SendAssertionViolated ( LPCSTR  dumpGroup = NULL) const
inline

Sends assertion violation report from this point and continue execution.

See also
ExceptionAssertionViolated
Note
Functions containing "SkipDoctorDump" will be ignored in stack parsing.
See also
CRASHRPT_ENABLE_RELEASE_ASSERTS ExceptionAssertionViolated
Parameters
[in]dumpGroupAll dumps with that group will be separated from dumps with same stack but another group. Set parameter to NULL if no grouping is required.

Member Data Documentation

const DWORD crash_rpt::CrashRpt::ExceptionAssertionViolated = ((DWORD)0xCCE17000)
static

To send a report about violated assertion you can throw exception with this exception code using:

RaiseException(CrashRpt::ExceptionAssertionViolated, 0, 0, NULL);

Execution will continue after report will be sent (EXCEPTION_CONTINUE_EXECUTION would be used). You may pass grouping string as first parameter (see SkipDoctorDump_SendAssertionViolated).

Note
If you called CrashRpt constructor and crashrpt.dll was missing you still may using this exception. It will be caught, ignored and execution will continue. SendReport function also works safely when crashrpt.dll was missing.
See also
CRASHRPT_ENABLE_RELEASE_ASSERTS SkipDoctorDump_SendAssertionViolated