Funzione RoOriginateError (roerrorapi.h)

Articolo
03/05/2024

Segnala un errore e una stringa informativa a un debugger collegato.

Sintassi

BOOL RoOriginateError(
  [in] HRESULT error,
  [in] HSTRING message
);

Parametri

[in] error

Tipo: HRESULT

Codice di errore associato alla condizione di errore. Se l'errore è un codice riuscito, ad esempio S_OK, la funzione non ha alcun effetto e restituisce FALSE. Questo comportamento consente di chiamare la funzione quando non si è verificato alcun errore senza causare un messaggio di errore indesiderato.

[in] message

Tipo: HSTRING

Stringa informativa che consente agli sviluppatori di correggere la condizione di errore segnalata. La lunghezza massima è di 512 caratteri, incluso il carattere NUL finale; le stringhe più lunghe vengono troncate.

Se la stringa è vuota, la funzione ha esito positivo ma non viene segnalata alcuna informazione sull'errore. È consigliabile fornire sempre una stringa informativa.

Se il messaggio è NULL, la funzione ha esito positivo e segnala la stringa generica in Winerror.h, se disponibile o la stringa generica associata a E_FAIL.

Questa funzione non supporta i caratteri NUL incorporati, quindi vengono segnalati solo i caratteri prima del primo NUL .

La stringa del messaggio deve essere localizzata.

Valore restituito

Tipo: BOOL

Codice restituito	Descrizione
TRUE	Il messaggio di errore è stato segnalato correttamente.
FALSE	message è NULL o punta a una stringa vuota oppure l'errore è un codice di operazione riuscita.

Commenti

Utilizzare la funzione RoOriginateError per segnalare una condizione di errore e un messaggio corrispondente a un debugger. Questa funzione non esegue la registrazione o la traccia degli eventi.

L'errore viene comunicato al debugger generando un'eccezione strutturata. Questa eccezione viene intercettata dal debugger collegato e i parametri di eccezione contengono sia l'errore che la stringa del messaggio . Il debugger può visualizzare questi parametri all'utente.

A seconda della configurazione corrente del debugger, la funzione RoOriginateError può causare l'arresto dell'esecuzione nel debugger nel sito dell'eccezione.

Se il flag UseSetErrorInfo viene impostato chiamando la funzione RoSetErrorReportingFlags e il thread chiamante è stato inizializzato in COM, la funzione crea un oggetto errore appropriato che supporta IRestrictedErrorInfo e lo associa al canale COM chiamando SetErrorInfo. Se il thread non è stato inizializzato in COM, la chiamata avrà comunque esito positivo senza errori, ma l'errore non verrà associato al canale COM.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8 [app desktop \| App UWP]
Server minimo supportato	Windows Server 2012 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	roerrorapi.h
Libreria	RuntimeObject.lib