Using CrashRptProbe API

This page describes the application programming interface (API) for processing error reports generated by CrashRpt. The API is used internally by the crprober.exe tool presented in the previous section.

The error report processing functionality is encapsulated inside of CrashRptProbe.dll. Internally CrashRptProbe uses the functions provided by dbghelp.dll (Microsoft Debug Help Library) for loading the minidump file contained in the report.

The CrashRptProbe provides several functions you can use in your own error report processing tool (see CrashRptProbe Functions). All CrashRptProbe functions have crp prefix in function name, constants have CRP prefix and types have Crp prefix.

All CrashRptProbe functions using character set dependent arguments have two versions of function name (multi-byte versions are A-suffixed and wide character versions are W-suffixed). For example, crpGetProperty() function has two versions of function name: crpGetPropertyA() and crpGetPropertyW(). Typically you use a character set independent mapping of function name in your program, for example use crpGetProperty() that expands into crpGetPropertyW() if you use wide character set or into crpGetPropertyA() if you use multi-byte character set.

Include and Lib Files

At this point you should have CrashRpt solution's source code compiled as described Compiling CrashRpt.

Configure your Visual Studio directories as described in below:

In Visual Studio window, open Tools-> Options->Projects and Solutions->VC++ Directories.

• In the 'Show directories for' combo box, select 'Include files', then add the path to [CRASHRPT_HOME]\include directory to the list.
• In the 'Show directories for' combo box, select 'Library files', then add the path to [CRASHRPT_HOME]\lib directory to the list.

Here [CRASHRPT_HOME] should be replaced with the actual path of the directory you unzipped CrashRpt package to.

Include the CrashRptProbe.h header file in the beginning of your code in order to use CrashRptProbe API in your crash report processing program.

//Include CrashRptProbe header in the beginning of your code
#include <CrashRptProbe.h>

Add CrashRptProbe.lib file to the list of input libraries for your project. In the Solution Explorer window, right-click your project and choose Properties item in the context menu. Then open Configuration Properties->Linker->Input->Additional Dependencies and then add CrashRptProbe.lib to the list of libraries.

Opening and Closing Error Reports

Error report files are normal ZIP archives containing several files as described in About an Error Report. To open an error report file, you use the crpOpenErrorReport() function. The function returns the handle to the opened report as CrpHandle type, which is an integer number identifying the opened report. You pass the handle to other CrashRptProbe functions.

When you have retrieved all the data you need, close the report. To close previously opened error report, you use crpCloseErrorReport() function.

Retrieving Error Report Properties

You can think of the error report as a set of properties. All properties are organized into tables consisting of rows and columns. Each property is a text string. But sometimes you might need to convert text properties to some other types for further processing.

The list of table IDs you can use is presented below in The List of Table IDs section. Table IDs are actually strings, but we use aliases for convenience. For example, CRP_TBL_XMLDESC_MISC expands into "XmlDescMisc" string.

The list of table IDs is not fixed. There may be additional tables in the report, and you can determine their IDs at run time only. For example, each execution thread has the stack trace. The stack trace is the table containing a collection of stack frames. You can retrieve table IDs of the stack trace of each thread from CRP_TBL_MDMP_THREADS table.

Each table may have several rows. The CRP_TBL_XMLDESC_MISC and CRP_TBL_MDMP_MISC tables always have single row. Other ones may have more than one row. You can determine the number of rows in the table by passing special constant CRP_META_ROW_COUNT to the crpGetProperty() function, as shown in the example below:

#include <CrashRptProbe.h>

// It is assumed the handle to the opened error report is stored in hReport variable.
CrpHandle hReport;

// Get row count in the Modules table.
// The return value is non-negative on success.
int nRowCount = crpGetProperty(hReport, CRP_TBL_MDMP_MODULES, 
                    CRP_META_ROW_COUNT, 0, NULL, 0, NULL);

Each table has several columns. Column IDs are actually strings, but we use aliases for convenience. For example, CRP_COL_APP_NAME expands into "AppName" string.

The list of available column IDs for each table is presented in the following sections below:

• The List of Column IDs of the CRP_TBL_XMLDESC_MISC Table
• The List of Column IDs of the CRP_TBL_XMLDESC_CUSTOM_PROPS Table
• The List of Column IDs of the CRP_TBL_XMLDESC_FILE_ITEMS Table
• The List of Column IDs of the CRP_TBL_MDMP_MISC Table
• The List of Column IDs of the CRP_TBL_MDMP_MODULES Table
• The List of Column IDs of the CRP_TBL_MDMP_THREADS Table
• The List of Column IDs of a Stack Trace Table
• The List of Column IDs of the CRP_MDMP_LOAD_LOG Table

