CException Class

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CException Class.

The base class for all exceptions in the Microsoft Foundation Class Library.

Syntax

class AFX_NOVTABLE CException : public CObject  

Members

Public Constructors

Public Methods

Remarks

Because CException is an abstract base class you cannot create CException objects directly; you must create objects of derived classes. If you need to create your own CException-style class, use one of the derived classes listed above as a model. Make sure that your derived class also uses IMPLEMENT_DYNAMIC.

The derived classes and their descriptions are listed below:

These exceptions are intended to be used with the THROW, [THROW_LAST](../Topic/Exception%20Processing.md#not_found.md#throw_last, [try](../topic/not_found.md#try, [catch](../topic/not_found.md#catch, [and_catch](../topic/not_found.md#and_catch, and [end_catch](../topic/not_found.md#end_catch macros. for more information on exceptions, see [exception processing]--brokenlink--(../topic/exception_processing), or see the article Exception Handling (MFC).

To catch a specific exception, use the appropriate derived class. To catch all types of exceptions, use CException, and then use CObject::IsKindOf to differentiate among CException-derived classes. Note that CObject::IsKindOf works only for classes declared with the IMPLEMENT_DYNAMIC macro, in order to take advantage of dynamic type checking. Any CException-derived class that you create should use the IMPLEMENT_DYNAMIC macro, too.

You can report details about exceptions to the user by calling GetErrorMessage or ReportError, two member functions that work with any of CException's derived classes.

If an exception is caught by one of the macros, the CException object is deleted automatically; do not delete it yourself. If an exception is caught by using a catch keyword, it is not automatically deleted. See the article Exception Handling (MFC) for more information about when to delete an exeption object.

Inheritance Hierarchy

CObject

CException

Requirements

Header: afx.h

CException::CException

This member function constructs a CException object.

explicit CException(BOOL bAutoDelete);

Parameters

b_AutoDelete
Specify TRUE if the memory for the CException object has been allocated on the heap. This will cause the CException object to be deleted when the Delete member function is called to delete the exception. Specify FALSE if the CException object is on the stack or is a global object. In this case, the CException object will not be deleted when the Delete member function is called.

Remarks

You would normally never need to call this constructor directly. A function that throws an exception should create an instance of a CException-derived class and call its constructor, or it should use one of the MFC throw functions, such as [AfxThrowFileException]--brokenlink--(../Topic/not%20found.md#afxthrowfileexception), to throw a predefined type. This documentation is provided only for completeness.

CException::Delete

This function checks to see if the CException object was created on the heap, and if so, it calls the delete operator on the object.

void Delete();

Remarks

When deleting a CException object, use the Delete member function to delete the exception. Do not use the delete operator directly, because the CException object may be a global object or have been created on the stack.

You can specify whether the object should be deleted when the object is constructed. For more information, see CException::CException.

You only need to call Delete if you are using the C++ try- catch mechanism. If you are using the MFC macros TRY and CATCH, then these macros will automatically call this function.

Example

   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.

   // Note that this example performs the same actions as the 
   // example for CATCH, but uses C++ try/catch syntax instead
   // of using the MFC TRY/CATCH macros. This sample must use
   // CException::Delete() to delete the exception objects
   // before closing the catch block, while the CATCH example
   // implicitly performs the deletion via the macros.

   try
   {
      pFile = new CFile(_T("C:\\WINDOWS\\SYSTEM.INI"),
         CFile::modeRead | CFile::shareDenyNone);

      ULONGLONG ullLength = pFile->GetLength();

      CString str;
      str.Format(_T("Your SYSTEM.INI file is %u bytes long."), ullLength);

      AfxMessageBox(str);
   }
   catch(CFileException* pEx)
   {
      // Simply show an error message to the user.

      pEx->ReportError();
      pEx->Delete();
   }
   catch(CMemoryException* pEx)
   {
      // We can't recover from this memory exception, so we'll
      // just terminate the app without any cleanup. Normally, an
      // an application should do everything it possibly can to
      // clean up properly and _not_ call AfxAbort().

      pEx->Delete();
      AfxAbort();
   }

   // If an exception occurrs in the CFile constructor,
   // the language will free the memory allocated by new
   // and will not complete the assignment to pFile.
   // Thus, our clean-up code needs to test for NULL.

   if (pFile != NULL)
   {
      pFile->Close();
      delete pFile;
   }   

CException::ReportError

Call this member function to report error text in a message box to the user.

virtual int ReportError(
    UINT nType = MB_OK,  
    UINT nMessageID = 0);

Parameters

nType
Specifies the style of the message box. Apply any combination of the message-box styles to the box. If you don't specify this parameter, the default is MB_OK.

nMessageID
Specifies the resource ID (string table entry) of a message to display if the exception object does not have an error message. If 0, the message "No error message is available" is displayed.

Return Value

An AfxMessageBox value; otherwise 0 if there is not enough memory to display the message box. See [AfxMessageBox]--brokenlink--(../Topic/not%20found.md#afxmessagebox) for the possible return values.

Example

Here is an example of the use of CException::ReportError. For another example, see the example for [CATCH]--brokenlink--(../Topic/not%20found.md#catch).

   CFile fileInput;
   CFileException ex;

   // try to open a file for reading.  
   // The file will certainly not
   // exist because there are too many explicit
   // directories in the name.

   // if the call to Open() fails, ex will be
   // initialized with exception
   // information.  the call to ex.ReportError() will
   // display an appropriate
   // error message to the user, such as
   // "\Too\Many\Bad\Dirs.DAT contains an
   // invalid path."  The error message text will be
   // appropriate for the
   // file name and error condition.

   if (!fileInput.Open(_T("\\Too\\Many\\Bad\\Dirs.DAT"), CFile::modeRead, &ex))
   {
      ex.ReportError();
   }
   else
   {
      // the file was opened, so do whatever work
      // with fileInput we were planning...

      fileInput.Close();
   }

See Also

CObject Class
Hierarchy Chart
Exception Processing
How Do I: Create my Own Custom Exception Classes