Condividi tramite

Funzioni globali di debug e segnalazione errori

  • Articolo

Queste funzioni forniscono utili funzionalità di debug e traccia.

Nome Descrizione
AtlHresultFromLastError Restituisce un GetLastError codice di errore sotto forma di HRESULT.
AtlHresultFromWin32 Converte un codice di errore Win32 in HRESULT.
AtlReportError Configura per IErrorInfo fornire i dettagli dell'errore a un client.
AtlThrow Genera un oggetto CAtlException.
AtlThrowLastWin32 Chiamare questa funzione per segnalare un errore in base al risultato della funzione Windows GetLastError.

AtlHresultFromLastError

Restituisce il valore del codice dell'ultimo errore del thread chiamante sotto forma di HRESULT.

HRESULT AtlHresultFromLastError();

Osservazioni:

AtlHresultFromLastError chiama GetLastError per ottenere l'ultimo errore e restituisce l'errore dopo la conversione in HRESULT usando la macro HRESULT_FROM_WIN32.

Requisiti

Intestazione: atlcomcli.h

AtlHresultFromWin32

Converte un codice di errore Win32 in HRESULT.

AtlHresultFromWin32(DWORD error);

Parametri

error
Valore di errore da convertire.

Osservazioni:

Converte un codice di errore Win32 in hresult usando la macro HRESULT_FROM_WIN32.

Nota

Anziché usare HRESULT_FROM_WIN32(GetLastError()), usare la funzione AtlHresultFromLastError.

Requisiti

Intestazione: atlcomcli.h

AtlReportError

Configura l'interfaccia IErrorInfo per fornire informazioni sugli errori ai client dell'oggetto.

HRESULT WINAPI AtlReportError(
    const CLSID& clsid,
    LPCOLESTR lpszDesc,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0);

HRESULT WINAPI AtlReportError(
    const CLSID& clsid,
    LPCOLESTR lpszDesc,
    DWORD dwHelpID,
    LPCOLESTR lpszHelpFile,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0);

HRESULT WINAPI AtlReportError(
    const CLSID& clsid,
    LPCSTR lpszDesc,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0);

HRESULT WINAPI AtlReportError(
    const CLSID& clsid,
    LPCSTR lpszDesc,
    DWORD dwHelpID,
    LPCSTR lpszHelpFile,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0);

HRESULT WINAPI AtlReportError(
    const CLSID& clsid,
    UINT nID,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0,
    HINSTANCE hInst = _AtlBaseModule.GetResourceInstance());

HRESULT WINAPI AtlReportError(
    const CLSID& clsid,
    UINT nID,
    DWORD dwHelpID,
    LPCOLESTR lpszHelpFile,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0,
    HINSTANCE hInst = _AtlBaseModule.GetResourceInstance());

Parametri

Clsid
[in] CLSID dell'oggetto che segnala l'errore.

lpszDesc
[in] Stringa che descrive l'errore. Le versioni Unicode specificano che lpszDesc è di tipo LPCOLESTR. La versione ANSI specifica un tipo di LPCSTR.

Iid
[in] IID dell'interfaccia che definisce l'errore o GUID_NULL se l'errore è definito dal sistema operativo.

hRes
[in] HRESULT che si desidera restituire al chiamante.

nID
[in] Identificatore della risorsa in cui è archiviata la stringa di descrizione dell'errore. Questo valore deve essere compreso tra 0x0200 e 0xFFFF, inclusi. Nelle compilazioni di debug, un AS edizione Standard RT genererà un risultato se nID non indicizza una stringa valida. Nelle build di rilascio, la stringa di descrizione dell'errore verrà impostata su "Errore sconosciuto".

dwHelpID
[in] Identificatore del contesto della Guida per l'errore.

lpszHelpFile
[in] Percorso e nome del file della Guida che descrive l'errore.

hInst
[in] Handle per la risorsa. Per impostazione predefinita, questo parametro è __AtlBaseModuleModule::GetResourceInstance, dove __AtlBaseModuleModule è l'istanza globale di CAtlBaseModule o una classe derivata da essa.

Valore restituito

