CrashRpt Functions

Macros
#define	crSetEmailSubject   crSetEmailSubjectA
	Character set-independent mapping of crSetEmailSubjectW() and crSetEmailSubjectA() functions.
#define	crSetCrashCallback   crSetCrashCallbackA
	Character set-independent mapping of crSetCrashCallbackW() and crSetCrashCallbackA() functions.
#define	crInstall   crInstallA
	Character set-independent mapping of crInstallW() and crInstallA() functions.
#define	crAddFile2   crAddFile2A
	Character set-independent mapping of crAddFile2W() and crAddFile2A() functions.
#define	crAddProperty   crAddPropertyA
	Character set-independent mapping of crAddPropertyW() and crAddPropertyA() functions.
#define	crAddRegKey   crAddRegKeyA
	Character set-independent mapping of crAddRegKeyW() and crAddRegKeyA() functions.
#define	crGetLastErrorMsg   crGetLastErrorMsgA
	Defines character set-independent mapping for crGetLastErrorMsgW() and crGetLastErrorMsgA().

Typedefs
typedef int(CALLBACK *	PFNCRASHCALLBACKW) (CR_CRASH_CALLBACK_INFOW *pInfo)
	Client crash callback function prototype. More...
typedef int(CALLBACK *	PFNCRASHCALLBACKA) (CR_CRASH_CALLBACK_INFOA *pInfo)
	Client crash callback function prototype. More...

Functions
	crSetCrashCallbackW (PFNCRASHCALLBACKW pfnCallbackFunc, LPVOID lpParam)
	Sets the crash callback function. More...
	crSetCrashCallbackA (PFNCRASHCALLBACKA pfnCallbackFunc, LPVOID lpParam)
	Sets the crash callback function. More...
	crInstallW (__in PCR_INSTALL_INFOW pInfo)
	Installs exception handlers for the caller process. More...
	crInstallA (__in PCR_INSTALL_INFOA pInfo)
	Installs exception handlers for the caller process. More...
	crUninstall ()
	Uninitializes the CrashRpt library and unsinstalls exception handlers previously installed with crInstall(). More...
	crInstallToCurrentThread2 (DWORD dwFlags)
	Installs exception handlers to the caller thread. More...
	crUninstallFromCurrentThread ()
	Uninstalls C++ exception handlers from the current thread. More...
	crAddFile2W (LPCWSTR pszFile, LPCWSTR pszDestFile, LPCWSTR pszDesc, DWORD dwFlags)
	Adds a file to crash report. More...
	crAddFile2A (LPCSTR pszFile, LPCSTR pszDestFile, LPCSTR pszDesc, DWORD dwFlags)
	Adds a file to crash report. More...
	crAddScreenshot2 (DWORD dwFlags, int nJpegQuality)
	Adds a screenshot to the crash report. More...
	crAddVideo (DWORD dwFlags, int nDuration, int nFrameInterval, PSIZE pDesiredFrameSize, HWND hWndParent)
	Allows to record what happened before crash to a video file and include the file to crash report. More...
	crAddPropertyW (LPCWSTR pszPropName, LPCWSTR pszPropValue)
	Adds a string property to the crash report. More...
	crAddPropertyA (LPCSTR pszPropName, LPCSTR pszPropValue)
	Adds a string property to the crash report. More...
	crAddRegKeyW (LPCWSTR pszRegKey, LPCWSTR pszDstFileName, DWORD dwFlags)
	Adds a registry key dump to the crash report. More...
	crAddRegKeyA (LPCSTR pszRegKey, LPCSTR pszDstFileName, DWORD dwFlags)
	Adds a registry key dump to the crash report. More...
	crGenerateErrorReport (__in_opt CR_EXCEPTION_INFO *pExceptionInfo)
	Manually generates an error report. More...
	crExceptionFilter (unsigned int code, __in_opt struct _EXCEPTION_POINTERS *ep)
	Can be used as a SEH exception filter. More...
	crEmulateCrash (unsigned ExceptionType) throw (...)
	Emulates a predefined crash situation. More...
	crGetLastErrorMsgW (__out_ecount_z(uBuffSize) LPWSTR pszBuffer, UINT uBuffSize)
	Gets the last CrashRpt error message. More...
	crGetLastErrorMsgA (__out_ecount_z(uBuffSize) LPSTR pszBuffer, UINT uBuffSize)
	Gets the last CrashRpt error message. More...

Detailed Description

Typedef Documentation

PFNCRASHCALLBACKA

typedef int(CALLBACK * PFNCRASHCALLBACKA) (CR_CRASH_CALLBACK_INFOA *pInfo)

Client crash callback function prototype.

Parameters

[in]

pInfo

Points to information about the crash.

Remarks

The crash callback function is called when a crash occurs. This way client application is notified about the crash.

Crash information is passed by CrashRpt to the callback function through the pInfo parameter as a pointer to CR_CRASH_CALLBACK_INFO structure. See below for a code example.

It is generally unsafe to do complex actions (e.g. memory allocation, heap operations) inside of this callback. The application state may be unstable.

One reason the application may use this callback for is to close handles to open log files that the application plans to include into the error report. Files should be accessible for reading, otherwise CrashRpt won't be able to include them into error report.

It is also possible (but not recommended) to add files (see crAddFile2()), properties (see crAddProperty()), desktop screenshots (see crAddScreenshot2()) and registry keys (see crAddRegKey()) inside of the crash callback function.

By default, CrashRpt terminates the client application after crash report generation and launching the CrashSender.exe process. However, it is possible to continue program execution after crash report generation by seting CR_CRASH_CALLBACK_INFO::bContinueExecution structure field to TRUE.

The crash report generation consists of several stages. First, exception pointers are retrieved and the callback function is called for the first time. The callback function may check the retrieved exception information and decide wheter to proceed with crash report generation or to continue client program execution. On the next stage, the CrashSender.exe process is launched and the crash callback function is (optionally) called for the second time. Further crash report data collection and delivery work is performed in CrashSender.exe process. The crash callback may use the provided handle to CrashSender.exe process to wait until it exits.

