Traitement des exceptions

Lorsqu’un programme s’exécute, un certain nombre de conditions anormales et d’erreurs appelées « exceptions » peuvent se produire. Il peut s’agir d’un manque de mémoire, d’erreurs d’allocation de ressources et d’échecs de recherche de fichiers.

La bibliothèque de classes Microsoft Foundation utilise un schéma de gestion des exceptions qui est modélisé étroitement après celui proposé par le comité des normes ANSI pour C++. Un gestionnaire d’exceptions doit être configuré avant d’appeler une fonction susceptible de rencontrer une situation anormale. Si la fonction rencontre une condition anormale, elle lève une exception et un contrôle est transmis au gestionnaire d’exceptions.

Plusieurs macros incluses dans la bibliothèque de classes Microsoft Foundation configurent des gestionnaires d’exceptions. Un certain nombre d’autres fonctions globales permettent de lever des exceptions spécialisées et de mettre fin aux programmes, si nécessaire. Ces macros et fonctions globales appartiennent aux catégories suivantes :

• Macros d’exception, qui structurent votre gestionnaire d’exceptions.

• Fonctions de levée d’exceptions), qui génèrent des exceptions de types spécifiques.

• Fonctions d’arrêt, qui provoquent l’arrêt du programme.

Pour obtenir des exemples et plus d’informations, consultez l’article Exceptions.

Macros d’exception

Nom	Description
ESSAYER	Désigne un bloc de code pour le traitement des exceptions.
CATCH	Désigne un bloc de code pour intercepter une exception du bloc TRY précédent.
CATCH_ALL	Désigne un bloc de code pour intercepter toutes les exceptions du bloc TRY précédent.
AND_CATCH	Désigne un bloc de code pour intercepter des types d’exceptions supplémentaires du bloc TRY précédent.
AND_CATCH_ALL	Désigne un bloc de code pour intercepter tous les autres types d’exceptions supplémentaires levées dans un bloc TRY précédent.
END_CATCH	Termine le dernier bloc de code CATCH ou AND_CATCH .
END_CATCH_ALL	Termine le dernier bloc de code CATCH_ALL .
THROW	Lève une exception spécifiée.
THROW_LAST	Lève l’exception actuellement gérée au gestionnaire externe suivant.

Fonctions de levée d’exceptions

Nom	Description
AfxThrowArchiveException	Lève une exception d’archive.
AfxThrowFileException	Lève une exception de fichier.
AfxThrowInvalidArgException	Lève une exception d’argument non valide.
AfxThrowMemoryException	Lève une exception de mémoire.
AfxThrowNotSupportedException	Lève une exception non prise en charge.
AfxThrowResourceException	Lève une exception de ressource Windows introuvable.
AfxThrowUserException	Lève une exception dans une action de programme initiée par l’utilisateur.

MFC fournit deux fonctions de levée d’exceptions spécifiquement pour les exceptions OLE :

Fonctions d’exception OLE

Nom	Description
AfxThrowOleDispatchException	Lève une exception dans une fonction d’automatisation OLE.
AfxThrowOleException	Lève une exception OLE.

Pour prendre en charge les exceptions de base de données, les classes de base de données fournissent deux classes d’exception et CDBException , et CDaoExceptionles fonctions globales pour prendre en charge les types d’exceptions :

Fonctions d’exception DAO

Nom	Description
AfxThrowDAOException	Lève une exception CDaoException à partir de votre propre code.
AfxThrowDBException	Lève une exception CDBException à partir de votre propre code.

MFC fournit la fonction d’arrêt suivante :

Fonctions d’arrêt

Nom	Description
AfxAbort	Appelé pour mettre fin à une application lorsqu’une erreur irrécupérable se produit.

TRY

Configure un bloc TRY .

TRY

Notes

Un bloc TRY identifie un bloc de code qui peut lever des exceptions. Ces exceptions sont gérées dans les blocs CATCH et AND_CATCH suivants. La récursivité est autorisée : les exceptions peuvent être passées à un bloc TRY externe, soit en les ignorant, soit en utilisant la macro THROW_LAST. Terminez le bloc TRY avec une macro END_CATCH ou END_CATCH_ALL.

Pour plus d’informations, consultez l’article Exceptions.

Exemple

Consultez l’exemple de CATCH.

Spécifications

En-tête : afx.h

CATCH

Définit un bloc de code qui intercepte le premier type d’exception levée dans le bloc TRY précédent.

CATCH(exception_class, exception_object_pointer_name)

Paramètres

exception_class
Spécifie le type d’exception à tester. Pour obtenir la liste des classes d’exception standard, consultez la classe CException.

