Elaborazione delle eccezioni

Quando viene eseguito un programma, possono verificarsi una serie di condizioni e errori anomali denominati "eccezioni". Questi possono includere l'esaurimento della memoria, gli errori di allocazione delle risorse e l'impossibilità di trovare i file.

Microsoft Foundation Class Library usa uno schema di gestione delle eccezioni modellato in modo stretto dopo quello proposto dal comitato degli standard ANSI per C++. È necessario configurare un gestore eccezioni prima di chiamare una funzione che potrebbe riscontrare una situazione anomala. Se la funzione rileva una condizione anomala, genera un'eccezione e un controllo viene passato al gestore eccezioni.

Diverse macro incluse nella libreria di classi di Microsoft Foundation configurano i gestori eccezioni. Una serie di altre funzioni globali consente di generare eccezioni specializzate e di terminare i programmi, se necessario. Queste macro e funzioni globali rientrano nelle categorie seguenti:

• Macro di eccezione, che strutturano il gestore eccezioni.

• Funzioni di generazione di eccezioni, che generano eccezioni di tipi specifici.

• Funzioni di terminazione, che causano la terminazione del programma.

Per esempi e altri dettagli, vedere l'articolo Eccezioni.

Macro eccezioni

Nome	Descrizione
PROVARE	Definisce un blocco di codice per l'elaborazione delle eccezioni.
PRENDERE	Definisce un blocco di codice per intercettare un'eccezione dal blocco TRY precedente.
CATCH_ALL	Definisce un blocco di codice per intercettare tutte le eccezioni dal blocco TRY precedente.
AND_CATCH	Definisce un blocco di codice per intercettare altri tipi di eccezione dal blocco TRY precedente.
AND_CATCH_ALL	Definisce un blocco di codice per intercettare tutti gli altri tipi di eccezione aggiuntivi generati in un blocco TRY precedente.
END_CATCH	Termina l'ultimo blocco di codice CATCH o AND_CATCH .
END_CATCH_ALL	Termina l'ultimo blocco di codice CATCH_ALL .
THROW	Genera un'eccezione specificata.
THROW_LAST	Genera l'eccezione attualmente gestita al gestore esterno successivo.

Funzioni di generazione di eccezioni

Nome	Descrizione
AfxThrowArchiveException	Genera un'eccezione di archivio.
AfxThrowFileException	Genera un'eccezione di file.
AfxThrowInvalidArgException	Genera un'eccezione di argomento non valida.
AfxThrowMemoryException	Genera un'eccezione di memoria.
AfxThrowNotSupportedException	Genera un'eccezione non supportata.
AfxThrowResourceException	Genera un'eccezione di risorsa windows non trovata.
AfxThrowUserException	Genera un'eccezione in un'azione del programma avviata dall'utente.

MFC fornisce due funzioni di generazione di eccezioni specifiche per le eccezioni OLE:

Funzioni eccezioni OLE

Nome	Descrizione
AfxThrowOleDispatchException	Genera un'eccezione all'interno di una funzione di automazione OLE.
AfxThrowOleException	Genera un'eccezione OLE.

Per supportare le eccezioni di database, le classi di database forniscono due classi di eccezioni CDBException , e CDaoExceptione funzioni globali per supportare i tipi di eccezione:

Funzioni eccezioni DAO

Nome	Descrizione
AfxThrowDAOException	Genera un'eccezione CDaoException dal codice personalizzato.
AfxThrowDBException	Genera un'eccezione CDBException dal codice personalizzato.

MFC fornisce la funzione di terminazione seguente:

Funzioni di terminazione

Nome	Descrizione
AfxAbort	Chiamato per terminare un'applicazione quando si verifica un errore irreversibile.

TRY

Configura un blocco TRY .

TRY

Osservazioni:

Un blocco TRY identifica un blocco di codice che potrebbe generare eccezioni. Tali eccezioni vengono gestite nei blocchi CATCH e AND_CATCH seguenti. È consentita la ricorsione: le eccezioni possono essere passate a un blocco TRY esterno, ignorandole o usando la macro THROW_LAST. Terminare il blocco TRY con una macro END_CATCH o END_CATCH_ALL.

Per altre informazioni, vedere l'articolo Eccezioni.

Esempio

Vedere l'esempio per CATCH.

