| crashrpt |
A crash reporting system for Windows applications

# CrashRptProbe Functions

## Defines

#define | crpOpenErrorReport crpOpenErrorReportA
| Character set-independent mapping of crpOpenErrorReportW() and crpOpenErrorReportA() functions.
#define | crpGetProperty crpGetPropertyA
| Character set-independent mapping of crpGetPropertyW() and crpGetPropertyA() functions.
#define | crpExtractFile crpExtractFileA
| Character set-independent mapping of crpExtractFileW() and crpExtractFileA() functions.
#define | crpGetLastErrorMsg crpGetLastErrorMsgA
| Defines character set-independent mapping for crpGetLastErrorMsgW() and crpGetLastErrorMsgA().

## Functions

int | crpOpenErrorReportW (LPCWSTR pszFileName, LPCWSTR pszMd5Hash, LPCWSTR pszSymSearchPath, DWORD dwFlags, CrpHandle *phReport)
| Opens a zipped crash report file.
int | crpOpenErrorReportA (LPCSTR pszFileName, LPCSTR pszMd5Hash, LPCSTR pszSymSearchPath, DWORD dwFlags, CrpHandle *phReport)
int | crpCloseErrorReport (CrpHandle hReport)
| Closes the crash report.
int | crpGetPropertyW (CrpHandle hReport, LPCWSTR lpszTableId, LPCWSTR lpszColumnId, INT nRowIndex, LPWSTR lpszBuffer, ULONG cchBuffSize, PULONG pcchCount)
| Retrieves a string property from crash report.
int | crpGetPropertyA (CrpHandle hReport, LPCSTR lpszTableId, LPCSTR lpszColumnId, INT nRowIndex, LPSTR lpszBuffer, ULONG cchBuffSize, PULONG pcchCount)
int | crpExtractFileW (CrpHandle hReport, LPCWSTR lpszFileName, LPCWSTR lpszFileSaveAs, BOOL bOverwriteExisting)
| Extracts a file from the opened error report.
int | crpExtractFileA (CrpHandle hReport, LPCSTR lpszFileName, LPCSTR lpszFileSaveAs, BOOL bOverwriteExisting)
int | crpGetLastErrorMsgW (LPWSTR pszBuffer, UINT cchBuffSize)
| Gets the last CrashRptProbe error message.
int | crpGetLastErrorMsgA (LPSTR pszBuffer, UINT cchBuffSize)

## Detailed Description

## Function Documentation

int crpCloseErrorReport | ( | CrpHandle | hReport | ) |

Closes the crash report.

Returns:
  This function returns zero on success.

Parameters:

  `[in]` | hReport | Handle to the opened error report.

Remarks:

Use this function to close the error report previously opened with crpOpenErrorReport() function.

If this function fails, use crpGetLastErrorMsg() function to get the error message.

See also:
  crpOpenErrorReport(), crpOpenErrorReportW(), crpOpenErrorReportA(), crpGetLastErrorMsg()

int crpExtractFileA | ( | CrpHandle | hReport,
|  | LPCSTR | lpszFileName,
|  | LPCSTR | lpszFileSaveAs,
|  | BOOL | bOverwriteExisting |
| ) |  |  |

Extracts a file from the opened error report.

Returns:
  This function returns zero if succeeded.

Parameters:

  `[in]` | hReport | Handle to the opened error report.
  `[in]` | lpszFileName | The name of the file to extract.
  `[in]` | lpszFileSaveAs | The resulting name of the extracted file.
  `[in]` | bOverwriteExisting | Overwrite the destination file if it already exists?

Remarks:

Use this function to extract a compressed file from the error report (ZIP) file.

lpszFileName parameter should be the name of the file to extract. For more information about enumerating file names, see Examples of Using CrashRptProbe API.

lpszFileSaveAs defines the name of the file to extract to.

bOverwriteExisting flag defines the behavior when the destination file already exists. If this parameter is TRUE, the file is overwritten, otherwise the function fails.

If this function fails, use crpGetLastErrorMsg() to retrieve the error message.

Note:
  The crpExtractFileW() and crpExtractFileA() are wide character and multibyte character versions of crpExtractFile().

See also:
  crpExtractFileA(), crpExtractFileW(), crpExtractFile()

int crpExtractFileW | ( | CrpHandle | hReport,
|  | LPCWSTR | lpszFileName,
|  | LPCWSTR | lpszFileSaveAs,
|  | BOOL | bOverwriteExisting |
| ) |  |  |

Extracts a file from the opened error report.

