Macros
#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
	crpOpenErrorReportW (__in LPCWSTR pszFileName, __in_opt LPCWSTR pszMd5Hash, __in_opt LPCWSTR pszSymSearchPath, __reserved DWORD dwFlags, __out CrpHandle *phReport)
	Opens a zipped crash report file. More...

	crpOpenErrorReportA (__in LPCSTR pszFileName, __in_opt LPCSTR pszMd5Hash, __in_opt LPCSTR pszSymSearchPath, __reserved DWORD dwFlags, __out CrpHandle *phReport)
	Opens a zipped crash report file. More...

	crpCloseErrorReport (CrpHandle hReport)
	Closes the crash report. More...

	crpGetPropertyW (CrpHandle hReport, LPCWSTR lpszTableId, LPCWSTR lpszColumnId, INT nRowIndex, __out_ecount_z(pcchBuffSize) LPWSTR lpszBuffer, ULONG cchBuffSize, __out PULONG pcchCount)
	Retrieves a string property from crash report. More...

	crpGetPropertyA (CrpHandle hReport, LPCSTR lpszTableId, LPCSTR lpszColumnId, INT nRowIndex, __out_ecount_z(pcchBuffSize) LPSTR lpszBuffer, ULONG cchBuffSize, __out PULONG pcchCount)
	Retrieves a string property from crash report. More...

	crpExtractFileW (CrpHandle hReport, LPCWSTR lpszFileName, LPCWSTR lpszFileSaveAs, BOOL bOverwriteExisting)
	Extracts a file from the opened error report. More...

	crpExtractFileA (CrpHandle hReport, LPCSTR lpszFileName, LPCSTR lpszFileSaveAs, BOOL bOverwriteExisting)
	Extracts a file from the opened error report. More...

	crpGetLastErrorMsgW (__out_ecount(cchBuffSize) LPWSTR pszBuffer, __in UINT cchBuffSize)
	Gets the last CrashRptProbe error message. More...

	crpGetLastErrorMsgA (__out_ecount(cchBuffSize) LPSTR pszBuffer, __in UINT cchBuffSize)
	Gets the last CrashRptProbe error message. More...

Detailed Description

Function Documentation

§ crpCloseErrorReport()

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

§ crpExtractFileA()

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

§ crpExtractFileW()

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

§ crpGetLastErrorMsgA()

crpGetLastErrorMsgA	(	__out_ecount(cchBuffSize) LPSTR	pszBuffer,
		__in 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()

§ crpGetLastErrorMsgW()

crpGetLastErrorMsgW	(	__out_ecount(cchBuffSize) LPWSTR	pszBuffer,
		__in 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()

§ crpGetPropertyA()

crpGetPropertyA	(	CrpHandle	hReport,
		LPCSTR	lpszTableId,
		LPCSTR	lpszColumnId,
		INT	nRowIndex,
		__out_ecount_z(pcchBuffSize) LPSTR	lpszBuffer,
		ULONG	cchBuffSize,
		__out 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()

§ crpGetPropertyW()

crpGetPropertyW	(	CrpHandle	hReport,
		LPCWSTR	lpszTableId,
		LPCWSTR	lpszColumnId,
		INT	nRowIndex,
		__out_ecount_z(pcchBuffSize) LPWSTR	lpszBuffer,
		ULONG	cchBuffSize,
		__out 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()

§ crpOpenErrorReportA()

crpOpenErrorReportA	(	__in LPCSTR	pszFileName,
		__in_opt LPCSTR	pszMd5Hash,
		__in_opt LPCSTR	pszSymSearchPath,
		__reserved DWORD	dwFlags,
		__out 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()

§ crpOpenErrorReportW()

crpOpenErrorReportW	(	__in LPCWSTR	pszFileName,
		__in_opt LPCWSTR	pszMd5Hash,
		__in_opt LPCWSTR	pszSymSearchPath,
		__reserved DWORD	dwFlags,
		__out 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()

Macros

Functions

Detailed Description

Function Documentation

§ crpCloseErrorReport()

§ crpExtractFileA()

§ crpExtractFileW()

§ crpGetLastErrorMsgA()

§ crpGetLastErrorMsgW()

§ crpGetPropertyA()

§ crpGetPropertyW()

§ crpOpenErrorReportA()

§ crpOpenErrorReportW()