| crashrpt |
A crash reporting system for Windows applications

# 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\CrashRptTest.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.