PageRenderTime 34ms CodeModel.GetById 21ms app.highlight 9ms RepoModel.GetById 1ms app.codeStats 0ms

/include/CrashRptProbe.h

http://crashrpt.googlecode.com/
C++ Header | 470 lines | 171 code | 49 blank | 250 comment | 0 complexity | 686414786c7034ae7d272c2ebf23eb4a MD5 | raw file
  1/************************************************************************************* 
  2This file is a part of CrashRpt library.
  3Copyright (c) 2003-2013 The CrashRpt project authors. All Rights Reserved.
  4
  5Use of this source code is governed by a BSD-style license
  6that can be found in the License.txt file in the root of the source
  7tree. All contributing project authors may
  8be found in the Authors.txt file in the root of the source tree.
  9***************************************************************************************/
 10
 11/*! \file   CrashRptProbe.h
 12*  \brief  Defines the interface for the CrashRptProbe.DLL.
 13*  \date   2009-2011
 14*  \author zexspectrum
 15*/
 16
 17#ifndef __CRASHRPT_PROBE_H__
 18#define __CRASHRPT_PROBE_H__
 19
 20#ifdef __cplusplus
 21#define CRASHRPTPROBE_EXTERNC extern "C"
 22#else
 23#define CRASHRPTPROBE_EXTERNC
 24#endif
 25
 26// Define SAL macros to be empty if some old Visual Studio used
 27#ifndef __reserved
 28#define __reserved
 29#endif
 30#ifndef __in
 31#define __in
 32#endif
 33#ifndef __in_opt
 34#define __in_opt
 35#endif
 36#ifndef __out
 37#define __out
 38#endif
 39#ifndef __out_ecount
 40#define __out_ecount(x)
 41#endif
 42#ifndef __out_ecount_z
 43#define __out_ecount_z(x)
 44#endif
 45
 46#define CRASHRPTPROBE_API(rettype) CRASHRPTPROBE_EXTERNC rettype WINAPI
 47
 48//! Handle to an opened error report.
 49typedef int CrpHandle;
 50
 51/*! \defgroup CrashRptProbeAPI CrashRptProbe Functions*/
 52
 53/*! \ingroup CrashRptProbeAPI
 54*  \brief Opens a zipped crash report file.
 55*
 56*  \return This function returns zero on success. 
 57*
 58*  \param[in] pszFileName Zipped report file name.
 59*  \param[in] pszMd5Hash String containing MD5 hash for the ZIP file data.
 60*  \param[in] pszSymSearchPath Symbol files (PDB) search path.
 61*  \param[in] dwFlags Flags, reserved for future use.
 62*  \param[out] phReport Handle to the opened crash report.
 63*
 64*  \remarks
 65*
 66*  Use this function to open a ZIP archive containing an error report. The error report typically contains
 67*  several compressed files, such as XML crash description file, crash minidump file, and (optionally) 
 68*  application-defined files.
 69*
 70*  \a pszFileName should be the name of the error report (ZIP file) to open. Absolute or relative path accepted.
 71*  This parameter is required.
 72*
 73*  \a pszMd5Hash is a string containing the MD5 hash calculated for \a pszFileName. The MD5
 74*  hash is a sequence of 16 characters being used for integrity checks. 
 75*  If this parameter is NULL, integrity check is not performed.
 76*
 77*  If the error report is delivered by HTTP, the MD5 hash can be extracted by server-side script from the
 78*  'md5' parameter. When the error report is delivered by email, the MD5 hash is attached to the mail message.
 79*  The integrity check can be performed to ensure the error report was not corrupted during delivery.
 80*  For more information, see \ref sending_error_reports.
 81*
 82*  \a pszSymSearchPath parameter defines where to look for symbols files (*.PDB). You can specify the list of 
 83*  semicolon-separated directories to search in. If this parameter is NULL, the default search sequence is used.
 84*  For the default search sequence, see the documentation for \b SymInitialize() function in MSDN.
 85*
 86*  Symbol files are required for crash report processing. They contain various information used by the debugger.
 87*  For more information about saving symbol files, see \ref preparing_to_software_release.
 88*
 89*  \a dwFlags is currently not used, should be zero.
 90*
 91*  \a phReport parameter receives the handle to the opened crash report. If the function fails,
 92*  this parameter becomes zero. 
 93*
 94*  This function does the following when opening report file:
 95*    - It performs integrity checks for the error report being opened, if MD5 hash is specified.
 96*    - It searches for crashrpt.xml and crashdump.dml files inside of ZIP archive, if such files
 97*      do not present, it assumes the report was generated by CrashRpt v1.0. In such case it searches for
 98*      any file having *.dmp or *.xml extension and assumes these are valid XML and DMP file.
 99*    - It extracts and loads the XML file and checks its structure.
100*    - It extracts the minidump file to the temporary location.
101*
102*  On failure, use crpGetLastErrorMsg() function to get the last error message.
103*
104*  Use the crpCloseErrorReport() function to close the opened error report.
105*
106*  \note
107*
108*  The crpOpenErrorReportW() and crpOpenErrorReportA() are wide character and multibyte 
109*  character versions of crpOpenErrorReport(). 
110* 
111*
112*  \sa 
113*    crpCloseErrorReport()
114*/
115
116CRASHRPTPROBE_API(int)
117crpOpenErrorReportW(
118                    __in LPCWSTR pszFileName,
119                    __in_opt LPCWSTR pszMd5Hash,
120                    __in_opt LPCWSTR pszSymSearchPath,
121                    __reserved DWORD dwFlags,
122                    __out CrpHandle* phReport
123                    );
124
125/*! \ingroup CrashRptProbeAPI
126*  \copydoc crpOpenErrorReportW()
127*
128*/
129
130CRASHRPTPROBE_API(int)
131crpOpenErrorReportA(
132                    __in LPCSTR pszFileName,
133                    __in_opt LPCSTR pszMd5Hash,
134                    __in_opt LPCSTR pszSymSearchPath,  
135                    __reserved DWORD dwFlags,
136                    __out CrpHandle* phReport
137                    );
138
139/*! \brief Character set-independent mapping of crpOpenErrorReportW() and crpOpenErrorReportA() functions. 
140*  \ingroup CrashRptProbeAPI
141*/
142
143#ifdef UNICODE
144#define crpOpenErrorReport crpOpenErrorReportW
145#else
146#define crpOpenErrorReport crpOpenErrorReportA
147#endif //UNICODE
148
149/*! \ingroup CrashRptProbeAPI
150*  \brief Closes the crash report.
151*  \return This function returns zero on success.
152*  \param[in] hReport Handle to the opened error report.
153*
154*  \remarks
155*
156*  Use this function to close the error report previously opened with crpOpenErrorReport()
157*  function.
158*
159*  If this function fails, use crpGetLastErrorMsg() function to get the error message.
160*
161*  \sa
162*    crpOpenErrorReport(), crpOpenErrorReportW(), crpOpenErrorReportA(), crpGetLastErrorMsg()
163*/
164
165CRASHRPTPROBE_API(int) 
166crpCloseErrorReport(
167                    CrpHandle hReport  
168                    );
169
170/* Table names passed to crpGetProperty() function. */
171
172#define CRP_TBL_XMLDESC_MISC _T("XmlDescMisc")                //!< Table: Miscellaneous info contained in crash description XML file. 
173#define CRP_TBL_XMLDESC_FILE_ITEMS _T("XmlDescFileItems")     //!< Table: The list of file items contained in error report.
174#define CRP_TBL_XMLDESC_CUSTOM_PROPS _T("XmlDescCustomProps") //!< Table: The list of application-defined properties (available since v.1.2.1).
175#define CRP_TBL_MDMP_MISC    _T("MdmpMisc")    //!< Table: Miscellaneous info contained in crash minidump file.  
176#define CRP_TBL_MDMP_MODULES _T("MdmpModules") //!< Table: The list of loaded modules.
177#define CRP_TBL_MDMP_THREADS _T("MdmpThreads") //!< Table: The list of threads.
178#define CRP_TBL_MDMP_LOAD_LOG _T("MdmpLoadLog") //!< Table: Minidump loading log.
179
180/* Meta information */
181
182#define CRP_META_ROW_COUNT _T("RowCount") //!< Row count in the table.  
183
184/* Column names passed to crpGetProperty() function. */
185
186// Columns IDs of the CRP_XMLDESC_MISC table
187#define CRP_COL_CRASHRPT_VERSION _T("CrashRptVersion") //!< Column: Version of CrashRpt library that generated the report.
188#define CRP_COL_CRASH_GUID       _T("CrashGUID")       //!< Column: Globally unique identifier (GUID) of the error report.
189#define CRP_COL_APP_NAME         _T("AppName")         //!< Column: Application name.
190#define CRP_COL_APP_VERSION      _T("AppVersion")      //!< Column: Application version.
191#define CRP_COL_IMAGE_NAME       _T("ImageName")       //!< Column: Path to the executable file.
192#define CRP_COL_OPERATING_SYSTEM _T("OperatingSystem") //!< Column: Opration system name, including build number and service pack.
193#define CRP_COL_SYSTEM_TIME_UTC  _T("SystemTimeUTC")   //!< Column: Time (UTC) when the crash occured.
194#define CRP_COL_EXCEPTION_TYPE   _T("ExceptionType")   //!< Column: Code of exception handler that cought the exception.
195#define CRP_COL_EXCEPTION_CODE   _T("ExceptionCode")   //!< Column: Exception code; for the structured exceptions only.
196#define CRP_COL_INVPARAM_FUNCTION _T("InvParamFunction") //!< Column: Function name; for invalid parameter errors only.
197#define CRP_COL_INVPARAM_EXPRESSION _T("InvParamExpression") //!< Column: Expression; for invalid parameter errors only.
198#define CRP_COL_INVPARAM_FILE    _T("InvParamFile")    //!< Column: Source file name; for invalid parameter errors only.
199#define CRP_COL_INVPARAM_LINE    _T("InvParamLine")    //!< Column: Source line; for invalid parameter errors only.
200#define CRP_COL_FPE_SUBCODE      _T("FPESubcode")      //!< Column: Subcode of floating point exception; for FPE exceptions only.
201#define CRP_COL_USER_EMAIL       _T("UserEmail")       //!< Column: Email of the user who sent this report.
202#define CRP_COL_PROBLEM_DESCRIPTION _T("ProblemDescription") //!< Column: User-provided problem description.
203#define CRP_COL_MEMORY_USAGE_KBYTES _T("MemoryUsageKbytes")  //!<  Column: Memory usage at the moment of crash (in KB).
204#define CRP_COL_GUI_RESOURCE_COUNT _T("GUIResourceCount")    //!<  Column: Count of used GUI resources at the moment of crash.
205#define CRP_COL_OPEN_HANDLE_COUNT  _T("OpenHandleCount")     //!<  Column: Count of open handles at the moment of crash.
206#define CRP_COL_OS_IS_64BIT  _T("OSIs64Bit")                 //!<  Column: Operating system is 64-bit.
207#define CRP_COL_GEO_LOCATION _T("GeoLocation")               //!<  Column: Geographic location of the error report sender.
208
209// Column IDs of the CRP_XMLDESC_FILE_ITEMS table
210#define CRP_COL_FILE_ITEM_NAME   _T("FileItemName")    //!< Column: File list: Name of the file contained in the report.
211#define CRP_COL_FILE_ITEM_DESCRIPTION _T("FileItemDescription") //!< Column: File list: Description of the file contained in the report.
212
213// Column IDs of the CRP_XMLDESC_CUSTOM_PROPS table
214#define CRP_COL_PROPERTY_NAME   _T("PropertyName")     //!< Column: Name of the application-defined property.
215#define CRP_COL_PROPERTY_VALUE  _T("PropertyValue")    //!< Column: Value of the application-defined property.
216
217// Column IDs of the CRP_MDMP_MISC table
218#define CRP_COL_CPU_ARCHITECTURE _T("CPUArchitecture") //!< Column: Processor architecture.
219#define CRP_COL_CPU_COUNT        _T("CPUCount")        //!< Column: Number of processors.
220#define CRP_COL_PRODUCT_TYPE     _T("ProductType")     //!< Column: Type of system (server or workstation).
221#define CRP_COL_OS_VER_MAJOR     _T("OSVerMajor")      //!< Column: OS major version.
222#define CRP_COL_OS_VER_MINOR     _T("OSVerMinor")      //!< Column: OS minor version.
223#define CRP_COL_OS_VER_BUILD     _T("OSVerBuild")      //!< Column: OS build number.
224#define CRP_COL_OS_VER_CSD       _T("OSVerCSD")        //!< Column: The latest service pack installed.
225#define CRP_COL_EXCPTRS_EXCEPTION_CODE _T("ExptrsExceptionCode")  //!< Column: Code of the structured exception.
226#define CRP_COL_EXCEPTION_ADDRESS _T("ExceptionAddress")          //!< Column: Exception address.
227#define CRP_COL_EXCEPTION_THREAD_ROWID _T("ExceptionThreadROWID") //!< Column: ROWID in \ref CRP_TBL_MDMP_THREADS of the thread in which exception occurred.
228#define CRP_COL_EXCEPTION_THREAD_STACK_MD5  _T("ExceptionThreadStackMD5") //!< Column: MD5 hash of the stack trace of the thread where exception occurred.
229#define CRP_COL_EXCEPTION_MODULE_ROWID _T("ExceptionModuleROWID") //!< Column: ROWID in \ref CRP_TBL_MDMP_MODULES of the module in which exception occurred.
230
231// Column IDs of the CRP_MDMP_MODULES table
232#define CRP_COL_MODULE_NAME      _T("ModuleName")           //!< Column: Module name.
233#define CRP_COL_MODULE_IMAGE_NAME _T("ModuleImageName")     //!< Column: Image name containing full path.  
234#define CRP_COL_MODULE_BASE_ADDRESS _T("ModuleBaseAddress") //!< Column: Module base load address.
235#define CRP_COL_MODULE_SIZE      _T("ModuleSize")           //!< Column: Module size.
236#define CRP_COL_MODULE_LOADED_PDB_NAME _T("LoadedPDBName")  //!< Column: The full path and file name of the .pdb file. 
237#define CRP_COL_MODULE_LOADED_IMAGE_NAME _T("LoadedImageName")  //!< Column: The full path and file name of executable file.
238#define CRP_COL_MODULE_SYM_LOAD_STATUS _T("ModuleSymLoadStatus") //!< Column: Symbol load status for the module.
239
240// Column IDs of the CRP_MDMP_THREADS table
241#define CRP_COL_THREAD_ID            _T("ThdeadID")           //!< Column: Thread ID.
242#define CRP_COL_THREAD_STACK_TABLEID _T("ThreadStackTABLEID") //!< Column: The table ID of the table containing stack trace for this thread.
243
244// Column IDs of a stack trace table
245#define CRP_COL_STACK_MODULE_ROWID     _T("StackModuleROWID")    //!< Column: Stack trace: ROWID of the module in the CRP_TBL_MODULES table.
246#define CRP_COL_STACK_SYMBOL_NAME      _T("StackSymbolName")     //!< Column: Stack trace: symbol name.
247#define CRP_COL_STACK_OFFSET_IN_SYMBOL _T("StackOffsetInSymbol") //!< Column: Stack trace: offset in symbol, hexadecimal.
248#define CRP_COL_STACK_SOURCE_FILE      _T("StackSourceFile")     //!< Column: Stack trace: source file name.
249#define CRP_COL_STACK_SOURCE_LINE      _T("StackSourceLine")     //!< Column: Stack trace: source file line number.
250#define CRP_COL_STACK_ADDR_PC_OFFSET   _T("StackAddrPCOffset")   //!< Column: Stack trace: AddrPC offset.
251
252// Column IDs of the CRP_MDMP_LOAD_LOG table
253#define CRP_COL_LOAD_LOG_ENTRY _T("LoadLogEntry")   //!< Column: A entry of the minidump loading log.
254
255/*! \ingroup CrashRptProbeAPI
256*  \brief Retrieves a string property from crash report.
257*  \return This function returns zero on success, with one exception (see Remarks for more information).
258*
259*  \param[in]  hReport Handle to the previously opened crash report.
260*  \param[in]  lpszTableId Table ID.
261*  \param[in]  lpszColumnId Column ID.
262*  \param[in]  nRowIndex Index of the row in the table.
263*  \param[out] lpszBuffer Output buffer.
264*  \param[in]  cchBuffSize Size of the output buffer in characters.
265*  \param[out] pcchCount Count of characters written to the buffer.
266*
267*  \remarks
268*
269*  Use this function to retrieve data from the crash report that was previously opened with the
270*  crpOpenErrorReport() function.
271*
272*  Properties are organized into tables having rows and columns. For the list of available tables,
273*  see \ref using_crashrptprobe_api.
274*
275*  To get the number of rows in a table, pass the constant \ref CRP_META_ROW_COUNT as column ID. In this case the
276*  function returns number of rows as its return value, or negative value on failure. 
277*
278*  In all other cases the function returns zero on success.
279*
280*  Some properties are loaded from crash description XML file, while others are loaded from crash minidump file.
281*  The minidump is loaded once when you retrive a property from it. This reduces the overall processing time.
282*
283*  \a hReport should be the handle to the opened error report.
284*
285*  \a lpszTableId represente the ID of the table.
286*
287*  \a lpszColumnId represents the ID of the column in the table. 
288*
289*  \a nRowIndex defines the zero-based index of the row in the table.
290*  
291*  \a lpszBuffer defines the buffer where retrieved property value will be placed. If this parameter
292*  is NULL, it is ignored and \a pcchCount is set with the required size in characters of the buffer.
293*
294*  \a cchBuffSize defines the buffer size in characters. To calculate required buffer size, set \a lpszBuffer with NULL, 
295*  the function will set \a pcchCount with the number of characters required.
296*
297*  \a pcchCount is set with the actual count of characters copied to the \a lpszBuffer. If this parameter is NULL,
298*  it is ignored.
299*
300*  If this function fails, use crpGetLastErrorMsg() function to get the error message.
301*
302*  For code examples of using this function, see \ref crashrptprobe_api_examples.
303*
304*  \note
305*  The crpGetPropertyW() and crpGetPropertyA() are wide character and multibyte 
306*  character versions of crpGetProperty(). 
307*
308*  \sa
309*    crpGetPropertyW(), crpGetPropertyA(), crpOpenErrorReport(), crpGetLastErrorMsg()
310*/ 
311
312CRASHRPTPROBE_API(int) 
313crpGetPropertyW(
314                CrpHandle hReport,
315                LPCWSTR lpszTableId,
316                LPCWSTR lpszColumnId,
317                INT nRowIndex,
318                __out_ecount_z(pcchBuffSize) LPWSTR lpszBuffer,
319                ULONG cchBuffSize,
320                __out PULONG pcchCount
321                );
322
323/*! \ingroup CrashRptProbeAPI
324*  \copydoc crpGetPropertyW()
325*
326*/
327
328CRASHRPTPROBE_API(int) 
329crpGetPropertyA(
330                CrpHandle hReport,
331                LPCSTR lpszTableId,
332                LPCSTR lpszColumnId,
333                INT nRowIndex,
334                __out_ecount_z(pcchBuffSize) LPSTR lpszBuffer,
335                ULONG cchBuffSize,
336                __out PULONG pcchCount
337                );
338
339/*! \brief Character set-independent mapping of crpGetPropertyW() and crpGetPropertyA() functions. 
340*  \ingroup CrashRptProbeAPI
341*/
342
343#ifdef UNICODE
344#define crpGetProperty crpGetPropertyW
345#else
346#define crpGetProperty crpGetPropertyA
347#endif //UNICODE
348
349/*! \ingroup CrashRptProbeAPI
350*  \brief Extracts a file from the opened error report.
351*  \return This function returns zero if succeeded.
352*
353*  \param[in] hReport Handle to the opened error report.
354*  \param[in] lpszFileName The name of the file to extract.
355*  \param[in] lpszFileSaveAs The resulting name of the extracted file.
356*  \param[in] bOverwriteExisting Overwrite the destination file if it already exists?
357*
358*  \remarks
359*
360*  Use this function to extract a compressed file from the error report (ZIP) file.
361*
362*  \a lpszFileName parameter should be the name of the file to extract. For more information
363*  about enumerating file names, see \ref crashrptprobe_api_examples.
364*
365*  \a lpszFileSaveAs defines the name of the file to extract to. 
366*
367*  \a bOverwriteExisting flag defines the behavior when the destination file already exists.
368*  If this parameter is TRUE, the file is overwritten, otherwise the function fails.
369*
370*  If this function fails, use crpGetLastErrorMsg() to retrieve the error message.
371*
372*  \note
373*    The crpExtractFileW() and crpExtractFileA() are wide character and multibyte 
374*    character versions of crpExtractFile(). 
375*
376*  \sa
377*    crpExtractFileA(), crpExtractFileW(), crpExtractFile()
378*/
379
380CRASHRPTPROBE_API(int) 
381crpExtractFileW(
382                CrpHandle hReport,
383                LPCWSTR lpszFileName,
384                LPCWSTR lpszFileSaveAs,
385                BOOL bOverwriteExisting
386                );
387
388/*! \ingroup CrashRptProbeAPI
389*  \copydoc crpExtractFileW() 
390*/
391
392CRASHRPTPROBE_API(int) 
393crpExtractFileA(
394                CrpHandle hReport,
395                LPCSTR lpszFileName,
396                LPCSTR lpszFileSaveAs,
397                BOOL bOverwriteExisting
398                );
399
400/*! \brief Character set-independent mapping of crpExtractFileW() and crpExtractFileA() functions. 
401*  \ingroup CrashRptProbeAPI
402*/
403
404#ifdef UNICODE
405#define crpExtractFile crpExtractFileW
406#else
407#define crpExtractFile crpExtractFileA
408#endif //UNICODE
409
410/*! \ingroup CrashRptProbeAPI 
411*  \brief Gets the last CrashRptProbe error message.
412*
413*  \return This function returns length of error message in characters.
414*
415*  \param[out] pszBuffer Pointer to the buffer.
416*  \param[in]  cchBuffSize Size of buffer in characters.
417*
418*  \remarks
419*
420*  This function gets the last CrashRptProbe error message. You can use this function
421*  to retrieve the text status of the last called CrashRptProbe function.
422*
423*  If buffer is too small for the error message, the message is truncated.
424*
425*  \note 
426*    crpGetLastErrorMsgW() and crpGetLastErrorMsgA() are wide-character and multi-byte character versions
427*    of crpGetLastErrorMsg(). The crpGetLastErrorMsg() macro defines character set independent mapping.
428*
429*  The following example shows how to use crpGetLastErrorMsg() function.
430*
431*  \code
432*  
433*  // .. call some CrashRptProbe function
434*
435*  // Get the status message
436*  TCHAR szErrorMsg[256];
437*  crpGetLastErrorMsg(szErrorMsg, 256);
438*  \endcode
439*
440*  \sa crpGetLastErrorMsgA(), crpGetLastErrorMsgW(), crpGetLastErrorMsg()
441*/
442
443CRASHRPTPROBE_API(int)
444crpGetLastErrorMsgW(
445                    __out_ecount(cchBuffSize) LPWSTR pszBuffer, 
446                    __in UINT cchBuffSize);
447
448/*! \ingroup CrashRptProbeAPI
449*  \copydoc crpGetLastErrorMsgW()
450*
451*/
452
453CRASHRPTPROBE_API(int)
454crpGetLastErrorMsgA(
455                    __out_ecount(cchBuffSize) LPSTR pszBuffer, 
456                    __in UINT cchBuffSize);
457
458/*! \brief Defines character set-independent mapping for crpGetLastErrorMsgW() and crpGetLastErrorMsgA().
459*  \ingroup CrashRptProbeAPI
460*/
461
462#ifdef UNICODE
463#define crpGetLastErrorMsg crpGetLastErrorMsgW
464#else
465#define crpGetLastErrorMsg crpGetLastErrorMsgA
466#endif //UNICODE
467
468
469#endif __CRASHRPT_PROBE_H__
470