The crash callback function should typically return CR_CB_DODEFAULT constant to proceed with error report generation without being called back on the next stage(s). Returning the CR_CB_NOTIFY_NEXT_STAGE constant causes CrashRpt to call the crash callback function on the next stage, too. Returning CR_CB_CANCEL constant will prevent further stage(s) of crash report generation.

PFNCRASHCALLBACKW() and PFNCRASHCALLBACKA() are wide-character and multi-byte character versions of PFNCRASHCALLBACK() function.

The following code example shows the simplest way of using the crash callback function:

// Define the crash callback
int CALLBACK CrashCallback(CR_CRASH_CALLBACK_INFO* pInfo)
{    
   
   // Do something...

   // Proceed with crash report generation. 
   // This return code also makes CrashRpt to not call this callback function for 
   // the next crash report generation stage.
   return CR_CB_DODEFAULT;
}

The following code example shows how to use the crash callback function to be notified on every stage of crash report generation:

// Define the crash callback
int CALLBACK CrashCallback(CR_CRASH_CALLBACK_INFO* pInfo)
{    
   
   // We want to continue program execution after crash report generation
   pInfo->bContinueExecution = TRUE;

   switch(pInfo->nStage)
   {
       case CR_CB_STAGE_PREPARE:
             // do something
             break;
       case CR_CB_STAGE_FINISH:
             // do something
             break;
   }

   // Proceed to the next stage. 
   return CR_CB_NOTIFY_NEXT_STAGE;
}

See also

CR_CRASH_CALLBACK_INFO, crSetCrashCallback(), crAddFile2(), crAddProperty(), crAddScreenshot2(), crAddRegKey()

PFNCRASHCALLBACKW

typedef int(CALLBACK * PFNCRASHCALLBACKW) (CR_CRASH_CALLBACK_INFOW *pInfo)

Client crash callback function prototype.

Parameters

[in]

pInfo

Points to information about the crash.

Remarks

The crash callback function is called when a crash occurs. This way client application is notified about the crash.

Crash information is passed by CrashRpt to the callback function through the pInfo parameter as a pointer to CR_CRASH_CALLBACK_INFO structure. See below for a code example.

It is generally unsafe to do complex actions (e.g. memory allocation, heap operations) inside of this callback. The application state may be unstable.

One reason the application may use this callback for is to close handles to open log files that the application plans to include into the error report. Files should be accessible for reading, otherwise CrashRpt won't be able to include them into error report.

It is also possible (but not recommended) to add files (see crAddFile2()), properties (see crAddProperty()), desktop screenshots (see crAddScreenshot2()) and registry keys (see crAddRegKey()) inside of the crash callback function.

By default, CrashRpt terminates the client application after crash report generation and launching the CrashSender.exe process. However, it is possible to continue program execution after crash report generation by seting CR_CRASH_CALLBACK_INFO::bContinueExecution structure field to TRUE.

The crash report generation consists of several stages. First, exception pointers are retrieved and the callback function is called for the first time. The callback function may check the retrieved exception information and decide wheter to proceed with crash report generation or to continue client program execution. On the next stage, the CrashSender.exe process is launched and the crash callback function is (optionally) called for the second time. Further crash report data collection and delivery work is performed in CrashSender.exe process. The crash callback may use the provided handle to CrashSender.exe process to wait until it exits.

The crash callback function should typically return CR_CB_DODEFAULT constant to proceed with error report generation without being called back on the next stage(s). Returning the CR_CB_NOTIFY_NEXT_STAGE constant causes CrashRpt to call the crash callback function on the next stage, too. Returning CR_CB_CANCEL constant will prevent further stage(s) of crash report generation.

PFNCRASHCALLBACKW() and PFNCRASHCALLBACKA() are wide-character and multi-byte character versions of PFNCRASHCALLBACK() function.

The following code example shows the simplest way of using the crash callback function:

// Define the crash callback
int CALLBACK CrashCallback(CR_CRASH_CALLBACK_INFO* pInfo)
{    
   
   // Do something...

   // Proceed with crash report generation. 
   // This return code also makes CrashRpt to not call this callback function for 
   // the next crash report generation stage.
   return CR_CB_DODEFAULT;
}

The following code example shows how to use the crash callback function to be notified on every stage of crash report generation:

// Define the crash callback
int CALLBACK CrashCallback(CR_CRASH_CALLBACK_INFO* pInfo)
{    
   
   // We want to continue program execution after crash report generation
   pInfo->bContinueExecution = TRUE;

   switch(pInfo->nStage)
   {
       case CR_CB_STAGE_PREPARE:
             // do something
             break;
       case CR_CB_STAGE_FINISH:
             // do something
             break;
   }

   // Proceed to the next stage. 
   return CR_CB_NOTIFY_NEXT_STAGE;
}

See also

CR_CRASH_CALLBACK_INFO, crSetCrashCallback(), crAddFile2(), crAddProperty(), crAddScreenshot2(), crAddRegKey()

Function Documentation

crAddFile2A()

crAddFile2A	(	LPCSTR	pszFile,
		LPCSTR	pszDestFile,
		LPCSTR	pszDesc,
		DWORD	dwFlags
	)

Adds a file to crash report.

Returns

This function returns zero if succeeded.

Parameters

[in]	pszFile	Absolute path to the file (or file search pattern) to add to crash report, required.
[in]	pszDestFile	Destination file name, optional.
[in]	pszDesc	File description (used in Error Report Details dialog), optional.
[in]	dwFlags	Flags, optional.

This function can be called anytime after crInstall() to add one or more files to the generated crash report.

When this function is called, the file is marked to be added to the error report, then the function returns control to the caller. When a crash occurs, all marked files are added to the report by the CrashSender.exe process. If a file is locked by someone for exclusive access, the file won't be included. Inside of PFNCRASHCALLBACK() crash callback, close open file handles and ensure files to be included are acessible for reading.