To retrieve a property from the report, you use the crpGetProperty() function. You pass table ID, column ID and row ID identifying the property to this function, and receive the value to the text buffer (see the following example).

The number of columns is not fixed, it depends on what version of CrashRpt generated the report, and on various other factors.

If there is no such table or there is no such column in the table, or row index is invalid, the crpGetProperty() function fails. Check the return code to ensure the property is retrieved successfully.

The following code example shows how to retrieve a property from error report:

#include <CrashRptProbe.h>

// It is assumed the handle to the opened error report is stored in hReport variable.
CrpHandle hReport;

const int BUFF_SIZE = 1024;
TCHAR szBuffer[BUFF_SIZE];  

// Get the count of processors on user's machine.
int nResult = crpGetProperty(hReport, CRP_TBL_MDMP_MISC, 
                CRP_COL_CPU_COUNT, 0, szBuffer, BUFF_SIZE, NULL);

For additional code examples, please see Examples of Using CrashRptProbe API.

Retrieving Files Contained in the Error Report

An error report is a ZIP archive containing several files. The files are: crash minidump file (.dmp), crash report description file (.xml) and optional application-defined files, such as application log file.

To enumerate files contained in report, you use CRP_TBL_XMLDESC_FILE_ITEMS table.

To extract a file from the ZIP archive by its file name, you use crpExtractFile() function.

Handling Errors

Typically a CrashRptProbe API function returns zero value if succeeded and non-zero if failed. To get text error message of the last called function, use crpGetLastErrorMsg().

CrashRptProbe API Reference

• CrashRptProbe Functions

The List of Table IDs

Table ID	Description
CRP_TBL_XMLDESC_MISC	This table contains miscellaneous information retrieved from XML crash description file. For the list of columns this table may contain, see The List of Column IDs of the CRP_TBL_XMLDESC_MISC Table.
CRP_TBL_XMLDESC_CUSTOM_PROPS	This table contains the list of application-defined properties (available since v.1.2.1).. For the list of columns this table may contain, see The List of Column IDs of the CRP_TBL_XMLDESC_CUSTOM_PROPS Table.
CRP_TBL_XMLDESC_FILE_ITEMS	This table contains the list of files contained in the error report. For the list of columns this table may contain, see The List of Column IDs of the CRP_TBL_XMLDESC_FILE_ITEMS Table.
CRP_TBL_MDMP_MISC	This table contains miscellaneous information retrieved from crash minidump file. For the list of columns this table may contain, see The List of Column IDs of the CRP_TBL_MDMP_MISC Table.
CRP_TBL_MDMP_MODULES	This table contains the list of loaded modules retrieved from crash minidump file. For the list of columns this table may contain, see The List of Column IDs of the CRP_TBL_MDMP_MODULES Table.
CRP_TBL_MDMP_THREADS	This table contains the list of threads retrieved from crash minidump file. For the list of columns this table may contain, see The List of Column IDs of the CRP_TBL_MDMP_THREADS Table.
CRP_TBL_MDMP_LOAD_LOG	This table contains the minidump loading log. For the list of columns this table may contain, see The List of Column IDs of the CRP_MDMP_LOAD_LOG Table.

The List of Column IDs of the CRP_TBL_XMLDESC_MISC Table