Returns:
  This function returns zero if succeeded.

Parameters:

  `[in]` | hReport | Handle to the opened error report.
  `[in]` | lpszFileName | The name of the file to extract.
  `[in]` | lpszFileSaveAs | The resulting name of the extracted file.
  `[in]` | bOverwriteExisting | Overwrite the destination file if it already exists?

Remarks:

Use this function to extract a compressed file from the error report (ZIP) file.

lpszFileName parameter should be the name of the file to extract. For more information about enumerating file names, see Examples of Using CrashRptProbe API.

lpszFileSaveAs defines the name of the file to extract to.

bOverwriteExisting flag defines the behavior when the destination file already exists. If this parameter is TRUE, the file is overwritten, otherwise the function fails.

If this function fails, use crpGetLastErrorMsg() to retrieve the error message.

Note:
  The crpExtractFileW() and crpExtractFileA() are wide character and multibyte character versions of crpExtractFile().

See also:
  crpExtractFileA(), crpExtractFileW(), crpExtractFile()

int crpGetLastErrorMsgA | ( | LPSTR | pszBuffer,
|  | UINT | cchBuffSize |
| ) |  |  |

Gets the last CrashRptProbe error message.

Returns:
  This function returns length of error message in characters.

Parameters:

  `[out]` | pszBuffer | Pointer to the buffer.
  `[in]` | cchBuffSize | Size of buffer in characters.

Remarks:

This function gets the last CrashRptProbe error message. You can use this function to retrieve the text status of the last called CrashRptProbe function.

If buffer is too small for the error message, the message is truncated.

Note:
  crpGetLastErrorMsgW() and crpGetLastErrorMsgA() are wide-character and multi-byte character versions of crpGetLastErrorMsg(). The crpGetLastErrorMsg() macro defines character set independent mapping.

The following example shows how to use crpGetLastErrorMsg() function.

      // .. call some CrashRptProbe function

      // Get the status message
      TCHAR szErrorMsg[256];
      crpGetLastErrorMsg(szErrorMsg, 256);

See also:
  crpGetLastErrorMsgA(), crpGetLastErrorMsgW(), crpGetLastErrorMsg()

int crpGetLastErrorMsgW | ( | LPWSTR | pszBuffer,
|  | UINT | cchBuffSize |
| ) |  |  |

Gets the last CrashRptProbe error message.

Returns:
  This function returns length of error message in characters.

Parameters:

  `[out]` | pszBuffer | Pointer to the buffer.
  `[in]` | cchBuffSize | Size of buffer in characters.

Remarks:

This function gets the last CrashRptProbe error message. You can use this function to retrieve the text status of the last called CrashRptProbe function.

If buffer is too small for the error message, the message is truncated.

Note:
  crpGetLastErrorMsgW() and crpGetLastErrorMsgA() are wide-character and multi-byte character versions of crpGetLastErrorMsg(). The crpGetLastErrorMsg() macro defines character set independent mapping.

The following example shows how to use crpGetLastErrorMsg() function.

      // .. call some CrashRptProbe function

      // Get the status message
      TCHAR szErrorMsg[256];
      crpGetLastErrorMsg(szErrorMsg, 256);

See also:
  crpGetLastErrorMsgA(), crpGetLastErrorMsgW(), crpGetLastErrorMsg()

int crpGetPropertyA | ( | CrpHandle | hReport,
|  | LPCSTR | lpszTableId,
|  | LPCSTR | lpszColumnId,
|  | INT | nRowIndex,
|  | LPSTR | lpszBuffer,
|  | ULONG | cchBuffSize,
|  | PULONG | pcchCount |
| ) |  |  |

Retrieves a string property from crash report.

Returns:
  This function returns zero on success, with one exception (see Remarks for more information).

Parameters:

  `[in]` | hReport | Handle to the previously opened crash report.
  `[in]` | lpszTableId | Table ID.
  `[in]` | lpszColumnId | Column ID.
  `[in]` | nRowIndex | Index of the row in the table.
  `[out]` | lpszBuffer | Output buffer.
  `[in]` | cchBuffSize | Size of the output buffer in characters.
  `[out]` | pcchCount | Count of characters written to the buffer.

Remarks:

Use this function to retrieve data from the crash report that was previously opened with the crpOpenErrorReport() function.

Properties are organized into tables having rows and columns. For the list of available tables, see Using CrashRptProbe API.

To get the number of rows in a table, pass the constant CRP_META_ROW_COUNT as column ID. In this case the function returns number of rows as its return value, or negative value on failure.