Requisiti

Intestazione: afx.h

PRENDERE

Definisce un blocco di codice che intercetta il primo tipo di eccezione generato nel blocco TRY precedente.

CATCH(exception_class, exception_object_pointer_name)

Parametri

exception_class
Specifica il tipo di eccezione da testare. Per un elenco delle classi di eccezioni standard, vedere classe CException.

exception_object_pointer_name
Specifica un nome per un puntatore dell'oggetto eccezione che verrà creato dalla macro. È possibile usare il nome del puntatore per accedere all'oggetto eccezione all'interno del blocco CATCH . Questa variabile viene dichiarata automaticamente.

Osservazioni:

Il codice di elaborazione delle eccezioni può interrogare l'oggetto eccezione, se necessario, per ottenere ulteriori informazioni sulla causa specifica dell'eccezione. Richiamare la macro THROW_LAST per spostare l'elaborazione al frame di eccezione esterno successivo. Terminare il blocco TRY con una macro END_CATCH.

Se exception_class è la classe CException, verranno rilevati tutti i tipi di eccezione. È possibile usare la funzione membro CObject::IsKindOf per determinare quale eccezione specifica è stata generata. Un modo migliore per intercettare diversi tipi di eccezioni consiste nell'usare istruzioni sequenziali AND_CATCH , ognuna con un tipo di eccezione diverso.

Il puntatore all'oggetto eccezione viene creato dalla macro. Non è necessario dichiararlo manualmente.

Nota

Il blocco CATCH è definito come ambito C++ delineato da parentesi graffe. Se si dichiarano delle variabili in questo ambito, è possibile accedere a queste variabili solo all'interno di tale ambito. Questo vale anche per exception_object_pointer_name.

Per altre informazioni sulle eccezioni e sulla macro CATCH, vedere l'articolo Eccezioni.

Esempio

CFile* pFile = NULL;
// Constructing a CFile object with this override may throw
// a CFile exception and won't throw any other exceptions.
// Calling CString::Format() may throw a CMemoryException,
// so we have a catch block for such exceptions, too. Any
// other exception types this function throws will be
// routed to the calling function.
TRY
{
   pFile = new CFile(_T("C:\\WINDOWS\\SYSTEM.INI"),
      CFile::modeRead | CFile::shareDenyNone);
   ULONGLONG dwLength = pFile->GetLength();
   CString str;
   str.Format(_T("Your SYSTEM.INI file is %I64u bytes long.") , dwLength);
   AfxMessageBox(str);
}
CATCH(CFileException, pEx)
{
   // Simply show an error message to the user.
   pEx->ReportError();
}
AND_CATCH(CMemoryException, pEx)
{
   // We can't recover from this memory exception, so we'll
   // just terminate the app without any cleanup. Normally, 
   // an application should do everything it possibly can to
   // clean up properly and not call AfxAbort().
   AfxAbort();
}
END_CATCH
// If an exception occurs in the CFile constructor,
// the language will free the memory allocated by new
// and will not complete the assignment to pFile.
// Thus, our cleanup code needs to test for NULL.
if (pFile != NULL)
{
   pFile->Close();
   delete pFile;
}

CATCH_ALL

Definisce un blocco di codice che intercetta tutti i tipi di eccezione generati nel blocco TRY precedente.

CATCH_ALL(exception_object_pointer_name)

Parametri

exception_object_pointer_name
Specifica un nome per un puntatore dell'oggetto eccezione che verrà creato dalla macro. È possibile utilizzare il nome del puntatore per accedere all'oggetto eccezione all'interno del blocco CATCH_ALL. Questa variabile viene dichiarata automaticamente.

Osservazioni:

Il codice di elaborazione delle eccezioni può interrogare l'oggetto eccezione, se necessario, per ottenere ulteriori informazioni sulla causa specifica dell'eccezione. Richiama la macro THROW_LAST per spostare l'elaborazione sul frame esterno dell'eccezione. Se si usa CATCH_ALL, terminare il blocco TRY con una macro END_CATCH_ALL.

Nota

Il blocco CATCH_ALL è definito come ambito C++ delineato da parentesi graffe. Se si dichiarano delle variabili in questo ambito, è possibile accedere a queste variabili solo all'interno di tale ambito.