pszFile should be either a valid absolute path to the file or a file search pattern (e.g. "*.log") to be added to crash report.

pszDestFile should be the name of destination file. This parameter can be used to specify different file name for the file in ZIP archive. If this parameter is NULL, the pszFile file name is used as destination file name. If pszFile is a search pattern, this argument is ignored.

pszDesc is a short description of the file. It can be NULL.

dwFlags parameter defines the behavior of the function. This can be a combination of the following flags:

• CR_AF_TAKE_ORIGINAL_FILE On crash, the CrashSender.exe process will try to locate the file from its original location. This behavior is the default one.
• CR_AF_MAKE_FILE_COPY On crash, the CrashSender.exe process will make a copy of the file and save it to the error report folder.
• CR_AF_FILE_MUST_EXIST The function will fail if file doesn't exist at the moment of function call (the default behavior).
• CR_AF_MISSING_FILE_OK The function will not fail if file is missing (assume it will be created later).
• CR_AF_ALLOW_DELETE If this flag is specified, the user will be able to delete the file from error report using context menu of Error Report Details dialog.

If you do not use error report delivery (CR_INST_DONT_SEND_REPORT flag) or if you use postponed error report delivery (if you specify CR_INST_SEND_QUEUED_REPORTS flag) you must also specify the CR_AF_MAKE_FILE_COPY as dwFlags parameter value. This will guarantee that a snapshot of your file at the moment of crash is taken and saved to the error report folder. The error report folder is a folder where files included into the crash report are stored until they are sent to recipient.

This function fails if pszFile doesn't exist at the moment of function call, unless you specify CR_AF_MISSING_FILE_OK flag.

The crAddFile2W() and crAddFile2A() are wide-character and multibyte-character versions of crAddFile2() function. The crAddFile2() macro defines character set independent mapping.

Usage example:

// Add the error.log file to crash report. At the moment of crash, 
// the file will be copied to crash report folder. The end user 
// will be able to delete the file using CrashRpt GUI.
int nResult = crAddFile2(
           _T("C:\\Program Files (x86)\MyApp\\error.log"), 
           _T("error.log"), 
           _T("Log file"), 
           CR_AF_MAKE_FILE_COPY|CR_AF_ALLOW_DELETE);
if(nResult!=0)
{
  // Get the status message
  TCHAR szErrorMsg[256];
  crGetLastErrorMsg(szErrorMsg, 256);
}

// Add all *.txt files found in the folder. At the moment of crash, 
// the file(s) will be copied to crash report folder. The end user 
// won't be able to delete the file(s).
crAddFile2(_T("C:\\Program Files (x86)\MyApp\\*.txt"), 
    NULL, _T("TXT file"), CR_AF_MAKE_FILE_COPY);

See also

crAddFile2W(), crAddFile2A(), crAddFile2()

crAddFile2W()

crAddFile2W	(	LPCWSTR	pszFile,
		LPCWSTR	pszDestFile,
		LPCWSTR	pszDesc,
		DWORD	dwFlags
	)

Adds a file to crash report.

Returns

This function returns zero if succeeded.

Parameters

[in]	pszFile	Absolute path to the file (or file search pattern) to add to crash report, required.
[in]	pszDestFile	Destination file name, optional.
[in]	pszDesc	File description (used in Error Report Details dialog), optional.
[in]	dwFlags	Flags, optional.

This function can be called anytime after crInstall() to add one or more files to the generated crash report.

When this function is called, the file is marked to be added to the error report, then the function returns control to the caller. When a crash occurs, all marked files are added to the report by the CrashSender.exe process. If a file is locked by someone for exclusive access, the file won't be included. Inside of PFNCRASHCALLBACK() crash callback, close open file handles and ensure files to be included are acessible for reading.

pszFile should be either a valid absolute path to the file or a file search pattern (e.g. "*.log") to be added to crash report.

pszDestFile should be the name of destination file. This parameter can be used to specify different file name for the file in ZIP archive. If this parameter is NULL, the pszFile file name is used as destination file name. If pszFile is a search pattern, this argument is ignored.

pszDesc is a short description of the file. It can be NULL.

dwFlags parameter defines the behavior of the function. This can be a combination of the following flags:

• CR_AF_TAKE_ORIGINAL_FILE On crash, the CrashSender.exe process will try to locate the file from its original location. This behavior is the default one.
• CR_AF_MAKE_FILE_COPY On crash, the CrashSender.exe process will make a copy of the file and save it to the error report folder.
• CR_AF_FILE_MUST_EXIST The function will fail if file doesn't exist at the moment of function call (the default behavior).
• CR_AF_MISSING_FILE_OK The function will not fail if file is missing (assume it will be created later).
• CR_AF_ALLOW_DELETE If this flag is specified, the user will be able to delete the file from error report using context menu of Error Report Details dialog.

If you do not use error report delivery (CR_INST_DONT_SEND_REPORT flag) or if you use postponed error report delivery (if you specify CR_INST_SEND_QUEUED_REPORTS flag) you must also specify the CR_AF_MAKE_FILE_COPY as dwFlags parameter value. This will guarantee that a snapshot of your file at the moment of crash is taken and saved to the error report folder. The error report folder is a folder where files included into the crash report are stored until they are sent to recipient.

This function fails if pszFile doesn't exist at the moment of function call, unless you specify CR_AF_MISSING_FILE_OK flag.

The crAddFile2W() and crAddFile2A() are wide-character and multibyte-character versions of crAddFile2() function. The crAddFile2() macro defines character set independent mapping.

Usage example:

// Add the error.log file to crash report. At the moment of crash, 
// the file will be copied to crash report folder. The end user 
// will be able to delete the file using CrashRpt GUI.
int nResult = crAddFile2(
           _T("C:\\Program Files (x86)\MyApp\\error.log"), 
           _T("error.log"), 
           _T("Log file"), 
           CR_AF_MAKE_FILE_COPY|CR_AF_ALLOW_DELETE);
