src/crashrpt/CrashRpt.h

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