Per altre informazioni sulle eccezioni, vedere l'articolo Eccezioni.

Esempio

Vedere l'esempio per CFile::Abort.

Requisiti

Intestazione afx.h

AND_CATCH

Definisce un blocco di codice per intercettare altri tipi di eccezione generati in un blocco TRY precedente.

AND_CATCH(exception_class, exception_object_pointer_name)

Parametri

exception_class
Specifica il tipo di eccezione da testare. Per un elenco delle classi di eccezioni standard, vedere classe CException.

exception_object_pointer_name
Nome di un puntatore a un oggetto eccezione che verrà creato dalla macro. È possibile usare il nome del puntatore per accedere all'oggetto eccezione all'interno del blocco AND_CATCH . Questa variabile viene dichiarata automaticamente.

Osservazioni:

Utilizzare la macro CATCH per intercettare un tipo di eccezione, quindi la macro AND_CATCH per intercettare ogni tipo successivo. Terminare il blocco TRY con una macro END_CATCH.

Il codice di elaborazione delle eccezioni può interrogare l'oggetto eccezione, se necessario, per ottenere ulteriori informazioni sulla causa specifica dell'eccezione. Chiamare la macro THROW_LAST all'interno del blocco AND_CATCH per spostare l'elaborazione al frame di eccezione esterno successivo. AND_CATCH contrassegna la fine del blocco CATCH o AND_CATCH precedente.

Nota

Il blocco AND_CATCH è definito come ambito C++ (delineato da parentesi graffe). Se si dichiarano variabili in questo ambito, tenere presente che sono accessibili solo all'interno di tale ambito. Questo vale anche per la variabile exception_object_pointer_name .

Esempio

Vedere l'esempio per CATCH.

Requisiti

Intestazione afx.h

AND_CATCH_ALL

Definisce un blocco di codice per intercettare altri tipi di eccezione generati in un blocco TRY precedente.

AND_CATCH_ALL(exception_object_pointer_name)

Parametri

exception_object_pointer_name
Nome di un puntatore a un oggetto eccezione che verrà creato dalla macro. È possibile usare il nome del puntatore per accedere all'oggetto eccezione all'interno del blocco AND_CATCH_ALL . Questa variabile viene dichiarata automaticamente.

Osservazioni:

Utilizzare la macro CATCH per intercettare un tipo di eccezione, quindi la macro AND_CATCH_ALL per intercettare tutti gli altri tipi successivi. Se si usa AND_CATCH_ALL, terminare il blocco TRY con una macro END_CATCH_ALL.

Il codice di elaborazione delle eccezioni può interrogare l'oggetto eccezione, se necessario, per ottenere ulteriori informazioni sulla causa specifica dell'eccezione. Chiamare la macro THROW_LAST all'interno del blocco AND_CATCH_ALL per spostare l'elaborazione al frame di eccezione esterno successivo. AND_CATCH_ALL contrassegna la fine del blocco CATCH o AND_CATCH_ALL precedente.

Nota

Il blocco AND_CATCH_ALL è definito come ambito C++ (delineato da parentesi graffe). Se si dichiarano variabili in questo ambito, tenere presente che sono accessibili solo all'interno di tale ambito.

Requisiti

Intestazione afx.h

END_CATCH

Contrassegna la fine dell'ultimo blocco CATCH o AND_CATCH .

END_CATCH

Osservazioni:

Per altre informazioni sulla macro END_CATCH, vedere l'articolo Eccezioni.

Requisiti

Intestazione afx.h

END_CATCH_ALL

Contrassegna la fine dell'ultimo blocco CATCH_ALL88 o AND_CATCH_ALL .

END_CATCH_ALL

Requisiti

Intestazione afx.h

THROW (MFC)

Genera l'eccezione specificata.

THROW(exception_object_pointer)

Parametri

exception_object_pointer
Punta a un oggetto eccezione derivato da CException.

Osservazioni:

THROW interrompe l'esecuzione del programma, passando il controllo al blocco CATCH associato nel programma. Se non è stato specificato il blocco CATCH, il controllo viene passato a un modulo della libreria di classi di Microsoft Foundation che stampa un messaggio di errore e viene chiuso.

Per altre informazioni, vedere l'articolo Eccezioni.

Requisiti

Intestazione afx.h

THROW_LAST

