Classe CFileException

Representa uma condição de exceção relacionada ao arquivo.

Sintaxe

class CFileException : public CException

Membros

Construtores públicos

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

Métodos públicos

Nome	Descrição
CFileException::ErrnoToException	Retorna código de causa correspondente a um número de erro em tempo de execução.
CFileException::GetErrorMessage	Recupera a mensagem que descreve uma exceção.
CFileException::OsErrorToException	Retorna um código de causa correspondente a um código de erro do sistema operacional.
CFileException::ThrowErrno	Gera uma exceção de arquivo com base em um número de erro de runtime.
CFileException::ThrowOsError	Gera uma exceção de arquivo com base em um número de erro do sistema operacional.

Membros de Dados Públicos

Nome	Descrição
CFileException::m_cause	Contém código portátil correspondente à causa da exceção.
CFileException::m_lOsError	Contém o número de erro do sistema operacional relacionado.
CFileException::m_strFileName	Contém o nome do arquivo para essa exceção.

Comentários

A classe CFileException inclui membros de dados públicos que contêm o código de causa portátil e o número de erro específico do sistema operacional. A classe também fornece funções de membro estático para gerar exceções de arquivo e para retornar códigos de causa para erros do sistema operacional e erros de tempo de execução C.

Os objetos CFileException são construídos e gerados em funções de membro CFile e em funções de membro de classes derivadas. Você pode acessar esses objetos dentro do escopo de uma expressão CATCH. Para portabilidade, use apenas o código de causa para obter o motivo de uma exceção. Para mais informações sobre exceções, confira o artigo Tratamento de exceções (MFC).

Hierarquia de herança

CObject

CException

CFileException

Requisitos

Cabeçalho: afx.h

CFileException::CFileException

Constrói um objeto CFileException que armazena o código de causa e o código do sistema operacional no objeto.

CFileException(
    int cause = CFileException::none,
    LONG lOsError = -1,
    LPCTSTR lpszArchiveName = NULL);

Parâmetros

cause
A variável de tipo enumerado que indica o motivo da exceção. Confira CFileException::m_cause para obter uma lista de valores possíveis.

lOsError
Um motivo específico do sistema operacional para a exceção, se disponível. O parâmetro lOsError fornece mais informações do que cause.

lpszArchiveName
Aponta para uma cadeia de caracteres que contém o nome do objeto CFile que está causando a exceção.

Comentários

Não use esse construtor diretamente, mas chame a função global AfxThrowFileException.

Observação

A variável lOsError se aplica somente a objetos CFile e CStdioFile. A classe CMemFile não lida com esse código de erro.

CFileException::ErrnoToException

Converte um determinado valor de erro de biblioteca em tempo de execução em um valor de erro enumerado CFileException.

static int PASCAL ErrnoToException(int nErrno);

Parâmetros

nErrno
Um código de erro inteiro conforme definido no arquivo de inclusão em tempo de execução ERRNO.H.

Valor de retorno

Valor enumerado que corresponde a um determinado valor de erro de biblioteca em tempo de execução.

Comentários

Confira CFileException::m_cause para uma lista de valores enumerados.

Exemplo

ASSERT(CFileException::ErrnoToException(EACCES) == 
   CFileException::accessDenied);

CFileException::GetErrorMessage

Recupera o texto que descreve uma exceção.

virtual BOOL GetErrorMessage(
    LPTSTR lpszError,
    UINT nMaxError,
    PUINT pnHelpContext = NULL) const;

Parâmetros

lpszError
[in, out] Ponteiro para um buffer que recebe uma mensagem de erro.

nMaxError
[in] Indica o número máximo de caracteres que o buffer especificado pode conter. Isso inclui o caractere de terminação NULL.

pnHelpContext
[in, out] Ponteiro para um inteiro sem sinal que recebe a ID de contexto de ajuda. Se NULL, nenhuma ID será retornada.

Valor de retorno

TRUE se o método foi bem-sucedido; caso contrário, FALSE.

Comentários

Se o buffer especificado for muito pequeno, a mensagem de erro será truncada.

Exemplo

O exemplo a seguir usa CFileException::GetErrorMessage.

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.GetErrorMessage()
// will retrieve an appropriate message describing
// the error, and we'll add our own text
// to make sure the user is perfectly sure what
// went wrong.