Se il parametro hRes è diverso da zero, restituisce il valore di hRes. Se hRes è zero, le prime quattro versioni del AtlReportError DISP_E_EXCEPTION restituito. Le ultime due versioni restituiscono il risultato della macro MAKE_HRESULT( 1, FACILITY_ITF,nID).

Osservazioni:

La stringa lpszDesc viene utilizzata come descrizione testuale dell'errore. Quando il client riceve hRes restituito da AtlReportError, il client può accedere alla IErrorInfo struttura per informazioni dettagliate sull'errore.

Esempio

STDMETHODIMP CMyControl::MyErrorProneMethod()
{
   BOOL bSucceeded = ErrorProneFunc();
   if (bSucceeded)
      return S_OK;
   else
      // hRes is set to DISP_E_EXCEPTION
      return AtlReportError(GetObjectCLSID(), L"My error message");
}

Attenzione

Non usare AtlReportError nei gestori catch C++. Alcune sostituzioni di queste funzioni usano internamente le macro di conversione di stringhe ATL, che a loro volta usano la _alloca funzione internamente. L'uso AtlReportError di in un gestore catch C++ può causare eccezioni nei gestori catch C++.

Requisiti

Intestazione: atlcom.h

AtlThrow

Chiamare questa funzione per segnalare un errore in base a un codice di stato HRESULT.

__declspec(noreturn) inline void AtlThrow(HRESULT hr);

Parametri

Hr
Valore HRESULT standard.

Osservazioni:

Questa funzione viene usata dal codice ATL e MFC in caso di condizione di errore. Può anche essere chiamato dal proprio codice. L'implementazione predefinita di questa funzione dipende dalla definizione del simbolo _ATL_NO_EXCEPTIONS e dal tipo di progetto, MFC o ATL.

In tutti i casi, questa funzione esegue l'analisi del valore HRESULT nel debugger.

In Visual Studio 2015 Update 3 e versioni successive, questa funzione viene attribuita __declspec(noreturn) per evitare avvisi SAL spuri.

Se _ATL_NO_EXCEPTIONS non è definito in un progetto MFC, questa funzione genera un'eccezione CMemoryException o COleException in base al valore di HRESULT.

Se _ATL_NO_EXCEPTIONS non è definito in un progetto ATL, la funzione genera un'eccezione CAtlException.

Se _ATL_NO_EXCEPTIONS è definito, la funzione genera un errore di asserzione anziché generare un'eccezione.

Per i progetti ATL, è possibile fornire la propria implementazione di questa funzione da usare da ATL in caso di errore. A tale scopo, definire la propria funzione con la stessa firma di AtlThrow e #define AtlThrow come nome della funzione. Questa operazione deve essere eseguita prima di includere atlexcept.h (il che significa che deve essere eseguita prima di includere eventuali intestazioni ATL poiché atlbase.h include atlexcept.h). Attribuire la funzione __declspec(noreturn) per evitare avvisi SAL spuri.

Esempio

// Constructors and operators cannot return error codes, and
// so they are the place where exceptions are generally used.
class CMyClass
{
private:
   CComPtr<IBuddy> m_spBuddy;
public:
   CMyClass()
   {
      HRESULT hr = m_spBuddy.CoCreateInstance(CLSID_Buddy);
      if (FAILED(hr))
         AtlThrow(hr);
   }
   //   methods ..
};

Requisiti

Intestazione: atldef.h

AtlThrowLastWin32

Chiamare questa funzione per segnalare un errore in base al risultato della funzione Windows GetLastError.

inline void AtlThrowLastWin32();

Osservazioni:

Questa funzione traccia il risultato di GetLastError nel debugger.

Se _ATL_NO_EXCEPTIONS non è definito in un progetto MFC, questa funzione genera un'eccezione CMemoryException o COleExceptionin base al valore restituito da GetLastError.

Se _ATL_NO_EXCEPTIONS non è definito in un progetto ATL, la funzione genera un'eccezione CAtlException.

Se _ATL_NO_EXCEPTIONS è definito, la funzione genera un errore di asserzione anziché generare un'eccezione.

Requisiti

Intestazione: atldef.h

Vedi anche

Funzioni
Macro di debug e segnalazione errori