Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.
This topic has not yet been rated - Rate this topic

RoTransformErrorW function

Reports a transformed error and an informative string to an attached debugger.

Syntax


BOOL WINAPI RoTransformErrorW(
  _In_  HRESULT oldError,
  _In_  HRESULT newError,
  _In_  UINT cchMax,
  _In_  PCWSTR message
);

Parameters

oldError [in]

Type: HRESULT

The original error code associated with the error condition.

newError [in]

Type: HRESULT

The custom error code to associate with the error condition. If oldError and newError are the same, or both are success codes, such as S_OK, the function has no effect and returns FALSE.

cchMax [in]

Type: UINT

The maximum number of characters in message, excluding the terminating null character. If the value is 0, the string is read to the first null character or 512 characters, whichever is less. If cchMax is greater than 512, all characters after 512 are ignored.

message [in]

Type: PCWSTR

An informative string to help developers to correct the reported error condition. The maximum length is 512 characters, including the trailing null character; longer strings are truncated.

If the string is empty, the function succeeds but no error information is reported. It is recommended that you always provide an informative string.

If message is NULL, the function succeeds and reports the generic string in Winerror.h if available or the generic string associated with E_FAIL.

This function does not support embedded null characters, so only the characters before the first null are reported.

Return value

Type: BOOL

Return codeDescription
TRUE

The error message was reported successfully.

FALSE

message is NULL or points to an empty string, or oldError and newError are the same, or both are success codes.

 

Remarks

Use the RoTransformErrorW function to substitute a custom error code for an existing error condition. For example, if the current error condition is E_FAIL, you can substitute a more specific error code, such as E_FILENOTFOUND and report the transformed error to an attached debugger.

The behavior of the RoTransformErrorW function is otherwise the same as the RoOriginateErrorW function.

If the UseSetErrorInfo flag is set by calling the RoSetErrorReportingFlags function, and the calling thread has been initialized in COM, the function creates an appropriate error object that supports IRestrictedErrorInfo and associates it with the COM channel by calling SetErrorInfo. If the thread has not been initialized into COM, the call will still succeed with no error, but the error will not be associated with the COM channel.

Note  This is no ANSI version of the RoTransformErrorW function. Message strings are required to be Unicode.

Windows Phone 8: This API is supported.

Windows Phone 8.1: This API is supported.

Requirements

Minimum supported client

Windows 8 [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2012 [desktop apps | Windows Store apps]

Header

Roerrorapi.h

See also

RoGetErrorReportingFlags
RO_ERROR_REPORTING_FLAGS
RoSetErrorReportingFlags
RoOriginateErrorW
RoTransformError

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

Show:
© 2014 Microsoft. All rights reserved.