Processamento de exceção
Quando um programa é executado, uma série de condições anormais e erros chamados "exceções" podem ocorrer. Isso pode incluir memória insuficiente, erros de alocação de recursos e falha ao localizar arquivos.
A Biblioteca Microsoft Foundation Class usa um esquema de tratamento de exceções modelado de uma forma muito parecida com a proposta do comitê de padrões ANSI para C++. Um manipulador de exceção 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, gerará uma exceção e o controle será passado para o manipulador de exceção.
Várias macros incluídas na Biblioteca Microsoft Foundation Class configurarão os manipuladores de exceção. Várias outras funções globais ajudam a gerar exceções especializadas e encerrar programas, se necessário. Essas macros e funções globais se enquadram nas seguintes categorias:
Macros de exceção, que estruturam o manipulador de exceção.
Funções geradoras de exceções, que geram exceções de tipos específicos.
Funções de término, que terminam o programa.
Para obter exemplos e mais detalhes, confira o artigo Exceções.
Macros de Exceção
| Nome | Descrição |
|---|---|
| TRY | Designa um bloco de código para processamento de exceção. |
| CATCH | Designa um bloco de código para capturar uma exceção do bloco TRY anterior. |
| CATCH_ALL | Designa um bloco de código para capturar todas as exceções do bloco TRY anterior. |
| AND_CATCH | Designa um bloco de código para capturar tipos adicionais de exceção do bloco TRY anterior. |
| AND_CATCH_ALL | Designa um bloco de código para capturar todos os outros tipos de exceção gerados em um bloco TRY anterior. |
| END_CATCH | Termina o último bloco de código CATCH ou AND_CATCH. |
| END_CATCH_ALL | Termina o último bloco de código CATCH_ALL. |
| THROW | Gera uma exceção especificada. |
| THROW_LAST | Gera a exceção tratada no momento para o próximo manipulador externo. |
Funções Geradoras de Exceções
| Nome | Descrição |
|---|---|
| AfxThrowArchiveException | Gera uma exceção de camada de armazenamento de arquivos. |
| AfxThrowFileException | Gera uma exceção de arquivo. |
| AfxThrowInvalidArgException | Gera uma exceção de argumento inválido. |
| AfxThrowMemoryException | Gera uma exceção de memória. |
| AfxThrowNotSupportedException | Gera uma exceção sem suporte. |
| AfxThrowResourceException | Gera uma exceção de recurso não encontrado do Windows. |
| AfxThrowUserException | Gera uma exceção em uma ação de programa iniciada pelo usuário. |
A biblioteca MFC fornece duas funções geradoras de exceções especificamente para exceções OLE:
Funções de Exceção OLE
| Nome | Descrição |
|---|---|
| AfxThrowOleDispatchException | Gera uma exceção em uma função de automação OLE. |
| AfxThrowOleException | Gera uma exceção OLE. |
Para dar suporte a exceções de banco de dados, as classes de banco de dados fornecem duas classes de exceção, CDBException e CDaoException, e funções globais para dar suporte aos tipos de exceção:
Funções de Exceção DAO
| Nome | Descrição |
|---|---|
| AfxThrowDAOException | Gera um CDaoException a partir de seu próprio código. |
| AfxThrowDBException | Gera um CDBException a partir de seu próprio código. |
A biblioteca MFC fornece a função de término a seguir:
Funções de Término
| Nome | Descrição |
|---|---|
| AfxAbort | Chamado para terminar um aplicativo quando ocorre um erro fatal. |
TRY
Configura um bloco TRY.
TRY
Comentários
Um bloco TRY identifica um bloco de código que pode gerar exceções. Essas exceções são tratadas nos seguintes blocos CATCH e AND_CATCH. A recursão é permitida: as exceções podem ser passadas para um bloco TRY externo, ao ignorá-las ou usar a macro THROW_LAST. Termine o bloco TRY com uma macro END_CATCH ou END_CATCH_ALL.
Para saber mais, confira o artigo Exceções.
Exemplo
Confira o exemplo de CATCH.
Requisitos
Cabeçalho: afx.h
CATCH
Define um bloco de código que captura o primeiro tipo de exceção gerado no bloco TRY anterior.
CATCH(exception_class, exception_object_pointer_name)
Parâmetros
exception_class
Especifica o tipo de exceção a ser testado. Para obter uma lista de classes de exceção padrão, confira a classe CException.
exception_object_pointer_name
Especifica um nome para um ponteiro de objeto de exceção, que será criado pela macro. Você pode usar o nome do ponteiro para acessar o objeto de exceção no bloco CATCH. Essa variável é declarada para você.
Comentários
O código de processamento de exceção pode interrogar o objeto de exceção, se apropriado, para obter mais informações sobre a causa específica da exceção. Invoque a macro THROW_LAST para mudar o processamento para o próximo quadro de exceção externa. Termine o bloco TRY com uma macro END_CATCH.
Se exception_class for a classe CException, todos os tipos de exceção serão capturados. Você pode usar a função de membro CObject::IsKindOf para determinar qual exceção específica foi gerada. Uma maneira melhor de capturar vários tipos de exceções é usar instruções sequenciais AND_CATCH, cada uma com um tipo de exceção diferente.
O ponteiro do objeto de exceção é criado pela macro. Você não precisa declarar isso por si mesmo.
Observação
O bloco CATCH é definido como um escopo do C++ entre chaves. Se você declarar variáveis nesse escopo, elas estarão acessíveis somente dentro desse escopo. Isso também se aplica a exception_object_pointer_name.
Para obter mais informações sobre exceções e a macro CATCH, confira o artigo Exceções.
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.
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 gerados 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. Você pode usar o nome do ponteiro para acessar o objeto de exceção no bloco CATCH_ALL. Essa variável é declarada para você.
Comentários
O código de processamento de exceção pode interrogar o objeto de exceção, se apropriado, para obter mais informações sobre a causa específica da exceção. Invoque a macro THROW_LAST para mudar o processamento para o próximo quadro de exceção externa. Se você usar CATCH_ALL, termine o bloco TRY com uma macro END_CATCH_ALL.
Observação
O bloco CATCH_ALL é definido como um escopo do C++ entre chaves. Se você declarar variáveis nesse escopo, elas estarão acessíveis somente dentro desse escopo.
Para mais informações sobre exceções, confira o artigo Exceções.
Exemplo
Confira o exemplo de CFile::Abort.
Requisitos
Cabeçalho afx.h
AND_CATCH
Defina um bloco de código para capturar os tipos adicionais de exceção gerados em um bloco TRY anterior.
AND_CATCH(exception_class, exception_object_pointer_name)
Parâmetros
exception_class
Especifica o tipo de exceção a ser testado. Para obter uma lista de classes de exceção padrão, confira a classe CException.
exception_object_pointer_name
Um nome para um ponteiro de objeto de exceção, que será criado pela macro. Você pode usar o nome do ponteiro para acessar o objeto de exceção no bloco AND_CATCH. Essa variável é declarada para você.
Comentários
Use a macro CATCH para capturar um tipo de exceção e, em seguida, a macro AND_CATCH para capturar cada tipo subsequente. Termine o bloco TRY com uma macro END_CATCH.
O código de processamento de exceção pode interrogar o objeto de exceção, se apropriado, para obter mais informações sobre a causa específica da exceção. Chame a macro THROW_LAST no bloco AND_CATCH para deslocar o processamento para o próximo quadro de exceção externa. AND_CATCH marca o final do bloco CATCH ou AND_CATCH anterior.
Observação
O bloco CATCH é definido como escopo do C++ (entre chaves). Se você declarar variáveis nesse escopo, lembre-se que elas estarão acessíveis somente dentro desse escopo. Isso também se aplica à variável exception_object_pointer_name.
Exemplo
Confira o exemplo de CATCH.
Requisitos
Cabeçalho afx.h
AND_CATCH_ALL
Defina um bloco de código para capturar os tipos adicionais de exceção gerados em um 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. Você pode usar o nome do ponteiro para acessar o objeto de exceção no bloco AND_CATCH_ALL. Essa variável é declarada para você.
Comentários
Use a macro CATCH para capturar um tipo de exceção e, em seguida, a macro AND_CATCH_ALL para capturar todos os outros tipos subsequentes. Se você usar AND_CATCH_ALL, termine o bloco TRY com uma macro END_CATCH_ALL.
O código de processamento de exceção pode interrogar o objeto de exceção, se apropriado, para obter mais informações sobre a causa específica da exceção. Chame a macro THROW_LAST no bloco AND_CATCH_ALL para deslocar o processamento para o próximo quadro de exceção externa. AND_CATCH_ALL marca o final do bloco CATCH ou AND_CATCH_ALL anterior.
Observação
O bloco AND_CATCH_ALL é definido como um escopo do C++ (entre chaves). Se você declarar variáveis nesse escopo, lembre-se que elas estarão acessíveis somente dentro desse escopo.
Requisitos
Cabeçalho afx.h
END_CATCH
Marca o final do último bloco CATCH ou AND_CATCH.
END_CATCH
Comentários
Para obter mais informações sobre a macro END_CATCH, confira o artigo Exceções.
Requisitos
Cabeçalho afx.h
END_CATCH_ALL
Marca o final do último bloco CATCH_ALL88 ou AND_CATCH_ALL.
END_CATCH_ALL
Requisitos
Cabeçalho afx.h
LANÇAMENTO (MFC)
Gera a exceção especificada.
THROW(exception_object_pointer)
Parâmetros
exception_object_pointer
Aponta para um objeto de exceção derivado de CException.
Comentários
THROW interrompe a execução do programa, passando o controle para o bloco CATCH associado no programa. Se você não tiver fornecido o bloco CATCH, o controle será passado para um módulo da Biblioteca Microsoft Foundation Class, que imprime uma mensagem de erro e sai.
Para saber mais, confira o artigo Exceções.
Requisitos
Cabeçalho afx.h
THROW_LAST
Gera a exceção novamente para o próximo bloco CATCH externo.
THROW_LAST()
Comentários
Essa macro permite que você gere uma exceção criada localmente. Se você tentar lançar uma exceção que acabou de capturar, ela normalmente sairá do escopo e será excluída. Com THROW_LAST, a exceção é passada corretamente para o próximo manipulador CATCH.
Para saber mais, confira o artigo Exceções.
Exemplo
Confira o exemplo de CFile::Abort.
Requisitos
Cabeçalho afx.h
AfxThrowArchiveException
Gera uma exceção de camada de armazenamento de arquivos.
void AfxThrowArchiveException(int cause, LPCTSTR lpszArchiveName);
Parâmetros
causa
Especifica um inteiro que indica o motivo da exceção. Para obter uma lista dos valores possíveis, confira CArchiveException::m_cause.
lpszArchiveName
Aponta para uma cadeia de caracteres que contém o nome do objeto CArchive que causou a exceção (se disponível).
Requisitos
Cabeçalho afx.h
AfxThrowFileException
Gera uma exceção de arquivo.
void AfxThrowFileException(
int cause,
LONG lOsError = -1,
LPCTSTR lpszFileName = NULL);
Parâmetros
causa
Especifica um inteiro que indica o motivo da exceção. Para obter uma lista dos valores possíveis, confira CFileException::m_cause.
lOsError
Contém o número do erro do sistema operacional (se disponível) que indica o motivo da exceção. Confira o manual do sistema operacional para obter uma lista de códigos de erro.
lpszFileName
Aponta para uma cadeia de caracteres que contém o nome do arquivo que causou a exceção (se disponível).
Comentários
Você é responsável por determinar a causa com base no código de erro do sistema operacional.
Requisitos
Cabeçalho afx.h
AfxThrowInvalidArgException
Gera uma exceção de argumento inválido.
Sintaxe
void AfxThrowInvalidArgException( );
Comentários
Essa função é chamada quando argumentos inválidos são usados.
Requisitos
Cabeçalho: afx.h
AfxThrowMemoryException
Gera uma exceção de memória.
void AfxThrowMemoryException();
Comentários
Chame essa função em caso de falha nas chamadas para os alocadores de memória do sistema subjacentes (como malloc e a função GlobalAlloc do Windows). Você não precisa chamá-la para new, pois new gerará uma exceção de memória automaticamente, em caso de falha na alocação de memória.
Requisitos
Cabeçalho afx.h
AfxThrowNotSupportedException
Gera uma exceção que é o resultado de uma solicitação para um recurso sem suporte.
void AfxThrowNotSupportedException();
Requisitos
Cabeçalho afx.h
AfxThrowResourceException
Gera uma exceção de recurso.
void AfxThrowResourceException();
Comentários
Essa função normalmente é chamada quando um recurso do Windows não pode ser carregado.
Requisitos
Cabeçalho afx.h
AfxThrowUserException
Gera uma exceção para interromper uma operação de usuário final.
void AfxThrowUserException();
Comentários
Essa função normalmente é chamada imediatamente depois que AfxMessageBox relatou um erro ao usuário.
Requisitos
Cabeçalho afx.h
AfxThrowOleDispatchException
Use essa função para gerar uma exceção em 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 do aplicativo.
lpszDescription
Descrição verbal do erro.
nDescriptionID
ID do recurso para a descrição do erro verbal.
nHelpID
Um contexto de ajuda para o arquivo de ajuda do aplicativo (.HLP).
Comentários
As informações fornecidas para essa função podem ser exibidas pelo aplicativo de condução (Microsoft Visual Basic ou outro aplicativo cliente de automação OLE).
Exemplo
// 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;
}
Requisitos
Cabeçalho afx.h
AfxThrowOleException
Cria um objeto do tipo COleException e gera uma exceção.
void AFXAPI AfxThrowOleException(SCODE sc);
void AFXAPI AfxThrowOleException(HRESULT hr);
Parâmetros
sc
Um código de status OLE que indica o motivo da exceção.
RH
Identificador para um código de resultado que indica o motivo da exceção.
Comentários
A versão que usa um HRESULT como argumento converte esse código de resultado no SCODE correspondente. Para obter mais informações sobre o HRESULT e SCODE, confira Estrutura de códigos de erro COM no SDK do Windows.
Requisitos
Cabeçalho afxdao.h
AfxThrowDaoException
Chame essa função para gerar uma exceção do tipo CDaoException a partir de 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 estendido do DAO, que pode ser um dos valores listados em CDaoException::m_nAfxDaoError.
scode
Um código de erro OLE do DAO, do tipo SCODE. Para obter informações, confira CDaoException::m_scode.
Comentários
A estrutura também chama AfxThrowDaoException. Na chamada, você pode passar um dos parâmetros ou ambos. Por exemplo, se você quiser gerar um dos erros definidos em CDaoException::nAfxDaoError, mas não se importar com o parâmetro scode, passe um código válido no parâmetro nAfxDaoError e aceite o valor padrão para scode.
Para obter informações sobre exceções relacionadas às classes MFC DAO, confira a classe CDaoException neste manual e o artigo Exceções: Exceções de Banco de Dados.
Requisitos
Cabeçalho afxdb.h
AfxThrowDBException
Chame essa função para gerar uma exceção do tipo CDBException a partir de seu 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 fez com que a exceção fosse gerada.
pdb
Um ponteiro para o objeto CDatabase, que representa a conexão de fonte de dados à qual a exceção está associada.
HSTMT
Um identificador ODBC HSTMT que especifica o identificador da instrução ao qual a exceção está associada.
Comentários
A estrutura chama AfxThrowDBException quando recebe um RETCODE ODBC de uma chamada para uma função de API ODBC e interpreta o RETCODE como uma condição excepcional, em vez de um erro esperado. Por exemplo, uma operação de acesso a dados pode falhar devido a um erro de leitura de disco.
Para obter informações sobre os valores RETCODE definidos pelo ODBC, confira o Capítulo 8, "Recuperação de informações de status e erro", no SDK do Windows. Para obter informações sobre extensões da biblioteca MFC para esses códigos, confira a classe CDBException.
Requisitos
Cabeçalho afx.h
AfxAbort
A função de término padrão fornecida pela biblioteca MFC.
void AfxAbort();
Comentários
AfxAbort é chamado internamente pelas funções de membro da biblioteca MFC, quando ocorre um erro fatal, como uma exceção não capturada que não pode ser tratada. Você pode chamar AfxAbort no caso raro em que encontrar um erro catastrófico do qual não é possível se recuperar.
Exemplo
Confira o exemplo de CATCH.
Requisitos
Cabeçalho afx.h
Confira também
Macros e Globais
Classe CException
Classe CInvalidArgException
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de