In all other cases the function returns zero on success.

Some properties are loaded from crash description XML file, while others are loaded from crash minidump file. The minidump is loaded once when you retrive a property from it. This reduces the overall processing time.

hReport should be the handle to the opened error report.

lpszTableId represente the ID of the table.

lpszColumnId represents the ID of the column in the table.

nRowIndex defines the zero-based index of the row in the table.

lpszBuffer defines the buffer where retrieved property value will be placed. If this parameter is NULL, it is ignored and pcchCount is set with the required size in characters of the buffer.

cchBuffSize defines the buffer size in characters. To calculate required buffer size, set lpszBuffer with NULL, the function will set pcchCount with the number of characters required.

pcchCount is set with the actual count of characters copied to the lpszBuffer. If this parameter is NULL, it is ignored.

If this function fails, use crpGetLastErrorMsg() function to get the error message.

For code examples of using this function, see Examples of Using CrashRptProbe API.

Note:
  The crpGetPropertyW() and crpGetPropertyA() are wide character and multibyte character versions of crpGetProperty().

See also:
  crpGetPropertyW(), crpGetPropertyA(), crpOpenErrorReport(), crpGetLastErrorMsg()

int crpGetPropertyW | ( | CrpHandle | hReport,
|  | LPCWSTR | lpszTableId,
|  | LPCWSTR | lpszColumnId,
|  | INT | nRowIndex,
|  | LPWSTR | lpszBuffer,
|  | ULONG | cchBuffSize,
|  | PULONG | pcchCount |
| ) |  |  |

Retrieves a string property from crash report.

Returns:
  This function returns zero on success, with one exception (see Remarks for more information).

Parameters:

  `[in]` | hReport | Handle to the previously opened crash report.
  `[in]` | lpszTableId | Table ID.
  `[in]` | lpszColumnId | Column ID.
  `[in]` | nRowIndex | Index of the row in the table.
  `[out]` | lpszBuffer | Output buffer.
  `[in]` | cchBuffSize | Size of the output buffer in characters.
  `[out]` | pcchCount | Count of characters written to the buffer.

Remarks:

Use this function to retrieve data from the crash report that was previously opened with the crpOpenErrorReport() function.

Properties are organized into tables having rows and columns. For the list of available tables, see Using CrashRptProbe API.

To get the number of rows in a table, pass the constant CRP_META_ROW_COUNT as column ID. In this case the function returns number of rows as its return value, or negative value on failure.

In all other cases the function returns zero on success.

Some properties are loaded from crash description XML file, while others are loaded from crash minidump file. The minidump is loaded once when you retrive a property from it. This reduces the overall processing time.

hReport should be the handle to the opened error report.

lpszTableId represente the ID of the table.

lpszColumnId represents the ID of the column in the table.

nRowIndex defines the zero-based index of the row in the table.

lpszBuffer defines the buffer where retrieved property value will be placed. If this parameter is NULL, it is ignored and pcchCount is set with the required size in characters of the buffer.

cchBuffSize defines the buffer size in characters. To calculate required buffer size, set lpszBuffer with NULL, the function will set pcchCount with the number of characters required.

pcchCount is set with the actual count of characters copied to the lpszBuffer. If this parameter is NULL, it is ignored.

If this function fails, use crpGetLastErrorMsg() function to get the error message.

For code examples of using this function, see Examples of Using CrashRptProbe API.

Note:
  The crpGetPropertyW() and crpGetPropertyA() are wide character and multibyte character versions of crpGetProperty().

See also:
  crpGetPropertyW(), crpGetPropertyA(), crpOpenErrorReport(), crpGetLastErrorMsg()

int crpOpenErrorReportA | ( | LPCSTR | pszFileName,
|  | LPCSTR | pszMd5Hash,
|  | LPCSTR | pszSymSearchPath,
|  | DWORD | dwFlags,
|  | CrpHandle * | phReport |
| ) |  |  |

Opens a zipped crash report file.

Returns:
  This function returns zero on success.

Parameters:

  `[in]` | pszFileName | Zipped report file name.
  `[in]` | pszMd5Hash | String containing MD5 hash for the ZIP file data.
  `[in]` | pszSymSearchPath | Symbol files (PDB) search path.
  `[in]` | dwFlags | Flags, reserved for future use.
  `[out]` | phReport | Handle to the opened crash report.

Remarks:

Use this function to open a ZIP archive containing an error report. The error report typically contains several compressed files, such as XML crash description file, crash minidump file, and (optionally) application-defined files.

