/*!

\page using_crashrptprobe_api 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 \b crprober.exe tool presented in 
the previous section. 

The error report processing functionality is encapsulated inside of <b>CrashRptProbe.dll</b>. 
Internally CrashRptProbe uses the functions provided by \b 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 \ref CrashRptProbeAPI). All CrashRptProbe functions have \c crp prefix in function name, 
constants have \c CRP prefix and types have \c 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.

\section crprobe_include_and_lib_files Include and Lib Files

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

Configure your Visual Studio directories as described in below:

In Visual Studio window, open <i>Tools->
Options->Projects and Solutions->VC++ Directories</i>.
- In the 'Show directories for' combo box, select 'Include files', then add 
  the path to <i>[CRASHRPT_HOME]\\include</i> directory to the list.
- In the 'Show directories for' combo box, select 'Library files', then add 
  the path to <i>[CRASHRPT_HOME]\\lib</i> directory to the list.

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

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

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

Add \b 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 <i>Configuration Properties->Linker->Input->Additional Dependencies</i> 
and then add \b CrashRptProbe.lib to the list of libraries. 

\section opening_and_closing_error_reports Opening and Closing Error Reports

Error report files are normal ZIP archives containing several files as described in \ref error_report.
To open an error report file, you use the crpOpenErrorReport() function. The function returns the
handle to the opened report as \ref 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.

\section retrieving_report_properties 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 \ref list_of_table_ids section. 
Table IDs are actually strings, but we use aliases for convenience. For example, 
\ref 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 
\ref CRP_TBL_MDMP_THREADS table.

Each table may have several rows. The \ref CRP_TBL_XMLDESC_MISC and \ref 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 \ref CRP_META_ROW_COUNT to the 
crpGetProperty() function, as shown in the example below:

\code
#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);
\endcode

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

The list of available column IDs for each table is presented in the following sections below:
- \ref list_of_column_ids_for_xmldescmisc
- \ref list_of_column_ids_for_xmldesccustomprops
- \ref list_of_column_ids_for_xmldescfileitems
- \ref list_of_column_ids_for_mdmpmisc
- \ref list_of_column_ids_for_mdmpmodules
- \ref list_of_column_ids_for_mdmpthreads
- \ref list_of_column_ids_for_stacktrace 
- \ref list_of_column_ids_for_mdmploadlog

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:

\code
#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);

\endcode

For additional code examples, please see \ref crashrptprobe_api_examples.

\section retrieving_report_files 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 \ref CRP_TBL_XMLDESC_FILE_ITEMS table.

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

\section handling_crprobe_errors 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().

\section crashrptprobe_api_reference CrashRptProbe API Reference

- \ref CrashRptProbeAPI

\section list_of_table_ids The List of Table IDs

<table>

<tr>
<td> <b>Table ID</b>
<td> <b>Description</b>
</tr>

<tr>
<td> \ref CRP_TBL_XMLDESC_MISC
<td> This table contains miscellaneous information retrieved from XML crash description file.    
For the list of columns this table may contain, see \ref list_of_column_ids_for_xmldescmisc.
</tr>

<tr>
<td> \ref CRP_TBL_XMLDESC_CUSTOM_PROPS
<td> 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 \ref list_of_column_ids_for_xmldesccustomprops.
</tr>

<tr>
<td> \ref CRP_TBL_XMLDESC_FILE_ITEMS
<td> This table contains the list of files contained in the error report.
For the list of columns this table may contain, see \ref list_of_column_ids_for_xmldescfileitems.
</tr>

<tr>
<td> \ref CRP_TBL_MDMP_MISC
<td> This table contains miscellaneous information retrieved from crash minidump file.
For the list of columns this table may contain, see  \ref list_of_column_ids_for_mdmpmisc.
</tr>

<tr>
<td> \ref CRP_TBL_MDMP_MODULES
<td> This table contains the list of loaded modules retrieved from crash minidump file.
For the list of columns this table may contain, see  \ref list_of_column_ids_for_mdmpmodules.
</tr>

<tr>
<td> \ref CRP_TBL_MDMP_THREADS
<td> This table contains the list of threads retrieved from crash minidump file.
For the list of columns this table may contain, see \ref list_of_column_ids_for_mdmpthreads.
</tr>

<tr>
<td> \ref CRP_TBL_MDMP_LOAD_LOG
<td> This table contains the minidump loading log.
For the list of columns this table may contain, see \ref list_of_column_ids_for_mdmploadlog.
</tr>

</table>


\section list_of_column_ids_for_xmldescmisc The List of Column IDs of the CRP_TBL_XMLDESC_MISC Table

<table>

<tr>
<td> <b>Column ID</b>
<td> <b>Description</b>

<tr>
<td> \ref CRP_COL_CRASHRPT_VERSION
<td> 

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.

<tr>
<td> \ref CRP_COL_CRASH_GUID
<td> 

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 <b>CrashRpt v1.1b and later</b>

<tr>
<td> \ref CRP_COL_APP_NAME

<td> 

Examples: "My Application", "myapp"

Represents the name of the application name this report was generated for.

<tr>
<td> \ref CRP_COL_APP_VERSION

<td> 

Examples: "6.1.0.200", "1.3.5"

Application version this report was generated for.

<tr>
<td> \ref CRP_COL_IMAGE_NAME
<td> 
Example: "C:\Program Files\My Application\MyApp.exe"

Path to the executable file.

<tr>
<td> \ref CRP_COL_OPERATING_SYSTEM
<td> 

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 <b>CrashRpt v1.1b and later</b>

<tr>
<td> \ref CRP_COL_SYSTEM_TIME_UTC

<td> 
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 <b>CrashRpt v1.1b and later</b>

<tr>
<td> \ref CRP_COL_EXCEPTION_TYPE
<td> 
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 \ref using_crash_descriptor.

This property may present in reports generated by <b>CrashRpt v1.1b and later</b>

<tr>
<td> \ref CRP_COL_EXCEPTION_CODE
<td> 
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 <b>CrashRpt v1.1b and later</b>

<tr>
<td> \ref CRP_COL_INVPARAM_FUNCTION
<td> 
Example: "_stprintf_s".

Function name; for invalid parameter errors only.

This property may present in reports generated by <b>CrashRpt v1.1b and later</b>

<tr>
<td> \ref CRP_COL_INVPARAM_EXPRESSION
<td> 
Example: "sizeOfBuffer!=0"

Expression; for invalid parameter errors only.

This property may present in reports generated by <b>CrashRpt v1.1b and later</b>

<tr>
<td> \ref CRP_COL_INVPARAM_FILE
<td>
Example: "invarg.c"

Source file name; for invalid parameter errors only.

This property may present in reports generated by <b>CrashRpt v1.1b and later</b>

<tr>
<td> \ref CRP_COL_INVPARAM_LINE
<td> 
Example: "25"

Source line number; decimal number; for invalid parameter errors only.

This property may present in reports generated by <b>CrashRpt v1.1b and later</b>

<tr>
<td> \ref CRP_COL_FPE_SUBCODE
<td> 
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 \b signal function in MSDN
or \c FPE_-prefixed constants in <float.h> header.

This property may present in reports generated by <b>CrashRpt v1.1b and later</b>

<tr>
<td> \ref CRP_COL_USER_EMAIL
<td> 
Example: "example@hotmail.com"

Email of the user who sent this report.

This property may present in reports generated by <b>CrashRpt v1.1b and later</b>

<tr>
<td> \ref CRP_COL_PROBLEM_DESCRIPTION
<td> 
Example: "I don't know"

User-provided problem description.

This property may present in reports generated by <b>CrashRpt v1.1b and later</b>

<tr>
<td> \ref CRP_COL_GEO_LOCATION
<td> 
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 <b>CrashRpt v1.2.7 and later</b>

<tr>
<td> \ref CRP_COL_OS_IS_64BIT
<td> 
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 <b>CrashRpt v1.2.7 and later</b>


</table>

\section list_of_column_ids_for_xmldesccustomprops The List of Column IDs of the CRP_TBL_XMLDESC_CUSTOM_PROPS Table

<table>

<tr>
<td> <b>Column ID</b>
<td> <b>Description</b>

<tr>
<td> \ref CRP_COL_PROPERTY_NAME
<td> 
Example: "VideoAdapter"

This represents the name of a user-defined property.

<tr>
<td> \ref CRP_COL_PROPERTY_VALUE
<td> 
Example: "NVIDIA GeForce GTX 295"

Value of the user-defined property.

</table>

\section list_of_column_ids_for_xmldescfileitems The List of Column IDs of the CRP_TBL_XMLDESC_FILE_ITEMS Table

<table>

<tr>
<td> <b>Column ID</b>
<td> <b>Description</b>

<tr>
<td> \ref CRP_COL_FILE_ITEM_NAME
<td> 
Example: "crashdump.dmp"

This property represents the name of a file contained in the error report.

<tr>
<td> \ref CRP_COL_FILE_ITEM_DESCRIPTION
<td> 
Example: "Crash Dump"

Description of a file contained in the report.

</table>

\section list_of_column_ids_for_mdmpmisc The List of Column IDs of the CRP_TBL_MDMP_MISC Table

<table>

<tr>
<td> <b>Column ID</b>
<td> <b>Description</b>

<tr>
<td> \ref CRP_COL_CPU_ARCHITECTURE
<td> 
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"

<tr>
<td> \ref CRP_COL_CPU_COUNT
<td> 
Example: "1"

Number of processors. Decimal number equal or greater than one.

<tr> 
<td> \ref CRP_COL_PRODUCT_TYPE
<td> 
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.

<tr>
<td> \ref CRP_COL_OS_VER_MAJOR
<td> 

Example: "6"

OS major version. Decimal number. Equals to "5" for Win2000/XP, "6" for Vista/Windows 7.

<tr>
<td> \ref CRP_COL_OS_VER_MINOR
<td> 
Examples: "0", "1"

OS minor version. Used in combination with major version. 

<tr>
<td> \ref CRP_COL_OS_VER_BUILD
<td> 
Example: "2600"

OS build number.

<tr>
<td> \ref CRP_COL_OS_VER_CSD
<td> 
Example: "Service Pack 3"

The latest service pack installed.

<tr>
<td> \ref CRP_COL_EXCPTRS_EXCEPTION_CODE
<td> 
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 \ref 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.

<tr>
<td> \ref CRP_COL_EXCEPTION_ADDRESS
<td> 
Example: "0x284323407"

Exception address. Hexadecimal value. This value may be empty if there is no exception information contained in the minidump file.

<tr>
<td> \ref CRP_COL_EXCEPTION_THREAD_ROWID
<td>  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 \c int and use as row ID to retrieve the thread information from
\ref CRP_TBL_MDMP_THREADS table.


<tr>
<td> \ref CRP_COL_EXCEPTION_MODULE_ROWID
<td>
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 \c int and use as row ID to retrieve the module information from
\ref CRP_TBL_MDMP_MODULES table.

<tr>
<td> \ref CRP_COL_EXCEPTION_THREAD_STACK_MD5
<td>
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 <b>CrashRpt v1.2.7 and later</b>

</table>

\section list_of_column_ids_for_mdmpmodules The List of Column IDs of the CRP_TBL_MDMP_MODULES Table

<table>

<tr>
<td> <b>Column ID</b>
<td> <b>Description</b>

<tr>
<td> \ref CRP_COL_MODULE_NAME
<td> 
Short module name (filename+extension).

Example: "ntdll.dll"

<tr>
<td> \ref CRP_COL_MODULE_IMAGE_NAME
<td> 
Path to module image file.

Example: "C:\Program Files\MyApp\msvcr80.dll"

<tr>
<td> \ref CRP_COL_MODULE_BASE_ADDRESS
<td> Module base load address. Hexadecimal value.

Example: "0x80000000"

<tr>
<td> \ref CRP_COL_MODULE_SIZE
<td> Module size in bytes. Decimal.

Example: "560008"

<tr>
<td> \ref CRP_COL_MODULE_LOADED_PDB_NAME
<td> 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"

<tr>
<td> \ref CRP_COL_MODULE_LOADED_IMAGE_NAME
<td> 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 <b>CrashRpt v1.2.8 and later</b>

</table>

\section list_of_column_ids_for_mdmpthreads The List of Column IDs of the CRP_TBL_MDMP_THREADS Table

<table>

<tr>
<td> <b>Column ID</b>
<td> <b>Description</b>

<tr>
<td> \ref CRP_COL_THREAD_ID
<td> Thread identifier. Hexadecimal value. Thread ID is assigned 
on thread creation by \b CreateThread() WinAPI function. 

Example: "0x1ff"

<tr>
<td> \ref CRP_COL_THREAD_STACK_TABLEID
<td> Table ID of the stack frace table for this thread. Decimal. 
Pass this string to crpGetProperty() as table ID.

Example values are implementation specific.

</table>

\section list_of_column_ids_for_stacktrace The List of Column IDs of a Stack Trace Table

<table>

<tr>
<td> <b>Column ID</b>
<td> <b>Description</b>

<tr>
<td> \ref CRP_COL_STACK_MODULE_ROWID
<td> Row index of a module in \ref CRP_TBL_MDMP_MODULES table. 
Use this value to get module information for this stack frame. 
Convert this value to \c 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.

<tr>
<td> \ref CRP_COL_STACK_SYMBOL_NAME
<td> 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"

<tr>
<td> \ref CRP_COL_STACK_OFFSET_IN_SYMBOL
<td> Offset in symbol, hexadecimal value.

Example: "0x1f"

<tr>
<td> \ref CRP_COL_STACK_SOURCE_FILE
<td> Path to source file.

Example: "D:\MyProject\src\memfuncs.cpp"

<tr>
<td> \ref CRP_COL_STACK_SOURCE_LINE
<td> Source file line number. Decimal.

Example: "100"

<tr>
<td> \ref CRP_COL_STACK_ADDR_PC_OFFSET
<td> Program counter CPU register's value for this stack frame. Hexadecimal.

Example: "0x800000435"

</table>

\section list_of_column_ids_for_mdmploadlog The List of Column IDs of the CRP_MDMP_LOAD_LOG Table

<table>

<tr>
<td> <b>Column ID</b>
<td> <b>Description</b>

<tr>
<td> \ref CRP_COL_LOAD_LOG_ENTRY
<td> A entry of the minidump loading log. 

This property may present in reports generated by <b>CrashRpt v1.2.8 and later</b>

Example values are implementation specific.

</table>

*/