src/crashrpt/CrashHandler.h

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