exception_object_pointer_name
Spécifie un nom pour un pointeur d’objet d’exception qui sera créé par la macro. Vous pouvez utiliser le nom du pointeur pour accéder à l’objet d’exception dans le bloc CATCH . Cette variable est déclarée pour vous.

Notes

Le code de traitement des exceptions peut interroger l’objet d’exception, le cas échéant, pour obtenir plus d’informations sur la cause spécifique de l’exception. Appelez la macro THROW_LAST pour déplacer le traitement vers le cadre d’exception externe suivant. Terminez le bloc TRY avec une macro END_CATCH.

Si exception_class est la classe CException, tous les types d’exceptions sont interceptés. Vous pouvez utiliser la fonction membre CObject ::IsKindOf pour déterminer quelle exception spécifique a été levée. Une meilleure façon d’intercepter plusieurs types d’exceptions consiste à utiliser des instructions de AND_CATCH séquentielles, chacune avec un type d’exception différent.

Le pointeur d’objet d’exception est créé par la macro. Vous n’avez pas besoin de le déclarer vous-même.

Remarque

Le bloc CATCH est défini comme une étendue C++ délimitée par des accolades. Si vous déclarez des variables dans cette étendue, elles sont accessibles uniquement dans cette étendue. Cela s’applique également à exception_object_pointer_name.

Pour plus d’informations sur les exceptions et la macro CATCH, consultez l’article Exceptions.

Exemple

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

Définit un bloc de code qui intercepte tous les types d’exceptions levées dans le bloc TRY précédent.

CATCH_ALL(exception_object_pointer_name)

Paramètres

exception_object_pointer_name
Spécifie un nom pour un pointeur d’objet d’exception qui sera créé par la macro. Vous pouvez utiliser le nom du pointeur pour accéder à l’objet d’exception dans le CATCH_ALL bloc. Cette variable est déclarée pour vous.

Notes

Le code de traitement des exceptions peut interroger l’objet d’exception, le cas échéant, pour obtenir plus d’informations sur la cause spécifique de l’exception. Appelez la macro pour déplacer le THROW_LAST traitement vers le cadre d’exception externe suivant. Si vous utilisez CATCH_ALL, terminez le bloc TRY avec une macro END_CATCH_ALL.

Remarque

Le bloc CATCH_ALL est défini comme une étendue C++ délimitée par des accolades. Si vous déclarez des variables dans cette étendue, elles sont accessibles uniquement dans cette étendue.

Pour plus d’informations sur les exceptions, consultez l’article Exceptions.

Exemple

Consultez l’exemple de CFile ::Abort.

Spécifications

En-tête afx.h

AND_CATCH

Définit un bloc de code permettant d’intercepter des types d’exceptions supplémentaires levées dans un bloc TRY précédent.

AND_CATCH(exception_class, exception_object_pointer_name)

Paramètres

exception_class
Spécifie le type d’exception à tester. Pour obtenir la liste des classes d’exception standard, consultez la classe CException.

exception_object_pointer_name
Nom d’un pointeur d’objet d’exception qui sera créé par la macro. Vous pouvez utiliser le nom du pointeur pour accéder à l’objet d’exception dans le bloc AND_CATCH . Cette variable est déclarée pour vous.

Notes

Utilisez la macro CATCH pour intercepter un type d’exception, puis la macro AND_CATCH pour intercepter chaque type suivant. Terminez le bloc TRY avec une macro END_CATCH.

Le code de traitement des exceptions peut interroger l’objet d’exception, le cas échéant, pour obtenir plus d’informations sur la cause spécifique de l’exception. Appelez la macro THROW_LAST dans le bloc AND_CATCH pour déplacer le traitement vers le cadre d’exception externe suivant. AND_CATCH marque la fin du bloc CATCH ou AND_CATCH précédent.

Remarque

Le bloc AND_CATCH est défini comme une étendue C++ (délimitée par des accolades). Si vous déclarez des variables dans cette étendue, n’oubliez pas qu’elles sont accessibles uniquement dans cette étendue. Cela s’applique également à la variable exception_object_pointer_name .

Exemple

Consultez l’exemple de CATCH.

Spécifications

En-tête afx.h

AND_CATCH_ALL

Définit un bloc de code permettant d’intercepter des types d’exceptions supplémentaires levées dans un bloc TRY précédent.

AND_CATCH_ALL(exception_object_pointer_name)

Paramètres

exception_object_pointer_name
Nom d’un pointeur d’objet d’exception qui sera créé par la macro. Vous pouvez utiliser le nom du pointeur pour accéder à l’objet d’exception dans le bloc AND_CATCH_ALL . Cette variable est déclarée pour vous.