Column ID	Description
CRP_COL_CRASHRPT_VERSION	Example values: "1000" (v1.0), "1100" (v1.1b), "1101" (v1.1.1), "1102" (v1.1.2), "1103" (v1.1.3), "1200" (v1.2.0). Use this property to get the version of CrashRpt library that generated the error report. For example, "1000" means the report was generated using old v1.0, and "1103" means the report was generated using v1.1.3.
CRP_COL_CRASH_GUID	Example value: "0b3b0c1b-3450-4c39-9459-42221ae66460" This property represents the globally unique identifier (GUID) assigned to the error report. This property may present in reports generated by CrashRpt v1.1b and later
CRP_COL_APP_NAME	Examples: "My Application", "myapp" Represents the name of the application name this report was generated for.
CRP_COL_APP_VERSION	Examples: "6.1.0.200", "1.3.5" Application version this report was generated for.
CRP_COL_IMAGE_NAME	Example: "C:\Program Files\My Application\MyApp.exe" Path to the executable file.
CRP_COL_OPERATING_SYSTEM	Examples:"Windows XP Build 2600 Service Pack 3", "Windows 7 Ultimate Build 7100" Operating system name, including build number and service pack. This value is taken from end user's registry. This property may present in reports generated by CrashRpt v1.1b and later
CRP_COL_SYSTEM_TIME_UTC	Example: "2009-06-28T04:47:32Z" Time (UTC) when the crash had occurred, including year, month, day, hour, min and sec. This property may present in reports generated by CrashRpt v1.1b and later
CRP_COL_EXCEPTION_TYPE	Examples: "0 SEH exception", "1 terminate call". Code of exception handler that caught the exception followed by short description. For the list of possible exception types, see Using Crash Description XML. This property may present in reports generated by CrashRpt v1.1b and later
CRP_COL_EXCEPTION_CODE	Example: "0xc0000005 Access violation reading location." Exception code; for the SEH exceptions only. Hexadecimal number followed by the textual description. This property may present in reports generated by CrashRpt v1.1b and later
CRP_COL_INVPARAM_FUNCTION	Example: "_stprintf_s". Function name; for invalid parameter errors only. This property may present in reports generated by CrashRpt v1.1b and later
CRP_COL_INVPARAM_EXPRESSION	Example: "sizeOfBuffer!=0" Expression; for invalid parameter errors only. This property may present in reports generated by CrashRpt v1.1b and later
CRP_COL_INVPARAM_FILE	Example: "invarg.c" Source file name; for invalid parameter errors only. This property may present in reports generated by CrashRpt v1.1b and later
CRP_COL_INVPARAM_LINE	Example: "25" Source line number; decimal number; for invalid parameter errors only. This property may present in reports generated by CrashRpt v1.1b and later
CRP_COL_FPE_SUBCODE	Example: "0x81" Sub-code of floating point exception, hexadecimal number. For FPE exceptions only. For the list of possible FPE sub-codes, see the documentation of signal function in MSDN or FPE_-prefixed constants in <float.h> header. This property may present in reports generated by CrashRpt v1.1b and later
CRP_COL_USER_EMAIL	Example: "example@hotmail.com" Email of the user who sent this report. This property may present in reports generated by CrashRpt v1.1b and later
CRP_COL_PROBLEM_DESCRIPTION	Example: "I don't know" User-provided problem description. This property may present in reports generated by CrashRpt v1.1b and later
CRP_COL_GEO_LOCATION	Example: "en-us" Geographic location of the error report sender in an RFC 1766 compliant form. This property is a string consisting of two parts separated with `-` symbol. The first part is the language abbreviation, the second is country name abbreviation. This property may present in reports generated by CrashRpt v1.2.7 and later
CRP_COL_OS_IS_64BIT	Example: "1" or "0" Equals to 1 if user's OS is 64-bit, otherwize equals to 0. This property may present in reports generated by CrashRpt v1.2.7 and later

The List of Column IDs of the CRP_TBL_XMLDESC_CUSTOM_PROPS Table

Column ID	Description
CRP_COL_PROPERTY_NAME	Example: "VideoAdapter" This represents the name of a user-defined property.
CRP_COL_PROPERTY_VALUE	Example: "NVIDIA GeForce GTX 295" Value of the user-defined property.

The List of Column IDs of the CRP_TBL_XMLDESC_FILE_ITEMS Table

Column ID	Description
CRP_COL_FILE_ITEM_NAME	Example: "crashdump.dmp" This property represents the name of a file contained in the error report.
CRP_COL_FILE_ITEM_DESCRIPTION	Example: "Crash Dump" Description of a file contained in the report.

The List of Column IDs of the CRP_TBL_MDMP_MISC Table

