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()