Notes

Utilisez la macro CATCH pour intercepter un type d’exception, puis la macro AND_CATCH_ALL pour intercepter tous les autres types suivants. Si vous utilisez AND_CATCH_ALL, terminez le bloc TRY avec une macro END_CATCH_ALL.

Le code de traitement des exceptions peut interroger l’objet d’exception, le cas échéant, pour obtenir plus d’informations sur la cause spécifique de l’exception. Appelez la macro THROW_LAST dans le bloc AND_CATCH_ALL pour déplacer le traitement vers le cadre d’exception externe suivant. AND_CATCH_ALL marque la fin du bloc CATCH ou AND_CATCH_ALL précédent.

Remarque

Le bloc AND_CATCH_ALL est défini comme une étendue C++ (délimitée par des accolades). Si vous déclarez des variables dans cette étendue, n’oubliez pas qu’elles sont accessibles uniquement dans cette étendue.

Spécifications

En-tête afx.h

END_CATCH

Marque la fin du dernier bloc CATCH ou AND_CATCH .

END_CATCH

Notes

Pour plus d’informations sur la macro END_CATCH, consultez l’article Exceptions.

Spécifications

En-tête afx.h

END_CATCH_ALL

Marque la fin du dernier bloc CATCH_ALL88 ou AND_CATCH_ALL .

END_CATCH_ALL

Spécifications

En-tête afx.h

THROW (MFC)

Lève l’exception spécifiée.

THROW(exception_object_pointer)

Paramètres

exception_object_pointer
Pointe vers un objet d’exception dérivé de CException.

Notes

THROW interrompt l’exécution du programme, en passant le contrôle au bloc CATCH associé dans votre programme. Si vous n’avez pas fourni le bloc CATCH , le contrôle est passé à un module bibliothèque de classes Microsoft Foundation qui imprime un message d’erreur et se ferme.

Pour plus d’informations, consultez l’article Exceptions.

Spécifications

En-tête afx.h

THROW_LAST

Renvoie l’exception au bloc CATCH externe suivant.

THROW_LAST()

Notes

Cette macro vous permet de lever une exception créée localement. Si vous essayez de lever une exception que vous venez d’intercepter, elle sortira normalement de l’étendue et sera supprimée. Avec THROW_LAST, l’exception est transmise correctement au gestionnaire CATCH suivant.

Pour plus d’informations, consultez l’article Exceptions.

Exemple

Consultez l’exemple de CFile ::Abort.

Spécifications

En-tête afx.h

AfxThrowArchiveException

Lève une exception d’archive.

void  AfxThrowArchiveException(int cause, LPCTSTR lpszArchiveName);

Paramètres

cause
Spécifie un entier qui indique la raison de l’exception. Pour obtenir la liste des valeurs possibles, consultez CArchiveException ::m_cause.

lpszArchiveName
Pointe vers une chaîne contenant le nom de l’objet CArchive qui a provoqué l’exception (si disponible).

Spécifications

En-tête afx.h

AfxThrowFileException

Lève une exception de fichier.

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

Paramètres

cause
Spécifie un entier qui indique la raison de l’exception. Pour obtenir la liste des valeurs possibles, consultez CFileException ::m_cause.

lOsError
Contient le numéro d’erreur du système d’exploitation (le cas échéant) qui indique la raison de l’exception. Consultez le manuel de votre système d’exploitation pour obtenir la liste des codes d’erreur.

lpszFileName
Pointe vers une chaîne contenant le nom du fichier qui a provoqué l’exception (le cas échéant).

Notes

Vous êtes responsable de la détermination de la cause en fonction du code d’erreur du système d’exploitation.

Spécifications

En-tête afx.h

AfxThrowInvalidArgException

Lève une exception d’argument non valide.

Syntaxe

void AfxThrowInvalidArgException( );

Notes

Cette fonction est appelée lorsque des arguments non valides sont utilisés.

Spécifications

En-tête : afx.h

AfxThrowMemoryException

Lève une exception de mémoire.

void AfxThrowMemoryException();

Notes

Appelez cette fonction si les appels à des allocateurs de mémoire système sous-jacents (tels que malloc et la fonction Windows GlobalAlloc ) échouent. Vous n’avez pas besoin de l’appeler car newnew lève automatiquement une exception de mémoire si l’allocation de mémoire échoue.

Spécifications

En-tête afx.h

AfxThrowNotSupportedException

Lève une exception qui est le résultat d’une demande pour une fonctionnalité non prise en charge.

void AfxThrowNotSupportedException();

