Classe `CFileException`

Artigo
04/03/2023

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

Partilhar via

Classe CFileException

Sintaxe

Membros

Construtores públicos

Métodos públicos

Membros de Dados Públicos

Comentários

Hierarquia de herança

Requisitos

CFileException::CFileException

Parâmetros

Comentários

CFileException::ErrnoToException

Parâmetros

Valor de retorno

Comentários

Exemplo

CFileException::GetErrorMessage

Parâmetros

Valor de retorno

Comentários

Exemplo

CFileException::m_cause

Comentários

Exemplo

CFileException::m_lOsError

Comentários

CFileException::m_strFileName

CFileException::OsErrorToException

Parâmetros

Valor de retorno

Exemplo

CFileException::ThrowErrno

Parâmetros

Exemplo

CFileException::ThrowOsError

Parâmetros

Exemplo

Confira também

Comentários

Recursos adicionais

Classe `CFileException`

`CFileException::CFileException`

`CFileException::ErrnoToException`

`CFileException::GetErrorMessage`

`CFileException::m_cause`

`CFileException::m_lOsError`

`CFileException::m_strFileName`

`CFileException::OsErrorToException`

`CFileException::ThrowErrno`

`CFileException::ThrowOsError`