pszFileName should be the name of the error report (ZIP file) to open. Absolute or relative path accepted. This parameter is required.

pszMd5Hash is a string containing the MD5 hash calculated for pszFileName. The MD5 hash is a sequence of 16 characters being used for integrity checks. If this parameter is NULL, integrity check is not performed.

If the error report is delivered by HTTP, the MD5 hash can be extracted by server-side script from the 'md5' parameter. When the error report is delivered by email, the MD5 hash is attached to the mail message. The integrity check can be performed to ensure the error report was not corrupted during delivery. For more information, see Sending Error Reports.

pszSymSearchPath parameter defines where to look for symbols files (*.PDB). You can specify the list of semicolon-separated directories to search in. If this parameter is NULL, the default search sequence is used. For the default search sequence, see the documentation for SymInitialize() function in MSDN.

Symbol files are required for crash report processing. They contain various information used by the debugger. For more information about saving symbol files, see Preparing to Software Release.

dwFlags is currently not used, should be zero.

phReport parameter receives the handle to the opened crash report. If the function fails, this parameter becomes zero.

This function does the following when opening report file:

- It performs integrity checks for the error report being opened, if MD5 hash is specified.
- It searches for crashrpt.xml and crashdump.dml files inside of ZIP archive, if such files do not present, it assumes the report was generated by CrashRpt v1.0. In such case it searches for any file having *.dmp or *.xml extension and assumes these are valid XML and DMP file.
- It extracts and loads the XML file and checks its structure.
- It extracts the minidump file to the temporary location.

On failure, use crpGetLastErrorMsg() function to get the last error message.

Use the crpCloseErrorReport() function to close the opened error report.

Note:

The crpOpenErrorReportW() and crpOpenErrorReportA() are wide character and multibyte character versions of crpOpenErrorReport().

See also:
  crpCloseErrorReport()

int crpOpenErrorReportW | ( | LPCWSTR | pszFileName,
|  | LPCWSTR | pszMd5Hash,
|  | LPCWSTR | pszSymSearchPath,
|  | DWORD | dwFlags,
|  | CrpHandle * | phReport |
| ) |  |  |

Opens a zipped crash report file.

Returns:
  This function returns zero on success.

Parameters:

  `[in]` | pszFileName | Zipped report file name.
  `[in]` | pszMd5Hash | String containing MD5 hash for the ZIP file data.
  `[in]` | pszSymSearchPath | Symbol files (PDB) search path.
  `[in]` | dwFlags | Flags, reserved for future use.
  `[out]` | phReport | Handle to the opened crash report.

Remarks:

Use this function to open a ZIP archive containing an error report. The error report typically contains several compressed files, such as XML crash description file, crash minidump file, and (optionally) application-defined files.

pszFileName should be the name of the error report (ZIP file) to open. Absolute or relative path accepted. This parameter is required.

pszMd5Hash is a string containing the MD5 hash calculated for pszFileName. The MD5 hash is a sequence of 16 characters being used for integrity checks. If this parameter is NULL, integrity check is not performed.

If the error report is delivered by HTTP, the MD5 hash can be extracted by server-side script from the 'md5' parameter. When the error report is delivered by email, the MD5 hash is attached to the mail message. The integrity check can be performed to ensure the error report was not corrupted during delivery. For more information, see Sending Error Reports.

pszSymSearchPath parameter defines where to look for symbols files (*.PDB). You can specify the list of semicolon-separated directories to search in. If this parameter is NULL, the default search sequence is used. For the default search sequence, see the documentation for SymInitialize() function in MSDN.

Symbol files are required for crash report processing. They contain various information used by the debugger. For more information about saving symbol files, see Preparing to Software Release.

dwFlags is currently not used, should be zero.

phReport parameter receives the handle to the opened crash report. If the function fails, this parameter becomes zero.

This function does the following when opening report file:

- It performs integrity checks for the error report being opened, if MD5 hash is specified.
- It searches for crashrpt.xml and crashdump.dml files inside of ZIP archive, if such files do not present, it assumes the report was generated by CrashRpt v1.0. In such case it searches for any file having *.dmp or *.xml extension and assumes these are valid XML and DMP file.
- It extracts and loads the XML file and checks its structure.
- It extracts the minidump file to the temporary location.

On failure, use crpGetLastErrorMsg() function to get the last error message.

Use the crpCloseErrorReport() function to close the opened error report.

Note:

The crpOpenErrorReportW() and crpOpenErrorReportA() are wide character and multibyte character versions of crpOpenErrorReport().

See also:
  crpCloseErrorReport()