Spécifications

En-tête afx.h

AfxThrowResourceException

Lève une exception de ressource.

void  AfxThrowResourceException();

Notes

Cette fonction est normalement appelée lorsqu’une ressource Windows ne peut pas être chargée.

Spécifications

En-tête afx.h

AfxThrowUserException

Lève une exception pour arrêter une opération de l’utilisateur final.

void AfxThrowUserException();

Notes

Cette fonction est normalement appelée immédiatement après AfxMessageBox avoir signalé une erreur à l’utilisateur.

Spécifications

En-tête afx.h

AfxThrowOleDispatchException

Utilisez cette fonction pour lever une exception dans une fonction OLE Automation.

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

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

Paramètres

wCode
Code d’erreur spécifique à votre application.

lpszDescription
Description verbale de l’erreur.

nDescriptionID
ID de ressource pour la description d’erreur verbale.

nHelpID
Contexte d’aide pour l’aide de votre application (. Fichier HLP).

Notes

Les informations fournies à cette fonction peuvent être affichées par l’application de conduite (Microsoft Visual Basic ou une autre application cliente OLE Automation).

Exemple

// 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;
}

Spécifications

En-tête afx.h

AfxThrowOleException

Crée un objet de type COleException et lève une exception.

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

Paramètres

Sc
Code d’état OLE qui indique la raison de l’exception.

Hr
Gérez vers un code de résultat qui indique la raison de l’exception.

Notes

La version qui prend UN HRESULT en tant qu’argument convertit ce code de résultat en SCODE correspondant. Pour plus d’informations sur HRESULT et SCODE, consultez Structure des codes d’erreur COM dans le Kit de développement logiciel (SDK) Windows.

Spécifications

En-tête afxdao.h

AfxThrowDaoException

Appelez cette fonction pour lever une exception de type CDaoException à partir de votre propre code.

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

Paramètres

nAfxDaoError
Valeur entière représentant un code d’erreur étendu DAO, qui peut être l’une des valeurs répertoriées sous CDaoException ::m_nAfxDaoError.

scode
Code d’erreur OLE de DAO, de type SCODE. Pour plus d’informations, consultez CDaoException ::m_scode.

Notes

L’infrastructure appelle AfxThrowDaoExceptionégalement . Dans votre appel, vous pouvez passer l’un des paramètres ou les deux. Par exemple, si vous souhaitez déclencher l’une des erreurs définies dans CDaoException ::nAfxDaoError , mais que vous ne vous souciez pas du paramètre scode , passez un code valide dans le paramètre nAfxDaoError et acceptez la valeur par défaut pour scode.

Pour plus d’informations sur les exceptions liées aux classes DAO MFC, consultez la classe CDaoException dans ce livre et l’article Exceptions : Exceptions de base de données.

Spécifications

En-tête afxdb.h

AfxThrowDBException

Appelez cette fonction pour lever une exception de type CDBException à partir de votre propre code.

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

Paramètres

nRetCode
Valeur de type RETCODE, définissant le type d’erreur qui a provoqué la levée de l’exception.

Apb
Pointeur vers l’objet CDatabase qui représente la connexion de source de données avec laquelle l’exception est associée.

hstmt
Handle ODBC HSTMT qui spécifie le handle d’instruction auquel l’exception est associée.

Notes

L’infrastructure appelle AfxThrowDBException lorsqu’elle reçoit un RETCODE ODBC à partir d’un appel à une fonction d’API ODBC et interprète RETCODE comme une condition exceptionnelle plutôt qu’une erreur attendue. Par exemple, une opération d’accès aux données peut échouer en raison d’une erreur de lecture de disque.

Pour plus d’informations sur les valeurs RETCODE définies par ODBC, consultez le chapitre 8, « Récupération des informations d’état et d’erreur » dans le Kit de développement logiciel (SDK) Windows. Pour plus d’informations sur les extensions MFC de ces codes, consultez la classe CDBException.

Spécifications

En-tête afx.h

AfxAbort

Fonction d’arrêt par défaut fournie par MFC.

void  AfxAbort();

Notes

AfxAbort est appelé en interne par les fonctions membres MFC lorsqu’il existe une erreur irrécupérable, telle qu’une exception non interceptée qui ne peut pas être gérée. Vous pouvez appeler AfxAbort dans le cas rare lorsque vous rencontrez une erreur catastrophique à partir de laquelle vous ne pouvez pas récupérer.

Exemple

Consultez l’exemple de CATCH.

Spécifications

En-tête afx.h

Voir aussi

Macros et globals
CException, classe
CInvalidArgException, classe