/*************************************************************************************
This file is a part of CrashRpt library.
Copyright (c) 2003-2013 The CrashRpt project authors. All Rights Reserved.
Use of this source code is governed by a BSD-style license
that can be found in the License.txt file in the root of the source
tree. All contributing project authors may
be found in the Authors.txt file in the root of the source tree.
***************************************************************************************/
/*! \file CrashRpt.h
* \brief Defines the interface for the CrashRpt.DLL.
* \date 2003
* \author Michael Carruth
* \author Oleg Krivtsov (zeXspectrum)
*/
#ifndef _CRASHRPT_H_
#define _CRASHRPT_H_
#include <windows.h>
#include <dbghelp.h>
// Define SAL macros to be empty if some old Visual Studio used
#ifndef __reserved
#define __reserved
#endif
#ifndef __in
#define __in
#endif
#ifndef __in_opt
#define __in_opt
#endif
#ifndef __out_ecount_z
#define __out_ecount_z(x)
#endif
#ifdef __cplusplus
#define CRASHRPT_EXTERNC extern "C"
#else
#define CRASHRPT_EXTERNC
#endif
#define CRASHRPTAPI(rettype) CRASHRPT_EXTERNC rettype WINAPI
//! Current CrashRpt version
#define CRASHRPT_VER 1500
/*! \defgroup CrashRptAPI CrashRpt Functions */
/*! \defgroup DeprecatedAPI Obsolete Functions */
/*! \defgroup CrashRptStructs CrashRpt Structures */
/*! \defgroup CrashRptWrappers CrashRpt Wrapper Classes */
/*! \ingroup DeprecatedAPI
* \brief Client crash callback function prototype
* \param[in] lpvState Must be set to NULL.
*
* \remarks
*
* This function is deprecated, it is recommended to use \ref PFNCRASHCALLBACK()
* instead.
*
* 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. 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, properties, desktop screenshots,
* registry keys inside of the crash callback function.
*
* The crash callback function should typically return \c TRUE to allow generate error report.
* Returning \c FALSE will prevent crash report generation.
*
* The following example shows how to use the crash callback function.
*
* \code
* // define the crash callback
* BOOL CALLBACK CrashCallback(LPVOID lpvState)
* {
* // Do something...
*
* return TRUE;
* }
* \endcode
*
* \sa crAddFile2(), PFNCRASHCALLBACK()
*/
typedef BOOL (CALLBACK *LPGETLOGFILE) (__reserved LPVOID lpvState);
// Exception types used in CR_EXCEPTION_INFO::exctype structure member.
#define CR_SEH_EXCEPTION 0 //!< SEH exception.
#define CR_CPP_TERMINATE_CALL 1 //!< C++ terminate() call.
#define CR_CPP_UNEXPECTED_CALL 2 //!< C++ unexpected() call.
#define CR_CPP_PURE_CALL 3 //!< C++ pure virtual function call (VS .NET and later).
#define CR_CPP_NEW_OPERATOR_ERROR 4 //!< C++ new operator fault (VS .NET and later).
#define CR_CPP_SECURITY_ERROR 5 //!< Buffer overrun error (VS .NET only).
#define CR_CPP_INVALID_PARAMETER 6 //!< Invalid parameter exception (VS 2005 and later).
#define CR_CPP_SIGABRT 7 //!< C++ SIGABRT signal (abort).
#define CR_CPP_SIGFPE 8 //!< C++ SIGFPE signal (flotating point exception).
#define CR_CPP_SIGILL 9 //!< C++ SIGILL signal (illegal instruction).
#define CR_CPP_SIGINT 10 //!< C++ SIGINT signal (CTRL+C).
#define CR_CPP_SIGSEGV 11 //!< C++ SIGSEGV signal (invalid storage access).
#define CR_CPP_SIGTERM 12 //!< C++ SIGTERM signal (termination request).
/*! \ingroup CrashRptStructs
* \brief This structure contains information about the crash.
*
* The information provided by this structure includes the exception type, exception code,
* exception pointers and so on. These are needed to generate crash minidump file and
* provide the developer with other information about the error. This structure is used by
* the crGenerateErrorReport() function. Pointer to this structure is also passed to the
* crash callback function (see the \ref PFNCRASHCALLBACK() function prototype).
*
* Structure members details are provided below:
*
* \b cb [in]
*
* This must contain the size of this structure in bytes.
*
* \b pexcptrs [in, optional]
*
* Should contain the exception pointers. If this parameter is NULL,
* the current CPU state is used to generate exception pointers.
*
* \b exctype [in]
*
* The type of exception. This parameter may be one of the following:
* - \ref CR_SEH_EXCEPTION SEH (Structured Exception Handling) exception
* - \ref CR_CPP_TERMINATE_CALL C++ terminate() function call
* - \ref CR_CPP_UNEXPECTED_CALL C++ unexpected() function call
* - \ref CR_CPP_PURE_CALL Pure virtual method call (Visual Studio .NET 2003 and later)
* - \ref CR_CPP_NEW_OPERATOR_ERROR C++ 'new' operator error (Visual Studio .NET 2003 and later)
* - \ref CR_CPP_SECURITY_ERROR Buffer overrun (Visual Studio .NET 2003 only)
* - \ref CR_CPP_INVALID_PARAMETER Invalid parameter error (Visual Studio 2005 and later)
* - \ref CR_CPP_SIGABRT C++ SIGABRT signal
* - \ref CR_CPP_SIGFPE C++ floating point exception
* - \ref CR_CPP_SIGILL C++ illegal instruction
* - \ref CR_CPP_SIGINT C++ SIGINT signal
* - \ref CR_CPP_SIGSEGV C++ invalid storage access
* - \ref CR_CPP_SIGTERM C++ termination request
*
* \b code [in, optional]
*
* Used if \a exctype is \ref CR_SEH_EXCEPTION and represents the SEH exception code.
* If \a pexptrs is NULL, this value is used when generating exception information for initializing
* \c pexptrs->ExceptionRecord->ExceptionCode member, otherwise it is ignored.
*
* \b fpe_subcode [in, optional]
*
* Used if \a exctype is equal to \ref CR_CPP_SIGFPE. It defines the floating point
* exception subcode (see \c signal() function ducumentation in MSDN).
*
* \b expression, \b function, \b file and \b line [in, optional]
*
* These parameters are used when \a exctype is \ref CR_CPP_INVALID_PARAMETER.
* These members are typically non-zero when using debug version of CRT.
*
* \b bManual [in]
*
* Since v.1.2.4, \a bManual parameter should be equal to TRUE if the report is generated manually.
* The value of \a bManual parameter affects the automatic application restart behavior. If the application
* restart is requested by the \ref CR_INST_APP_RESTART flag of CR_INSTALL_INFO::dwFlags structure member,
* and if \a bManual is FALSE, the application will be
* restarted after error report generation. If \a bManual is TRUE, the application won't be restarted.
*
* \b hSenderProcess [out]
*
* As of v.1.2.8, \a hSenderProcess parameter will contain the handle to the <b>CrashSender.exe</b> process when
* \ref crGenerateErrorReport function returns. The caller may use this handle to wait until <b>CrashSender.exe</b>
* process exits and check the exit code. When the handle is not needed anymore, release it with the \b CloseHandle() function.
*/
typedef struct tagCR_EXCEPTION_INFO
{
WORD cb; //!< Size of this structure in bytes; should be initialized before using.
PEXCEPTION_POINTERS pexcptrs; //!< Exception pointers.
int exctype; //!< Exception type.
DWORD code; //!< Code of SEH exception.
unsigned int fp