Genera l'eccezione al blocco CATCH esterno successivo.

THROW_LAST()

Osservazioni:

Questa macro consente di generare un'eccezione creata in locale. Se si tenta di generare un'eccezione appena rilevata, in genere esce dall'ambito e viene eliminata. Con THROW_LAST, l'eccezione viene passata correttamente al gestore CATCH successivo.

Per altre informazioni, vedere l'articolo Eccezioni.

Esempio

Vedere l'esempio per CFile::Abort.

Requisiti

Intestazione afx.h

AfxThrowArchiveException

Genera un'eccezione di archivio.

void  AfxThrowArchiveException(int cause, LPCTSTR lpszArchiveName);

Parametri

cause
Specifica un numero intero che indica il motivo dell'eccezione. Per un elenco dei valori possibili, vedere CArchiveException::m_cause.

lpszArchiveName
Punta a una stringa contenente il nome dell'oggetto CArchive che ha causato l'eccezione (se disponibile).

Requisiti

Intestazione afx.h

AfxThrowFileException

Genera un'eccezione di file.

void AfxThrowFileException(
    int cause,
    LONG lOsError = -1,
    LPCTSTR lpszFileName = NULL);

Parametri

cause
Specifica un numero intero che indica il motivo dell'eccezione. Per un elenco dei valori possibili, vedere CFileException::m_cause.

lOsError
Contiene il numero di errore del sistema operativo (se disponibile) che indica il motivo dell'eccezione. Per un elenco dei codici di errore, vedere il manuale del sistema operativo.

lpszFileName
Punta a una stringa contenente il nome del file che ha causato l'eccezione (se disponibile).

Osservazioni:

L'utente è responsabile della determinazione della causa in base al codice di errore del sistema operativo.

Requisiti

Intestazione afx.h

AfxThrowInvalidArgException

Genera un'eccezione di argomento non valida.

Sintassi

void AfxThrowInvalidArgException( );

Osservazioni:

Questa funzione viene chiamata quando vengono utilizzati argomenti non validi.

Requisiti

Intestazione: afx.h

AfxThrowMemoryException

Genera un'eccezione di memoria.

void AfxThrowMemoryException();

Osservazioni:

Chiamare questa funzione se le chiamate agli allocatori di memoria di sistema sottostanti (ad esempio malloc e la funzione Windows GlobalAlloc ) hanno esito negativo. Non è necessario chiamarlo perché newnew genererà automaticamente un'eccezione di memoria se l'allocazione di memoria non riesce.

Requisiti

Intestazione afx.h

AfxThrowNotSupportedException

Genera un'eccezione che è il risultato di una richiesta per una funzionalità non supportata.

void AfxThrowNotSupportedException();

Requisiti

Intestazione afx.h

AfxThrowResourceException

Genera un'eccezione di risorsa.

void  AfxThrowResourceException();

Osservazioni:

Questa funzione viene in genere chiamata quando non è possibile caricare una risorsa di Windows.

Requisiti

Intestazione afx.h

AfxThrowUserException

Genera un'eccezione per arrestare un'operazione dell'utente finale.

void AfxThrowUserException();

Osservazioni:

Questa funzione viene in genere chiamata immediatamente dopo AfxMessageBox che è stato segnalato un errore all'utente.

Requisiti

Intestazione afx.h

AfxThrowOleDispatchException

Utilizzare questa funzione per generare un'eccezione all'interno di una funzione di automazione OLE.

void AFXAPI AfxThrowOleDispatchException(
    WORD wCode ,
    LPCSTR lpszDescription,
    UINT nHelpID = 0);

void AFXAPI AfxThrowOleDispatchException(
    WORD wCode,
    UINT nDescriptionID,
    UINT nHelpID = -1);

Parametri

wCode
Codice di errore specifico dell'applicazione.

lpszDescription
Descrizione verbale dell'errore.

nDescriptionID
ID risorsa per la descrizione dell'errore verbale.

nHelpID
Contesto della Guida per la Guida dell'applicazione (. File HLP).

Osservazioni:

Le informazioni fornite a questa funzione possono essere visualizzate dall'applicazione di guida (Microsoft Visual Basic o un'altra applicazione client di automazione OLE).

Esempio