Column ID	Description
CRP_COL_CPU_ARCHITECTURE	Example: "0 x86" Processor architecture. Decimal number followed by textual description. Possible values are: "0 x86", "6 Intel Itanium Processor Family (IPF)", "9 x64 (AMD or Intel)", "10 WOW"
CRP_COL_CPU_COUNT	Example: "1" Number of processors. Decimal number equal or greater than one.
CRP_COL_PRODUCT_TYPE	Examples: "1 workstation", "2 domain controller", "3 server" Type of end user's system (server, domain controller or workstation). Decimal number followed by textual description.
CRP_COL_OS_VER_MAJOR	Example: "6" OS major version. Decimal number. Equals to "5" for Win2000/XP, "6" for Vista/Windows 7.
CRP_COL_OS_VER_MINOR	Examples: "0", "1" OS minor version. Used in combination with major version.
CRP_COL_OS_VER_BUILD	Example: "2600" OS build number.
CRP_COL_OS_VER_CSD	Example: "Service Pack 3" The latest service pack installed.
CRP_COL_EXCPTRS_EXCEPTION_CODE	Example: "0xc000005 Access violation reading location." Code of the SEH exception. Hexadecimal value followed by textual description. Valid for SEH exceptions only. This value is taken from minidump file; it is assumed to be the same as CRP_COL_EXCEPTION_CODE property taken form XML file. This value may be empty if there is no exception information contained in the minidump file.
CRP_COL_EXCEPTION_ADDRESS	Example: "0x284323407" Exception address. Hexadecimal value. This value may be empty if there is no exception information contained in the minidump file.
CRP_COL_EXCEPTION_THREAD_ROWID	Example: "0" Row ID of the thread in which exception occurred. Decimal value. This value may be empty if there is no exception information contained in the minidump file. When not empty, convert this text value to int and use as row ID to retrieve the thread information from CRP_TBL_MDMP_THREADS table.
CRP_COL_EXCEPTION_MODULE_ROWID	Example: "12" Row ID of the module in which exception occurred. Decimal value. This value may be empty if there is no exception information contained in the minidump file. When not empty, convert this text value to int and use as row ID to retrieve the module information from CRP_TBL_MDMP_MODULES table.
CRP_COL_EXCEPTION_THREAD_STACK_MD5	Example: "1fe384ded60d27a03c7375e80a1d6f4e" An MD5 hash of the stack of exception thread. Only meaningful (having valid module name and symbol name) stack frames are selected to compute the hash. You can use this value to group error reports by similar stack traces of the exception thread. This value may be empty if there is no exception information contained in the minidump file. This property may present in reports generated by CrashRpt v1.2.7 and later

The List of Column IDs of the CRP_TBL_MDMP_MODULES Table

Column ID	Description
CRP_COL_MODULE_NAME	Short module name (filename+extension). Example: "ntdll.dll"
CRP_COL_MODULE_IMAGE_NAME	Path to module image file. Example: "C:\Program Files\MyApp\msvcr80.dll"
CRP_COL_MODULE_BASE_ADDRESS	Module base load address. Hexadecimal value. Example: "0x80000000"
CRP_COL_MODULE_SIZE	Module size in bytes. Decimal. Example: "560008"
CRP_COL_MODULE_LOADED_PDB_NAME	Path to the PDB file loaded for this module or empty string if symbols not loaded. Example: "D:\CrashRptSaved\MyApp_v1.3.5\Sym\myapp.pdb"
CRP_COL_MODULE_LOADED_IMAGE_NAME	Path to the image file loaded for this module or empty string if image was not loaded. Example: "D:\CrashRptSaved\MyApp_v1.3.5\bin\WTLDemo.exe" This property may present in reports generated by CrashRpt v1.2.8 and later

The List of Column IDs of the CRP_TBL_MDMP_THREADS Table

Column ID	Description
CRP_COL_THREAD_ID	Thread identifier. Hexadecimal value. Thread ID is assigned on thread creation by CreateThread() WinAPI function. Example: "0x1ff"
CRP_COL_THREAD_STACK_TABLEID	Table ID of the stack frace table for this thread. Decimal. Pass this string to crpGetProperty() as table ID. Example values are implementation specific.

The List of Column IDs of a Stack Trace Table

Column ID	Description
CRP_COL_STACK_MODULE_ROWID	Row index of a module in CRP_TBL_MDMP_MODULES table. Use this value to get module information for this stack frame. Convert this value to int and pass to crpGetProperty() function as row index. Possible values are integer numbers starting from zero, or -1 if there module can't be determined for this stack frame.
CRP_COL_STACK_SYMBOL_NAME	Symbol name for this stack frame. Symbol name may be the name of function or class method. This value may be empty, if the symbol name can't be determined for this stack frame. Example: "CBaseClass::SomeMethod", "memcpy"
CRP_COL_STACK_OFFSET_IN_SYMBOL	Offset in symbol, hexadecimal value. Example: "0x1f"
CRP_COL_STACK_SOURCE_FILE	Path to source file. Example: "D:\MyProject\src\memfuncs.cpp"
CRP_COL_STACK_SOURCE_LINE	Source file line number. Decimal. Example: "100"
CRP_COL_STACK_ADDR_PC_OFFSET	Program counter CPU register's value for this stack frame. Hexadecimal. Example: "0x800000435"

The List of Column IDs of the CRP_MDMP_LOAD_LOG Table

Column ID	Description
CRP_COL_LOAD_LOG_ENTRY	A entry of the minidump loading log. This property may present in reports generated by CrashRpt v1.2.8 and later Example values are implementation specific.