Processamento de Exceções

Quando um programa é executado, podem ocorrer várias condições anormais e erros chamados "exceções". Estas podem incluir falta de memória, erros de alocação de recursos e falha em encontrar ficheiros.

A Microsoft Foundation Class Library utiliza um esquema de gestão de exceções que é modelado de perto naquele proposto pelo comité de normas ANSI para C++. Um tratador de exceções deve ser configurado antes de chamar uma função que possa encontrar uma situação anormal. Se a função encontrar uma condição anormal, lança uma exceção e o controlo é passado para o gestor de exceções.

Várias macros incluídas na Microsoft Foundation Class Library vão configurar os manipuladores de exceções. Várias outras funções globais ajudam a lançar exceções especializadas e a terminar programas, se necessário. Estas macros e funções globais enquadram-se nas seguintes categorias:

• Macros de exceção, que estruturam o teu gestor de exceções.

• Funções de lançamento de exceções), que geram exceções de tipos específicos.

• Funções de terminação, que causam a terminação do programa.

Para exemplos e mais detalhes, consulte o artigo Exceções.

Macros de exceção

Exception-Throwing Funções

O MFC fornece duas funções de lançamento de exceções especificamente para exceções OLE:

Funções de exceção OLE

Para suportar exceções de base de dados, as classes de base de dados fornecem duas classes de exceção, CDBException e CDaoException, e funções globais para suportar os tipos de exceção:

Funções de Exceção DAO

A MFC fornece a seguinte função de terminação:

Funções de Terminação

TRY

Cria um bloqueio TRY .

TRY

Observações

Um bloco TRY identifica um bloco de código que pode lançar exceções. Essas exceções são tratadas nos blocos CATCH e AND_CATCH seguintes. A recursão é permitida: exceções podem ser passadas a um bloco TRY externo, seja ignorando-as ou usando a macro THROW_LAST. Termina o bloco TRY com uma macro END_CATCH ou END_CATCH_ALL.

Para obter mais informações, consulte o artigo Exceções.

Example

Veja o exemplo do CATCH.

Requerimentos

Cabeçalho: afx.h

AGARRA

Define um bloco de código que captura o primeiro tipo de exceção inserido no bloco TRY anterior.

CATCH(exception_class, exception_object_pointer_name)

Parâmetros

exception_class
Especifica o tipo de exceção a testar. Para uma lista de classes padrão de exceção, veja classe CException.

exception_object_pointer_name
Especifica um nome para um ponteiro de objeto de exceção que será criado pela macro. Pode usar o nome do ponteiro para aceder ao objeto exceção dentro do bloco CATCH . Esta variável é declarada para si.

Observações

O código de processamento de exceções pode interrogar o objeto de exceção, se apropriado, para obter mais informações sobre a causa específica da exceção. Invoca a macro THROW_LAST para transferir o processamento para o próximo frame de exceção exterior. Termina o bloco TRY com uma macro END_CATCH.

Se exception_class for a classe CException, então todos os tipos de exceção serão apanhados. Pode usar a função membro CObject::IsKindOf para determinar qual exceção específica foi lançada. Uma forma melhor de detetar vários tipos de exceções é usar instruções AND_CATCH sequenciais, cada uma com um tipo de exceção diferente.

O ponteiro de objeto de exceção é criado pela macro. Não precisas de o declarar tu mesmo.

Para mais informações sobre exceções e a macro CATCH, consulte o artigo Exceções.

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

Define um bloco de código que captura todos os tipos de exceção lançados no bloco TRY anterior.

CATCH_ALL(exception_object_pointer_name)

Parâmetros

exception_object_pointer_name
Especifica um nome para um ponteiro de objeto de exceção que será criado pela macro. Podes usar o nome do ponteiro para aceder ao objeto exceção dentro do CATCH_ALL bloco. Esta variável é declarada para si.

Observações

O código de processamento de exceções pode interrogar o objeto de exceção, se apropriado, para obter mais informações sobre a causa específica da exceção. Invocar a THROW_LAST macro para transferir o processamento para o próximo frame de exceção exterior. Se usares CATCH_ALL, termina o bloco TRY com uma macro END_CATCH_ALL.

Para mais informações sobre exceções, consulte o artigo Exceções.

Example

Veja o exemplo de CFile::Abort.

Requerimentos

Cabeçalho afx.h

AND_CATCH

Define um bloco de código para capturar tipos de exceção adicionais inseridos num bloco TRY anterior.

AND_CATCH(exception_class, exception_object_pointer_name)

Parâmetros

exception_class
Especifica o tipo de exceção a testar. Para uma lista de classes padrão de exceção, veja classe CException.

exception_object_pointer_name
Um nome para um ponteiro de objeto de exceção que será criado pela macro. Podes usar o nome do ponteiro para aceder ao objeto exceção dentro do bloco AND_CATCH . Esta variável é declarada para si.

