CrashRpt Functions

Defines
#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().
Functions
typedef	BOOL (CALLBACK *LPGETLOGFILE)(LPVOID lpvState)
	Client crash callback function prototype.
int WINAPI	crInstallW (PCR_INSTALL_INFOW pInfo)
	Installs exception handlers for the caller process.
int WINAPI	crInstallA (PCR_INSTALL_INFOA pInfo)
int WINAPI	crUninstall ()
	Unsinstalls exception handlers previously installed with crInstall().
int WINAPI	crInstallToCurrentThread2 (DWORD dwFlags)
	Installs exception handlers to the caller thread.
int WINAPI	crUninstallFromCurrentThread ()
	Uninstalls C++ exception handlers from the current thread.
int WINAPI	crAddFile2W (LPCWSTR pszFile, LPCWSTR pszDestFile, LPCWSTR pszDesc, DWORD dwFlags)
	Adds a file to crash report.
int WINAPI	crAddFile2A (LPCSTR pszFile, LPCSTR pszDestFile, LPCSTR pszDesc, DWORD dwFlags)
int WINAPI	crAddScreenshot (DWORD dwFlags)
	Adds a screenshot to the crash report.
int WINAPI	crAddScreenshot2 (DWORD dwFlags, int nJpegQuality)
	Adds a screenshot to the crash report.
int WINAPI	crAddPropertyW (LPCWSTR pszPropName, LPCWSTR pszPropValue)
	Adds a string property to the crash report.
int WINAPI	crAddPropertyA (LPCSTR pszPropName, LPCSTR pszPropValue)
int WINAPI	crAddRegKeyW (LPCWSTR pszRegKey, LPCWSTR pszDstFileName, DWORD dwFlags)
	Adds a registry key dump to the crash report.
int WINAPI	crAddRegKeyA (LPCSTR pszRegKey, LPCSTR pszDstFileName, DWORD dwFlags)
int WINAPI	crGenerateErrorReport (CR_EXCEPTION_INFO *pExceptionInfo)
	Manually generates an errror report.
int WINAPI	crEmulateCrash (unsigned ExceptionType) throw (...)
	Emulates a predefined crash situation.
int WINAPI	crGetLastErrorMsgW (LPWSTR pszBuffer, UINT uBuffSize)
	Gets the last CrashRpt error message.
int WINAPI	crGetLastErrorMsgA (LPSTR pszBuffer, UINT uBuffSize)

---

Define Documentation

#define crAddFile2   crAddFile2A

Character set-independent mapping of crAddFile2W() and crAddFile2A() functions.

Definition at line 952 of file CrashRpt.h.

#define crAddProperty   crAddPropertyA

Character set-independent mapping of crAddPropertyW() and crAddPropertyA() functions.

Definition at line 1120 of file CrashRpt.h.

#define crAddRegKey   crAddRegKeyA

Character set-independent mapping of crAddRegKeyW() and crAddRegKeyA() functions.

Definition at line 1183 of file CrashRpt.h.

#define crGetLastErrorMsg   crGetLastErrorMsgA

Defines character set-independent mapping for crGetLastErrorMsgW() and crGetLastErrorMsgA().

Definition at line 1493 of file CrashRpt.h.

#define crInstall   crInstallA

Character set-independent mapping of crInstallW() and crInstallA() functions.

Definition at line 669 of file CrashRpt.h.

---

Function Documentation

typedef BOOL

(

CALLBACK *

LPGETLOGFILE

)

Client crash callback function prototype.

Parameters:

[in]

lpvState

Currently not used, equals to NULL.

Remarks:

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

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. Log files should be accessible for reading, otherwise CrashRpt won't be able to include them into error report.

The crash callback function should typically return TRUE to allow generate error report. Returning FALSE will prevent crash report generation.

The following example shows how to use the crash callback function.

  // define the crash callback
  BOOL CALLBACK CrashCallback(LPVOID lpvState)
  {    
    // Do something...

    return TRUE;
  }

See also:

crAddFile2()

int WINAPI 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 to add, 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 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 LPGETLOGFILE crash callback, close open file handles and ensure files to be included are acessible for reading.

pszFile should be a valid absolute path of a file to add 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.

pszDesc is a literal description of a 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 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 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 Do not fail if file is missing (assume it will be created later).

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.

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.

This function is available since v.1.2.1. This function replaces the crAddFile() function.

See also:

crAddFile2W(), crAddFile2A(), crAddFile2()

int WINAPI 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 to add, 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 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 LPGETLOGFILE crash callback, close open file handles and ensure files to be included are acessible for reading.

pszFile should be a valid absolute path of a file to add 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.

pszDesc is a literal description of a 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 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 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 Do not fail if file is missing (assume it will be created later).

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.

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.

This function is available since v.1.2.1. This function replaces the crAddFile() function.

See also:

crAddFile2W(), crAddFile2A(), crAddFile2()

int WINAPI 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.

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 store it as szFreeSpace string.
  LPCTSTR szFreeSpace = _T("0 Kb");
  crAddProperty(_T("FreeDiskSpace"), szFreeSpace);

See also:

crAddFile2(), crAddScreenshot()

int WINAPI 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.

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 store it as szFreeSpace string.
  LPCTSTR szFreeSpace = _T("0 Kb");
  crAddProperty(_T("FreeDiskSpace"), szFreeSpace);

See also:

crAddFile2(), crAddScreenshot()

int WINAPI 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 is reserved for future use and should be set to zero.

The following example shows how to dump two registry keys to 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()

int WINAPI 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 is reserved for future use and should be set to zero.

The following example shows how to dump two registry keys to 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()

int WINAPI crAddScreenshot

(

DWORD

dwFlags

)

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.

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 the 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 application's 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.

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.

If you use JPEG image format, you may better use the crAddScreenshot2() function, that allows to define JPEG image quality.

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()

int WINAPI 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()

int WINAPI 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).

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);

int WINAPI crGenerateErrorReport

(

CR_EXCEPTION_INFO *

pExceptionInfo

)

Manually generates an errror report.

Returns:

This function returns zero if succeeded. When failed, it returns a non-zero value. Use crGetLastErrorMsg() 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 contains crash minidump, crash description in XML format and additional custom files added with 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);

int WINAPI crGetLastErrorMsgA	(	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()

int WINAPI crGetLastErrorMsgW	(	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()

int WINAPI crInstallA

(

PCR_INSTALL_INFOA

pInfo

)

Installs exception handlers for the caller process.

Parameters:

[in]

pInfo

General 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 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 simple_example.

See also:

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

int WINAPI 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.

The function works the same way as obsolete crInstallToCurrentThread(), but provides an ability to select what exception handlers to install.

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

• CR_INST_TERMINATE_HANDLER Install terminate handler
• CR_INST_UNEXPECTED_HANDLER Install unexpected handler
• CR_INST_SIGFPE_HANDLER Install SIGFPE signal handler
• CR_INST_SIGILL_HANDLER Install SIGILL signal handler
• 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:

crInstallToCurrentThread()

int WINAPI crInstallW

(

PCR_INSTALL_INFOW

pInfo

)

Installs exception handlers for the caller process.

Parameters:

[in]

pInfo

General 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 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 simple_example.

See also:

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

int WINAPI crUninstall

(

)

Unsinstalls exception handlers previously installed with crInstall().

Returns:

This function returns zero if succeeded.

Remarks:

Call this function on application exit to 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 crGetLastErrorMsg() to retrieve the error message.

See also:

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

int WINAPI 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:

crInstallToCurrentThread(), crInstallToCurrentThread2(), crUninstallFromCurrentThread(), CrThreadAutoInstallHelper