| crashrpt |
A crash reporting system for Windows applications

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

## Typedefs

typedef BOOL(* | LPGETLOGFILE )(LPVOID lpvState)
| Client crash callback function prototype.

## Functions

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

## Detailed Description

## Typedef Documentation

typedef BOOL( * LPGETLOGFILE)(LPVOID lpvState)

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

## Function Documentation

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

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

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