Função RoTransformError (roerrorapi.h)

Artigo
08/25/2023

Relata um erro modificado e uma cadeia de caracteres informativa para um depurador anexado.

Sintaxe

BOOL RoTransformError(
  [in] HRESULT oldError,
  [in] HRESULT newError,
  [in] HSTRING message
);

Parâmetros

[in] oldError

Tipo: HRESULT

O código de erro original associado à condição de erro.

[in] newError

Tipo: HRESULT

Um código de erro diferente a ser associado à condição de erro. Se oldError e newError forem iguais ou ambos forem códigos de êxito, como S_OK, a função não terá efeito e retornará FALSE.

[in] message

Tipo: HSTRING

Uma cadeia de caracteres informativa para ajudar os desenvolvedores a corrigir a condição de erro relatada. O comprimento máximo é de 512 caracteres, incluindo o caractere nulo à direita; cadeias de caracteres mais longas são truncadas.

Se a cadeia de caracteres estiver vazia, a função terá êxito, mas nenhuma informação de erro será relatada. É recomendável que você sempre forneça uma cadeia de caracteres informativa.

Se message for NULL, a função terá êxito e relatará a cadeia de caracteres genérica em Winerror.h se disponível ou a cadeia de caracteres genérica associada a E_FAIL.

Embora a cadeia de caracteres de mensagem seja um HSTRING, a função RoTransformError não dá suporte a caracteres nulos inseridos, portanto, somente os caracteres antes do primeiro nulo são relatados.

Retornar valor

Tipo: BOOL

Código de retorno	Descrição
TRUE	A mensagem de erro foi relatada com êxito.
FALSE	message é NULL ou aponta para uma cadeia de caracteres vazia ou oldError e newError são iguais ou ambos são códigos de êxito.

Comentários

Use a função RoTransformError para substituir um código de erro personalizado por uma condição de erro existente. Por exemplo, se a condição de erro atual for E_FAIL, você poderá substituir um código de erro mais específico, como E_FILENOTFOUND, e relatar o erro transformado para um depurador anexado.

O comportamento da função RoTransformError é, de outra forma, o mesmo que a função RoTransformErrorW .

Se o sinalizador UseSetErrorInfo for definido chamando a função RoSetErrorReportingFlags e o thread de chamada tiver sido inicializado em COM, a função criará um objeto de erro apropriado que dá suporte a IRestrictedErrorInfo e o associará ao canal COM chamando SetErrorInfo. Se o thread não tiver sido inicializado em COM, a chamada ainda terá êxito sem nenhum erro, mas o erro não será associado ao canal COM.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 8 [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2012 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	roerrorapi.h