src/crashrpt/CrashHandler.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 //
   3 //  Module: CrashHandler.h
   4 //
   5 //    Desc: CCrashHandler is the main class used by crashrpt to manage all
   6 //          of the details associated with handling the exception, generating
   7 //          the report, gathering client input, and sending the report.
   8 //
   9 // Copyright (c) 2003 Michael Carruth
  10 //
  11 ///////////////////////////////////////////////////////////////////////////////
  12
  13 #pragma once
  14
  15 #include "crashrpt.h"      // defines LPGETLOGFILE callback
  16 #include "excprpt.h"       // bulk of crash report generation
  17
  18 #ifndef TStrStrVector
  19 #include <vector>
  20
  21 typedef std::pair<string,string> TStrStrPair;
  22 typedef std::vector<TStrStrPair> TStrStrVector;
  23 #endif // !defined TStrStrVector
  24
  25
  26 extern BOOL g_bNoCrashHandler;// don't use the crash handler but let the system handle it
  27
  28 ////////////////////////////// Class Definitions /////////////////////////////
  29
  30 // ===========================================================================
  31 // CCrashHandler
  32 //
  33 // See the module comment at top of file.
  34 //
  35 class CCrashHandler
  36 {
  37 public:
  38
  39    //-----------------------------------------------------------------------------
  40    // GetInstance (static)
  41    //    Returns the instance for the current process. Creates one if necessary.
  42    //
  43    // Parameters
  44    //    none
  45    //
  46    // Return Values
  47    //    none
  48    //
  49    // Remarks
  50    //    none
  51    //
  52    static CCrashHandler * GetInstance();
  53
  54
  55    //-----------------------------------------------------------------------------
  56    // Install
  57    //    Installs the crash handler..
  58    //
  59    // Parameters
  60    //    lpfn        Client crash callback
  61    //    lpcszTo     Email address to send crash report
  62    //    lpczSubject Subject line to be used with email
  63    //
  64    // Return Values
  65    //    none
  66    //
  67    // Remarks
  68    //    Passing NULL for lpTo will disable the email feature and cause the crash
  69    //    report to be saved to disk.
  70    //
  71    void Install(
  72       LPGETLOGFILE lpfn = NULL,           // Client crash callback
  73       LPCTSTR lpcszTo = NULL,             // EMail:To
  74       LPCTSTR lpcszSubject = NULL,        // EMail:Subject
  75       BOOL bUseUI = TRUE
  76       );
  77
  78    //-----------------------------------------------------------------------------
  79    // Unnstall
  80    //    Removes the crash handler..
  81    //
  82    // Parameters
  83    //    none
  84    //
  85    // Return Values
  86    //    none
  87    //
  88    // Remarks
  89    //    none
  90    //
  91    void Uninstall();
  92
  93    //-----------------------------------------------------------------------------
  94    // EnableUI
  95    //    Enables the UI part
  96    //
  97    // Parameters
  98    //    none
  99    //
 100    // Return Values
 101    //    none
 102    //
 103    // Remarks
 104    //    none
 105    //
 106    void EnableUI();
 107
 108    //-----------------------------------------------------------------------------
 109    // DisableUI
 110    //    Disables the UI part
 111    //
 112    // Parameters
 113    //    none
 114    //
 115    // Return Values
 116    //    none
 117    //
 118    // Remarks
 119    //    none
 120    //
 121    void DisableUI();
 122
 123    //-----------------------------------------------------------------------------
 124    // DisableUI
 125    //    Disables the exception handler
 126    //
 127    // Parameters
 128    //    none
 129    //
 130    // Return Values
 131    //    none
 132    //
 133    // Remarks
 134    //    none
 135    //
 136    void DisableHandler();
 137
 138    //-----------------------------------------------------------------------------
 139    // DisableUI
 140    //    Enables the custom exception handler
 141    //
 142    // Parameters
 143    //    none
 144    //
 145    // Return Values
 146    //    none
 147    //
 148    // Remarks
 149    //    none
 150    //
 151    void EnableHandler();
 152
 153    //-----------------------------------------------------------------------------
 154    // ~CCrashHandler
 155    //    Uninitializes the crashrpt library.
 156    //
 157    // Parameters
 158    //    none
 159    //
 160    // Return Values
 161    //    none
 162    //
 163    // Remarks
 164    //    none
 165    //
 166    virtual
 167    ~CCrashHandler();
 168
 169    //-----------------------------------------------------------------------------
 170    // AddFile
 171    //    Adds a file to the crash report.
 172    //
 173    // Parameters
 174    //    lpFile      Fully qualified file name
 175    //    lpDesc      File description
 176    //
 177    // Return Values
 178    //    none
 179    //
 180    // Remarks
 181    //    Call this function to include application specific file(s) in the crash
 182    //    report.  For example, application logs, initialization files, etc.
 183    //
 184    void
 185    AddFile(
 186       LPCTSTR lpFile,                     // File nae
 187       LPCTSTR lpDesc                      // File description
 188       );
 189
 190    //-----------------------------------------------------------------------------
 191    // RemoveFile
 192    //    Removes a file from the crash report.
 193    //
 194    // Parameters
 195    //    lpFile      Fully qualified file name
 196    //
 197    // Return Values
 198    //    none
 199    //
 200    // Remarks
 201    //    lpFile must exactly match that passed to AddFile.
 202    //
 203    void
 204    RemoveFile(
 205       LPCTSTR lpFile                      // File nae
 206       );
 207
 208    //-----------------------------------------------------------------------------
 209    // AddRegistryHive
 210    //    Adds a registry hive to the crash report.
 211    //
 212    // Parameters
 213    //    lpKey       Fully registry eky
 214    //    lpDesc      Description
 215    //
 216    // Return Values
 217    //    none
 218    //
 219    // Remarks
 220    //    Call this function to include application specific registry hive(s) in the crash
 221    //    report.
 222    //
 223    void
 224    AddRegistryHive(
 225       LPCTSTR lpKey,                      // Registry key
 226       LPCTSTR lpDesc                      // description
 227       );
 228
 229    //-----------------------------------------------------------------------------
 230    // RemoveRegistryHive
 231    //    Removes a registry hive from the crash report.
 232    //
 233    // Parameters
 234    //    lpKey       Full registry key
 235    //
 236    // Return Values
 237    //    none
 238    //
 239    // Remarks
 240    //    lpKey must exactly match that passed to AddRegistryHive.
 241    //
 242    void
 243    RemoveRegistryHive(
 244       LPCTSTR lpKey                       // Registry key
 245       );
 246
 247    //-----------------------------------------------------------------------------
 248    // AddEventLog
 249    //    Adds an event log to the crash report.
 250    //
 251    // Parameters
 252    //    lpKey       Event log name ("Application", "System", "Security")
 253    //    lpDesc      Description
 254    //
 255    // Return Values
 256    //    none
 257    //
 258    // Remarks
 259    //    Call this function to include application specific registry hive(s) in the crash
 260    //    report.
 261    //
 262    void
 263    AddEventLog(
 264       LPCTSTR lpKey,                      // Event log name
 265       LPCTSTR lpDesc                      // description
 266       );
 267
 268    //-----------------------------------------------------------------------------
 269    // RemoveEventLog
 270    //    Removes an event log from the crash report.
 271    //
 272    // Parameters
 273    //    lpKey       Event log name
 274    //
 275    // Return Values
 276    //    none
 277    //
 278    // Remarks
 279    //    lpKey must exactly match that passed to AddEventLog.
 280    //
 281    void
 282    RemoveEventLog(
 283       LPCTSTR lpKey                       // Registry key
 284       );
 285
 286    //-----------------------------------------------------------------------------
 287    // GenerateErrorReport
 288    //    Produces a crash report.
 289    //
 290    // Parameters
 291    //    pExInfo     Pointer to an EXCEPTION_POINTERS structure
 292    //
 293    // Return Values
 294    //    BOOL        TRUE if exception to be executed; FALSE
 295    //                if to search for another handler. This
 296    //                should be used to allow breaking into
 297    //                the debugger, where appropriate.
 298    //
 299    // Remarks
 300    //    Call this function to manually generate a crash report.
 301    //
 302    BOOL
 303    GenerateErrorReport(
 304       PEXCEPTION_POINTERS pExInfo,         // Exception pointers (see MSDN)
 305           BSTR message = NULL
 306       );
 307
 308
 309 protected:
 310
 311    //-----------------------------------------------------------------------------
 312    // CCrashHandler
 313    //    Initializes the library and optionally set the client crash callback and
 314    //    sets up the email details.
 315    //
 316    // Parameters
 317    //    none
 318    //
 319    // Return Values
 320    //    none
 321    //
 322    // Remarks
 323    //    Passing NULL for lpTo will disable the email feature and cause the crash
 324    //    report to be saved to disk.
 325    //
 326    CCrashHandler(
 327       );
 328
 329    //-----------------------------------------------------------------------------
 330    // SaveReport
 331    //    Presents the user with a file save dialog and saves the crash report
 332    //    file to disk.  This function is called if an Email:To was not provided
 333    //    in the constructor.
 334    //
 335    // Parameters
 336    //    rpt         The report details
 337    //    lpcszFile   The zipped crash report
 338    //
 339    // Return Values
 340    //    True is successful.
 341    //
 342    // Remarks
 343    //    none
 344    //
 345    BOOL
 346    SaveReport(
 347       CExceptionReport &rpt,
 348       LPCTSTR lpcszFile
 349       );
 350
 351    //-----------------------------------------------------------------------------
 352    // MailReport
 353    //    Mails the zipped crash report to the address specified.
 354    //
 355    // Parameters
 356    //    rpt         The report details
 357    //    lpcszFile   The zipped crash report
 358    //    lpcszEmail  The Email:To
 359    //    lpcszDesc
 360    //
 361    // Return Values
 362    //    TRUE is successful.
 363    //
 364    // Remarks
 365    //    MAPI is used to send the report.
 366    //
 367    BOOL
 368    MailReport(
 369       CExceptionReport &rpt,
 370       LPCTSTR lpcszFile,
 371       LPCTSTR lpcszEmail,
 372       LPCTSTR lpcszSubject
 373       );
 374
 375    //-----------------------------------------------------------------------------
 376    // DialogThreadExecute
 377    //    Displays the dialog and handles the user's reply. Executed as a separate
 378    //    thread.
 379    //
 380    // Parameters
 381    //    pParam      Standard CreateThreadParameter; set to pointer to CCrashHandler
 382    //
 383    // Return Values
 384    //    none
 385    //
 386    // Remarks
 387    //    Started from GenerateErrorReport via CreateThread. This ensures the caller
 388    //    is stopped (and will not confuse state by dispatching messages).
 389    //
 390    static DWORD WINAPI CCrashHandler::DialogThreadExecute(LPVOID pParam);
 391
 392    string LoadResourceString(UINT id);
 393    LPTOP_LEVEL_EXCEPTION_FILTER  m_oldFilter;      // previous exception filter
 394    LPGETLOGFILE                  m_lpfnCallback;   // client crash callback
 395    int                           m_pid;            // process id
 396    TStrStrVector                 m_files;          // custom files to add
 397    TStrStrVector                                 m_registryHives;  // custom registry hives to save
 398    TStrStrVector                                 m_eventLogs;      // custom event logs to save
 399    string                                                m_sTo;            // Email:To
 400    string                        m_sSubject;       // Email:Subject
 401    HANDLE                        m_ipc_event;      // Event for dialog thread synchronization
 402    CExceptionReport              *m_rpt;            // Exception report for dialog
 403    bool                          m_installed;      // True if already installed
 404    HMODULE                       m_hModule;        // Module handle for loading resource strings
 405    string                                                m_userDataFile;   // file to save user input when m_sTo is empty
 406    bool                          m_wantDebug;      // user pushed Debug button
 407    BOOL                                                  m_bUseUI;                 // use an UI or print to the error output
 408 };
 409