Observações

Use a macro CATCH para apanhar um tipo de exceção, depois a macro AND_CATCH para apanhar cada tipo seguinte. Termina o bloco TRY com uma macro END_CATCH.

O código de processamento de exceções pode interrogar o objeto de exceção, se apropriado, para obter mais informações sobre a causa específica da exceção. Chama a macro THROW_LAST dentro do bloco AND_CATCH para transferir o processamento para o próximo frame de exceção exterior. AND_CATCH marca o fim do bloqueio CATCH ou AND_CATCH anterior.

Example

Veja o exemplo do CATCH.

Requerimentos

Cabeçalho afx.h

AND_CATCH_ALL

Define um bloco de código para capturar tipos de exceção adicionais inseridos num bloco TRY anterior.

AND_CATCH_ALL(exception_object_pointer_name)

Parâmetros

exception_object_pointer_name
Um nome para um ponteiro de objeto de exceção que será criado pela macro. Podes usar o nome do ponteiro para aceder ao objeto exceção dentro do bloco AND_CATCH_ALL . Esta variável é declarada para si.

Observações

Use a macro CATCH para apanhar um tipo de exceção, depois a macro AND_CATCH_ALL para apanhar todos os outros tipos subsequentes. Se usares AND_CATCH_ALL, termina o bloco TRY com uma macro END_CATCH_ALL.

O código de processamento de exceções pode interrogar o objeto de exceção, se apropriado, para obter mais informações sobre a causa específica da exceção. Chama a macro THROW_LAST dentro do bloco AND_CATCH_ALL para deslocar o processamento para o próximo frame de exceção exterior. AND_CATCH_ALL marca o fim do bloqueio CATCH ou AND_CATCH_ALL anterior.

Requerimentos

Cabeçalho afx.h

END_CATCH

Marca o fim do último bloco CATCH ou AND_CATCH .

END_CATCH

Observações

Para mais informações sobre a macro END_CATCH, consulte o artigo Exceções.

Requerimentos

Cabeçalho afx.h

END_CATCH_ALL

Marca o fim do último CATCH_ALL88 ou AND_CATCH_ALL quarteirão.

END_CATCH_ALL

Requerimentos

Cabeçalho afx.h

LANÇAMENTO (MFC)

Lança a exceção especificada.

THROW(exception_object_pointer)

Parâmetros

exception_object_pointer
Aponta para um objeto exceção derivado de CException.

Observações

O THROW interrompe a execução do programa, passando o controlo para o bloco CATCH associado no seu programa. Se não forneceu o bloco CATCH , então o controlo é passado para um módulo da Microsoft Foundation Class Library que imprime uma mensagem de erro e sai.

Para obter mais informações, consulte o artigo Exceções.

Requerimentos

Cabeçalho afx.h

THROW_LAST

Lança a exceção de volta para o próximo bloco externo de CATCH .

THROW_LAST()

Observações

Esta macro permite-te lançar uma exceção criada localmente. Se tentares lançar uma exceção que acabaste de apanhar, normalmente ela sai do âmbito e será eliminada. Com THROW_LAST, a exceção é passada corretamente ao próximo manipulador CATCH .

Para obter mais informações, consulte o artigo Exceções.

Example

Veja o exemplo de CFile::Abort.

Requerimentos

Cabeçalho afx.h

AfxThrowArchiveException

Lança uma exceção de arquivo.

void  AfxThrowArchiveException(int cause, LPCTSTR lpszArchiveName);

Parâmetros

Causa
Especifica um inteiro que indica a razão da exceção. Para uma lista dos valores possíveis, veja CArchiveException::m_cause.

lpszArchiveName
Aponta para uma cadeia que contém o nome do CArchive objeto que causou a exceção (se disponível).

Requerimentos

Cabeçalho afx.h

AfxThrowFileException

Lança uma exceção no ficheiro.

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

Parâmetros

Causa
Especifica um inteiro que indica a razão da exceção. Para uma lista dos valores possíveis, veja CFileException::m_cause.

lOsError
Contém o número de erro do sistema operativo (se disponível) que indica a razão da exceção. Consulte o manual do seu sistema operativo para uma lista de códigos de erro.

lpszFileName
Aponta para uma string contendo o nome do ficheiro que causou a exceção (se disponível).

Observações

És responsável por determinar a causa com base no código de erro do sistema operativo.

Requerimentos

Cabeçalho afx.h

AfxThrowInvalidArgException

Lança uma exceção de argumento inválido.

Sintaxe

void AfxThrowInvalidArgException( );

Observações

Esta função é chamada quando são usados argumentos inválidos.

Requerimentos

Cabeçalho: afx.h