if(nResult!=0)
{
  // Get the status message
  TCHAR szErrorMsg[256];
  crGetLastErrorMsg(szErrorMsg, 256);
}

// Add all *.txt files found in the folder. At the moment of crash, 
// the file(s) will be copied to crash report folder. The end user 
// won't be able to delete the file(s).
crAddFile2(_T("C:\\Program Files (x86)\MyApp\\*.txt"), 
    NULL, _T("TXT file"), CR_AF_MAKE_FILE_COPY);

See also

crAddFile2W(), crAddFile2A(), crAddFile2()

crAddPropertyA()

crAddPropertyA	(	LPCSTR	pszPropName,
		LPCSTR	pszPropValue
	)

Adds a string property to the crash report.

Returns

This function returns zero if succeeded. Use crGetLastErrorMsg() to retrieve the error message on fail.

Parameters

[in]	pszPropName	Name of the property, required.
[in]	pszPropValue	Value of the property, required.

Remarks

Use this function to add a string property to the crash description XML file. User-added properties are listed under <CustomProps> tag of the XML file. In the XML file properties are ordered by names in alphabetic order.

The following example shows how to add information about the amount of free disk space to the crash description XML file:

// It is assumed that you already calculated the amount of free disk space, 
// converted it to text and stored it as szFreeSpace string.
LPCTSTR szFreeSpace = _T("0 Kb");
crAddProperty(_T("FreeDiskSpace"), szFreeSpace);

See also

crAddFile2(), crAddScreenshot()

crAddPropertyW()

crAddPropertyW	(	LPCWSTR	pszPropName,
		LPCWSTR	pszPropValue
	)

Adds a string property to the crash report.

Returns

This function returns zero if succeeded. Use crGetLastErrorMsg() to retrieve the error message on fail.

Parameters

[in]	pszPropName	Name of the property, required.
[in]	pszPropValue	Value of the property, required.

Remarks

Use this function to add a string property to the crash description XML file. User-added properties are listed under <CustomProps> tag of the XML file. In the XML file properties are ordered by names in alphabetic order.

The following example shows how to add information about the amount of free disk space to the crash description XML file:

// It is assumed that you already calculated the amount of free disk space, 
// converted it to text and stored it as szFreeSpace string.
LPCTSTR szFreeSpace = _T("0 Kb");
crAddProperty(_T("FreeDiskSpace"), szFreeSpace);

See also

crAddFile2(), crAddScreenshot()

crAddRegKeyA()

crAddRegKeyA	(	LPCSTR	pszRegKey,
		LPCSTR	pszDstFileName,
		DWORD	dwFlags
	)

Adds a registry key dump to the crash report.

Returns

This function returns zero if succeeded. Use crGetLastErrorMsg() to retrieve the error message on fail.

Parameters

[in]	pszRegKey	Registry key to dump, required.
[in]	pszDstFileName	Name of the destination file, required.
[in]	dwFlags	Flags, reserved.

Remarks

Use this function to add a dump of a Windows registry key into the crash report. This function is available since v.1.2.6.

The pszRegKey parameter must be the name of the registry key. The key name should begin with "HKEY_CURRENT_USER" or "HKEY_LOCAL_MACHINE". Other root keys are not supported.

The content of the key specified by the pszRegKey parameter will be stored in a human-readable XML format and included into the error report as pszDstFileName destination file. You can dump multiple registry keys to the same destination file.

The dwFlags parameter can be either set to zero (no flags) or with the following constant:

• CR_AR_ALLOW_DELETE allows the user to delete the file from error report using context menu of Error Report Details dialog.

The following example shows how to dump two registry keys to a single regkey.xml file:

crAddRegKey(_T("HKEY_CURRENT_USER\\Software\\MyApp"), _T("regkey.xml"), 0);
crAddRegKey(_T("HKEY_LOCAL_MACHINE\\Software\\MyApp"), _T("regkey.xml"), 0);

See also

crAddFile2(), crAddScreenshot(), crAddProperty()

crAddRegKeyW()

crAddRegKeyW	(	LPCWSTR	pszRegKey,
		LPCWSTR	pszDstFileName,
		DWORD	dwFlags
	)

Adds a registry key dump to the crash report.

Returns

This function returns zero if succeeded. Use crGetLastErrorMsg() to retrieve the error message on fail.

Parameters

[in]	pszRegKey	Registry key to dump, required.
[in]	pszDstFileName	Name of the destination file, required.
[in]	dwFlags	Flags, reserved.

Remarks

Use this function to add a dump of a Windows registry key into the crash report. This function is available since v.1.2.6.

The pszRegKey parameter must be the name of the registry key. The key name should begin with "HKEY_CURRENT_USER" or "HKEY_LOCAL_MACHINE". Other root keys are not supported.

The content of the key specified by the pszRegKey parameter will be stored in a human-readable XML format and included into the error report as pszDstFileName destination file. You can dump multiple registry keys to the same destination file.

The dwFlags parameter can be either set to zero (no flags) or with the following constant:

• CR_AR_ALLOW_DELETE allows the user to delete the file from error report using context menu of Error Report Details dialog.

The following example shows how to dump two registry keys to a single regkey.xml file:

crAddRegKey(_T("HKEY_CURRENT_USER\\Software\\MyApp"), _T("regkey.xml"), 0);
crAddRegKey(_T("HKEY_LOCAL_MACHINE\\Software\\MyApp"), _T("regkey.xml"), 0);

See also

crAddFile2(), crAddScreenshot(), crAddProperty()

crAddScreenshot2()

crAddScreenshot2	(	DWORD	dwFlags,
		int	nJpegQuality
	)

Adds a screenshot to the crash report.

Returns

This function returns zero if succeeded. Use crGetLastErrorMsg() to retrieve the error message on fail.

Parameters

[in]	dwFlags	Flags, optional.
[in]	nJpegQuality	Defines the JPEG image quality, optional.

