src/crashrpt/CrashRptDL.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 //
   3 //  Module: CrashRptDL.h
   4 //
   5 //    Desc: Defines the interface for the CrashRpt.DLL, using a dynamically
   6 //          loaded instance of the library. Can be used when CrashRpt.dll may
   7 //          not be present on the system.
   8 //
   9 //          Note that all functions except GetInstanceDL() and
  10 //          ReleaseInstanceDL() return an integer, which is non-zero ('true')
  11 //          when the real DLL function was located and called. This does not
  12 //          mean the actual DLL function succeeded, however.
  13 //
  14 //          Please don't get confused by the macro usage; all functions do end
  15 //          in DL, even though the name supplied to CRASHRPT_DECLARE does not.
  16 //
  17 // Copyright (c) 2003 Michael Carruth
  18 // Copyright (c) 2003 Grant McDorman
  19 //  This software is provided 'as-is', without any express or implied
  20 //  warranty.  In no event will the authors be held liable for any damages
  21 //  arising from the use of this software.
  22 //
  23 //  Permission is granted to anyone to use this software for any purpose,
  24 //  including commercial applications, and to alter it and redistribute it
  25 //  freely, subject to the following restrictions:
  26 //
  27 //  1. The origin of this software must not be misrepresented; you must not
  28 //     claim that you wrote the original software. If you use this software
  29 //     in a product, an acknowledgment in the product documentation would be
  30 //     appreciated but is not required.
  31 //  2. Altered source versions must be plainly marked as such, and must not be
  32 //     misrepresented as being the original software.
  33 //  3. This notice may not be removed or altered from any source distribution.
  34 //
  35 ///////////////////////////////////////////////////////////////////////////////
  36
  37 #ifndef _CRASHRPT_H_
  38 #define _CRASHRPT_H_
  39
  40 #if _MSC_VER >= 1000
  41 #pragma once
  42 #endif // _MSC_VER >= 1000
  43
  44 #include <windows.h>
  45 #include <wtypes.h>     // BSTR
  46
  47 // Client crash callback
  48 typedef BOOL (CALLBACK *LPGETLOGFILE) (LPVOID lpvState);
  49 // Stack trace callback
  50 typedef void (*TraceCallbackFunction)(DWORD address, const char *ImageName,
  51                                                                           const char *FunctionName, DWORD functionDisp,
  52                                                                           const char *Filename, DWORD LineNumber, DWORD lineDisp,
  53                                                                           void *data);
  54
  55 // macro to create the inline forwarding function
  56 #define CRASHRPT_DECLARE(function, declare1, declare2, arguments) \
  57  __inline int function##DL declare1 \
  58  { \
  59          typedef void (*function##_t) declare2; \
  60          function##_t p##function; \
  61          p##function = (function##_t) GetProcAddress(hModule, #function); \
  62          if (p##function != NULL) { \
  63                  p##function arguments; \
  64                  return 1; \
  65          } \
  66          return 0; \
  67  }
  68
  69
  70
  71 //-----------------------------------------------------------------------------
  72 // GetInstanceDL
  73 //    Returns the instance (module handle) for the CrashRpt DLL.
  74 //
  75 // Parameters
  76 //    none
  77 //
  78 // Return Values
  79 //    If the function succeeds, the return value is a module handle for the CrashRpt
  80 //    shared library (CrashRpt.dll). This handle is required for all the other functions.
  81 //
  82 // Remarks
  83 //    none
  84 //
  85 __inline
  86 HMODULE
  87 GetInstanceDL()
  88 {
  89         return LoadLibrary("CrashRpt");
  90 }
  91
  92 //-----------------------------------------------------------------------------
  93 // InstallDL
  94 //    Initializes the library and optionally set the client crash callback and
  95 //    sets up the email details.
  96 //
  97 // Parameters
  98 //    hModule     State information returned from GetInstanceDL() (must not be NULL)
  99 //    pfn         Client crash callback
 100 //    lpTo        Email address to send crash report
 101 //    lpSubject   Subject line to be used with email
 102 //
 103 // Return Values
 104 //    non-zero if successful
 105 //
 106 // Remarks
 107 //    Passing NULL for lpTo will disable the email feature and cause the crash
 108 //    report to be saved to disk.
 109 //
 110 CRASHRPT_DECLARE(Install, (IN HMODULE hModule, IN LPGETLOGFILE pfn, IN LPCTSTR lpTo OPTIONAL, IN LPCTSTR lpSubject OPTIONAL),  \
 111                             (LPGETLOGFILE pfn, LPCTSTR lpTo, LPCTSTR lpSubject),  \
 112                             (pfn, lpTo, lpSubject))
 113
 114 //-----------------------------------------------------------------------------
 115 // UninstallDL
 116 //    Uninstalls the unhandled exception filter set up in InstallDL().
 117 //
 118 // Parameters
 119 //    hModule     Module handle returned from GetInstanceDL()
 120 //
 121 // Return Values
 122 //    non-zero if successful
 123 //
 124 // Remarks
 125 //    This call is optional.  The crash report library will automatically
 126 //    deinitialize when the library is unloaded.  Call this function to
 127 //    unhook the exception filter manually.
 128 //
 129 CRASHRPT_DECLARE(Uninstall, (IN HMODULE hModule),  \
 130                             (), \
 131                                                         ())
 132 //-----------------------------------------------------------------------------
 133 // ReleaseInstanceDL
 134 //    Releases the library.
 135 //
 136 // Parameters
 137 //    hModule     Module handle returned from GetInstanceDL()
 138 //
 139 // Return Values
 140 //    void
 141 //
 142 // Remarks
 143 //    This will call UninstallDL before releasing the library.
 144 //
 145 __inline
 146 void
 147 ReleaseInstanceDL(IN HMODULE hModule)
 148 {
 149         UninstallDL(hModule);
 150         FreeLibrary(hModule);
 151 }
 152
 153 //-----------------------------------------------------------------------------
 154 // AddFileDL
 155 //    Adds a file to the crash report.
 156 //
 157 // Parameters
 158 //    hModule     Module handle returned from GetInstanceDL()
 159 //    lpFile      Fully qualified file name
 160 //    lpDesc      Description of file, used by details dialog
 161 //
 162 // Return Values
 163 //    non-zero if successful
 164 //
 165 // Remarks
 166 //    This function can be called anytime after Install() to add one or more
 167 //    files to the generated crash report. If lpFile exactly matches
 168 //    a previously added file, it is not added again.
 169 //
 170 CRASHRPT_DECLARE(AddFile, (IN HMODULE hModule, IN LPCTSTR lpFile, IN LPCTSTR lpDesc),  \
 171                             (LPCTSTR lpFile, LPCTSTR lpDesc),  \
 172                             (lpFile, lpDesc))
 173
 174 //-----------------------------------------------------------------------------
 175 // RemoveFileDL
 176 //    Removes a file from the crash report.
 177 //
 178 // Parameters
 179 //    hModule     Module handle returned from GetInstanceDL()
 180 //    lpFile      Fully qualified file name
 181 //
 182 // Return Values
 183 //    non-zero if successful
 184 //
 185 // Remarks
 186 //    The filename must exactly match that provided to AddFile.
 187 //
 188 CRASHRPT_DECLARE(RemoveFile, (IN HMODULE hModule, IN LPCTSTR lpFile),  \
 189                             (LPCTSTR lpFile),  \
 190                             (lpFile))
 191
 192 //-----------------------------------------------------------------------------
 193 // AddRegistryHiveDL
 194 //    Adds a RegistryHive to the crash report.
 195 //
 196 // Parameters
 197 //    hModule     Module handle returned from GetInstanceDL()
 198 //    lpRegistryHive      Fully qualified RegistryHive name
 199 //    lpDesc      Description of RegistryHive, used by details dialog
 200 //
 201 // Return Values
 202 //    non-zero if successful
 203 //
 204 // Remarks
 205 //    This function can be called anytime after Install() to add one or more
 206 //    RegistryHives to the generated crash report. If lpRegistryHive exactly matches
 207 //    a previously added file, it is not added again.
 208 //
 209 CRASHRPT_DECLARE(AddRegistryHive, (IN HMODULE hModule, IN LPCTSTR lpRegistryHive, IN LPCTSTR lpDesc),  \
 210                             (LPCTSTR lpRegistryHive, LPCTSTR lpDesc),  \
 211                             (lpRegistryHive, lpDesc))
 212
 213 //-----------------------------------------------------------------------------
 214 // RemoveRegistryHiveDL
 215 //    Removes a RegistryHive from the crash report.
 216 //
 217 // Parameters
 218 //    hModule     Module handle returned from GetInstanceDL()
 219 //    lpRegistryHive      Fully qualified RegistryHive name
 220 //
 221 // Return Values
 222 //    non-zero if successful
 223 //
 224 // Remarks
 225 //    The RegistryHive name must exactly match that provided to AddRegistryHive.
 226 //
 227 CRASHRPT_DECLARE(RemoveRegistryHive, (IN HMODULE hModule, IN LPCTSTR lpRegistryHive),  \
 228                             (LPCTSTR lpRegistryHive),  \
 229                             (lpRegistryHive))
 230
 231 //-----------------------------------------------------------------------------
 232 // AddEventLogDL
 233 //    Adds an event log to the crash report.
 234 //
 235 // Parameters
 236 //    hModule     Module handle returned from GetInstanceDL()
 237 //    lpEventLog  Event log name ("Application", "Security", "System" or any other known to your system)
 238 //    lpDesc      Description of event log, used by details dialog
 239 //
 240 // Return Values
 241 //    non-zero if successful
 242 //
 243 // Remarks
 244 //    This function can be called anytime after Install() to add one or more
 245 //    event logs to the generated crash report. If lpEventLog exactly matches
 246 //    a previously added file, it is not added again.
 247 //
 248 CRASHRPT_DECLARE(AddEventLog, (IN HMODULE hModule, IN LPCTSTR lpEventLog, IN LPCTSTR lpDesc),  \
 249                             (LPCTSTR lpEventLog, LPCTSTR lpDesc),  \
 250                             (lpEventLog, lpDesc))
 251
 252 //-----------------------------------------------------------------------------
 253 // RemoveEventLogDL
 254 //    Removes a EventLog from the crash report.
 255 //
 256 // Parameters
 257 //    hModule     Module handle returned from GetInstanceDL()
 258 //    lpEventLog      Fully qualified EventLog name
 259 //
 260 // Return Values
 261 //    non-zero if successful
 262 //
 263 // Remarks
 264 //    The EventLog name must exactly match that provided to AddEventLog.
 265 //
 266 CRASHRPT_DECLARE(RemoveEventLog, (IN HMODULE hModule, IN LPCTSTR lpEventLog),  \
 267                             (LPCTSTR lpEventLog),  \
 268                             (lpEventLog))
 269
 270 //-----------------------------------------------------------------------------
 271 // GenerateErrorReportDL
 272 //    Generates the crash report.
 273 //
 274 // Parameters
 275 //    hModule     Module handle returned from GetInstanceDL()
 276 //    pExInfo     Optional; exception information
 277 //        message     Optional; message to include in report
 278 //
 279 // Return Values
 280 //    non-zero if successful
 281 //
 282 // Remarks
 283 //    Call this function to manually generate a crash report.
 284 //
 285 __inline
 286 int
 287 GenerateErrorReportDL(
 288    IN HMODULE hModule,
 289    IN PEXCEPTION_POINTERS pExInfo OPTIONAL,
 290    IN BSTR message OPTIONAL
 291    )
 292 {
 293         // we can't use GenerateErrorReport(), because that is lacking the PEXCEPTION_POINTERS parameter
 294         LPVOID instance;
 295     typedef LPVOID (*GetInstance_t) ();
 296     GetInstance_t pGetInstance;
 297     pGetInstance = (GetInstance_t) GetProcAddress(hModule, "GetInstance");
 298     if (pGetInstance != NULL) {
 299                 typedef void (*GenerateErrorReportEx_t)(LPVOID lpState, PEXCEPTION_POINTERS pExInfo, BSTR message);
 300                 GenerateErrorReportEx_t pGenerateErrorReportEx;
 301
 302                 instance = pGetInstance();
 303                 pGenerateErrorReportEx = (GenerateErrorReportEx_t) GetProcAddress(hModule, "GenerateErrorReportEx");
 304                 if (pGenerateErrorReportEx != NULL) {
 305                         pGenerateErrorReportEx(instance, pExInfo, message);
 306                         return 1;
 307                 }
 308     }
 309     return 0;
 310 }
 311
 312
 313 //-----------------------------------------------------------------------------
 314 // StackTraceDL
 315 //    Creates a stack trace.
 316 //
 317 // Parameters
 318 //    hModule     Module handle returned from GetInstanceDL()
 319 //    numSkip     Number of initial stack frames to skip
 320 //    depth       Number of stack frames to process
 321 //        pFunction   Optional; function to call for each frame
 322 //    pContext    Optional; stack context to trace
 323 //
 324 // Return Values
 325 //    void
 326 //
 327 // Remarks
 328 //    Call this function to manually generate a stack trace. If
 329 //    pFunction is not supplied, stack trace frames are output using
 330 //    OutputDebugString. Can be called without installing (InstallDL)
 331 //    CrashRpt.
 332 //
 333 CRASHRPT_DECLARE(StackTrace, (IN HMODULE hModule, IN int numSkip, IN int depth, IN TraceCallbackFunction pFunction OPTIONAL, IN CONTEXT * pContext OPTIONAL, IN LPVOID data OPTIONAL),  \
 334                             (int numSkip, int depth, TraceCallbackFunction pFunction, CONTEXT * pContext, LPVOID data),  \
 335                             (numSkip, depth, pFunction, pContext, data))
 336
 337 #undef CRASHRPT_DECLARE
 338
 339 #endif