// Sort is method of automation class CStrArrayDoc
long CStrArrayDoc::Sort(VARIANT* vArray)
{
   USES_CONVERSION;

   // Type check VARIANT parameter. It should contain a BSTR array
   // passed by reference. The array must be passed by reference; it is
   // an in-out-parameter.

   // throwing COleDispatchException allows the EXCEPINFO structure of 
   // IDispatch::Invoke() to set
   if (V_VT(vArray) != (VT_ARRAY | VT_BSTR))
      AfxThrowOleDispatchException(1001,
         _T("Type Mismatch in Parameter. Pass a string array by reference"));

   // ...
   // ...

   return 0;
}

Requisiti

Intestazione afx.h

AfxThrowOleException

Crea un oggetto di tipo COleException e genera un'eccezione.

void AFXAPI AfxThrowOleException(SCODE sc);
void AFXAPI AfxThrowOleException(HRESULT hr);

Parametri

M.b
Codice di stato OLE che indica il motivo dell'eccezione.

Hr
Handle in un codice di risultato che indica il motivo dell'eccezione.

Osservazioni:

La versione che accetta hresult come argomento converte il codice del risultato nel codice SCODE corrispondente. Per altre informazioni su HRESULT e SCODE, vedere Struttura dei codici di errore COM in Windows SDK.

Requisiti

Intestazione afxdao.h

AfxThrowDaoException

Chiamare questa funzione per generare un'eccezione di tipo CDaoException dal codice personalizzato.

void AFXAPI AfxThrowDaoException(
    int nAfxDaoError = NO_AFX_DAO_ERROR,
    SCODE scode = S_OK);

Parametri

nAfxDaoError
Valore intero che rappresenta un codice di errore esteso DAO, che può essere uno dei valori elencati in CDaoException::m_nAfxDaoError.

scode
Codice di errore OLE da DAO di tipo SCODE. Per informazioni, vedere CDaoException::m_scode.

Osservazioni:

Il framework chiama AfxThrowDaoExceptionanche . Nella chiamata è possibile passare uno dei parametri o entrambi. Ad esempio, se si vuole generare uno degli errori definiti in CDaoException::nAfxDaoError , ma non ci si preoccupa del parametro scode , passare un codice valido nel parametro nAfxDaoError e accettare il valore predefinito per scode.

Per informazioni sulle eccezioni correlate alle classi DAO MFC, vedere classe CDaoException in questo libro e l'articolo Eccezioni: Eccezioni al database.

Requisiti

Intestazione afxdb.h

AfxThrowDBException

Chiamare questa funzione per generare un'eccezione di tipo CDBException dal proprio codice.

void AfxThrowDBException(
    RETCODE nRetCode,
    CDatabase* pdb,
    HSTMT hstmt);

Parametri

nRetCode
Valore di tipo RETCODE, che definisce il tipo di errore che ha causato la generazione dell'eccezione.

Pdb
Puntatore all'oggetto che rappresenta la connessione all'origine CDatabase dati a cui è associata l'eccezione.

Hstmt
Handle ODBC HSTMT che specifica l'handle di istruzione a cui è associata l'eccezione.

Osservazioni:

Il framework chiama AfxThrowDBException quando riceve un codice RETCODE ODBC da una chiamata a una funzione API ODBC e interpreta RETCODE come condizione eccezionale anziché come errore prevedibile. Ad esempio, un'operazione di accesso ai dati potrebbe non riuscire a causa di un errore di lettura del disco.

Per informazioni sui valori RETCODE definiti da ODBC, vedere capitolo 8, "Recupero di informazioni sullo stato e sugli errori" in Windows SDK. Per informazioni sulle estensioni MFC a questi codici, vedere classe CDBException.

Requisiti

Intestazione afx.h

AfxAbort

Funzione di terminazione predefinita fornita da MFC.

void  AfxAbort();

Osservazioni:

AfxAbort viene chiamato internamente dalle funzioni membro MFC quando si verifica un errore irreversibile, ad esempio un'eccezione non rilevata che non può essere gestita. È possibile chiamare AfxAbort nel raro caso in cui si verifica un errore irreversibile da cui non è possibile eseguire il ripristino.

Esempio

Vedere l'esempio per CATCH.

Requisiti

Intestazione afx.h

Vedi anche

Macro e globali
Classe CException
Classe CInvalidArgException