Remarks

This function can be used to take a screenshot at the moment of crash and add it to the error report. Screenshot information may help the developer to better understand state of the application at the moment of crash and reproduce the error.

When this function is called, screenshot flags are saved, then the function returns control to the caller. When crash occurs, screenshot is made by the CrashSender.exe process and added to the report.

dwFlags

Use one of the following constants to specify what part of virtual screen to capture:

• CR_AS_VIRTUAL_SCREEN Use this to take a screenshot of the whole desktop (virtual screen).
• CR_AS_MAIN_WINDOW Use this to take a screenshot of the main application main window.
• CR_AS_PROCESS_WINDOWS Use this to take a screenshot of all visible windows that belong to the process.

The main application window is a window that has a caption (WS_CAPTION), system menu (WS_SYSMENU) and the WS_EX_APPWINDOW extended style. If CrashRpt doesn't find such window, it considers the first found process window as the main window.

Screenshots are added in form of PNG files by default. You can specify the CR_AS_USE_JPEG_FORMAT flag to save screenshots as JPEG files instead.

If you use JPEG format, you can use the nJpegQuality parameter to define the JPEG image quality. This should be the number between 0 and 100, inclusively. The bigger the number, the better the quality and the bigger the JPEG file size. If you use PNG file format, this parameter is ignored.

In addition, you can specify the CR_AS_GRAYSCALE_IMAGE flag to make a grayscale screenshot (by default color image is made). Grayscale image gives smaller file size.

When capturing entire desktop consisting of several monitors, one screenshot file is added per each monitor.

You should be careful when using this feature, because screenshots may contain user-identifying or private information. Always specify purposes you will use collected information for in your Privacy Policy.

See also

crAddFile2()

crAddVideo()

crAddVideo	(	DWORD	dwFlags,
		int	nDuration,
		int	nFrameInterval,
		PSIZE	pDesiredFrameSize,
		HWND	hWndParent
	)

Allows to record what happened before crash to a video file and include the file to crash report.

Returns

This function returns zero if succeeded. Use crGetLastErrorMsg() to retrieve the error message on failure.

Parameters

[in]	dwFlags	Flags, optional.
[in]	nDuration	Video duration (in milliseconds). Optional.
[in]	nFrameInterval	Interval between subsequent frames (in milliseconds). Optional.
[in]	pDesiredFrameSize	Defines the desired video frame size, optional.
[in]	hWndParent	Window that becomes the parent for GUI displayed by this function. Optional.

Remarks

This function is available as of v.1.4.0.

dwFlags can be a combination of the following constants:

• use one of the following constants to specify what part of virtual screen to capture:
  • CR_AV_VIRTUAL_SCREEN Use this to capture the whole desktop (virtual screen). This is the default.
  • CR_AV_MAIN_WINDOW Use this to capture the application's main window.
  • CR_AV_PROCESS_WINDOWS Use this to capture all visible windows that belong to the process.
• use one of the following constants to define the desired video encoding quality:
  • CR_AV_QUALITY_LOW Low-quality video encoding. This is the default.
  • CR_AV_QUALITY_GOOD Good encoding quality, larger file.
  • CR_AV_QUALITY_BEST The best encoding quality, the largest file.
• use the CR_AV_ALLOW_DELETE to allow the user to delete the recorded video file from error report using context menu of Error Report Details dialog.

The main application window is a window that has a caption (WS_CAPTION), system menu (WS_SYSMENU) and the WS_EX_APPWINDOW extended style. If CrashRpt doesn't find such a window, it considers the first found process window as the main window.

When the function is called, it displays a dialog notifying the user about video recording. The displayed dialog's parent window can be specified with the hWndParent argument. If the hWndParent is NULL, the currently active process window becomes the parent. If you do not want to display the dialog, specify the CR_AV_NO_GUI flag for dwFlags argument.

The recorded video will be maximum nDuration milliseconds long with nFrameInterval milliseconds interval between subsequent video frames. If nDuration and nFrameInterval are set to zero (0), the default implementation-defined duration and frame interval are used.

