XtfGetErrorText

Provides a user friendly error message and trouble shooting guidance for the provided HRESULT.

Syntax

HRESULT XtfGetErrorText(
         HRESULT HResult,
         PWSTR *errorMessageBuffer,
         UINT32 *errorMessageBufferLength,
         PWSTR *userActionTextBuffer,
         UINT32 *userActionTextBufferLength
)  

Parameters

HResult
Type: HRESULT 

[in] The HRESULT to lookup up the error message and action text for.

errorMessageBuffer
Type: PWSTR *

[out] A pointer to the buffer that receives the error message as a null terminated string. To determine the required buffer length, set this parameter to nullptr and the errorMessageBufferLength parameter to 0. When the function returns errorMessageBufferLength will be set to the length of the required buffer in WCHARs including the terminating null character.

errorMessageBufferLength
Type: UINT32 *

[in, out] On input the length of the error message buffer in WCHARs. The buffer length must include room for a terminating null character. On output the required length of errorMessageBuffer in WCHARs

userActionTextBuffer
Type: PWSTR *

[out] A pointer to the buffer that receives the user action text as a null terminated string. To determine the required buffer length, set this parameter to nullptr and the userActionTextBufferLength parameter to 0. When the function returns userActionTextBufferLength will be set to the length of the required buffer in WCHARs including the terminating null character.

userActionTextBufferLength
Type: UINT32 *

[in, out] The length of the error message buffer in WCHARs. The buffer length must include room for a terminating null character.

Return value

Type: HRESULT 

HRESULT success or error code.

S_OK indicates the function succeeded and errorMessageBuffer and userActionTextBuffer contain the text for the give HRESULT.

HRESULT_FROM_WIN32(ERROR_MORE_DATA) indicates the buffer supplied for errorMessageBuffer or userActionTextBuffer was not large enough. The required buffer lengths are contained in errorMessageBufferLength and userActionTextBufferLength.

Any other value indicates an unexpected error occurred.

Remarks

If the HRESULT passed to XtfGetErrorText is not a recognized XTF error code, the resulting error text returned in errorMessageBuffer will be “Unspecified error”. The caller can use this result to check whether the provided HRESULT is a recognized XTF code.

Requirements

Header: Declared in XtfApi.h.

Library: Use XtfApi.lib.