Classe CException

A classe base para todas as exceções na biblioteca Microsoft Foundation Class.

Sintaxe

class AFX_NOVTABLE CException : public CObject

Membros

Construtores públicos

Nome	Descrição
CException::CException	Constrói um objeto CException.

Métodos públicos

Nome	Descrição
CException::Delete	Exclui um objeto CException.
CException::ReportError	Relata uma mensagem de erro em uma caixa de mensagem para o usuário.

Comentários

Como CException é uma classe base abstrata, você não pode criar CException objetos diretamente; você deve criar objetos de classes derivadas. Se você precisar criar sua própria classe no estilo CException, use uma das classes derivadas listadas acima como um modelo. Verifique se sua classe derivada também usa IMPLEMENT_DYNAMIC.

As classes derivadas e suas descrições estão listadas abaixo:

Nome	Descrição
CSimpleException	Uma classe base para exceções MFC críticas a recursos
CInvalidArgException	Condição de exceção de argumento inválida
CMemoryException	Exceção de memória insuficiente
CNotSupportedException	Solicitação para uma operação sem suporte
CArchiveException	Exceção específica do arquivo morto
CFileException	Exceção específica do arquivo
CResourceException	Recurso do Windows não encontrado ou não criável
COleException	Exceções OLE
CDBException	Exceção de banco de dados (ou seja, condições de exceção decorrentes de classes de banco de dados MFC com base em ODBC)
COleDispatchException	Exceções de expedição OLE (automação)
CUserException	Exceção que indica que não foi possível encontrar um recurso
CDaoException	Exceção de objeto de acesso a dados (ou seja, condições de exceção decorrentes de classes DAO)
CInternetException	Exceção de Internet (ou seja, condições de exceção decorrentes de classes de Internet).

Essas exceções destinam-se a ser usadas com macros THROW, THROW_LAST, try, catch, and_catch e end_catch. Para obter mais informações sobre exceções, consulte Processamento de Exceções ou confira o artigo Tratamento de Exceções (MFC).

Para capturar uma exceção específica, use a classe derivada apropriada. Para capturar todos os tipos de exceções, use CException e, em seguida, use CObject::IsKindOf para diferenciar entre classes derivadas de CException. Observe que CObject::IsKindOf funciona apenas para classes declaradas com a macro IMPLEMENT_DYNAMIC, a fim de aproveitar a verificação de tipo dinâmico. Qualquer classe derivada de CException que você criar também deve usar a macro IMPLEMENT_DYNAMIC.

Você pode relatar detalhes sobre exceções ao usuário chamando GetErrorMessage ou ReportError, duas funções membro que funcionam com qualquer uma das classes derivadas de CException.

Se uma exceção for capturada por uma das macros, o objeto CException será excluído automaticamente; não o exclua por conta própria. Se uma exceção for capturada usando uma palavra-chave catch, ela não será excluída automaticamente. Consulte o artigo Tratamento de Exceções (MFC) para obter mais informações sobre quando excluir um objeto de exceção.

Hierarquia de herança

CObject

CException

Requisitos

Cabeçalho: afx.h

CException::CException

Essa função membro constrói um objeto CException.

explicit CException(BOOL bAutoDelete);

Parâmetros

b_AutoDelete
Especifique TRUE se a memória do objeto CException foi alocada no heap. Isso fará com que o objeto CException seja excluído quando a função membro Delete for chamada para excluir a exceção. Especifique FALSE se o objeto CException estiver na pilha ou se for um objeto global. Nesse caso, o objeto CException não será excluído quando a função membro Delete for chamada.

Comentários

Normalmente, você nunca precisaria chamar esse construtor diretamente. Uma função que gera uma exceção deve criar uma instância de uma classe derivada de CException e chamar seu construtor, ou deve usar uma das funções throw do MFC, como AfxThrowFileException, para lançar um tipo predefinido. Esta documentação é fornecida apenas para fins de completude.

CException::Delete

Essa função verifica se o objeto CException foi criado no heap e, em caso afirmativo, chama o operador delete no objeto.

void Delete();

Comentários

Ao excluir um objeto CException, use a função membro Delete para excluir a exceção. Não use o operador delete diretamente, pois o objeto CException pode ser um objeto global ou ter sido criado na pilha.

Você pode especificar se o objeto deve ser excluído quando o objeto é construído. Para obter mais informações, consulte CException::CException.

Você só precisa chamar Delete se estiver usando o mecanismo C++ try- catch. Se você estiver usando as macros TRY e CATCH do MFC, então essas macros chamarão automaticamente essa função.

Exemplo

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 occurs 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

Chame essa função membro para relatar o texto de erro em uma caixa de mensagem para o usuário.

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

Parâmetros

nType
Especifica o estilo da caixa de mensagem. Aplique qualquer combinação de estilos de caixa de mensagem à caixa. Se você não especificar esse parâmetro, o padrão será MB_OK.

nMessageID
Especifica a ID do recurso (entrada de tabela de cadeia de caracteres) de uma mensagem a ser exibida se o objeto de exceção não tiver uma mensagem de erro. Se for 0, a mensagem "Nenhuma mensagem de erro está disponível" será exibida.

Valor de retorno

Um valor AfxMessageBox; caso contrário, 0 se não houver memória suficiente para exibir a caixa de mensagem. Consulte AfxMessageBox para obter os possíveis valores retornados.

Exemplo

Veja um exemplo do uso de CException::ReportError. Para outro exemplo, consulte o exemplo de 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();
}

Confira também

Classe CObject
Gráfico da hierarquia
Processamento de exceção