if (!fileInput.Open(_T("\\Too\\Many\\Bad\\Dirs.DAT"), CFile::modeRead, &ex))
{
   TCHAR szCause[255];
   CString strFormatted;

   ex.GetErrorMessage(szCause, 255);

   // (in real life, it's probably more
   // appropriate to read this from
   //  a string resource so it would be easy to
   // localize)

   strFormatted = _T("The data file could not be opened because of this error: ");
   strFormatted += szCause;

   AfxMessageBox(strFormatted);
}
else
{
   // the file was opened, so do whatever work
   // with fileInput
   // we were planning...

   fileInput.Close();
}

CFileException::m_cause

Contém valores definidos por um tipo enumerado de CFileException.

int m_cause;

Comentários

Esse membro de dados é uma variável pública do tipo int. Os enumeradores e seus significados são os seguintes:

Erro	Valor e significado
CFileException::none	0: Não ocorreu nenhum erro.
CFileException::genericException	1: Ocorreu um erro não especificado.
CFileException::fileNotFound	2: não foi possível localizar o arquivo.
CFileException::badPath	3: Todo ou parte do caminho é inválido.
CFileException::tooManyOpenFiles	4: O número permitido de arquivos abertos foi excedido.
CFileException::accessDenied	5: não foi possível acessar o arquivo.
CFileException::invalidFile	6: Houve uma tentativa de usar um identificador de arquivo inválido.
CFileException::removeCurrentDir	7: O diretório de trabalho atual não pode ser removido.
CFileException::directoryFull	8: Não há mais entradas de diretório.
CFileException::badSeek	9: Ocorreu um erro ao tentar definir o ponteiro do arquivo.
CFileException::hardIO	10: Ocorreu um erro de hardware.
CFileException::sharingViolation	11: SHARE.EXE não foi carregado ou uma região compartilhada foi bloqueada.
CFileException::lockViolation	12: Houve uma tentativa de bloquear uma região que já estava bloqueada.
CFileException::diskFull	13: O disco está cheio.
CFileException::endOfFile	14: O final do arquivo foi alcançado.

Observação

Esses enumeradores de causa de CFileException são diferentes dos enumeradores de causa de CArchiveException.

Observação

CArchiveException::generic foi preterido. Use o genericException em vez disso. Se generic for usado em um aplicativo e compilado com /clr, os erros de sintaxe resultantes não serão fáceis de decifrar.

Exemplo

try
{
   CFile f(_T("M_Cause_File.dat"), CFile::modeWrite);
}
catch(CFileException* e)
{
   if( e->m_cause == CFileException::fileNotFound)
      TRACE(_T("ERROR: File not found\n"));
   e->Delete();
}

CFileException::m_lOsError

Contém o código de erro do sistema operacional para essa exceção.

LONG m_lOsError;

Comentários

Confira o manual técnico do sistema operacional para obter uma lista de códigos de erro. Esse membro de dados é uma variável pública do tipo LONG.

CFileException::m_strFileName

Contém o nome do arquivo para essa condição de exceção.

CString m_strFileName;

CFileException::OsErrorToException

Retorna um enumerador que corresponde a um determinado valor lOsError. Se o código de erro for desconhecido, a função retornará CFileException::generic.

static int PASCAL OsErrorToException(LONG lOsError);

Parâmetros

lOsError
Um código de erro específico do sistema operacional.

Valor de retorno

Valor enumerado que corresponde a um determinado valor de erro do sistema operacional.

Exemplo

ASSERT(CFileException::OsErrorToException(ERROR_ACCESS_DENIED) == 
   CFileException::accessDenied);

CFileException::ThrowErrno

Constrói um objeto CFileException correspondente a um determinado valor nErrno e gera a exceção.

static void PASCAL ThrowErrno(int nErrno, LPCTSTR lpszFileName = NULL);

Parâmetros

nErrno
Um código de erro inteiro conforme definido no arquivo de inclusão em tempo de execução ERRNO.H.

lpszFileName
Um ponteiro para a cadeia de caracteres que contém o nome do arquivo que causou a exceção, se disponível.

Exemplo

CFileException::ThrowErrno(EACCES);  // "access denied"

CFileException::ThrowOsError

Gera um CFileException correspondente a um determinado valor lOsError. Se o código de erro for desconhecido, a função gerará uma exceção codificada como CFileException::generic.

static void PASCAL ThrowOsError(LONG lOsError, LPCTSTR lpszFileName = NULL);

Parâmetros

lOsError
Um código de erro específico do sistema operacional.

lpszFileName
Um ponteiro para a cadeia de caracteres que contém o nome do arquivo que causou a exceção, se disponível.

Exemplo

CFileException::ThrowOsError(ERROR_ACCESS_DENIED);  // "access denied"         

Confira também

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