AfxThrowMemoryException

Faz uma exceção de memória.

void AfxThrowMemoryException();

Observações

Chame esta função se as chamadas a alocadores de memória subjacentes do sistema (como malloc e a função GlobalAlloc Windows) falharem. Não precisas de o chamar porque newnew automaticamente gera uma exceção de memória se a alocação falhar.

Requerimentos

Cabeçalho afx.h

AfxThrowNotSupportedException

Lança uma exceção que resulta de um pedido para uma funcionalidade não suportada.

void AfxThrowNotSupportedException();

Requerimentos

Cabeçalho afx.h

AfxThrowResourceException

Lança uma exceção de recurso.

void  AfxThrowResourceException();

Observações

Esta função é normalmente chamada quando um recurso Windows não pode ser carregado.

Requerimentos

Cabeçalho afx.h

AfxThrowUserException

Lança uma exceção para parar uma operação do utilizador final.

void AfxThrowUserException();

Observações

Esta função é normalmente chamada imediatamente após AfxMessageBox ter reportado um erro ao utilizador.

Requerimentos

Cabeçalho afx.h

AfxThrowOleDispatchException

Use esta função para lançar uma exceção dentro de uma função de automação OLE.

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

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

Parâmetros

wCode
Um código de erro específico para a sua aplicação.

lpszDescription
Descrição verbal do erro.

nDescriptionID
ID de recurso para a descrição do erro verbal.

nHelpID
Um contexto de ajuda para a ajuda da sua candidatura (. HLP).

Observações

A informação fornecida a esta função pode ser apresentada pela aplicação de condução (Microsoft Visual Basic ou outra aplicação cliente de automação OLE).

Example

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

Requerimentos

Cabeçalho afx.h

AfxThrowOleException

Cria um objeto do tipo COleException e lança uma exceção.

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

Parâmetros

SC
Um código de estado OLE que indica a razão da exceção.

horas
Handle para um código de resultado que indica a razão da exceção.

Observações

A versão que toma um HRESULT como argumento converte esse código de resultado no SCODE correspondente. Para mais informações sobre HRESULT e SCODE, consulte Estrutura dos Códigos de Erro COM no Windows SDK.

Requerimentos

Cabeçalho afxdao.h

AfxThrowDaoException

Chame esta função para lançar uma exceção do tipo CDaoException do seu próprio código.

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

Parâmetros

nAfxDaoError
Um valor inteiro que representa um código de erro DAO estendido, que pode ser um dos valores listados em CDaoException::m_nAfxDaoError.

Scode
Um código de erro OLE do DAO, do tipo SCODE. Para informações, consulte CDaoException::m_scode.

Observações

O framework também chama AfxThrowDaoException. Na sua chamada, pode passar um dos parâmetros ou ambos. Por exemplo, se quiseres gerar um dos erros definidos em CDaoException::nAfxDaoError mas não te importas com o parâmetro scode , passa um código válido no parâmetro nAfxDaoError e aceita o valor padrão para scode.

Para informações sobre exceções relacionadas com as classes MFC DAO, veja a classe CDaoException neste livro e o artigo Exceções: Exceções na Base de Dados.

Requerimentos

Cabeçalho afxdb.h

AfxThrowDBException

Chama esta função para lançar uma exceção de tipo CDBException do teu próprio código.

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

Parâmetros

nRetCode
Um valor do tipo RETCODE, que define o tipo de erro que causou a lançamento da exceção.

PDB
Um ponteiro para o CDatabase objeto que representa a ligação da fonte de dados com a qual a exceção está associada.

HSTMT
Um handle ODBC HSTMT que especifica o handle da instrução com o qual a exceção está associada.

Observações

O framework chama AfxThrowDBException quando recebe um RETCODE ODBC a partir de uma chamada para uma função API ODBC e interpreta o RETCODE como uma condição excecional em vez de um erro esperado. Por exemplo, uma operação de acesso a dados pode falhar devido a um erro de leitura do disco.

Para informações sobre os valores RETCODE definidos pelo ODBC, consulte o Capítulo 8, "Recuperação de Informação de Estado e Erro", no SDK do Windows. Para informações sobre extensões MFC a estes códigos, veja a classe CDBException.

Requerimentos

Cabeçalho afx.h

AfxAbort

A função de terminação padrão fornecida pela MFC.

void  AfxAbort();

Observações

AfxAbort é chamada internamente pelas funções membros da MFC quando há um erro fatal, como uma exceção não detetada que não pode ser tratada. Pode chamar AfxAbort no raro caso de encontrar um erro catastrófico do qual não possa recuperar.

Example

Veja o exemplo do CATCH.

Requerimentos

Cabeçalho afx.h

Consulte também

Macros e Globais
Aula CException
Classe CInvalidArgException