src/crashrpt/CrashRptDL.h

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