The pDesiredFrameSize parameter allows to define the desired video frame size. Frame width and height must be a multiple of 16 (OGG Theora video codec's requirement). If they are not, they are modified automatically to be a multiple of 16.

To preserve correct aspect ratio of the captured area, set pDesiredFrameSize->cx or pDesiredFrameSize->cy to zero. For example, setting pDesiredFrameSize->cx=640 and pDesiredFrameSize->cy=0 results in video frames whose width is 640 pixels and height is calculated to preserve the correct aspect ratio of the captured area. If both cx and cy are specified, the aspect ratio of the captured area is not preserved.

Setting the pDesiredFrameSize parameter to NULL makes the function to determine the best video frame size automatically.

This function can be used to record the state of end user's desktop just before the moment of crash and add the video file to the error report. The recorded information may help the software vendor to better understand the state of the client application at the moment of crash and reproduce the error.

When this function is called, CrashRpt launches another process named CrashSender.exe. The CrashSender.exe process then continuously captures the desktop screenshots in background mode and stores them to disk as image files. To avoid high CPU load, image files are stored in uncompressed state as raw bitmap (BMP) files. When the count of screenshot files exceeds the predefined maximum number, the old screenshot files are reused cyclically.

If the client application does not crash and its main code or main window loop exits successfully, the captured desktop screenshot files are removed by the crUninstall() function call and CrashSender.exe process is terminated.

If the client application crashes at some moment of time, the recorded screenshot files are compressed by OGG Theora video codec and written into an .OGG file. The uncompressed temporary screenshots are then removed, and the resulting OGG file is included into crash report archive.

The OGG video format is a widely used video container provided by the open-source OGG Project. OGG files can be opened in a browser like Google Chrome or Mozilla Firefox or in another video player understanding this format, like ffmpeg.

Use this function only when necessary, because it may cause end user's computer performance loss. It also requires some amount of free disk space.

The recorded video may contain user-identifying or private information. Always specify the purposes you will use collected information for in your Privacy Policy.

Usage example:

// First install CrashRpt with crInstall() function

...

SIZE FrameSize = {0, 600}; // Frames 600 px in height
                    // Frame width is calculated automatically

// Start capturing desktop. Desktop capture video will
// be added to crash report on crash
int nResult = crAddVideo(
       CR_AV_VIRTUAL_SCREEN|CR_AV_QUALITY_GOOD, // Capture entire desktop
                                             // Good encoding quality
       10000,   // 10 seconds long video
       300,     // 300 msec between frames (3.33 FPS)
       &FrameSize,
       NULL
  );

See also

crAddFile2(), crAddScreenshot2(), crAddRegKey(), crUninstall().

crEmulateCrash()

crEmulateCrash	(	unsigned	ExceptionType	)
throw	(	...
	)

Emulates a predefined crash situation.

Returns

This function doesn't return if succeded. If failed, returns non-zero value. Call crGetLastErrorMsg() to get the last error message.

Parameters

[in]

ExceptionType

Type of crash.

Remarks

This function uses some a priori incorrect or vulnerable code or raises a C++ signal or raises an uncontinuable software exception to cause crash.

This function can be used to test if CrashRpt handles a crash situation correctly.

CrashRpt will intercept an error or exception if crInstall() and/or crInstallToCurrentThread2() were previously called. crInstall() installs exception handlers that function on per-process basis. crInstallToCurrentThread2() installs exception handlers that function on per-thread basis.

ExceptionType can be one of the following constants:

• CR_SEH_EXCEPTION This will generate a null pointer exception.
• CR_CPP_TERMINATE_CALL This results in call of terminate() C++ function.
• CR_CPP_UNEXPECTED_CALL This results in call of unexpected() C++ function.
• CR_CPP_PURE_CALL This emulates a call of pure virtual method call of a C++ class instance (Visual Studio .NET 2003 and later).
• CR_CPP_NEW_OPERATOR_ERROR This emulates C++ new operator failure (Visual Studio .NET 2003 and later).
• CR_CPP_SECURITY_ERROR This emulates copy of large amount of data to a small buffer (Visual Studio .NET 2003 only).
• CR_CPP_INVALID_PARAMETER This emulates an invalid parameter C++ exception (Visual Studio 2005 and later).
• CR_CPP_SIGABRT This raises SIGABRT signal (abnormal program termination).
• CR_CPP_SIGFPE This causes floating point exception.
• CR_CPP_SIGILL This raises SIGILL signal (illegal instruction signal).
• CR_CPP_SIGINT This raises SIGINT signal.
• CR_CPP_SIGSEGV This raises SIGSEGV signal.
• CR_CPP_SIGTERM This raises SIGTERM signal (program termination request).
• CR_NONCONTINUABLE_EXCEPTION This raises a noncontinuable software exception (expected result is the same as in CR_SEH_EXCEPTION).
• CR_THROW This throws a C++ typed exception (expected result is the same as in CR_CPP_TERMINATE_CALL).
• CR_STACK_OVERFLOW This causes stack overflow.

The CR_SEH_EXCEPTION uses null pointer write operation to cause the access violation.

The CR_NONCONTINUABLE_EXCEPTION has the same effect as CR_SEH_EXCEPTION, but it uses RaiseException() WinAPI function to raise noncontinuable software exception.

The following example shows how to use crEmulateCrash() function.

// emulate null pointer exception (access violation)
crEmulateCrash(CR_SEH_EXCEPTION);

crExceptionFilter()

crExceptionFilter	(	unsigned int	code,
		__in_opt struct _EXCEPTION_POINTERS *	ep
	)

Can be used as a SEH exception filter.

Returns

This function returns EXCEPTION_EXECUTE_HANDLER if succeeds; otherwise EXCEPTION_CONTINUE_SEARCH.

Parameters

[in]	code	Exception code.
[in]	ep	Exception pointers.

Remarks

This function can be called instead of a SEH exception filter inside of __try{}__except(Expression){} construction. The function generates an error report and returns control to the exception handler block.

The exception code is usually retrieved with GetExceptionCode() intrinsic function and the exception pointers are retrieved with GetExceptionInformation() intrinsic function.

If an error occurs, this function returns EXCEPTION_CONTINUE_SEARCH. Use crGetLastErrorMsg() to retrieve the error message on fail.

The following example shows how to use crExceptionFilter().

int* p = NULL;   // pointer to NULL
__try
{
   *p = 13; // causes an access violation exception;
}
__except(crExceptionFilter(GetExceptionCode(), GetExceptionInformation()))
{   
  // Terminate program
  ExitProcess(1);
}

crGenerateErrorReport()

crGenerateErrorReport

(

__in_opt CR_EXCEPTION_INFO *

pExceptionInfo

)

Manually generates an error report.

Returns

This function returns zero if succeeded. When failed, it returns a non-zero value. Use crGetLastErrorMsg() function to retrieve the error message.

Parameters

[in]

pExceptionInfo

Exception information.

Remarks

Call this function to manually generate a crash report. When crash information is collected, control is returned to the caller. The crGenerateErrorReport() doesn't terminate the caller process.

The crash report may contain the crash minidump file, crash description file in XML format and additional custom files added with a function like crAddFile2().

The exception information should be passed using CR_EXCEPTION_INFO structure.

The following example shows how to use crGenerateErrorReport() function.

CR_EXCEPTION_INFO ei;
memset(&ei, 0, sizeof(CR_EXCEPTION_INFO));
ei.cb = sizeof(CR_EXCEPTION_INFO);
ei.exctype = CR_SEH_EXCEPTION;
ei.code = 1234;
ei.pexcptrs = NULL;

int result = crGenerateErrorReport(&ei);

if(result!=0)
{
  // If goes here, crGenerateErrorReport() has failed
  // Get the last error message
  TCHAR szErrorMsg[256];
  crGetLastErrorMsg(szErrorMsg, 256);
}

// Manually terminate program
ExitProcess(0);

crGetLastErrorMsgA()

crGetLastErrorMsgA	(	__out_ecount_z(uBuffSize) LPSTR	pszBuffer,
		UINT	uBuffSize
	)

Gets the last CrashRpt error message.

Returns

This function returns length of error message in characters. If output buffer is invalid, returns a negative number.

Parameters

[out]	pszBuffer	Pointer to the buffer.
[in]	uBuffSize	Size of buffer in characters.

Remarks

This function gets the last CrashRpt error message. You can use this function to retrieve the text status of the last called CrashRpt function.

If buffer is too small for the error message, the message is truncated.

crGetLastErrorMsgW() and crGetLastErrorMsgA() are wide-character and multi-byte character versions of crGetLastErrorMsg(). The crGetLastErrorMsg() macro defines character set independent mapping.

The following example shows how to use crGetLastErrorMsg() function.

// .. call some CrashRpt function

// Get the status message
TCHAR szErrorMsg[256];
crGetLastErrorMsg(szErrorMsg, 256);

See also

crGetLastErrorMsgA(), crGetLastErrorMsgW(), crGetLastErrorMsg()

crGetLastErrorMsgW()

crGetLastErrorMsgW	(	__out_ecount_z(uBuffSize) LPWSTR	pszBuffer,
		UINT	uBuffSize
	)

Gets the last CrashRpt error message.

Returns

This function returns length of error message in characters. If output buffer is invalid, returns a negative number.

Parameters

[out]	pszBuffer	Pointer to the buffer.
[in]	uBuffSize	Size of buffer in characters.

Remarks

This function gets the last CrashRpt error message. You can use this function to retrieve the text status of the last called CrashRpt function.

If buffer is too small for the error message, the message is truncated.

crGetLastErrorMsgW() and crGetLastErrorMsgA() are wide-character and multi-byte character versions of crGetLastErrorMsg(). The crGetLastErrorMsg() macro defines character set independent mapping.

The following example shows how to use crGetLastErrorMsg() function.

// .. call some CrashRpt function

// Get the status message
TCHAR szErrorMsg[256];
crGetLastErrorMsg(szErrorMsg, 256);

See also

crGetLastErrorMsgA(), crGetLastErrorMsgW(), crGetLastErrorMsg()

crInstallA()

crInstallA

(

__in PCR_INSTALL_INFOA

pInfo

)

Installs exception handlers for the caller process.

Returns

This function returns zero if succeeded.

Parameters

[in]

pInfo

General congiration information.

Remarks

This function installs unhandled exception filter for the caller process. It also installs various CRT exception/error handlers that function for all threads of the caller process. For more information, see About Exceptions and Exception Handling

Below is the list of installed handlers:

• Top-level SEH exception filter [ SetUnhandledExceptionFilter() ]
• C++ pure virtual call handler (Visual Studio .NET 2003 and later) [ _set_purecall_handler() ]
• C++ invalid parameter handler (Visual Studio .NET 2005 and later) [ _set_invalid_parameter_handler() ]
• C++ new operator error handler (Visual Studio .NET 2003 and later) [ _set_new_handler() ]
• C++ buffer overrun handler (Visual Studio .NET 2003 only) [ _set_security_error_handler() ]
• C++ abort handler [ signal(SIGABRT) ]
• C++ illegal instruction handler [ signal(SIGINT) ]
• C++ termination request [ signal(SIGTERM) ]

In a multithreaded program, additionally use crInstallToCurrentThread2() function for each execution thread, except the main one.

The pInfo parameter contains all required information needed to install CrashRpt.

This function fails when pInfo->pszCrashSenderPath doesn't contain valid path to CrashSender.exe or when pInfo->pszCrashSenderPath is equal to NULL, but CrashSender.exe is not located in the directory where CrashRpt.dll located.

On crash, the crash minidump file is created, which contains CPU information and stack trace information. Also XML file is created that contains additional information that may be helpful for crash analysis. These files along with several additional files added with crAddFile2() are packed to a single ZIP file.

When crash information is collected, another process, CrashSender.exe, is launched and the process where crash had occured is terminated. The CrashSender process is responsible for letting the user know about the crash and send the error report.

The error report can be sent over E-mail using address and subject passed to the function as CR_INSTALL_INFO structure members. Another way of sending error report is an HTTP request using pszUrl member of CR_INSTALL_INFO.

This function may fail if an appropriate language file (crashrpt_lang.ini) is not found in the directory where the CrashSender.exe file is located.

If this function fails, use crGetLastErrorMsg() to retrieve the error message.

crInstallW() and crInstallA() are wide-character and multi-byte character versions of crInstall() function. The crInstall macro defines character set independent mapping for these functions.

For code example, see An Example of Using CrashRpt API.

See also

crInstallW(), crInstallA(), crInstall(), CR_INSTALL_INFOW, CR_INSTALL_INFOA, CR_INSTALL_INFO, crUninstall(), CrAutoInstallHelper

crInstallToCurrentThread2()

crInstallToCurrentThread2

(

DWORD

dwFlags

)

Installs exception handlers to the caller thread.

Returns

This function returns zero if succeeded.

Parameters

[in]

dwFlags

Flags.

Remarks

This function is available since v.1.1.2.

The function sets exception handlers for the caller thread. If you have several execution threads, you ought to call the function for each thread, except the main one.

dwFlags defines what exception handlers to install. Use zero value to install all possible exception handlers. Or use a combination of the following constants:

- \ref CR_INST_TERMINATE_HANDLER              Install terminate handler
- \ref CR_INST_UNEXPECTED_HANDLER             Install unexpected handler
- \ref CR_INST_SIGFPE_HANDLER                 Install SIGFPE signal handler   
- \ref CR_INST_SIGILL_HANDLER                 Install SIGILL signal handler  
- \ref CR_INST_SIGSEGV_HANDLER                Install SIGSEGV signal handler 

Example:

DWORD WINAPI ThreadProc(LPVOID lpParam)
{
  // Install exception handlers
  crInstallToCurrentThread2(0);

  // Your code...

  // Uninstall exception handlers
  crUninstallFromCurrentThread();
 
  return 0;
}

See also

crInstall()

crInstallW()

crInstallW

(

__in PCR_INSTALL_INFOW

pInfo

)

Installs exception handlers for the caller process.

Returns

This function returns zero if succeeded.

Parameters

[in]

pInfo

General congiration information.

Remarks

This function installs unhandled exception filter for the caller process. It also installs various CRT exception/error handlers that function for all threads of the caller process. For more information, see About Exceptions and Exception Handling

Below is the list of installed handlers:

• Top-level SEH exception filter [ SetUnhandledExceptionFilter() ]
• C++ pure virtual call handler (Visual Studio .NET 2003 and later) [ _set_purecall_handler() ]
• C++ invalid parameter handler (Visual Studio .NET 2005 and later) [ _set_invalid_parameter_handler() ]
• C++ new operator error handler (Visual Studio .NET 2003 and later) [ _set_new_handler() ]
• C++ buffer overrun handler (Visual Studio .NET 2003 only) [ _set_security_error_handler() ]
• C++ abort handler [ signal(SIGABRT) ]
• C++ illegal instruction handler [ signal(SIGINT) ]
• C++ termination request [ signal(SIGTERM) ]

In a multithreaded program, additionally use crInstallToCurrentThread2() function for each execution thread, except the main one.

The pInfo parameter contains all required information needed to install CrashRpt.

This function fails when pInfo->pszCrashSenderPath doesn't contain valid path to CrashSender.exe or when pInfo->pszCrashSenderPath is equal to NULL, but CrashSender.exe is not located in the directory where CrashRpt.dll located.

On crash, the crash minidump file is created, which contains CPU information and stack trace information. Also XML file is created that contains additional information that may be helpful for crash analysis. These files along with several additional files added with crAddFile2() are packed to a single ZIP file.

When crash information is collected, another process, CrashSender.exe, is launched and the process where crash had occured is terminated. The CrashSender process is responsible for letting the user know about the crash and send the error report.

The error report can be sent over E-mail using address and subject passed to the function as CR_INSTALL_INFO structure members. Another way of sending error report is an HTTP request using pszUrl member of CR_INSTALL_INFO.

This function may fail if an appropriate language file (crashrpt_lang.ini) is not found in the directory where the CrashSender.exe file is located.

If this function fails, use crGetLastErrorMsg() to retrieve the error message.

crInstallW() and crInstallA() are wide-character and multi-byte character versions of crInstall() function. The crInstall macro defines character set independent mapping for these functions.

For code example, see An Example of Using CrashRpt API.

See also

crInstallW(), crInstallA(), crInstall(), CR_INSTALL_INFOW, CR_INSTALL_INFOA, CR_INSTALL_INFO, crUninstall(), CrAutoInstallHelper

crSetCrashCallbackA()

crSetCrashCallbackA	(	PFNCRASHCALLBACKA	pfnCallbackFunc,
		LPVOID	lpParam
	)

Sets the crash callback function.

Returns

This function returns zero if succeeded. Use crGetLastErrorMsg() to retrieve the error message on fail.

Parameters

[in]	pfnCallbackFunc	Pointer to the crash callback function.
[in]	lpParam	User defined parameter. Optional.

Remarks

Use this to set the crash callback function that will be called on crash. This function is available since v.1.4.0.

For the crash callback function prototype, see documentation for PFNCRASHCALLBACK().

Optional lpParam parameter can be a pointer to user-defined data. It will be passed to the crash callback function as CR_CRASH_CALLBACK_INFO::pUserParam structure member.

See also

PFNCRASHCALLBACK()

crSetCrashCallbackW()

crSetCrashCallbackW	(	PFNCRASHCALLBACKW	pfnCallbackFunc,
		LPVOID	lpParam
	)

Sets the crash callback function.

Returns

This function returns zero if succeeded. Use crGetLastErrorMsg() to retrieve the error message on fail.

Parameters

[in]	pfnCallbackFunc	Pointer to the crash callback function.
[in]	lpParam	User defined parameter. Optional.

Remarks

Use this to set the crash callback function that will be called on crash. This function is available since v.1.4.0.

For the crash callback function prototype, see documentation for PFNCRASHCALLBACK().

Optional lpParam parameter can be a pointer to user-defined data. It will be passed to the crash callback function as CR_CRASH_CALLBACK_INFO::pUserParam structure member.

See also

PFNCRASHCALLBACK()

crUninstall()

crUninstall

(

)

Uninitializes the CrashRpt library and unsinstalls exception handlers previously installed with crInstall().

Returns

This function returns zero if succeeded.

Remarks

Call this function on application exit to uninitialize the library and uninstall exception handlers previously installed with crInstall(). After function call, the exception handlers are restored to states they had before calling crInstall().

This function fails if crInstall() wasn't previously called in context of the caller process.

When this function fails, use the crGetLastErrorMsg() function to retrieve the error message.

See also

crInstallW(), crInstallA(), crInstall(), CrAutoInstallHelper

crUninstallFromCurrentThread()

crUninstallFromCurrentThread

(

)

Uninstalls C++ exception handlers from the current thread.

Returns

This function returns zero if succeeded.

Remarks

This function unsets exception handlers from the caller thread. If you have several execution threads, you ought to call the function for each thread. After calling this function, the exception handlers for current thread are replaced with the handlers that were before call of crInstallToCurrentThread2().

This function fails if crInstallToCurrentThread2() wasn't called for current thread.

When this function fails, use crGetLastErrorMsg() to retrieve the error message.

No need to call this function for the main execution thread. The crUninstall() will automatically uninstall C++ exception handlers for the main thread.

See also

crInstallToCurrentThread2(), crUninstallFromCurrentThread(), CrThreadAutoInstallHelper