src/crashrpt/CrashRpt.h

   1 ///////////////////////////////////////////////////////////////////////////////\r
   2 //\r
   3 //  Module: CrashRpt.h\r
   4 //\r
   5 //    Desc: Defines the interface for the CrashRpt.DLL.\r
   6 //\r
   7 // Copyright (c) 2003 Michael Carruth\r
   8 //\r
   9 ///////////////////////////////////////////////////////////////////////////////\r
  10 \r
  11 #ifndef _CRASHRPT_H_\r
  12 #define _CRASHRPT_H_\r
  13 \r
  14 #if _MSC_VER >= 1000\r
  15 #pragma once\r
  16 #endif // _MSC_VER >= 1000\r
  17 \r
  18 #include <windows.h>\r
  19 #include <wtypes.h>     // BSTR\r
  20 \r
  21 // CrashRpt.h\r
  22 #ifdef CRASHRPTAPI\r
  23 \r
  24 // CRASHRPTAPI should be defined in all of the DLL's source files as\r
  25 // #define CRASHRPTAPI extern "C" __declspec(dllexport)\r
  26 \r
  27 #else\r
  28 \r
  29 // This header file is included by an EXE - export\r
  30 #define CRASHRPTAPI extern "C" __declspec(dllimport)\r
  31 \r
  32 #endif\r
  33 \r
  34 // Client crash callback\r
  35 typedef BOOL (CALLBACK *LPGETLOGFILE) (LPVOID lpvState);\r
  36 // Stack trace callback\r
  37 typedef void (*TraceCallbackFunction)(DWORD_PTR address, const char *ImageName,\r
  38                                                                           const char *FunctionName, DWORD_PTR functionDisp,\r
  39                                                                           const char *Filename, DWORD LineNumber, DWORD lineDisp,\r
  40                                                                           void *data);\r
  41 \r
  42 \r
  43 //-----------------------------------------------------------------------------\r
  44 // GetInstance\r
  45 //    Returns the instance (state information) for the current process. Will create\r
  46 //    one if required; does not install.\r
  47 //\r
  48 // Parameters\r
  49 //    none\r
  50 //\r
  51 // Return Values\r
  52 //    If the function succeeds, the return value is a pointer to the underlying\r
  53 //    crash object created.  This state information is required as the first\r
  54 //    parameter to all other crash report functions.\r
  55 //\r
  56 // Remarks\r
  57 //    none\r
  58 //\r
  59 CRASHRPTAPI \r
  60 LPVOID \r
  61 GetInstance();\r
  62 \r
  63 //-----------------------------------------------------------------------------\r
  64 // Install, InstallEx\r
  65 //    Initializes the library and optionally set the client crash callback and\r
  66 //    sets up the email details.\r
  67 //\r
  68 // Parameters\r
  69 //    pfn         Client crash callback\r
  70 //    lpTo        Email address to send crash report\r
  71 //    lpSubject   Subject line to be used with email\r
  72 //\r
  73 // Return Values\r
  74 //   InstallEx:\r
  75 //    If the function succeeds, the return value is a pointer to the underlying\r
  76 //    crash object created.  This state information is required as the first\r
  77 //    parameter to all other crash report functions.\r
  78 //   Install:\r
  79 //    void\r
  80 //\r
  81 // Remarks\r
  82 //    Passing NULL for lpTo will disable the email feature and cause the crash \r
  83 //    report to be saved to disk.\r
  84 //\r
  85 CRASHRPTAPI\r
  86 void\r
  87 Install(\r
  88    IN LPGETLOGFILE pfn OPTIONAL,               // client crash callback\r
  89    IN LPCSTR lpTo OPTIONAL,                    // Email:to\r
  90    IN LPCSTR lpSubject OPTIONAL,               // Email:subject\r
  91    IN BOOL bUseUI OPTIONAL                     // UI or console\r
  92    );\r
  93 CRASHRPTAPI \r
  94 LPVOID \r
  95 InstallEx(\r
  96    IN LPGETLOGFILE pfn OPTIONAL,               // client crash callback\r
  97    IN LPCSTR lpTo OPTIONAL,                    // Email:to\r
  98    IN LPCSTR lpSubject OPTIONAL,               // Email:subject\r
  99    IN BOOL bUseUI OPTIONAL                     // UI or console\r
 100    );\r
 101 \r
 102 //-----------------------------------------------------------------------------\r
 103 // Uninstall, UninstallEx\r
 104 //    Uninstalls the unhandled exception filter set up in Install().\r
 105 //\r
 106 // Parameters\r
 107 //    lpState     State information returned from Install()\r
 108 //\r
 109 // Return Values\r
 110 //    void\r
 111 //\r
 112 // Remarks\r
 113 //    This call is optional.  The crash report library will automatically \r
 114 //    deinitialize when the library is unloaded.  Call this function to\r
 115 //    unhook the exception filter manually.\r
 116 //\r
 117 CRASHRPTAPI void Uninstall();\r
 118 CRASHRPTAPI \r
 119 void \r
 120 UninstallEx(\r
 121    IN LPVOID lpState                            // State from Install()\r
 122    );\r
 123 \r
 124 CRASHRPTAPI void EnableUI();\r
 125 CRASHRPTAPI void DisableUI();\r
 126 //-----------------------------------------------------------------------------\r
 127 // AddFile, AddFileEx\r
 128 //    Adds a file to the crash report.\r
 129 //\r
 130 // Parameters\r
 131 //    lpState     State information returned from Install()\r
 132 //    lpFile      Fully qualified file name\r
 133 //    lpDesc      Description of file, used by details dialog\r
 134 //\r
 135 // Return Values\r
 136 //    void\r
 137 //\r
 138 // Remarks\r
 139 //    This function can be called anytime after Install() to add one or more\r
 140 //    files to the generated crash report. If lpFile and lpDesc exactly match\r
 141 //    a previously added pair, it is not added again.\r
 142 //\r
 143 CRASHRPTAPI\r
 144 void\r
 145 AddFile(\r
 146    IN LPCSTR lpFile,                           // File name\r
 147    IN LPCSTR lpDesc                            // File desc\r
 148    );\r
 149 CRASHRPTAPI \r
 150 void \r
 151 AddFileEx(\r
 152    IN LPVOID lpState,                           // State from Install()\r
 153    IN LPCSTR lpFile,                           // File name\r
 154    IN LPCSTR lpDesc                            // File desc\r
 155    );\r
 156 \r
 157 //-----------------------------------------------------------------------------\r
 158 // RemoveFile\r
 159 //    Removes a file from the crash report.\r
 160 //\r
 161 // Parameters\r
 162 //    lpState     State information returned from Install()\r
 163 //    lpFile      Fully qualified file name\r
 164 //\r
 165 // Return Values\r
 166 //    void\r
 167 //\r
 168 // Remarks\r
 169 //    The filename must exactly match that provided to AddFile.\r
 170 //\r
 171 CRASHRPTAPI\r
 172 void\r
 173 RemoveFile(\r
 174    IN LPCSTR lpFile                            // File name\r
 175    );\r
 176 CRASHRPTAPI \r
 177 void \r
 178 RemoveFileEx(\r
 179    IN LPVOID lpState,                           // State from Install()\r
 180    IN LPCSTR lpFile                            // File name\r
 181    );\r
 182 \r
 183 //-----------------------------------------------------------------------------\r
 184 // AddRegistryHive\r
 185 //    Adds a RegistryHive to the crash report.\r
 186 //\r
 187 // Parameters\r
 188 //    lpState     State information returned from Install()\r
 189 //    lpRegistryHive      Fully qualified RegistryHive name\r
 190 //    lpDesc      Description of RegistryHive, used by details dialog\r
 191 //\r
 192 // Return Values\r
 193 //    void\r
 194 //\r
 195 // Remarks\r
 196 //    This function can be called anytime after Install() to add one or more\r
 197 //    RegistryHives to the generated crash report. If lpRegistryHive and lpDesc exactly match\r
 198 //    a previously added pair, it is not added again.\r
 199 //\r
 200 CRASHRPTAPI\r
 201 void\r
 202 AddRegistryHive(\r
 203    IN LPCSTR lpRegistryHive,                   // RegistryHive name\r
 204    IN LPCSTR lpDesc                            // RegistryHive desc\r
 205    );\r
 206 CRASHRPTAPI \r
 207 void \r
 208 AddRegistryHiveEx(\r
 209    IN LPVOID lpState,                           // State from Install()\r
 210    IN LPCSTR lpRegistryHive,                   // RegistryHive name\r
 211    IN LPCSTR lpDesc                            // RegistryHive desc\r
 212    );\r
 213 \r
 214 //-----------------------------------------------------------------------------\r
 215 // RemoveRegistryHive\r
 216 //    Removes a RegistryHive from the crash report.\r
 217 //\r
 218 // Parameters\r
 219 //    lpState     State information returned from Install()\r
 220 //    lpRegistryHive      Fully qualified RegistryHive name\r
 221 //\r
 222 // Return Values\r
 223 //    void\r
 224 //\r
 225 // Remarks\r
 226 //    The RegistryHive name must exactly match that provided to AddRegistryHive.\r
 227 //\r
 228 CRASHRPTAPI\r
 229 void \r
 230 RemoveRegistryHive(\r
 231    IN LPCSTR lpRegistryHive                    // RegistryHive name\r
 232    );\r
 233 CRASHRPTAPI \r
 234 void \r
 235 RemoveRegistryHiveEx(\r
 236    IN LPVOID lpState,                           // State from Install()\r
 237    IN LPCSTR lpRegistryHive                    // RegistryHive name\r
 238    );\r
 239 \r
 240 //-----------------------------------------------------------------------------\r
 241 // AddEventLog\r
 242 //    Adds an event log to the crash report.\r
 243 //\r
 244 // Parameters\r
 245 //    lpState     State information returned from Install()\r
 246 //    lpEventLog  Event log name ("Application", "Security", "System" or any other known to your system)\r
 247 //    lpDesc      Description of event log, used by details dialog\r
 248 //\r
 249 // Return Values\r
 250 //    void\r
 251 //\r
 252 // Remarks\r
 253 //    This function can be called anytime after Install() to add one or more\r
 254 //    event logs to the generated crash report. If lpEventLog and lpDesc exactly match\r
 255 //    a previously added pair, it is not added again.\r
 256 //\r
 257 CRASHRPTAPI\r
 258 void\r
 259 AddEventLog(\r
 260    IN LPCSTR lpEventLog,                       // Event Log name\r
 261    IN LPCSTR lpDesc                            // Event Log desc\r
 262    );\r
 263 CRASHRPTAPI \r
 264 void \r
 265 AddEventLogEx(\r
 266    IN LPVOID lpState,                           // State from Install()\r
 267    IN LPCSTR lpEventLog,                       // Event Log name\r
 268    IN LPCSTR lpDesc                            // Event Log desc\r
 269    );\r
 270 \r
 271 //-----------------------------------------------------------------------------\r
 272 // RemoveEventLog\r
 273 //    Removes a EventLog from the crash report.\r
 274 //\r
 275 // Parameters\r
 276 //    lpState     State information returned from Install()\r
 277 //    lpEventLog      Fully qualified EventLog name\r
 278 //\r
 279 // Return Values\r
 280 //    void\r
 281 //\r
 282 // Remarks\r
 283 //    The EventLog name must exactly match that provided to AddEventLog.\r
 284 //\r
 285 CRASHRPTAPI\r
 286 void \r
 287 RemoveEventLog(\r
 288    IN LPCSTR lpEventLog                    // EventLog name\r
 289    );\r
 290 CRASHRPTAPI \r
 291 void \r
 292 RemoveEventLogEx(\r
 293    IN LPVOID lpState,                           // State from Install()\r
 294    IN LPCSTR lpEventLog                    // EventLog name\r
 295    );\r
 296 \r
 297 //-----------------------------------------------------------------------------\r
 298 // GenerateErrorReport, GenerateErrorReportEx\r
 299 //    Generates the crash report.\r
 300 //\r
 301 // Parameters\r
 302 //    lpState     State information returned from Install()\r
 303 //    pExInfo     Optional; pointer to an EXCEPTION_POINTERS structure\r
 304 //        message     Optional; message to include in report\r
 305 //\r
 306 // Return Values\r
 307 //    void\r
 308 //\r
 309 // Remarks\r
 310 //    Call this function to manually generate a crash report.\r
 311 //    Note that only GenerateErrorReportEx can be supplied exception information.\r
 312 //    If you are using the basic interfaces and wish to supply exception information,\r
 313 //    use the call GenerateErrorReportEx, supplying GetInstance() for the state\r
 314 //    information.\r
 315 //\r
 316 CRASHRPTAPI\r
 317 void\r
 318 GenerateErrorReport(\r
 319    IN BSTR message OPTIONAL\r
 320    );\r
 321 CRASHRPTAPI \r
 322 void \r
 323 GenerateErrorReportEx(\r
 324    IN LPVOID lpState,\r
 325    IN PEXCEPTION_POINTERS pExInfo OPTIONAL,\r
 326    IN BSTR message OPTIONAL\r
 327    );\r
 328 \r
 329 //-----------------------------------------------------------------------------\r
 330 // StackTrace\r
 331 //    Creates a stack trace.\r
 332 //\r
 333 // Parameters\r
 334 //    numSkip     Number of initial stack frames to skip\r
 335 //    depth       Number of stack frames to process\r
 336 //        pFunction   Optional; function to call for each frame\r
 337 //    pContext    Optional; stack context to trace\r
 338 //\r
 339 // Return Values\r
 340 //    void\r
 341 //\r
 342 // Remarks\r
 343 //    Call this function to manually generate a stack trace. If\r
 344 //    pFunction is not supplied, stack trace frames are output using\r
 345 //    OutputDebugString. Note that this function does not require the\r
 346 //    'lpState'; it can be called even if the crash handler is not\r
 347 //     installed.\r
 348 //\r
 349 CRASHRPTAPI\r
 350 void\r
 351 StackTrace(\r
 352    IN int numSkip,\r
 353    IN int depth OPTIONAL,\r
 354    IN TraceCallbackFunction pFunction OPTIONAL,\r
 355    IN CONTEXT * pContext OPTIONAL,\r
 356    IN LPVOID data OPTIONAL\r
 357    );\r
 358 \r
 359 \r
 360 //-----------------------------------------------------------------------------\r
 361 // The following functions are identical to the above save that they are callable from Visual Basic\r
 362 extern "C"\r
 363 LPVOID\r
 364 __stdcall\r
 365 InstallExVB(\r
 366    IN LPGETLOGFILE pfn OPTIONAL,                // client crash callback\r
 367    IN LPCSTR lpTo OPTIONAL,                    // Email:to\r
 368    IN LPCSTR lpSubject OPTIONAL,               // Email:subject\r
 369    IN BOOL bUseUI OPTIONAL                     // UI or console\r
 370    );\r
 371 \r
 372 \r
 373 extern "C"\r
 374 void\r
 375 __stdcall\r
 376 UninstallExVB(\r
 377    IN LPVOID lpState                            // State from InstallVB()\r
 378    );\r
 379 \r
 380 \r
 381 extern "C"\r
 382 void\r
 383 __stdcall\r
 384 EnableUIVB();\r
 385 \r
 386 extern "C"\r
 387 void\r
 388 __stdcall\r
 389 DisableUIVB();\r
 390 \r
 391 extern "C"\r
 392 void\r
 393 __stdcall\r
 394 AddFileExVB(\r
 395    IN LPVOID lpState,                           // State from InstallVB()\r
 396    IN LPCSTR lpFile,                           // File name\r
 397    IN LPCSTR lpDesc                            // File desc\r
 398    );\r
 399 \r
 400 extern "C"\r
 401 void\r
 402 __stdcall\r
 403 RemoveFileExVB(\r
 404    IN LPVOID lpState,                           // State from InstallVB()\r
 405    IN LPCSTR lpFile                            // File name\r
 406    );\r
 407 \r
 408 extern "C"\r
 409 void\r
 410 __stdcall\r
 411 AddRegistryHiveExVB(\r
 412    IN LPVOID lpState,                           // State from InstallVB()\r
 413    IN LPCSTR lpRegistryHive,                   // RegistryHive name\r
 414    IN LPCSTR lpDesc                            // RegistryHive desc\r
 415    );\r
 416 \r
 417 extern "C"\r
 418 void\r
 419 __stdcall\r
 420 RemoveRegistryHiveExVB(\r
 421    IN LPVOID lpState,                           // State from InstallVB()\r
 422    IN LPCSTR lpRegistryHive                    // RegistryHive name\r
 423    );\r
 424 \r
 425 extern "C"\r
 426 void\r
 427 __stdcall\r
 428 GenerateErrorReportExVB(\r
 429    IN LPVOID lpState,\r
 430    IN PEXCEPTION_POINTERS pExInfo OPTIONAL,\r
 431    IN BSTR message OPTIONAL\r
 432    );\r
 433 \r
 434 extern "C"\r
 435 void\r
 436 __stdcall\r
 437 StackTraceVB(\r
 438    IN int numSkip,\r
 439    IN int depth OPTIONAL,\r
 440    IN TraceCallbackFunction pFunction OPTIONAL,\r
 441    IN CONTEXT * pContext OPTIONAL,\r
 442    IN LPVOID data OPTIONAL\r
 443    );\r
 444 \r
 445 extern "C" void __stdcall InstallVB(IN LPGETLOGFILE pfn OPTIONAL, IN LPCSTR lpTo OPTIONAL, IN LPCSTR lpSubject OPTIONAL, IN BOOL bUseUI OPTIONAL);\r
 446 extern "C" void __stdcall UninstallVB();\r
 447 extern "C" void __stdcall AddFileVB(LPCSTR file, LPCSTR desc);\r
 448 extern "C" void __stdcall RemoveFileVB(LPCSTR file);\r
 449 extern "C" void __stdcall AddRegistryHiveVB(LPCSTR RegistryHive, LPCSTR desc);\r
 450 extern "C" void __stdcall RemoveRegistryHiveVB(LPCSTR RegistryHive);\r
 451 extern "C" void __stdcall GenerateErrorReportVB(BSTR message);\r
 452 \r
 453 #endif\r