1 ///////////////////////////////////////////////////////////////////////////////
\r
3 // Module: CrashRptDL.h
\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
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
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
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
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
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
35 ///////////////////////////////////////////////////////////////////////////////
\r
37 #ifndef _CRASHRPT_H_
\r
38 #define _CRASHRPT_H_
\r
40 #if _MSC_VER >= 1000
\r
42 #endif // _MSC_VER >= 1000
\r
44 #include <windows.h>
\r
45 #include <wtypes.h> // BSTR
\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
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
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
71 //-----------------------------------------------------------------------------
\r
73 // Returns the instance (module handle) for the CrashRpt DLL.
\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
89 return LoadLibrary("CrashRpt");
\r
92 //-----------------------------------------------------------------------------
\r
94 // Initializes the library and optionally set the client crash callback and
\r
95 // sets up the email details.
\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
104 // non-zero if successful
\r
107 // Passing NULL for lpTo will disable the email feature and cause the crash
\r
108 // report to be saved to disk.
\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
114 //-----------------------------------------------------------------------------
\r
116 // Uninstalls the unhandled exception filter set up in InstallDL().
\r
119 // hModule Module handle returned from GetInstanceDL()
\r
122 // non-zero if successful
\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
129 CRASHRPT_DECLARE(Uninstall, (IN HMODULE hModule), \
\r
132 //-----------------------------------------------------------------------------
\r
133 // ReleaseInstanceDL
\r
134 // Releases the library.
\r
137 // hModule Module handle returned from GetInstanceDL()
\r
143 // This will call UninstallDL before releasing the library.
\r
147 ReleaseInstanceDL(IN HMODULE hModule)
\r
149 UninstallDL(hModule);
\r
150 FreeLibrary(hModule);
\r
153 //-----------------------------------------------------------------------------
\r
155 // Adds a file to the crash report.
\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
163 // non-zero if successful
\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
170 CRASHRPT_DECLARE(AddFile, (IN HMODULE hModule, IN LPCTSTR lpFile, IN LPCTSTR lpDesc), \
\r
171 (LPCTSTR lpFile, LPCTSTR lpDesc), \
\r
174 //-----------------------------------------------------------------------------
\r
176 // Removes a file from the crash report.
\r
179 // hModule Module handle returned from GetInstanceDL()
\r
180 // lpFile Fully qualified file name
\r
183 // non-zero if successful
\r
186 // The filename must exactly match that provided to AddFile.
\r
188 CRASHRPT_DECLARE(RemoveFile, (IN HMODULE hModule, IN LPCTSTR lpFile), \
\r
189 (LPCTSTR lpFile), \
\r
192 //-----------------------------------------------------------------------------
\r
193 // AddRegistryHiveDL
\r
194 // Adds a RegistryHive to the crash report.
\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
202 // non-zero if successful
\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
209 CRASHRPT_DECLARE(AddRegistryHive, (IN HMODULE hModule, IN LPCTSTR lpRegistryHive, IN LPCTSTR lpDesc), \
\r
210 (LPCTSTR lpRegistryHive, LPCTSTR lpDesc), \
\r
211 (lpRegistryHive, lpDesc))
\r
213 //-----------------------------------------------------------------------------
\r
214 // RemoveRegistryHiveDL
\r
215 // Removes a RegistryHive from the crash report.
\r
218 // hModule Module handle returned from GetInstanceDL()
\r
219 // lpRegistryHive Fully qualified RegistryHive name
\r
222 // non-zero if successful
\r
225 // The RegistryHive name must exactly match that provided to AddRegistryHive.
\r
227 CRASHRPT_DECLARE(RemoveRegistryHive, (IN HMODULE hModule, IN LPCTSTR lpRegistryHive), \
\r
228 (LPCTSTR lpRegistryHive), \
\r
231 //-----------------------------------------------------------------------------
\r
233 // Adds an event log to the crash report.
\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
241 // non-zero if successful
\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
248 CRASHRPT_DECLARE(AddEventLog, (IN HMODULE hModule, IN LPCTSTR lpEventLog, IN LPCTSTR lpDesc), \
\r
249 (LPCTSTR lpEventLog, LPCTSTR lpDesc), \
\r
250 (lpEventLog, lpDesc))
\r
252 //-----------------------------------------------------------------------------
\r
253 // RemoveEventLogDL
\r
254 // Removes a EventLog from the crash report.
\r
257 // hModule Module handle returned from GetInstanceDL()
\r
258 // lpEventLog Fully qualified EventLog name
\r
261 // non-zero if successful
\r
264 // The EventLog name must exactly match that provided to AddEventLog.
\r
266 CRASHRPT_DECLARE(RemoveEventLog, (IN HMODULE hModule, IN LPCTSTR lpEventLog), \
\r
267 (LPCTSTR lpEventLog), \
\r
270 //-----------------------------------------------------------------------------
\r
271 // GenerateErrorReportDL
\r
272 // Generates the crash report.
\r
275 // hModule Module handle returned from GetInstanceDL()
\r
276 // pExInfo Optional; exception information
\r
277 // message Optional; message to include in report
\r
280 // non-zero if successful
\r
283 // Call this function to manually generate a crash report.
\r
287 GenerateErrorReportDL(
\r
288 IN HMODULE hModule,
\r
289 IN PEXCEPTION_POINTERS pExInfo OPTIONAL,
\r
290 IN BSTR message OPTIONAL
\r
293 // we can't use GenerateErrorReport(), because that is lacking the PEXCEPTION_POINTERS parameter
\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
302 instance = pGetInstance();
\r
303 pGenerateErrorReportEx = (GenerateErrorReportEx_t) GetProcAddress(hModule, "GenerateErrorReportEx");
\r
304 if (pGenerateErrorReportEx != NULL) {
\r
305 pGenerateErrorReportEx(instance, pExInfo, message);
\r
313 //-----------------------------------------------------------------------------
\r
315 // Creates a stack trace.
\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
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
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
337 #undef CRASHRPT_DECLARE
\r