1 /************************************************************************************* 2 This file is a part of CrashRpt library. 3 Copyright (c) 2003-2013 The CrashRpt project authors. All Rights Reserved. 4 5 Use of this source code is governed by a BSD-style license 6 that can be found in the License.txt file in the root of the source 7 tree. All contributing project authors may 8 be found in the Authors.txt file in the root of the source tree. 9 ***************************************************************************************/ 10 11 /*! \file CrashRpt.h 12 * \brief Defines the interface for the CrashRpt.DLL. 13 * \date 2003 14 * \author Michael Carruth 15 * \author Oleg Krivtsov (zeXspectrum) 16 */ 17 18 #ifndef _CRASHRPT_H_ 19 #define _CRASHRPT_H_ 20 21 #include <windows.h> 22 #include <dbghelp.h> 23 24 // Define SAL macros to be empty if some old Visual Studio used 25 #ifndef __reserved 26 #define __reserved 27 #endif 28 #ifndef __in 29 #define __in 30 #endif 31 #ifndef __in_opt 32 #define __in_opt 33 #endif 34 #ifndef __out_ecount_z 35 #define __out_ecount_z(x) 36 #endif 37 38 #ifdef __cplusplus 39 #define CRASHRPT_EXTERNC extern "C" 40 #else 41 #define CRASHRPT_EXTERNC 42 #endif 43 44 #define CRASHRPTAPI(rettype) CRASHRPT_EXTERNC rettype WINAPI 45 46 //! Current CrashRpt version 47 #define CRASHRPT_VER 1403 48 49 /*! \defgroup CrashRptAPI CrashRpt Functions */ 50 /*! \defgroup DeprecatedAPI Obsolete Functions */ 51 /*! \defgroup CrashRptStructs CrashRpt Structures */ 52 /*! \defgroup CrashRptWrappers CrashRpt Wrapper Classes */ 53 54 /*! \ingroup DeprecatedAPI 55 * \brief Client crash callback function prototype 56 * \param[in] lpvState Must be set to NULL. 57 * 58 * \remarks 59 * 60 * This function is deprecated, it is recommended to use \ref PFNCRASHCALLBACK() 61 * instead. 62 * 63 * The crash callback function is called when crash occurs. This way client application is 64 * notified about the crash. 65 * 66 * It is generally unsafe to do complex actions (e.g. memory allocation, heap operations) inside of this callback. 67 * The application state may be unstable. 68 * 69 * One reason the application may use this callback for is to close handles to open log files that the 70 * application plans to include into the error report. Files should be accessible for reading, otherwise 71 * CrashRpt won't be able to include them into error report. 72 * 73 * It is also possible (but not recommended) to add files, properties, desktop screenshots, 74 * registry keys inside of the crash callback function. 75 * 76 * The crash callback function should typically return \c TRUE to allow generate error report. 77 * Returning \c FALSE will prevent crash report generation. 78 * 79 * The following example shows how to use the crash callback function. 80 * 81 * \code 82 * // define the crash callback 83 * BOOL CALLBACK CrashCallback(LPVOID lpvState) 84 * { 85 * // Do something... 86 * 87 * return TRUE; 88 * } 89 * \endcode 90 * 91 * \sa crAddFile2(), PFNCRASHCALLBACK() 92 */ 93 typedef BOOL (CALLBACK *LPGETLOGFILE) (__reserved LPVOID lpvState); 94 95 // Exception types used in CR_EXCEPTION_INFO::exctype structure member. 96 #define CR_SEH_EXCEPTION 0 //!< SEH exception. 97 #define CR_CPP_TERMINATE_CALL 1 //!< C++ terminate() call. 98 #define CR_CPP_UNEXPECTED_CALL 2 //!< C++ unexpected() call. 99 #define CR_CPP_PURE_CALL 3 //!< C++ pure virtual function call (VS .NET and later). 100 #define CR_CPP_NEW_OPERATOR_ERROR 4 //!< C++ new operator fault (VS .NET and later). 101 #define CR_CPP_SECURITY_ERROR 5 //!< Buffer overrun error (VS .NET only). 102 #define CR_CPP_INVALID_PARAMETER 6 //!< Invalid parameter exception (VS 2005 and later). 103 #define CR_CPP_SIGABRT 7 //!< C++ SIGABRT signal (abort). 104 #define CR_CPP_SIGFPE 8 //!< C++ SIGFPE signal (flotating point exception). 105 #define CR_CPP_SIGILL 9 //!< C++ SIGILL signal (illegal instruction). 106 #define CR_CPP_SIGINT 10 //!< C++ SIGINT signal (CTRL+C). 107 #define CR_CPP_SIGSEGV 11 //!< C++ SIGSEGV signal (invalid storage access). 108 #define CR_CPP_SIGTERM 12 //!< C++ SIGTERM signal (termination request). 109 110 111 /*! \ingroup CrashRptStructs 112 * \brief This structure contains information about the crash. 113 * 114 * The information provided by this structure includes the exception type, exception code, 115 * exception pointers and so on. These are needed to generate crash minidump file and 116 * provide the developer with other information about the error. This structure is used by 117 * the crGenerateErrorReport() function. Pointer to this structure is also passed to the 118 * crash callback function (see the \ref PFNCRASHCALLBACK() function prototype). 119 * 120 * Structure members details are provided below: 121 * 122 * \b cb [in] 123 * 124 * This must contain the size of this structure in bytes. 125 * 126 * \b pexcptrs [in, optional] 127 * 128 * Should contain the exception pointers. If this parameter is NULL, 129 * the current CPU state is used to generate exception pointers. 130 * 131 * \b exctype [in] 132 * 133 * The type of exception. This parameter may be one of the following: 134 * - \ref CR_SEH_EXCEPTION SEH (Structured Exception Handling) exception 135 * - \ref CR_CPP_TERMINATE_CALL C++ terminate() function call 136 * - \ref CR_CPP_UNEXPECTED_CALL C++ unexpected() function call 137 * - \ref CR_CPP_PURE_CALL Pure virtual method call (Visual Studio .NET 2003 and later) 138 * - \ref CR_CPP_NEW_OPERATOR_ERROR C++ 'new' operator error (Visual Studio .NET 2003 and later) 139 * - \ref CR_CPP_SECURITY_ERROR Buffer overrun (Visual Studio .NET 2003 only) 140 * - \ref CR_CPP_INVALID_PARAMETER Invalid parameter error (Visual Studio 2005 and later) 141 * - \ref CR_CPP_SIGABRT C++ SIGABRT signal 142 * - \ref CR_CPP_SIGFPE C++ floating point exception 143 * - \ref CR_CPP_SIGILL C++ illegal instruction 144 * - \ref CR_CPP_SIGINT C++ SIGINT signal 145 * - \ref CR_CPP_SIGSEGV C++ invalid storage access 146 * - \ref CR_CPP_SIGTERM C++ termination request 147 * 148 * \b code [in, optional] 149 * 150 * Used if \a exctype is \ref CR_SEH_EXCEPTION and represents the SEH exception code. 151 * If \a pexptrs is NULL, this value is used when generating exception information for initializing 152 * \c pexptrs->ExceptionRecord->ExceptionCode member, otherwise it is ignored. 153 * 154 * \b fpe_subcode [in, optional] 155 * 156 * Used if \a exctype is equal to \ref CR_CPP_SIGFPE. It defines the floating point 157 * exception subcode (see \c signal() function ducumentation in MSDN). 158 * 159 * \b expression, \b function, \b file and \b line [in, optional] 160 * 161 * These parameters are used when \a exctype is \ref CR_CPP_INVALID_PARAMETER. 162 * These members are typically non-zero when using debug version of CRT. 163 * 164 * \b bManual [in] 165 * 166 * Since v.1.2.4, \a bManual parameter should be equal to TRUE if the report is generated manually. 167 * The value of \a bManual parameter affects the automatic application restart behavior. If the application 168 * restart is requested by the \ref CR_INST_APP_RESTART flag of CR_INSTALL_INFO::dwFlags structure member, 169 * and if \a bManual is FALSE, the application will be 170 * restarted after error report generation. If \a bManual is TRUE, the application won't be restarted. 171 * 172 * \b hSenderProcess [out] 173 * 174 * As of v.1.2.8, \a hSenderProcess parameter will contain the handle to the <b>CrashSender.exe</b> process when 175 * \ref crGenerateErrorReport function returns. The caller may use this handle to wait until <b>CrashSender.exe</b> 176 * process exits and check the exit code. When the handle is not needed anymore, release it with the \b CloseHandle() function. 177 */ 178 179 typedef struct tagCR_EXCEPTION_INFO 180 { 181 WORD cb; //!< Size of this structure in bytes; should be initialized before using. 182 PEXCEPTION_POINTERS pexcptrs; //!< Exception pointers. 183 int exctype; //!< Exception type. 184 DWORD code; //!< Code of SEH exception. 185 unsigned int fpe_subcode; //!< Floating point exception subcode. 186 const wchar_t* expression; //!< Assertion expression. 187 const wchar_t* function; //!< Function in which assertion happened. 188 const wchar_t* file; //!< File in which assertion happened. 189 unsigned int line; //!< Line number. 190 BOOL bManual; //!< Flag telling if the error report is generated manually or not. 191 HANDLE hSenderProcess; //!< Handle to the CrashSender.exe process. 192 } 193 CR_EXCEPTION_INFO; 194 195 typedef CR_EXCEPTION_INFO* PCR_EXCEPTION_INFO; 196 197 // Stages of crash report generation (used by the crash callback function). 198 #define CR_CB_STAGE_PREPARE 10 //!< Stage after exception pointers've been retrieved. 199 #define CR_CB_STAGE_FINISH 20 //!< Stage after the launch of CrashSender.exe process. 200 201 /*! \ingroup CrashRptStructs 202 * \struct CR_CRASH_CALLBACK_INFOW() 203 * \brief This structure contains information passed to crash callback function PFNCRASHCALLBACK(). 204 * 205 * \remarks 206 * 207 * The information contained in this structure may be used by the crash callback function 208 * to determine what type of crash has occurred and perform some action. For example, 209 * the client application may prefer to continue its execution on some type of crash, and 210 * terminate itself on another type of crash. 211 * 212 * Below, the stucture fields are described: 213 * 214 * \b cb [in] 215 * 216 * This contains the size of this structure in bytes. 217 * 218 * \b nStage [in] 219 * 220 * This field specifies the crash report generation stage. The callback function 221 * can be called once per each stage (depending on callback function's return value). 222 * Currently, there are two stages: 223 * - \ref CR_CB_STAGE_PREPARE Stage after exception pointers've been retrieved. 224 * - \ref CR_CB_STAGE_FINISH Stage after the launch of CrashSender.exe process. 225 * 226 * \b pszErrorReportFolder [in] 227 * 228 * This field contains the absolute path to the directory containing uncompressed 229 * crash report files. 230 * 231 * \b pExceptionInfo [in] 232 * 233 * This field contains a pointer to \ref CR_EXCEPTION_INFO structure. 234 * 235 * \b pUserParam [in, optional] 236 * 237 * This is a pointer to user-specified data passed to the crSetCrashCallback() function 238 * as \b pUserParam argument. 239 * 240 * \b bContinueExecution [in, out] 241 * 242 * This field is set to FALSE by default. The crash callback function may set it 243 * to true if it wants to continue its execution after crash report generation 244 * (otherwise the program will be terminated). 245 * 246 * \ref CR_CRASH_CALLBACK_INFOW and \ref CR_CRASH_CALLBACK_INFOA are 247 * wide-character and multi-byte character versions of \ref CR_CRASH_CALLBACK_INFO 248 * structure. In your program, use the \ref CR_CRASH_CALLBACK_INFO typedef which 249 * is a character-set-independent version of the structure name. 250 * 251 * \sa PFNCRASHCALLBACK() 252 */ 253 typedef struct tagCR_CRASH_CALLBACK_INFOW 254 { 255 WORD cb; //!< Size of this structure in bytes. 256 int nStage; //!< Stage. 257 LPCWSTR pszErrorReportFolder; //!< Directory where crash report files are located. 258 CR_EXCEPTION_INFO* pExceptionInfo; //!< Pointer to information about the crash. 259 LPVOID pUserParam; //!< Pointer to user-defined data. 260 BOOL bContinueExecution; //!< Whether to terminate the process (the default) or to continue program execution. 261 } 262 CR_CRASH_CALLBACK_INFOW; 263 264 /*! \ingroup CrashRptStructs 265 * \struct CR_CRASH_CALLBACK_INFOA 266 * \copydoc CR_CRASH_CALLBACK_INFOW 267 */ 268 typedef struct tagCR_CRASH_CALLBACK_INFOA 269 { 270 WORD cb; //!< Size of this structure in bytes. 271 int nStage; //!< Stage. 272 LPCSTR pszErrorReportFolder; //!< Directory where crash report files are located. 273 CR_EXCEPTION_INFO* pExceptionInfo; //!< Pointer to information about the crash. 274 LPVOID pUserParam; //!< Pointer to user-defined data. 275 BOOL bContinueExecution; //!< Whether to terminate the process (the default) or to continue program execution. 276 } 277 CR_CRASH_CALLBACK_INFOA; 278 279 /*! \brief Character set-independent mapping of CR_CRASH_CALLBACK_INFOW and CR_CRASH_CALLBACK_INFOA structures. 280 * \ingroup CrashRptStructs 281 */ 282 #ifdef UNICODE 283 typedef CR_CRASH_CALLBACK_INFOW CR_CRASH_CALLBACK_INFO; 284 #else 285 typedef CR_CRASH_CALLBACK_INFOA CR_CRASH_CALLBACK_INFO; 286 #endif // UNICODE 287 288 // Constants that may be returned by the crash callback function. 289 #define CR_CB_CANCEL 0 //!< Cancel crash report generation on the current stage. 290 #define CR_CB_DODEFAULT 1 //!< Proceed to the next stages of crash report generation without calling crash callback function. 291 #define CR_CB_NOTIFY_NEXT_STAGE 2 //!< Proceed and call the crash callback for the next stage. 292 293 /*! \ingroup CrashRptAPI 294 * \brief Client crash callback function prototype. 295 * \param[in] pInfo Points to information about the crash. 296 * 297 * \remarks 298 * 299 * The crash callback function is called when a crash occurs. This way client application is 300 * notified about the crash. 301 * 302 * Crash information is passed by CrashRpt to the callback function through the \b pInfo parameter as 303 * a pointer to \ref CR_CRASH_CALLBACK_INFO structure. See below for a code example. 304 * 305 * It is generally unsafe to do complex actions (e.g. memory allocation, heap operations) inside of this callback. 306 * The application state may be unstable. 307 * 308 * One reason the application may use this callback for is to close handles to open log files that the 309 * application plans to include into the error report. Files should be accessible for reading, otherwise 310 * CrashRpt won't be able to include them into error report. 311 * 312 * It is also possible (but not recommended) to add files (see crAddFile2()), 313 * properties (see crAddProperty()), desktop screenshots (see crAddScreenshot2()) 314 * and registry keys (see crAddRegKey()) inside of the crash callback function. 315 * 316 * By default, CrashRpt terminates the client application after crash report generation and 317 * launching the <i>CrashSender.exe</i> process. However, it is possible to continue program 318 * execution after crash report generation by seting \ref CR_CRASH_CALLBACK_INFO::bContinueExecution 319 * structure field to \a TRUE. 320 * 321 * The crash report generation consists of several stages. First, exception pointers are retrieved 322 * and the callback function is called for the first time. The callback function may check the 323 * retrieved exception information and decide wheter to proceed with crash report generation or to 324 * continue client program execution. On the next stage, the \a CrashSender.exe 325 * process is launched and the crash callback function is (optionally) called for the second time. 326 * Further crash report data collection and delivery work is performed in \a CrashSender.exe process. 327 * The crash callback may use the provided handle to \a CrashSender.exe process to wait until it exits. 328 * 329 * The crash callback function should typically return \ref CR_CB_DODEFAULT constant to proceed 330 * with error report generation without being called back on the next stage(s). Returning the 331 * \ref CR_CB_NOTIFY_NEXT_STAGE constant causes CrashRpt to call the crash callback function on the next 332 * stage, too. Returning \ref CR_CB_CANCEL constant will prevent further stage(s) of crash report generation. 333 * 334 * \ref PFNCRASHCALLBACKW() and \ref PFNCRASHCALLBACKA() are 335 * wide-character and multi-byte character versions of \ref PFNCRASHCALLBACK() 336 * function. 337 * 338 * The following code example shows the simplest way of using the crash callback function: 339 * 340 * \code 341 * // Define the crash callback 342 * int CALLBACK CrashCallback(CR_CRASH_CALLBACK_INFO* pInfo) 343 * { 344 * 345 * // Do something... 346 * 347 * // Proceed with crash report generation. 348 * // This return code also makes CrashRpt to not call this callback function for 349 * // the next crash report generation stage. 350 * return CR_CB_DODEFAULT; 351 * } 352 * \endcode 353 * 354 * The following code example shows how to use the crash callback function to be notified 355 * on every stage of crash report generation: 356 * 357 * \code 358 * // Define the crash callback 359 * int CALLBACK CrashCallback(CR_CRASH_CALLBACK_INFO* pInfo) 360 * { 361 * 362 * // We want to continue program execution after crash report generation 363 * pInfo->bContinueExecution = TRUE; 364 * 365 * switch(pInfo->nStage) 366 * { 367 * case CR_CB_STAGE_PREPARE: 368 * // do something 369 * break; 370 * case CR_CB_STAGE_FINISH: 371 * // do something 372 * break; 373 * } 374 * 375 * // Proceed to the next stage. 376 * return CR_CB_NOTIFY_NEXT_STAGE; 377 * } 378 * \endcode 379 * 380 * \sa CR_CRASH_CALLBACK_INFO, crSetCrashCallback(), crAddFile2(), crAddProperty(), crAddScreenshot2(), crAddRegKey() 381 */ 382 typedef int (CALLBACK *PFNCRASHCALLBACKW) (CR_CRASH_CALLBACK_INFOW* pInfo); 383 384 /*! \ingroup CrashRptAPI 385 * \copydoc PFNCRASHCALLBACKW() 386 */ 387 typedef int (CALLBACK *PFNCRASHCALLBACKA) (CR_CRASH_CALLBACK_INFOA* pInfo); 388 389 /*! \brief Character set-independent mapping of \ref PFNCRASHCALLBACKW() and \ref PFNCRASHCALLBACKA() function prototrypes. 390 * \ingroup CrashRptStructs 391 */ 392 #ifdef UNICODE 393 typedef PFNCRASHCALLBACKW PFNCRASHCALLBACK; 394 #else 395 typedef PFNCRASHCALLBACKA PFNCRASHCALLBACK; 396 #endif // UNICODE 397 398 /*! \ingroup CrashRptAPI 399 * \brief Sets the crash callback function. 400 * 401 * \return This function returns zero if succeeded. Use crGetLastErrorMsg() to retrieve the error message on fail. 402 * 403 * \param[in] pfnCallbackFunc Pointer to the crash callback function. 404 * \param[in] lpParam User defined parameter. Optional. 405 * 406 * \remarks 407 * 408 * Use this to set the crash callback function that will be called on crash. This function 409 * is available since v.1.4.0. 410 * 411 * For the crash callback function prototype, see documentation for PFNCRASHCALLBACK(). 412 * 413 * Optional \b lpParam parameter can be a pointer to user-defined data. It will be passed to the 414 * crash callback function as \ref CR_CRASH_CALLBACK_INFO::pUserParam structure member. 415 * 416 * \sa 417 * PFNCRASHCALLBACK() 418 */ 419 420 CRASHRPTAPI(int) 421 crSetCrashCallbackW( 422 PFNCRASHCALLBACKW pfnCallbackFunc, 423 LPVOID lpParam 424 ); 425 426 427 /*! \ingroup CrashRptAPI 428 * \copydoc crSetCrashCallbackW() 429 */ 430 CRASHRPTAPI(int) 431 crSetCrashCallbackA( 432 PFNCRASHCALLBACKA pfnCallbackFunc, 433 LPVOID lpParam 434 ); 435 436 437 /*! \brief Character set-independent mapping of crSetCrashCallbackW() and crSetCrashCallbackA() functions. 438 * \ingroup CrashRptAPI 439 */ 440 #ifdef UNICODE 441 #define crSetCrashCallback crSetCrashCallbackW 442 #else 443 #define crSetCrashCallback crSetCrashCallbackA 444 #endif //UNICODE 445 446 // Array indices for CR_INSTALL_INFO::uPriorities. 447 #define CR_HTTP 0 //!< Send error report via HTTP (or HTTPS) connection. 448 #define CR_SMTP 1 //!< Send error report via SMTP connection. 449 #define CR_SMAPI 2 //!< Send error report via simple MAPI (using default mail client). 450 451 //! Special priority constant that allows to skip certain delivery method. 452 #define CR_NEGATIVE_PRIORITY ((UINT)-1) 453 454 // Flags for CR_INSTALL_INFO::dwFlags 455 #define CR_INST_STRUCTURED_EXCEPTION_HANDLER 0x1 //!< Install SEH handler (deprecated name, use \ref CR_INST_SEH_EXCEPTION_HANDLER instead). 456 #define CR_INST_SEH_EXCEPTION_HANDLER 0x1 //!< Install SEH handler. 457 #define CR_INST_TERMINATE_HANDLER 0x2 //!< Install terminate handler. 458 #define CR_INST_UNEXPECTED_HANDLER 0x4 //!< Install unexpected handler. 459 #define CR_INST_PURE_CALL_HANDLER 0x8 //!< Install pure call handler (VS .NET and later). 460 #define CR_INST_NEW_OPERATOR_ERROR_HANDLER 0x10 //!< Install new operator error handler (VS .NET and later). 461 #define CR_INST_SECURITY_ERROR_HANDLER 0x20 //!< Install security error handler (VS .NET and later). 462 #define CR_INST_INVALID_PARAMETER_HANDLER 0x40 //!< Install invalid parameter handler (VS 2005 and later). 463 #define CR_INST_SIGABRT_HANDLER 0x80 //!< Install SIGABRT signal handler. 464 #define CR_INST_SIGFPE_HANDLER 0x100 //!< Install SIGFPE signal handler. 465 #define CR_INST_SIGILL_HANDLER 0x200 //!< Install SIGILL signal handler. 466 #define CR_INST_SIGINT_HANDLER 0x400 //!< Install SIGINT signal handler. 467 #define CR_INST_SIGSEGV_HANDLER 0x800 //!< Install SIGSEGV signal handler. 468 #define CR_INST_SIGTERM_HANDLER 0x1000 //!< Install SIGTERM signal handler. 469 470 #define CR_INST_ALL_POSSIBLE_HANDLERS 0x1FFF //!< Install all possible exception handlers. 471 #define CR_INST_CRT_EXCEPTION_HANDLERS 0x1FFE //!< Install exception handlers for the linked CRT module. 472 473 #define CR_INST_NO_GUI 0x2000 //!< Do not show GUI, send report silently (use for non-GUI apps only). 474 #define CR_INST_HTTP_BINARY_ENCODING 0x4000 //!< Deprecated, do not use. 475 #define CR_INST_DONT_SEND_REPORT 0x8000 //!< Don't send error report immediately, just save it locally. 476 #define CR_INST_APP_RESTART 0x10000 //!< Restart the application on crash. 477 #define CR_INST_NO_MINIDUMP 0x20000 //!< Do not include minidump file to crash report. 478 #define CR_INST_SEND_QUEUED_REPORTS 0x40000 //!< CrashRpt should send error reports that are waiting to be delivered. 479 #define CR_INST_STORE_ZIP_ARCHIVES 0x80000 //!< CrashRpt should store both uncompressed error report files and ZIP archives. 480 #define CR_INST_SEND_MANDATORY 0x100000 //!< This flag removes the "Close" and "Other actions" buttons from Error Report dialog, thus making the sending procedure mandatory for user. 481 #define CR_INST_SHOW_ADDITIONAL_INFO_FIELDS 0x200000 //!< Makes "Your E-mail" and "Describe what you were doing when the problem occurred" fields of Error Report dialog always visible. 482 #define CR_INST_ALLOW_ATTACH_MORE_FILES 0x400000 //!< Adds an ability for user to attach more files to crash report by clicking "Attach More File(s)" item from context menu of Error Report Details dialog. 483 #define CR_INST_AUTO_THREAD_HANDLERS 0x800000 //!< If this flag is set, installs exception handlers for newly created threads automatically. 484 485 /*! \ingroup CrashRptStructs 486 * \struct CR_INSTALL_INFOW() 487 * \brief This structure defines the general information used by crInstallW() function. 488 * 489 * \remarks 490 * 491 * \ref CR_INSTALL_INFOW and \ref CR_INSTALL_INFOA structures are wide-character and multi-byte character 492 * versions of \ref CR_INSTALL_INFO. \ref CR_INSTALL_INFO typedef defines character set independent mapping. 493 * 494 * Below, structure members are described in details. Required parameters must always be specified, while optional 495 * ones may be set with 0 (zero) or NULL. Most of parameters are optional. 496 * 497 * \b cb [in, required] 498 * 499 * This must contain the size of this structure in bytes. 500 * 501 * \b pszAppName [in, optional] 502 * 503 * This is the friendly name of the client application. The application name is 504 * displayed in the Error Report dialog. If this parameter is NULL, the name of EXE file 505 * that was used to start caller process becomes the application name. 506 * 507 * \b pszAppVersion [in, optional] 508 * 509 * Should be the application version. Example: "1.0.1". 510 * 511 * If this equals to NULL, product version is extracted from the executable file which started 512 * the caller process, and this product version is used as application version. If the executable file 513 * doesn's have a version info resource, the \ref crInstall() function will fail. 514 * 515 * \b pszEmailTo [in, optional] 516 * 517 * This is the email address of the recipient of error reports (or several E-mail adresses separated with semicolon), 518 * for example "name@example.com" or "person1@example.com;person2@someserver.com". If several E-mail addresses are 519 * specified, error report will be delivered to each of them. If this parameter equals to NULL, 520 * the crash report won't be sent using E-mail client. 521 * 522 * Keep this NULL if you plan to use large error reports (more than several MB in size), because 523 * large emails may be rejected by the mail server. 524 * 525 * \b pszEmailSubject [in, optional] 526 * 527 * This is the subject of the email message. If this parameter is NULL, 528 * the default subject of form '[app_name] [app_version] Error Report' is generated. 529 * 530 * \a pszUrl is the URL of a server-side script that would receive crash report data via HTTP or HTTPS 531 * connection. If this parmeter is NULL, HTTP(S) connection won't be used to send crash reports. For 532 * example of a server-side script that can receive crash reports, see \ref sending_error_reports. 533 * 534 * HTTP(S) transport is the recommended way of sending large error reports (more than several MB in size). 535 * To define a custom port for HTTP(S) connection, use the following URL format: "http://example.com[:port]/crashrpt.php" or 536 * "https://example.com[:port]/crashrpt.php", where optional \a port is the placeholder for the port number. 537 * 538 * \b pszCrashSenderPath [in, optional] 539 * 540 * This is the absolute path to the directory where CrashSender.exe is located. 541 * The crash sender process is responsible for letting end user know about the crash and 542 * sending the error report. If this is NULL, it is assumed that CrashSender.exe is located in 543 * the same directory as CrashRpt.dll. 544 * 545 * 546 * \b uPriorities [in, optional] 547 * 548 * This is an array that defines the preferred methods of sending error reports. 549 * The available methods are: HTTP (or HTTPS) connection, SMTP connection or simple MAPI (default mail client). 550 * 551 * A priority is a non-negative integer number or special constant \ref CR_NEGATIVE_PRIORITY. 552 * The greater positive number defines the greater priority. 553 * Specify the \ref CR_NEGATIVE_PRIORITY to skip the given delivery method. 554 * 555 * The element having index \ref CR_HTTP defines priority for using HTML connection. 556 * The element having index \ref CR_SMTP defines priority for using SMTP connection. 557 * The element having index \ref CR_SMAPI defines priority for using the default mail client. 558 * 559 * The methods having greater priority will be tried first. If priorities are equal to each other, HTTP (or HTTPS) 560 * connection will be tried the first, SMTP connection will be tried the second and simple MAPI will be tried 561 * the last. 562 * 563 * \b dwFlags [in, optional] 564 * 565 * Since v1.1.2, \a dwFlags can be used to define behavior parameters. This can be a combination of the following values: 566 * 567 * <table> 568 * <tr><td colspan="2"> <i>Use the combination of the following constants to specify what exception handlers to install:</i> 569 * <tr><td> \ref CR_INST_ALL_POSSIBLE_HANDLERS <td> Install all available exception handlers. 570 * <tr><td> \ref CR_INST_SEH_EXCEPTION_HANDLER <td> Install SEH exception handler. 571 * <tr><td> \ref CR_INST_PURE_CALL_HANDLER <td> Install pure call handler (VS .NET and later). 572 * <tr><td> \ref CR_INST_NEW_OPERATOR_ERROR_HANDLER <td> Install new operator error handler (VS .NET and later). 573 * <tr><td> \ref CR_INST_SECURITY_ERROR_HANDLER <td> Install security errror handler (VS .NET and later). 574 * <tr><td> \ref CR_INST_INVALID_PARAMETER_HANDLER <td> Install invalid parameter handler (VS 2005 and later). 575 * <tr><td> \ref CR_INST_SIGABRT_HANDLER <td> Install SIGABRT signal handler. 576 * <tr><td> \ref CR_INST_SIGINT_HANDLER <td> Install SIGINT signal handler. 577 * <tr><td> \ref CR_INST_SIGTERM_HANDLER <td> Install SIGTERM signal handler. 578 * <tr><td colspan="2"> <i>Use the combination of the following constants to define behavior parameters:</i> 579 * <tr><td> \ref CR_INST_NO_GUI 580 * <td> <b>Available since v.1.2.2</b> Do not show GUI. 581 * 582 * It is not recommended to use this flag for regular GUI-based applications. 583 * Use this only for services that have no GUI. 584 * <tr><td> \ref CR_INST_DONT_SEND_REPORT 585 * <td> <b>Available since v.1.2.2</b> This parameter means 'do not send error report immediately on crash, just save it locally'. 586 * Use this if you have direct access to the machine where crash happens and do not need 587 * to send report over the Internet. You can use this in couple with \ref CR_INST_STORE_ZIP_ARCHIVES flag to store zipped error reports 588 * along with uncompressed error report files. 589 * <tr><td> \ref CR_INST_APP_RESTART 590 * <td> <b>Available since v.1.2.4</b> This parameter allows to automatically restart the application on crash. The command line 591 * for the application is taken from \a pszRestartCmdLine parameter. To avoid cyclic restarts of an application which crashes on startup, 592 * the application is restarted only if at least 60 seconds elapsed since its start. 593 * <tr><td> \ref CR_INST_NO_MINIDUMP 594 * <td> <b>Available since v.1.2.4</b> Specify this parameter if you want minidump file not to be included into crash report. The default 595 * behavior is to include the minidump file. 596 * 597 * <tr><td> \ref CR_INST_SEND_QUEUED_REPORTS 598 * <td> <b>Available since v.1.2.5</b> Specify this parameter to send all queued reports. Those 599 * report files are by default stored in <i>%LOCAL_APPDATA%\\CrashRpt\\UnsentCrashReports\\%AppName%_%AppVersion%</i> folder. 600 * If this is specified, CrashRpt checks if it's time to remind user about recent errors in the application and offers to send 601 * all queued error reports. 602 * 603 * <tr><td> \ref CR_INST_STORE_ZIP_ARCHIVES 604 * <td> <b>Available since v.1.2.7</b> This parameter can be used in couple with \ref CR_INST_DONT_SEND_REPORT flag to store not only uncompressed 605 * error report files, but also ZIP archives. By default (if this flag omitted) CrashRpt stores all error report files 606 * in uncompressed state. 607 * 608 * <tr><td> \ref CR_INST_SEND_MANDATORY 609 * <td> <b>Available since v.1.3.1</b> This parameter makes sending procedure mandatory by removing the "Close" button 610 * and "Other actions..." button from the Error Report dialog. Typically, it is not recommended to use this flag, 611 * unless you intentionally want users to always send error reports for your application. 612 * <tr><td> \ref CR_INST_SHOW_ADDITIONAL_INFO_FIELDS 613 * <td> <b>Available since v.1.3.1</b> This parameter makes "Your E-mail" and "Describe what you were doing when the 614 * problem occurred" fields of Error Report dialog always visible. By default (when this parameter not specified), 615 * these fields are hidden and user needs to click the "Provide additional info (recommended)" link to show them. 616 * 617 * <tr><td> \ref CR_INST_ALLOW_ATTACH_MORE_FILES 618 * <td> <b>Available since v.1.3.1</b> Adds an ability for user to attach more files to crash report by choosing 619 * "Attach More File(s)" item from context menu of Error Report Details dialog. By default this feature is disabled. 620 * 621 * <tr><td> \ref CR_INST_AUTO_THREAD_HANDLERS 622 * <td> <b>Available since v.1.4.2</b> Specifying this flag results in automatic installation of all available exception handlers to 623 * all threads that will be created in the future. This flag only works if CrashRpt is compiled as a DLL, it does 624 * not work if you compile CrashRpt as static library. 625 * </table> 626 * 627 * \b pszPrivacyPolicyURL [in, optional] 628 * 629 * This parameter defines the URL for the Privacy Policy hyperlink of the 630 * Error Report dialog. If this parameter is NULL, the link is not displayed. For information on 631 * the Privacy Policy, see \ref error_report. This parameter is available since v1.1.2. 632 * 633 * \b pszDebugHelpDLL [in, optional] 634 * 635 * This parameter defines the location of the dbghelp.dll to load. 636 * If this parameter is NULL, the dbghelp.dll is searched using the default search sequence. 637 * This parameter is available since v1.2.1. 638 * 639 * \b uMiniDumpType [in, optional] 640 * 641 * This parameter defines the minidump type. For the list of available minidump 642 * types, see the documentation for the MiniDumpWriteDump() function in MSDN. 643 * Parameter is available since v.1.2.1. 644 * 645 * It is recommended to set this 646 * parameter with zero (equivalent of MiniDumpNormal constant). Other values may increase the minidump 647 * size significantly. 648 * 649 * \b pszErrorReportSaveDir [in, optional] 650 * 651 * This parameter defines the directory where to save the error reports. 652 * If this is NULL, the default directory is used (%%LOCAL_APP_DATA%\\CrashRpt\\UnsentCrashReports\\%%AppName%%_%%AppVersion%). 653 * This parameter is available since v.1.2.2. 654 * 655 * \b pszRestartCmdLine [in, optional] 656 * 657 * This parameter defines the string that specifies the 658 * command-line arguments for the application when it is restarted (when using \ref CR_INST_APP_RESTART flag). 659 * Do not include the name of the executable in the command line; it is added automatically. This parameter 660 * can be NULL. Available since v.1.2.4. 661 * 662 * \b pszLangFilePath [in, optional] 663 * 664 * This parameter defines the absolute path (including file name) for language file. 665 * If this is NULL, the lang file is assumed to be located in the same dir as CrashSender.exe file and have 666 * the name crashrpt_lang.ini. 667 * This parameter is available since v.1.2.4. 668 * 669 * \b pszEmailText [in, optional] 670 * 671 * This parameter defines the custom E-mail text that is used when deliverying error report 672 * as E-mail. If this is NULL, the default E-mail text is used. It is recommended to set this parameter with NULL. 673 * This parameter is available since v.1.2.4. 674 * 675 * \b pszSmtpProxy [in, optional] 676 * 677 * This parameter defines the network address (IP or domain) and, optionally, port formatted as "address[:port]" 678 * of SMTP server. Examples: "192.168.1.1:2525", "mail.example.com:25". 679 * If this parameter is NULL, the SMTP server address is resolved using the MX record of recipient's mailbox. 680 * You should typically set this parameter with NULL, except in the 681 * case when your software is a server and custom SMTP configuration is required. This parameter is available since v.1.2.4. 682 * 683 * \b pszCustomSenderIcon [in, optional] 684 * 685 * This parameter can be used to define a custom icon for <i>Error Report</i> dialog. This parameter is 686 * available since v.1.2.8. 687 * 688 * The value of this parameter should be absolute path to the module containing the icon resource, followed 689 * by resource identifier separated by comma. You can set this parameter with NULL to use the default icon. 690 * 691 * The resource identifier is a zero-based index of the icon to retrieve. For example, if this value is 0, 692 * the first icon in the specified file is used. If the identifier is a negative number not equal to -1, 693 * the icon in the specified file whose resource identifier is equal to the absolute value of the resource 694 * identifier is used. 695 * Example: "D:\MyApp\Resources.dll, -128". 696 * 697 * \b pszSmtpLogin [in, optional] 698 * 699 * This parameter defines the login name for SMTP authentication. It is typically used together with 700 * \ref pszSmtpProxy and \ref pszSmtpPassword parameter. 701 * If this parameter is ommitted (NULL), no SMTP autentication is used. This parameter is available since v.1.3.1. 702 * 703 * \b pszSmtpPassword [in, optional] 704 * 705 * This parameter defines the password for SMTP authentication. It is used in pair with \ref pszSmtpLogin parameter. 706 * This parameter is available since v.1.3.1. 707 * 708 * \b nRestartTimeout [in, optional] 709 * 710 * This parameter defines the timeout (in seconds) for the application restart (when using \ref CR_INST_APP_RESTART flag). 711 * It is recommended to set this with zero (in such a case, the default restart timeout of 60 seconds is applied). 712 * Available since v.1.4.3. 713 */ 714 715 typedef struct tagCR_INSTALL_INFOW 716 { 717 WORD cb; //!< Size of this structure in bytes; must be initialized before using! 718 LPCWSTR pszAppName; //!< Name of application. 719 LPCWSTR pszAppVersion; //!< Application version. 720 LPCWSTR pszEmailTo; //!< E-mail address of crash reports recipient. 721 LPCWSTR pszEmailSubject; //!< Subject of crash report e-mail. 722 LPCWSTR pszUrl; //!< URL of server-side script (used in HTTP connection). 723 LPCWSTR pszCrashSenderPath; //!< Directory name where CrashSender.exe is located. 724 LPGETLOGFILE pfnCrashCallback; //!< Deprecated, do not use. 725 UINT uPriorities[5]; //!< Array of error sending transport priorities. 726 DWORD dwFlags; //!< Flags. 727 LPCWSTR pszPrivacyPolicyURL; //!< URL of privacy policy agreement. 728 LPCWSTR pszDebugHelpDLL; //!< File name or folder of Debug help DLL. 729 MINIDUMP_TYPE uMiniDumpType; //!< Minidump type. 730 LPCWSTR pszErrorReportSaveDir; //!< Directory where to save error reports. 731 LPCWSTR pszRestartCmdLine; //!< Command line for application restart (without executable name). 732 LPCWSTR pszLangFilePath; //!< Path to the language file (including file name). 733 LPCWSTR pszEmailText; //!< Custom E-mail text (used when deliverying report as E-mail). 734 LPCWSTR pszSmtpProxy; //!< Network address and port to be used as SMTP proxy. 735 LPCWSTR pszCustomSenderIcon; //!< Custom icon used for Error Report dialog. 736 LPCWSTR pszSmtpLogin; //!< Login name used for SMTP authentication when sending error report as E-mail. 737 LPCWSTR pszSmtpPassword; //!< Password used for SMTP authentication when sending error report as E-mail. 738 int nRestartTimeout; //!< Timeout for application restart. 739 } 740 CR_INSTALL_INFOW; 741 742 typedef CR_INSTALL_INFOW* PCR_INSTALL_INFOW; 743 744 /*! \ingroup CrashRptStructs 745 * \struct CR_INSTALL_INFOA 746 * \copydoc CR_INSTALL_INFOW 747 */ 748 749 typedef struct tagCR_INSTALL_INFOA 750 { 751 WORD cb; //!< Size of this structure in bytes; must be initialized before using! 752 LPCSTR pszAppName; //!< Name of application. 753 LPCSTR pszAppVersion; //!< Application version. 754 LPCSTR pszEmailTo; //!< E-mail address of crash reports recipient. 755 LPCSTR pszEmailSubject; //!< Subject of crash report e-mail. 756 LPCSTR pszUrl; //!< URL of server-side script (used in HTTP connection). 757 LPCSTR pszCrashSenderPath; //!< Directory name where CrashSender.exe is located. 758 LPGETLOGFILE pfnCrashCallback; //!< Deprecated, do not use. 759 UINT uPriorities[5]; //!< Array of error sending transport priorities. 760 DWORD dwFlags; //!< Flags. 761 LPCSTR pszPrivacyPolicyURL; //!< URL of privacy policy agreement. 762 LPCSTR pszDebugHelpDLL; //!< File name or folder of Debug help DLL. 763 MINIDUMP_TYPE uMiniDumpType; //!< Mini dump type. 764 LPCSTR pszErrorReportSaveDir; //!< Directory where to save error reports. 765 LPCSTR pszRestartCmdLine; //!< Command line for application restart (without executable name). 766 LPCSTR pszLangFilePath; //!< Path to the language file (including file name). 767 LPCSTR pszEmailText; //!< Custom E-mail text (used when deliverying report as E-mail). 768 LPCSTR pszSmtpProxy; //!< Network address and port to be used as SMTP proxy. 769 LPCSTR pszCustomSenderIcon; //!< Custom icon used for Error Report dialog. 770 LPCSTR pszSmtpLogin; //!< Login name used for SMTP authentication when sending error report as E-mail. 771 LPCSTR pszSmtpPassword; //!< Password used for SMTP authentication when sending error report as E-mail. 772 int nRestartTimeout; //!< Timeout for application restart. 773 } 774 CR_INSTALL_INFOA; 775 776 typedef CR_INSTALL_INFOA* PCR_INSTALL_INFOA; 777 778 /*! \brief Character set-independent mapping of CR_INSTALL_INFOW and CR_INSTALL_INFOA structures. 779 * \ingroup CrashRptStructs 780 */ 781 #ifdef UNICODE 782 typedef CR_INSTALL_INFOW CR_INSTALL_INFO; 783 typedef PCR_INSTALL_INFOW PCR_INSTALL_INFO; 784 #else 785 typedef CR_INSTALL_INFOA CR_INSTALL_INFO; 786 typedef PCR_INSTALL_INFOA PCR_INSTALL_INFO; 787 #endif // UNICODE 788 789 /*! \ingroup CrashRptAPI 790 * \brief Installs exception handlers for the caller process. 791 * 792 * \return 793 * This function returns zero if succeeded. 794 * 795 * \param[in] pInfo General congiration information. 796 * 797 * \remarks 798 * 799 * This function installs unhandled exception filter for the caller process. 800 * It also installs various CRT exception/error handlers that function for all threads of the caller process. 801 * For more information, see \ref exception_handling 802 * 803 * Below is the list of installed handlers: 804 * - Top-level SEH exception filter [ \c SetUnhandledExceptionFilter() ] 805 * - C++ pure virtual call handler (Visual Studio .NET 2003 and later) [ \c _set_purecall_handler() ] 806 * - C++ invalid parameter handler (Visual Studio .NET 2005 and later) [ \c _set_invalid_parameter_handler() ] 807 * - C++ new operator error handler (Visual Studio .NET 2003 and later) [ \c _set_new_handler() ] 808 * - C++ buffer overrun handler (Visual Studio .NET 2003 only) [ \c _set_security_error_handler() ] 809 * - C++ abort handler [ \c signal(SIGABRT) ] 810 * - C++ illegal instruction handler [ \c signal(SIGINT) ] 811 * - C++ termination request [ \c signal(SIGTERM) ] 812 * 813 * In a multithreaded program, additionally use crInstallToCurrentThread2() function for each execution 814 * thread, except the main one. 815 * 816 * The \a pInfo parameter contains all required information needed to install CrashRpt. 817 * 818 * This function fails when \a pInfo->pszCrashSenderPath doesn't contain valid path to CrashSender.exe 819 * or when \a pInfo->pszCrashSenderPath is equal to NULL, but \b CrashSender.exe is not located in the 820 * directory where \b CrashRpt.dll located. 821 * 822 * On crash, the crash minidump file is created, which contains CPU information and 823 * stack trace information. Also XML file is created that contains additional 824 * information that may be helpful for crash analysis. These files along with several additional 825 * files added with crAddFile2() are packed to a single ZIP file. 826 * 827 * When crash information is collected, another process, <b>CrashSender.exe</b>, is launched 828 * and the process where crash had occured is terminated. The CrashSender process is 829 * responsible for letting the user know about the crash and send the error report. 830 * 831 * The error report can be sent over E-mail using address and subject passed to the 832 * function as \ref CR_INSTALL_INFO structure members. Another way of sending error report is an HTTP 833 * request using \a pszUrl member of \ref CR_INSTALL_INFO. 834 * 835 * This function may fail if an appropriate language file (\b crashrpt_lang.ini) is not found 836 * in the directory where the \b CrashSender.exe file is located. 837 * 838 * If this function fails, use crGetLastErrorMsg() to retrieve the error message. 839 * 840 * crInstallW() and crInstallA() are wide-character and multi-byte character versions of crInstall() 841 * function. The \ref crInstall macro defines character set independent mapping for these functions. 842 * 843 * For code example, see \ref simple_example. 844 * 845 * \sa crInstallW(), crInstallA(), crInstall(), CR_INSTALL_INFOW, 846 * CR_INSTALL_INFOA, CR_INSTALL_INFO, crUninstall(), 847 * CrAutoInstallHelper 848 */ 849 850 CRASHRPTAPI(int) 851 crInstallW( 852 __in PCR_INSTALL_INFOW pInfo 853 ); 854 855 /*! \ingroup CrashRptAPI 856 * \copydoc crInstallW() 857 */ 858 859 CRASHRPTAPI(int) 860 crInstallA( 861 __in PCR_INSTALL_INFOA pInfo 862 ); 863 864 /*! \brief Character set-independent mapping of crInstallW() and crInstallA() functions. 865 * \ingroup CrashRptAPI 866 */ 867 #ifdef UNICODE 868 #define crInstall crInstallW 869 #else 870 #define crInstall crInstallA 871 #endif //UNICODE 872 873 /*! \ingroup CrashRptAPI 874 * \brief Uninitializes the CrashRpt library and unsinstalls exception handlers previously installed with crInstall(). 875 * 876 * \return 877 * This function returns zero if succeeded. 878 * 879 * \remarks 880 * 881 * Call this function on application exit to uninitialize the library and uninstall exception 882 * handlers previously installed with crInstall(). After function call, the exception handlers 883 * are restored to states they had before calling crInstall(). 884 * 885 * This function fails if crInstall() wasn't previously called in context of the 886 * caller process. 887 * 888 * When this function fails, use the crGetLastErrorMsg() function to retrieve the error message. 889 * 890 * \sa crInstallW(), crInstallA(), crInstall(), 891 * CrAutoInstallHelper 892 */ 893 894 CRASHRPTAPI(int) 895 crUninstall(); 896 897 /*! \ingroup CrashRptAPI 898 * \brief Installs exception handlers to the caller thread. 899 * \return This function returns zero if succeeded. 900 * \param[in] dwFlags Flags. 901 * 902 * \remarks 903 * 904 * This function is available <b>since v.1.1.2</b>. 905 * 906 * The function sets exception handlers for the caller thread. If you have 907 * several execution threads, you ought to call the function for each thread, 908 * except the main one. 909 * 910 * \a dwFlags defines what exception handlers to install. Use zero value 911 * to install all possible exception handlers. Or use a combination of the following constants: 912 * 913 * - \ref CR_INST_TERMINATE_HANDLER Install terminate handler 914 * - \ref CR_INST_UNEXPECTED_HANDLER Install unexpected handler 915 * - \ref CR_INST_SIGFPE_HANDLER Install SIGFPE signal handler 916 * - \ref CR_INST_SIGILL_HANDLER Install SIGILL signal handler 917 * - \ref CR_INST_SIGSEGV_HANDLER Install SIGSEGV signal handler 918 * 919 * Example: 920 * 921 * \code 922 * DWORD WINAPI ThreadProc(LPVOID lpParam) 923 * { 924 * // Install exception handlers 925 * crInstallToCurrentThread2(0); 926 * 927 * // Your code... 928 * 929 * // Uninstall exception handlers 930 * crUninstallFromCurrentThread(); 931 * 932 * return 0; 933 * } 934 * \endcode 935 * 936 * \sa 937 * crInstall() 938 */ 939 940 CRASHRPTAPI(int) 941 crInstallToCurrentThread2(DWORD dwFlags); 942 943 /*! \ingroup CrashRptAPI 944 * \brief Uninstalls C++ exception handlers from the current thread. 945 * \return This function returns zero if succeeded. 946 * 947 * \remarks 948 * 949 * This function unsets exception handlers from the caller thread. If you have 950 * several execution threads, you ought to call the function for each thread. 951 * After calling this function, the exception handlers for current thread are 952 * replaced with the handlers that were before call of crInstallToCurrentThread2(). 953 * 954 * This function fails if crInstallToCurrentThread2() wasn't called for current thread. 955 * 956 * When this function fails, use crGetLastErrorMsg() to retrieve the error message. 957 * 958 * No need to call this function for the main execution thread. The crUninstall() 959 * will automatically uninstall C++ exception handlers for the main thread. 960 * 961 * \sa crInstallToCurrentThread2(), 962 * crUninstallFromCurrentThread(), CrThreadAutoInstallHelper 963 */ 964 965 CRASHRPTAPI(int) 966 crUninstallFromCurrentThread(); 967 968 // Flags for crAddFile2() function. 969 970 #define CR_AF_TAKE_ORIGINAL_FILE 0 //!< Take the original file (do not copy it to the error report folder). 971 #define CR_AF_MAKE_FILE_COPY 1 //!< Copy the file to the error report folder. 972 #define CR_AF_FILE_MUST_EXIST 0 //!< Function will fail if file doesn't exist at the moment of function call. 973 #define CR_AF_MISSING_FILE_OK 2 //!< Do not fail if file is missing (assume it will be created later). 974 #define CR_AF_ALLOW_DELETE 4 //!< If this flag is specified, the file will be deletable from context menu of Error Report Details dialog. 975 976 /*! \ingroup CrashRptAPI 977 * \brief Adds a file to crash report. 978 * 979 * \return This function returns zero if succeeded. 980 * 981 * \param[in] pszFile Absolute path to the file (or file search pattern) to add to crash report, required. 982 * \param[in] pszDestFile Destination file name, optional. 983 * \param[in] pszDesc File description (used in Error Report Details dialog), optional. 984 * \param[in] dwFlags Flags, optional. 985 * 986 * This function can be called anytime after crInstall() to add one or more 987 * files to the generated crash report. 988 * 989 * When this function is called, the file is marked to be added to the error report, 990 * then the function returns control to the caller. 991 * When a crash occurs, all marked files are added to the report by the \b CrashSender.exe process. 992 * If a file is locked by someone for exclusive access, the file won't be included. 993 * Inside of \ref PFNCRASHCALLBACK() crash callback, 994 * close open file handles and ensure files to be included are acessible for reading. 995 * 996 * \a pszFile should be either a valid absolute path to the file or a file search 997 * pattern (e.g. "*.log") to be added to crash report. 998 * 999 * \a pszDestFile should be the name of destination file. This parameter can be used 1000 * to specify different file name for the file in ZIP archive. If this parameter is NULL, the pszFile 1001 * file name is used as destination file name. If \a pszFile is a search pattern, this argument 1002 * is ignored. 1003 * 1004 * \a pszDesc is a short description of the file. It can be NULL. 1005 * 1006 * \a dwFlags parameter defines the behavior of the function. This can be a combination of the following flags: 1007 * - \ref CR_AF_TAKE_ORIGINAL_FILE On crash, the \b CrashSender.exe process will try to locate the file from its original location. This behavior is the default one. 1008 * - \ref CR_AF_MAKE_FILE_COPY On crash, the \b CrashSender.exe process will make a copy of the file and save it to the error report folder. 1009 * 1010 * - \ref CR_AF_FILE_MUST_EXIST The function will fail if file doesn't exist at the moment of function call (the default behavior). 1011 * - \ref CR_AF_MISSING_FILE_OK The function will not fail if file is missing (assume it will be created later). 1012 * 1013 * - \ref 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. 1014 * 1015 * If you do not use error report delivery (\ref CR_INST_DONT_SEND_REPORT flag) or if you use postponed error report delivery 1016 * (if you specify \ref CR_INST_SEND_QUEUED_REPORTS flag) 1017 * you must also specify the \ref CR_AF_MAKE_FILE_COPY as \a dwFlags parameter value. This will 1018 * guarantee that a snapshot of your file at the moment of crash is taken and saved to the error report folder. 1019 * The error report folder is a folder where files included into the crash report are stored 1020 * until they are sent to recipient. 1021 * 1022 * This function fails if \a pszFile doesn't exist at the moment of function call, 1023 * unless you specify \ref CR_AF_MISSING_FILE_OK flag. 1024 * 1025 * The crAddFile2W() and crAddFile2A() are wide-character and multibyte-character 1026 * versions of crAddFile2() function. The crAddFile2() macro defines character set 1027 * independent mapping. 1028 * 1029 * Usage example: 1030 * 1031 * \code 1032 * 1033 * // Add the error.log file to crash report. At the moment of crash, 1034 * // the file will be copied to crash report folder. The end user 1035 * // will be able to delete the file using CrashRpt GUI. 1036 * int nResult = crAddFile2( 1037 * _T("C:\\Program Files (x86)\MyApp\\error.log"), 1038 * _T("error.log"), 1039 * _T("Log file"), 1040 * CR_AF_MAKE_FILE_COPY|CR_AF_ALLOW_DELETE); 1041 * if(nResult!=0) 1042 * { 1043 * // Get the status message 1044 * TCHAR szErrorMsg[256]; 1045 * crGetLastErrorMsg(szErrorMsg, 256); 1046 * } 1047 * 1048 * // Add all *.txt files found in the folder. At the moment of crash, 1049 * // the file(s) will be copied to crash report folder. The end user 1050 * // won't be able to delete the file(s). 1051 * crAddFile2(_T("C:\\Program Files (x86)\MyApp\\*.txt"), 1052 * NULL, _T("TXT file"), CR_AF_MAKE_FILE_COPY); 1053 * 1054 * \endcode 1055 * 1056 * \sa crAddFile2W(), crAddFile2A(), crAddFile2() 1057 */ 1058 1059 CRASHRPTAPI(int) 1060 crAddFile2W( 1061 LPCWSTR pszFile, 1062 LPCWSTR pszDestFile, 1063 LPCWSTR pszDesc, 1064 DWORD dwFlags 1065 ); 1066 1067 /*! \ingroup CrashRptAPI 1068 * \copydoc crAddFile2W() 1069 */ 1070 1071 CRASHRPTAPI(int) 1072 crAddFile2A( 1073 LPCSTR pszFile, 1074 LPCSTR pszDestFile, 1075 LPCSTR pszDesc, 1076 DWORD dwFlags 1077 ); 1078 1079 /*! \brief Character set-independent mapping of crAddFile2W() and crAddFile2A() functions. 1080 * \ingroup CrashRptAPI 1081 */ 1082 #ifdef UNICODE 1083 #define crAddFile2 crAddFile2W 1084 #else 1085 #define crAddFile2 crAddFile2A 1086 #endif //UNICODE 1087 1088 1089 // Flags for crAddScreenshot function. 1090 #define CR_AS_VIRTUAL_SCREEN 0 //!< Take a screenshot of the virtual screen. 1091 #define CR_AS_MAIN_WINDOW 1 //!< Take a screenshot of application's main window. 1092 #define CR_AS_PROCESS_WINDOWS 2 //!< Take a screenshot of all visible process windows. 1093 #define CR_AS_GRAYSCALE_IMAGE 4 //!< Make a grayscale image instead of a full-color one. 1094 #define CR_AS_USE_JPEG_FORMAT 8 //!< Store screenshots as JPG files. 1095 #define CR_AS_ALLOW_DELETE 16 //!< If this flag is specified, the file will be deletable from context menu of Error Report Details dialog. 1096 1097 /*! \ingroup DeprecatedAPI 1098 * \brief Adds a screenshot to the crash report. 1099 * 1100 * \return This function returns zero if succeeded. Use crGetLastErrorMsg() to retrieve the error message on fail. 1101 * 1102 * \param[in] dwFlags Flags, optional. 1103 * 1104 * \remarks 1105 * 1106 * As of v.1.3.1, this function is deprecated and may be removed in one of the next releases. Use 1107 * \ref crAddScreenshot2() function instead. 1108 * 1109 * This function can be used to take a screenshot at the moment of crash and add it to the error report. 1110 * Screenshot information may help the developer to better understand the state of the application 1111 * at the moment of crash and reproduce the error. 1112 * 1113 * When this function is called, screenshot flags are saved, 1114 * then the function returns control to the caller. 1115 * When crash occurs, screenshot is made by the \b CrashSender.exe process and added to the report. 1116 * 1117 * \b dwFlags 1118 * 1119 * - \ref CR_AS_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. 1120 * 1121 * Use one of the following constants to specify what part of virtual screen to capture: 1122 * - \ref CR_AS_VIRTUAL_SCREEN Use this to take a screenshot of the whole desktop (virtual screen). 1123 * - \ref CR_AS_MAIN_WINDOW Use this to take a screenshot of the application's main window. 1124 * - \ref CR_AS_PROCESS_WINDOWS Use this to take a screenshot of all visible windows that belong to the process. 1125 * 1126 * The main application window is a window that has a caption (\b WS_CAPTION), system menu (\b WS_SYSMENU) and 1127 * the \b WS_EX_APPWINDOW extended style. If CrashRpt doesn't find such window, it considers the first found process window as 1128 * the main window. 1129 * 1130 * Screenshots are added in form of PNG files by default. You can specify the \ref CR_AS_USE_JPEG_FORMAT flag to save 1131 * screenshots as JPEG files instead. 1132 * 1133 * In addition, you can specify the \ref CR_AS_GRAYSCALE_IMAGE flag to make a grayscale screenshot 1134 * (by default color image is made). Grayscale image gives smaller file size. 1135 * 1136 * If you use JPEG image format, you may better use the \ref crAddScreenshot2() function, that allows to 1137 * define JPEG image quality. 1138 * 1139 * When capturing entire desktop consisting of several monitors, 1140 * one screenshot file is added per each monitor. 1141 * 1142 * You should be careful when using this feature, because screenshots may contain user-identifying 1143 * or private information. Always specify purposes you will use collected 1144 * information for in your Privacy Policy. 1145 * 1146 * \sa 1147 * crAddFile2() 1148 */ 1149 1150 CRASHRPTAPI(int) 1151 crAddScreenshot( 1152 DWORD dwFlags 1153 ); 1154 1155 /*! \ingroup CrashRptAPI 1156 * \brief Adds a screenshot to the crash report. 1157 * 1158 * \return This function returns zero if succeeded. Use crGetLastErrorMsg() to retrieve the error message on fail. 1159 * 1160 * \param[in] dwFlags Flags, optional. 1161 * \param[in] nJpegQuality Defines the JPEG image quality, optional. 1162 * 1163 * \remarks 1164 * 1165 * This function can be used to take a screenshot at the moment of crash and add it to the error report. 1166 * Screenshot information may help the developer to better understand state of the application 1167 * at the moment of crash and reproduce the error. 1168 * 1169 * When this function is called, screenshot flags are saved, then the function returns control to the caller. 1170 * When crash occurs, screenshot is made by the \b CrashSender.exe process and added to the report. 1171 * 1172 * \b dwFlags 1173 * 1174 * Use one of the following constants to specify what part of virtual screen to capture: 1175 * - \ref CR_AS_VIRTUAL_SCREEN Use this to take a screenshot of the whole desktop (virtual screen). 1176 * - \ref CR_AS_MAIN_WINDOW Use this to take a screenshot of the main application main window. 1177 * - \ref CR_AS_PROCESS_WINDOWS Use this to take a screenshot of all visible windows that belong to the process. 1178 * 1179 * The main application window is a window that has a caption (\b WS_CAPTION), system menu (\b WS_SYSMENU) and 1180 * the \b WS_EX_APPWINDOW extended style. If CrashRpt doesn't find such window, it considers the first found process window as 1181 * the main window. 1182 * 1183 * Screenshots are added in form of PNG files by default. You can specify the \ref CR_AS_USE_JPEG_FORMAT flag to save 1184 * screenshots as JPEG files instead. 1185 * 1186 * If you use JPEG format, you can use the \a nJpegQuality parameter to define the JPEG image quality. 1187 * 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. 1188 * If you use PNG file format, this parameter is ignored. 1189 * 1190 * In addition, you can specify the \ref CR_AS_GRAYSCALE_IMAGE flag to make a grayscale screenshot 1191 * (by default color image is made). Grayscale image gives smaller file size. 1192 * 1193 * When capturing entire desktop consisting of several monitors, 1194 * one screenshot file is added per each monitor. 1195 * 1196 * You should be careful when using this feature, because screenshots may contain user-identifying 1197 * or private information. Always specify purposes you will use collected 1198 * information for in your Privacy Policy. 1199 * 1200 * \sa 1201 * crAddFile2() 1202 */ 1203 1204 CRASHRPTAPI(int) 1205 crAddScreenshot2( 1206 DWORD dwFlags, 1207 int nJpegQuality 1208 ); 1209 1210 // Flags for crAddVideo function. 1211 #define CR_AV_VIRTUAL_SCREEN 0 //!< Capture the whole virtual screen. 1212 #define CR_AV_MAIN_WINDOW 1 //!< Capture the area of application's main window. 1213 #define CR_AV_PROCESS_WINDOWS 2 //!< Capture all visible process windows. 1214 #define CR_AV_QUALITY_LOW 0 //!< Low quality video encoding, smaller file size. 1215 #define CR_AV_QUALITY_GOOD 4 //!< Good encoding quality, larger file size. 1216 #define CR_AV_QUALITY_BEST 8 //!< The best encoding quality, the largest file size. 1217 #define CR_AV_NO_GUI 16 //!< Do not display the notification dialog. 1218 #define CR_AV_ALLOW_DELETE 32 //!< If this flag is specified, the file will be deletable from context menu of Error Report Details dialog. 1219 1220 /*! \ingroup CrashRptAPI 1221 * \brief Allows to record what happened before crash to a video file and include the file to crash report. 1222 * 1223 * \return This function returns zero if succeeded. Use \ref crGetLastErrorMsg() to retrieve the error message on failure. 1224 * 1225 * \param[in] dwFlags Flags, optional. 1226 * \param[in] nDuration Video duration (in milliseconds). Optional. 1227 * \param[in] nFrameInterval Interval between subsequent frames (in milliseconds). Optional. 1228 * \param[in] pDesiredFrameSize Defines the desired video frame size, optional. 1229 * \param[in] hWndParent Window that becomes the parent for GUI displayed by this function. Optional. 1230 * 1231 * \remarks 1232 * 1233 * This function is available as of v.1.4.0. 1234 * 1235 * \b dwFlags can be a combination of the following constants: 1236 * 1237 * - use one of the following constants to specify what part of virtual screen to capture: 1238 * - \ref CR_AV_VIRTUAL_SCREEN Use this to capture the whole desktop (virtual screen). This is the default. 1239 * - \ref CR_AV_MAIN_WINDOW Use this to capture the application's main window. 1240 * - \ref CR_AV_PROCESS_WINDOWS Use this to capture all visible windows that belong to the process. 1241 * 1242 * - use one of the following constants to define the desired video encoding quality: 1243 * - \ref CR_AV_QUALITY_LOW Low-quality video encoding. This is the default. 1244 * - \ref CR_AV_QUALITY_GOOD Good encoding quality, larger file. 1245 * - \ref CR_AV_QUALITY_BEST The best encoding quality, the largest file. 1246 * 1247 * - use the \ref 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. 1248 * 1249 * The main application window is a window that has a caption (\b WS_CAPTION), system menu (\b WS_SYSMENU) and 1250 * the \b WS_EX_APPWINDOW extended style. If CrashRpt doesn't find such a window, it considers the first found process window as 1251 * the main window. 1252 * 1253 * When the function is called, it displays a dialog notifying the user about video recording. 1254 * The displayed dialog's parent window can be specified with the \b hWndParent argument. 1255 * If the \b hWndParent is \a NULL, the currently active process window becomes the parent. 1256 * If you do not want to display the dialog, specify the \ref CR_AV_NO_GUI flag for \b dwFlags argument. 1257 * 1258 * The recorded video will be maximum \b nDuration milliseconds long with \b nFrameInterval 1259 * milliseconds interval between subsequent video frames. If \b nDuration and\or \b nFrameInterval 1260 * are set to zero (0), the default implementation-defined duration and frame interval are used. 1261 * 1262 * The \b pDesiredFrameSize parameter allows to define the desired video frame size. 1263 * Frame width and height must be a multiple of 16 (OGG Theora video codec's requirement). 1264 * If they are not, they are modified automatically to be a multiple of 16. 1265 * 1266 * To preserve correct aspect ratio of the captured area, set \b pDesiredFrameSize->cx or \b pDesiredFrameSize->cy 1267 * to zero. For example, setting \b pDesiredFrameSize->cx=640 and \b pDesiredFrameSize->cy=0 1268 * results in video frames whose width is 640 pixels and height is calculated to preserve the 1269 * correct aspect ratio of the captured area. If both \b cx and \b cy are specified, the aspect ratio 1270 * of the captured area is not preserved. 1271 * 1272 * Setting the \b pDesiredFrameSize 1273 * parameter to \a NULL makes the function to determine the best video frame size automatically. 1274 * 1275 * This function can be used to record the state of end user's desktop just before the moment 1276 * of crash and add the video file to the error report. The recorded information may help the 1277 * software vendor to better understand the state of the client application at the moment of 1278 * crash and reproduce the error. 1279 * 1280 * When this function is called, CrashRpt launches another process named \b CrashSender.exe. 1281 * The \b CrashSender.exe process then continuously captures the desktop screenshots in background 1282 * mode and stores them to disk as image files. To avoid high CPU load, image files are stored 1283 * in uncompressed state as raw bitmap (BMP) files. When the count of screenshot files exceeds 1284 * the predefined maximum number, the old screenshot files are reused cyclically. 1285 * 1286 * If the client application does not crash and its main code or main window loop exits successfully, 1287 * the captured desktop screenshot files are removed by the \ref crUninstall() function call and 1288 * \b CrashSender.exe process is terminated. 1289 * 1290 * If the client application crashes at some moment of time, the recorded screenshot files are compressed by 1291 * <a href="http://www.theora.org/">OGG Theora video codec</a> and written into an .OGG file. The 1292 * uncompressed temporary screenshots are then removed, and the resulting 1293 * OGG file is included into crash report archive. 1294 * 1295 * The <a href="http://en.wikipedia.org/wiki/Ogg">OGG video format</a> is a widely used 1296 * video container provided by the open-source OGG Project. 1297 * OGG files can be opened in a browser like Google Chrome or Mozilla Firefox or in 1298 * another video player understanding this format, like ffmpeg. 1299 * 1300 * Use this function only when necessary, because it may cause end user's computer performance 1301 * loss. It also requires some amount of free disk space. 1302 * 1303 * The recorded video may contain user-identifying or private information. Always 1304 * specify the purposes you will use collected information for in your Privacy Policy. 1305 * 1306 * Usage example: 1307 * 1308 * \code 1309 * 1310 * // First install CrashRpt with crInstall() function 1311 * 1312 * ... 1313 * 1314 * SIZE FrameSize = {0, 600}; // Frames 600 px in height 1315 * // Frame width is calculated automatically 1316 * 1317 * // Start capturing desktop. Desktop capture video will 1318 * // be added to crash report on crash 1319 * int nResult = crAddVideo( 1320 * CR_AV_VIRTUAL_SCREEN|CR_AV_QUALITY_GOOD, // Capture entire desktop 1321 * // Good encoding quality 1322 * 10000, // 10 seconds long video 1323 * 300, // 300 msec between frames (3.33 FPS) 1324 * &FrameSize, 1325 * NULL 1326 * ); 1327 * 1328 * \endcode 1329 * 1330 * \sa 1331 * crAddFile2(), crAddScreenshot2(), crAddRegKey(), crUninstall(). 1332 */ 1333 1334 CRASHRPTAPI(int) 1335 crAddVideo( 1336 DWORD dwFlags, 1337 int nDuration, 1338 int nFrameInterval, 1339 PSIZE pDesiredFrameSize, 1340 HWND hWndParent 1341 ); 1342 1343 /*! \ingroup CrashRptAPI 1344 * \brief Adds a string property to the crash report. 1345 * 1346 * \return This function returns zero if succeeded. Use crGetLastErrorMsg() to retrieve the error message on fail. 1347 * 1348 * \param[in] pszPropName Name of the property, required. 1349 * \param[in] pszPropValue Value of the property, required. 1350 * 1351 * \remarks 1352 * 1353 * Use this function to add a string property to the crash description XML file. 1354 * User-added properties are listed under \<CustomProps\> tag of the XML file. 1355 * In the XML file properties are ordered by names in alphabetic order. 1356 * 1357 * The following example shows how to add information about the amount of free disk space 1358 * to the crash description XML file: 1359 * 1360 * \code 1361 * // It is assumed that you already calculated the amount of free disk space, 1362 * // converted it to text and stored it as szFreeSpace string. 1363 * LPCTSTR szFreeSpace = _T("0 Kb"); 1364 * crAddProperty(_T("FreeDiskSpace"), szFreeSpace); 1365 * 1366 * \endcode 1367 * 1368 * \sa 1369 * crAddFile2(), crAddScreenshot() 1370 */ 1371 1372 CRASHRPTAPI(int) 1373 crAddPropertyW( 1374 LPCWSTR pszPropName, 1375 LPCWSTR pszPropValue 1376 ); 1377 1378 /*! \ingroup CrashRptAPI 1379 * \copydoc crAddPropertyW() 1380 */ 1381 1382 CRASHRPTAPI(int) 1383 crAddPropertyA( 1384 LPCSTR pszPropName, 1385 LPCSTR pszPropValue 1386 ); 1387 1388 /*! \brief Character set-independent mapping of crAddPropertyW() and crAddPropertyA() functions. 1389 * \ingroup CrashRptAPI 1390 */ 1391 #ifdef UNICODE 1392 #define crAddProperty crAddPropertyW 1393 #else 1394 #define crAddProperty crAddPropertyA 1395 #endif //UNICODE 1396 1397 // Flags that can be passed to crAddRegKey() function 1398 #define CR_AR_ALLOW_DELETE 0x1 //!< If this flag is specified, the file will be deletable from context menu of Error Report Details dialog. 1399 1400 /*! \ingroup CrashRptAPI 1401 * \brief Adds a registry key dump to the crash report. 1402 * 1403 * \return This function returns zero if succeeded. Use crGetLastErrorMsg() to retrieve the error message on fail. 1404 * 1405 * \param[in] pszRegKey Registry key to dump, required. 1406 * \param[in] pszDstFileName Name of the destination file, required. 1407 * \param[in] dwFlags Flags, reserved. 1408 * 1409 * \remarks 1410 * 1411 * Use this function to add a dump of a Windows registry key into the crash report. This function 1412 * is available since v.1.2.6. 1413 * 1414 * The \a pszRegKey parameter must be the name of the registry key. The key name should begin with "HKEY_CURRENT_USER" 1415 * or "HKEY_LOCAL_MACHINE". Other root keys are not supported. 1416 * 1417 * The content of the key specified by the \a pszRegKey parameter will be stored in a human-readable XML 1418 * format and included into the error report as \a pszDstFileName destination file. You can dump multiple registry keys 1419 * to the same destination file. 1420 * 1421 * The \a dwFlags parameter can be either set to zero (no flags) or with the following constant: 1422 * 1423 * - \ref CR_AR_ALLOW_DELETE allows the user to delete the file from error report using context menu of Error Report Details dialog. 1424 * 1425 * The following example shows how to dump two registry keys to a single \a regkey.xml file: 1426 * 1427 * \code 1428 * 1429 * crAddRegKey(_T("HKEY_CURRENT_USER\\Software\\MyApp"), _T("regkey.xml"), 0); 1430 * crAddRegKey(_T("HKEY_LOCAL_MACHINE\\Software\\MyApp"), _T("regkey.xml"), 0); 1431 * 1432 * \endcode 1433 * 1434 * \sa 1435 * crAddFile2(), crAddScreenshot(), crAddProperty() 1436 */ 1437 1438 CRASHRPTAPI(int) 1439 crAddRegKeyW( 1440 LPCWSTR pszRegKey, 1441 LPCWSTR pszDstFileName, 1442 DWORD dwFlags 1443 ); 1444 1445 /*! \ingroup CrashRptAPI 1446 * \copydoc crAddRegKeyW() 1447 */ 1448 1449 CRASHRPTAPI(int) 1450 crAddRegKeyA( 1451 LPCSTR pszRegKey, 1452 LPCSTR pszDstFileName, 1453 DWORD dwFlags 1454 ); 1455 1456 /*! \brief Character set-independent mapping of crAddRegKeyW() and crAddRegKeyA() functions. 1457 * \ingroup CrashRptAPI 1458 */ 1459 #ifdef UNICODE 1460 #define crAddRegKey crAddRegKeyW 1461 #else 1462 #define crAddRegKey crAddRegKeyA 1463 #endif //UNICODE 1464 1465 /*! \ingroup CrashRptAPI 1466 * \brief Manually generates an error report. 1467 * 1468 * \return This function returns zero if succeeded. When failed, it returns a non-zero value. 1469 * Use crGetLastErrorMsg() function to retrieve the error message. 1470 * 1471 * \param[in] pExceptionInfo Exception information. 1472 * 1473 * \remarks 1474 * 1475 * Call this function to manually generate a crash report. When crash information is collected, 1476 * control is returned to the caller. The crGenerateErrorReport() doesn't terminate the caller process. 1477 * 1478 * The crash report may contain the crash minidump file, crash description file in XML format and 1479 * additional custom files added with a function like crAddFile2(). 1480 * 1481 * The exception information should be passed using \ref CR_EXCEPTION_INFO structure. 1482 * 1483 * The following example shows how to use crGenerateErrorReport() function. 1484 * 1485 * \code 1486 * CR_EXCEPTION_INFO ei; 1487 * memset(&ei, 0, sizeof(CR_EXCEPTION_INFO)); 1488 * ei.cb = sizeof(CR_EXCEPTION_INFO); 1489 * ei.exctype = CR_SEH_EXCEPTION; 1490 * ei.code = 1234; 1491 * ei.pexcptrs = NULL; 1492 * 1493 * int result = crGenerateErrorReport(&ei); 1494 * 1495 * if(result!=0) 1496 * { 1497 * // If goes here, crGenerateErrorReport() has failed 1498 * // Get the last error message 1499 * TCHAR szErrorMsg[256]; 1500 * crGetLastErrorMsg(szErrorMsg, 256); 1501 * } 1502 * 1503 * // Manually terminate program 1504 * ExitProcess(0); 1505 * 1506 * \endcode 1507 */ 1508 1509 CRASHRPTAPI(int) 1510 crGenerateErrorReport( 1511 __in_opt CR_EXCEPTION_INFO* pExceptionInfo 1512 ); 1513 1514 /*! \ingroup CrashRptAPI 1515 * \brief Can be used as a SEH exception filter. 1516 * 1517 * \return This function returns \c EXCEPTION_EXECUTE_HANDLER if succeeds; otherwise \c EXCEPTION_CONTINUE_SEARCH. 1518 * 1519 * \param[in] code Exception code. 1520 * \param[in] ep Exception pointers. 1521 * 1522 * \remarks 1523 * 1524 * This function can be called instead of a SEH exception filter 1525 * inside of __try{}__except(Expression){} construction. The function generates an error report 1526 * and returns control to the exception handler block. 1527 * 1528 * The exception code is usually retrieved with \b GetExceptionCode() intrinsic function 1529 * and the exception pointers are retrieved with \b GetExceptionInformation() intrinsic 1530 * function. 1531 * 1532 * If an error occurs, this function returns \c EXCEPTION_CONTINUE_SEARCH. 1533 * Use crGetLastErrorMsg() to retrieve the error message on fail. 1534 * 1535 * The following example shows how to use crExceptionFilter(). 1536 * 1537 * \code 1538 * int* p = NULL; // pointer to NULL 1539 * __try 1540 * { 1541 * *p = 13; // causes an access violation exception; 1542 * } 1543 * __except(crExceptionFilter(GetExceptionCode(), GetExceptionInformation())) 1544 * { 1545 * // Terminate program 1546 * ExitProcess(1); 1547 * } 1548 * 1549 * \endcode 1550 */ 1551 1552 CRASHRPTAPI(int) 1553 crExceptionFilter( 1554 unsigned int code, 1555 __in_opt struct _EXCEPTION_POINTERS* ep); 1556 1557 1558 // Flags used by crEmulateCrash() function 1559 #define CR_NONCONTINUABLE_EXCEPTION 32 //!< Non continuable sofware exception. 1560 #define CR_THROW 33 //!< Throw C++ typed exception. 1561 #define CR_STACK_OVERFLOW 34 //!< Stack overflow. 1562 1563 /*! \ingroup CrashRptAPI 1564 * \brief Emulates a predefined crash situation. 1565 * 1566 * \return This function doesn't return if succeded. If failed, returns non-zero value. Call crGetLastErrorMsg() 1567 * to get the last error message. 1568 * 1569 * \param[in] ExceptionType Type of crash. 1570 * 1571 * \remarks 1572 * 1573 * This function uses some a priori incorrect or vulnerable code or raises a C++ signal or raises an uncontinuable 1574 * software exception to cause crash. 1575 * 1576 * This function can be used to test if CrashRpt handles a crash situation correctly. 1577 * 1578 * CrashRpt will intercept an error or exception if crInstall() and/or crInstallToCurrentThread2() 1579 * were previously called. crInstall() installs exception handlers that function on per-process basis. 1580 * crInstallToCurrentThread2() installs exception handlers that function on per-thread basis. 1581 * 1582 * \a ExceptionType can be one of the following constants: 1583 * - \ref CR_SEH_EXCEPTION This will generate a null pointer exception. 1584 * - \ref CR_CPP_TERMINATE_CALL This results in call of terminate() C++ function. 1585 * - \ref CR_CPP_UNEXPECTED_CALL This results in call of unexpected() C++ function. 1586 * - \ref CR_CPP_PURE_CALL This emulates a call of pure virtual method call of a C++ class instance (Visual Studio .NET 2003 and later). 1587 * - \ref CR_CPP_NEW_OPERATOR_ERROR This emulates C++ new operator failure (Visual Studio .NET 2003 and later). 1588 * - \ref CR_CPP_SECURITY_ERROR This emulates copy of large amount of data to a small buffer (Visual Studio .NET 2003 only). 1589 * - \ref CR_CPP_INVALID_PARAMETER This emulates an invalid parameter C++ exception (Visual Studio 2005 and later). 1590 * - \ref CR_CPP_SIGABRT This raises SIGABRT signal (abnormal program termination). 1591 * - \ref CR_CPP_SIGFPE This causes floating point exception. 1592 * - \ref CR_CPP_SIGILL This raises SIGILL signal (illegal instruction signal). 1593 * - \ref CR_CPP_SIGINT This raises SIGINT signal. 1594 * - \ref CR_CPP_SIGSEGV This raises SIGSEGV signal. 1595 * - \ref CR_CPP_SIGTERM This raises SIGTERM signal (program termination request). 1596 * - \ref CR_NONCONTINUABLE_EXCEPTION This raises a noncontinuable software exception (expected result 1597 * is the same as in \ref CR_SEH_EXCEPTION). 1598 * - \ref CR_THROW This throws a C++ typed exception (expected result is the same as in \ref CR_CPP_TERMINATE_CALL). 1599 * - \ref CR_STACK_OVERFLOW This causes stack overflow. 1600 * 1601 * The \ref CR_SEH_EXCEPTION uses null pointer write operation to cause the access violation. 1602 * 1603 * The \ref CR_NONCONTINUABLE_EXCEPTION has the same effect as \ref CR_SEH_EXCEPTION, but it uses 1604 * \b RaiseException() WinAPI function to raise noncontinuable software exception. 1605 * 1606 * The following example shows how to use crEmulateCrash() function. 1607 * 1608 * \code 1609 * // emulate null pointer exception (access violation) 1610 * crEmulateCrash(CR_SEH_EXCEPTION); 1611 * \endcode 1612 * 1613 */ 1614 1615 CRASHRPTAPI(int) 1616 crEmulateCrash( 1617 unsigned ExceptionType) throw (...); 1618 1619 1620 1621 /*! \ingroup CrashRptAPI 1622 * \brief Gets the last CrashRpt error message. 1623 * 1624 * \return This function returns length of error message in characters. If output buffer is invalid, returns a negative number. 1625 * 1626 * \param[out] pszBuffer Pointer to the buffer. 1627 * \param[in] uBuffSize Size of buffer in characters. 1628 * 1629 * \remarks 1630 * 1631 * This function gets the last CrashRpt error message. You can use this function 1632 * to retrieve the text status of the last called CrashRpt function. 1633 * 1634 * If buffer is too small for the error message, the message is truncated. 1635 * 1636 * crGetLastErrorMsgW() and crGetLastErrorMsgA() are wide-character and multi-byte character versions 1637 * of crGetLastErrorMsg(). The crGetLastErrorMsg() macro defines character set independent mapping. 1638 * 1639 * The following example shows how to use crGetLastErrorMsg() function. 1640 * 1641 * \code 1642 * 1643 * // .. call some CrashRpt function 1644 * 1645 * // Get the status message 1646 * TCHAR szErrorMsg[256]; 1647 * crGetLastErrorMsg(szErrorMsg, 256); 1648 * \endcode 1649 * 1650 * \sa crGetLastErrorMsgA(), crGetLastErrorMsgW(), crGetLastErrorMsg() 1651 */ 1652 1653 CRASHRPTAPI(int) 1654 crGetLastErrorMsgW( 1655 __out_ecount_z(uBuffSize) LPWSTR pszBuffer, 1656 UINT uBuffSize); 1657 1658 /*! \ingroup CrashRptAPI 1659 * \copydoc crGetLastErrorMsgW() 1660 * 1661 */ 1662 1663 CRASHRPTAPI(int) 1664 crGetLastErrorMsgA( 1665 __out_ecount_z(uBuffSize) LPSTR pszBuffer, 1666 UINT uBuffSize); 1667 1668 /*! \brief Defines character set-independent mapping for crGetLastErrorMsgW() and crGetLastErrorMsgA(). 1669 * \ingroup CrashRptAPI 1670 */ 1671 1672 #ifdef UNICODE 1673 #define crGetLastErrorMsg crGetLastErrorMsgW 1674 #else 1675 #define crGetLastErrorMsg crGetLastErrorMsgA 1676 #endif //UNICODE 1677 1678 1679 //// Helper wrapper classes 1680 1681 #ifndef _CRASHRPT_NO_WRAPPERS 1682 1683 /*! \class CrAutoInstallHelper 1684 * \ingroup CrashRptWrappers 1685 * \brief Installs exception handlers in constructor and uninstalls in destructor. 1686 * \remarks 1687 * Use this class to easily install/uninstall exception handlers in you \b main() 1688 * or \b WinMain() function. 1689 * 1690 * This wrapper class calls crInstall() in its constructor and calls crUninstall() in 1691 * its destructor. 1692 * 1693 * Use CrAutoInstallHelper::m_nInstallStatus member to check the return status of crInstall(). 1694 * 1695 * Example: 1696 * 1697 * \code 1698 * #include <CrashRpt.h> 1699 * 1700 * void main() 1701 * { 1702 * CR_INSTALL_INFO info; 1703 * memset(&info, 0, sizeof(CR_INSTALL_INFO)); 1704 * info.cb = sizeof(CR_INSTALL_INFO); 1705 * info.pszAppName = _T("My App Name"); 1706 * info.pszAppVersion = _T("1.2.3"); 1707 * info.pszEmailSubject = "Error Report from My App v.1.2.3"; 1708 * // The address to send reports by E-mail 1709 * info.pszEmailTo = _T("myname@hotmail.com"); 1710 * // The URL to send reports via HTTP connection 1711 * info.pszUrl = _T("http://myappname.com/utils/crashrpt.php"); 1712 * info.pfnCrashCallback = CrashCallback; 1713 * info.uPriorities[CR_HTTP] = 3; // Try HTTP first 1714 * info.uPriorities[CR_SMTP] = 2; // Try SMTP second 1715 * info.uPriorities[CR_SMAPI] = 1; // Try system email program last 1716 * 1717 * // Install crash reporting 1718 * CrAutoInstallHelper cr_install_helper(&info); 1719 * // Check that installed OK 1720 * assert(cr_install_helper.m_nInstallStatus==0); 1721 * 1722 * // Your code follows here ... 1723 * 1724 * } 1725 * \endcode 1726 */ 1727 1728 class CrAutoInstallHelper 1729 { 1730 public: 1731 1732 //! Installs exception handlers to the caller process CrAutoInstallHelper(__in PCR_INSTALL_INFOA pInfo)1733 CrAutoInstallHelper(__in PCR_INSTALL_INFOA pInfo) 1734 { 1735 m_nInstallStatus = crInstallA(pInfo); 1736 } 1737 1738 //! Installs exception handlers to the caller process CrAutoInstallHelper(__in PCR_INSTALL_INFOW pInfo)1739 CrAutoInstallHelper(__in PCR_INSTALL_INFOW pInfo) 1740 { 1741 m_nInstallStatus = crInstallW(pInfo); 1742 } 1743 1744 //! Uninstalls exception handlers from the caller process ~CrAutoInstallHelper()1745 ~CrAutoInstallHelper() 1746 { 1747 if(m_nInstallStatus==0) 1748 crUninstall(); 1749 } 1750 1751 //! Install status 1752 int m_nInstallStatus; 1753 }; 1754 1755 /*! \class CrThreadAutoInstallHelper 1756 * \ingroup CrashRptWrappers 1757 * \brief Installs (uninstalls) exception handlers for the caller thread in class' constructor (destructor). 1758 * 1759 * \remarks 1760 * 1761 * This wrapper class calls crInstallToCurrentThread2() in its constructor and 1762 * calls crUninstallFromCurrentThread() in its destructor. 1763 * 1764 * Use CrThreadAutoInstallHelper::m_nInstallStatus member to check 1765 * the return status of crInstallToCurrentThread2(). 1766 * 1767 * Example: 1768 * 1769 * \code 1770 * DWORD WINAPI ThreadProc(LPVOID lpParam) 1771 * { 1772 * CrThreadAutoInstallHelper cr_thread_install_helper(); 1773 * assert(cr_thread_install_helper.m_nInstallStatus==0); 1774 * 1775 * // Your code follows here ... 1776 * } 1777 * \endcode 1778 */ 1779 1780 class CrThreadAutoInstallHelper 1781 { 1782 public: 1783 1784 //! Installs exception handlers to the caller thread 1785 CrThreadAutoInstallHelper(DWORD dwFlags=0) 1786 { 1787 m_nInstallStatus = crInstallToCurrentThread2(dwFlags); 1788 } 1789 1790 //! Uninstalls exception handlers from the caller thread ~CrThreadAutoInstallHelper()1791 ~CrThreadAutoInstallHelper() 1792 { 1793 if (m_nInstallStatus == 0) 1794 crUninstallFromCurrentThread(); 1795 } 1796 1797 //! Install status 1798 int m_nInstallStatus; 1799 }; 1800 1801 #endif //!_CRASHRPT_NO_WRAPPERS 1802 1803 #endif //_CRASHRPT_H_ 1804 1805 1806