Classe CFile

A classe base para classes de arquivo Microsoft Foundation Class.

Sintaxe

class CFile : public CObject

Membros

Construtores públicos

Nome	Descrição
CFile::CFile	Cria um objeto CFile a partir de um identificador de caminho ou de arquivo.

Métodos públicos

Nome	Descrição
CFile::Abort	Fecha um arquivo, ignorando todos os avisos e erros.
CFile::Close	Fecha um arquivo e exclui o objeto.
CFile::Duplicate	Cria um objeto duplicado com base nesse arquivo.
CFile::Flush	Libera todos os dados que ainda devem ser gravados.
CFile::GetFileName	Recupera o nome do arquivo selecionado.
CFile::GetFilePath	Recupera o caminho completo do arquivo selecionado.
CFile::GetFileTitle	Recupera o título do arquivo selecionado.
CFile::GetLength	Recupera o comprimento do arquivo.
CFile::GetPosition	Recupera o ponteiro do arquivo atual.
CFile::GetStatus	Recupera o status do arquivo aberto ou, na versão estática, recupera o status do arquivo especificado (estático, função virtual).
CFile::LockRange	Bloqueia um intervalo de bytes em um arquivo.
CFile::Open	Abre com segurança um arquivo com uma opção de teste de erro.
CFile::Read	Lê dados (não armazenados) de um arquivo na posição atual do arquivo.
CFile::Remove	Exclui o arquivo especificado (função estática).
CFile::Rename	Renomeia o arquivo especificado (função estática).
CFile::Seek	Posiciona o ponteiro do arquivo atual.
CFile::SeekToBegin	Posiciona o ponteiro do arquivo atual no início do arquivo.
CFile::SeekToEnd	Posiciona o ponteiro do arquivo atual no final do arquivo.
CFile::SetFilePath	Define o caminho completo do arquivo selecionado.
CFile::SetLength	Altera o comprimento do arquivo.
CFile::SetStatus	Define o status do arquivo especificado (estático, função virtual).
CFile::UnlockRange	Desbloqueia um intervalo de bytes em um arquivo.
CFile::Write	Grava dados (não armazenados) em um arquivo na posição do arquivo atual.

Operadores públicos

Nome	Descrição
CFile::operator HANDLE	Um identificador para um objeto CFile.

Membros de Dados Públicos

Nome	Descrição
CFile::hFileNull	Determina se o objeto CFile tem um identificador válido.
CFile::m_hFile	Geralmente contém o identificador de arquivo do sistema operacional.

Membros de Dados Protegidos

Nome	Descrição
CFile::m_pTM	Ponteiro para o objeto CAtlTransactionManager.

Comentários

Fornece diretamente serviços de entrada/saída de disco binário não armazenados e dá suporte indiretamente a arquivos de texto e arquivos de memória por meio de suas classes derivadas. A CFile funciona em conjunto com a classe CArchive para dar suporte à serialização de objetos Microsoft Foundation Class.

A relação hierárquica entre essa classe e as classes derivadas permite que o programa opere em todos os objetos de arquivo por meio da interface polimórfica CFile. Um arquivo de memória, por exemplo, comporta-se como um arquivo de disco.

Use CFile e classes derivadas para a E/S do disco de uso geral. Use ofstream ou outras classes iostream da Microsoft para o texto formatado enviado a um arquivo de disco.

Normalmente, um arquivo de disco é aberto automaticamente na criação de CFile e é fechado na destruição. As funções de membro estático permitem que você interrogue o status de um arquivo sem abri-lo.

Para obter mais informações sobre como usar a CFile, confira os artigos Arquivos em MFC e Tratamento de arquivos na Referência de biblioteca de runtime.

Hierarquia de herança

CObject

CFile

Requisitos

Cabeçalho: afx.h

CFile::Abort

Fecha o arquivo associado a esse objeto e torna o arquivo protegido contra leitura ou gravação.

virtual void Abort();

Comentários

Caso ainda não tenha fechado o arquivo antes de destruir o objeto, o destruidor o fechará para você.

Ao tratar exceções, CFile::Abort difere de CFile::Close de duas formas importantes. Primeiro, a função Abort não gerará uma exceção em falhas, pois as falhas são ignoradas por Abort. Segundo, Abort não executará ASSERT se o arquivo não tiver sido aberto ou se tiver sido fechado anteriormente.

Se você usou new para alocar o objeto CFile no heap, deverá excluí-lo depois de fechar o arquivo. Abort define m_hFile como CFile::hFileNull.

Exemplo

CStdioFile fileTest;
TCHAR* pszFileName = _T("Abort_File.dat");

// do stuff that may cause exceptions
CFileException ex;
if (!fileTest.Open(pszFileName, CFile::modeWrite, &ex))
{
   ex.ReportError();
   fileTest.Abort();   // close file safely and quietly
}

CFile::CFile

Constrói e inicializa um objeto CFile.

CFile();
CFile(CAtlTransactionManager* pTM);
CFile(HANDLE hFile);

CFile(
LPCTSTR lpszFileName,
UINT nOpenFlags);

CFile(
LPCTSTR lpszFileName,
UINT nOpenFlags,
CAtlTransactionManager* pTM);

Parâmetros

hFile
Handle de um arquivo para anexar ao objeto CFile.

lpszFileName
Caminho relativo ou completo de um arquivo para anexar ao objeto CFile.

nOpenFlags
Combinação bit a bit (OR) das opções de acesso de arquivo do arquivo especificado. Consulte a seção Comentários para obter possíveis opções.

pTM
Ponteiro para objeto CAtlTransactionManager

Comentários

As cinco tabelas a seguir listam as possíveis opções para o parâmetro nOpenFlags.

Escolha apenas uma das opções de modo de acesso de arquivo a seguir. O modo de acesso de arquivo padrão é CFile::modeRead, que é somente leitura.

Valor	Descrição
CFile::modeRead	Solicita acesso somente leitura.
CFile::modeWrite	Solicita acesso somente gravação.
CFile::modeReadWrite	Solicita acesso de leitura e gravação.

Escolha uma das opções de modo de caractere a seguir.

Valor	Descrição
CFile::typeBinary	Define modo binário (usado apenas em classes derivadas).
CFile::typeText	Define modo de texto com processamento especial para retorno de carro (usado apenas em classes derivadas).
CFile::typeUnicode	Define modo Unicode (usado apenas em classes derivadas). O texto é gravado no arquivo em formato Unicode quando o aplicativo é compilado em uma configuração Unicode. Nenhum BOM é gravado no arquivo.

Escolha apenas uma das opções de modo de compartilhamento de arquivo a seguir. O modo de compartilhamento de arquivo padrão é CFile::shareExclusive, que é exclusivo.

Valor	Descrição
CFile::shareDenyNone	Sem restrições de compartilhamento.
CFile::shareDenyRead	Nega acesso de leitura a todos os outros.
CFile::shareDenyWrite	Nega acesso de gravação a todos os outros.
CFile::shareExclusive	Nega acesso de leitura e gravação a todos os outros.

Escolha a primeira ou as duas opções de modo de criação de arquivo a seguir. O modo de criação padrão é CFile::modeNoTruncate, que é abrir existente.

Valor	Descrição
CFile::modeCreate	Cria um novo arquivo caso já não exista um. Se o arquivo já existir, ele será substituído e definido inicialmente como tamanho zero.
CFile::modeNoTruncate	Cria um novo arquivo se nenhum arquivo existir; caso contrário, se o arquivo já existir, ele será anexado ao objeto CFile.

Escolha as opções de cache de arquivo conforme descritas a seguir. Por padrão, o sistema usa um esquema de cache de uso geral que não está disponível como opção.

Valor	Descrição
CFile::osNoBuffer	O sistema não usa um cache intermediário para o arquivo. Esta opção cancela as duas opções a seguir.
CFile::osRandomAccess	O cache do arquivo é otimizado para acesso aleatório. Não use essa opção nem a opção de varredura sequencial.
CFile::osSequentialScan	O cache do arquivo é otimizado para acesso sequencial. Não use essa opção nem a opção de acesso aleatório.
CFile::osWriteThrough	As operações de gravação são feitas sem atraso.

Escolha a opção de segurança a seguir para impedir que o handle do arquivo seja herdado. Por padrão, qualquer novo processo filho pode usar o handle do arquivo.

Valor	Descrição
CFile::modeNoInherit	Impede qualquer processo filho de usar o handle do arquivo.

O construtor padrão inicializa membros, mas não anexa um arquivo ao objeto CFile. Depois de usar esse construtor, use o método CFile::Open para abrir um arquivo e anexá-lo ao objeto CFile.

O construtor com um parâmetro inicializa membros e anexa um arquivo existente ao objeto CFile.

O construtor com dois parâmetros inicializa membros e tenta abrir o arquivo especificado. Se o construtor abrir o arquivo especificado com sucesso, o arquivo será anexado ao objeto CFile; caso contrário, o construtor lança um ponteiro para um objeto CInvalidArgException. Para obter mais informações sobre como tratar exceções, confira Exceções.

Se um objeto CFile abrir um arquivo especificado com sucesso, ele fechará esse arquivo automaticamente quando o objeto CFile for destruído; caso contrário, será necessário fechar explicitamente o arquivo após ele não estar mais anexado ao objeto CFile.

Exemplo

O código a seguir mostra como usar um CFile.

HANDLE hFile = CreateFile(_T("CFile_File.dat"),
   GENERIC_WRITE, FILE_SHARE_READ,
   NULL, CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL, NULL);

if (hFile == INVALID_HANDLE_VALUE)
{
   AfxMessageBox(_T("Couldn't create the file!"));
}
else
{
   // Attach a CFile object to the handle we have.
   CFile myFile(hFile);

   static const TCHAR sz[] = _T("I love CFile!");

   // write string
   myFile.Write(sz, sizeof(sz));

   // We need to call Close() explicitly. Note that there's no need to 
   // call CloseHandle() on the handle returned by the API because 
   // Close() automatically calls CloseHandle() for us.
   myFile.Close();

CFile::Close

Fecha o arquivo associado a esse objeto e torna o arquivo protegido contra leitura ou gravação.

virtual void Close();

Comentários

Caso ainda não tenha fechado o arquivo antes de destruir o objeto, o destruidor o fechará para você.

Se você usou new para alocar o objeto CFile no heap, deverá excluí-lo depois de fechar o arquivo. Close define m_hFile como CFile::hFileNull.

Exemplo

Confira o exemplo de CFile::CFile.

CFile::Duplicate

Constrói um objeto CFile duplicado para um determinado arquivo.

virtual CFile* Duplicate() const;

Valor de Devolução

Um ponteiro para um objeto CFile duplicado.

Comentários

Essa função é equivalente à função de tempo de execução C _dup.

CFile::Flush

Força que todos os dados restantes no buffer de arquivo sejam gravados no arquivo.

virtual void Flush();

Comentários

O uso de Flush não garante a liberação de buffers de CArchive. Se você estiver usando um arquivo, chame CArchive::Flush primeiro.

Exemplo

Confira o exemplo de CFile::SetFilePath.

CFile::GetFileName

Chame essa função de membro para recuperar o nome de um arquivo especificado.

virtual CString GetFileName() const;

Valor de Devolução

O nome do arquivo.

Comentários

Por exemplo, quando você chama GetFileName para gerar uma mensagem para o usuário sobre o arquivo c:\windows\write\myfile.wri, é retornado o nome do arquivo: myfile.wri.

Para retornar todo o caminho do arquivo, incluindo o nome, chame GetFilePath. Para retornar o título do arquivo (myfile), chame GetFileTitle.

Exemplo

Esse fragmento de código abre o arquivo SYSTEM.INI no seu diretório WINDOWS. Se encontrado, o exemplo imprimirá o nome, o caminho e o título, conforme mostrado em Saída:

try
{
   // try to open the file
   CFile sysFile(_T("C:\\WINDOWS\\SYSTEM.INI"), CFile::modeRead);

   // print out path name and title information
   _tprintf_s(_T("Path is : \"%s\"\n"),
      (LPCTSTR) sysFile.GetFilePath());
   _tprintf_s(_T("Name is : \"%s\"\n"),
      (LPCTSTR) sysFile.GetFileName());
   _tprintf_s(_T("Title is: \"%s\"\n"), 
      (LPCTSTR) sysFile.GetFileTitle());

   // close the file handle
   sysFile.Close();
}
catch (CFileException* pEx)
{
   // if an error occurs, just make a message box
   pEx->ReportError();
   pEx->Delete();
}

CFile::GetFilePath

Chame essa função de membro para recuperar o caminho completo de um arquivo especificado.

virtual CString GetFilePath() const;

Valor de Devolução

O caminho completo do arquivo especificado.

Comentários

Por exemplo, quando você chama GetFilePath para gerar uma mensagem para o usuário sobre o arquivo c:\windows\write\myfile.wri, é retornado o caminho completo: c:\windows\write\myfile.wri.

Para retornar apenas o nome do arquivo (myfile.wri), chame GetFileName. Para retornar o título do arquivo (myfile), chame GetFileTitle.

Exemplo

Confira o exemplo de GetFileName.

CFile::GetFileTitle

Chame essa função de membro para recuperar o título do arquivo (o nome de exibição) do arquivo.

virtual CString GetFileTitle() const;

Valor de Devolução

O título do arquivo subjacente.

Comentários

Esse método chama GetFileTitle para recuperar o título do arquivo. Se tiver êxito, o método retornará a cadeia de caracteres que o sistema usaria para exibir o nome do arquivo para o usuário. Caso contrário, o método chama PathFindFileName para recuperar o nome do arquivo (incluindo a extensão de arquivo) do arquivo subjacente. Isso significa que a extensão de arquivo nem sempre está incluída na cadeia de caracteres do título de arquivo retornada. Para obter mais informações, confira GetFileTitle e PathFindFileName no SDK do Windows.

Para retornar todo o caminho do arquivo, incluindo o nome, chame GetFilePath. Para retornar apenas o nome do arquivo, chame GetFileName.

Exemplo

Confira o exemplo de GetFileName.

CFile::GetLength

Obtém o comprimento lógico atual do arquivo em bytes.

virtual ULONGLONG GetLength() const;

Valor de Devolução

O comprimento do arquivo.

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();
   pEx->Delete();
}
catch(CMemoryException* pEx)
{
   pEx->ReportError();
   pEx->Delete();
   // 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();
}

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

CFile::GetPosition

Obtém o valor atual do ponteiro do arquivo, que pode ser usado em chamadas posteriores de Seek.

virtual ULONGLONG GetPosition() const;

Valor de Devolução

O ponteiro do arquivo.

Exemplo

CFile cfile;
cfile.Open(_T("Seek_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
LONGLONG lOffset = 1000;
ULONGLONG lActual;
lActual = cfile.Seek(lOffset, CFile::begin);
ASSERT(cfile.GetPosition() == lActual);

CFile::GetStatus

Esse método recupera informações de status relacionadas a uma determinada instância de objeto CFile ou a um determinado caminho de arquivo.

BOOL GetStatus(CFileStatus& rStatus) const;

static BOOL PASCAL GetStatus(
    LPCTSTR lpszFileName,
    CFileStatus& rStatus,
    CAtlTransactionManager* pTM = NULL);

Parâmetros

rStatus
Uma referência a uma estrutura CFileStatus fornecida pelo usuário que receberá as informações de status. A estrutura CFileStatus tem os seguintes campos:

• CTime m_ctime A data e a hora em que o arquivo foi criado.

• CTime m_mtime A data e a hora em que o arquivo foi modificado pela última vez.

• CTime m_atime A data e a hora em que o arquivo foi acessado para leitura.

• ULONGLONG m_size O tamanho lógico do arquivo em bytes, conforme relatado pelo comando DIR.

• BYTE m_attribute O byte do atributo do arquivo.

• char m_szFullName[_MAX_PATH] O nome de arquivo absoluto no conjunto de caracteres do Windows.

lpszFileName
Uma cadeia de caracteres no conjunto de caracteres do Windows, a qual é o caminho para o arquivo desejado. O caminho pode ser relativo ou absoluto ou pode conter um nome de caminho de rede.

pTM
Ponteiro para objeto CAtlTransactionManager

Valor de Devolução

TRUE se as informações de status do arquivo especificado forem obtidas com êxito; caso contrário, FALSE.

Comentários

A versão não estática de GetStatus recupera informações de status do arquivo aberto associado ao objeto CFile fornecido. A versão estática de GetStatus obtém o status do arquivo de um determinado caminho de arquivo sem abri-lo realmente. Essa versão ajuda a testar a existência e os direitos de acesso de um arquivo.

O membro m_attribute da estrutura CFileStatus refere-se ao conjunto de atributos de arquivo. A classe CFile fornece o tipo de enumeração Attribute para que os atributos de arquivo possam ser especificados simbolicamente:

enum Attribute {
    normal =    0x00,
    readOnly =  0x01,
    hidden =    0x02,
    system =    0x04,
    volume =    0x08,
    directory = 0x10,
    archive =   0x20
    };

Exemplo

CFile cfile;
cfile.Open(_T("SetLength_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
ULONGLONG dwNewLength = 10000;
cfile.SetLength(dwNewLength);
CFileStatus status;
if(cfile.GetStatus(status))    // virtual member function
{
   TRACE(_T("File size = %u\n"), status.m_size);
}
TCHAR* pszFileName = _T("SetLength_File.dat");
if(CFile::GetStatus(pszFileName, status))   // static function
{
   TRACE(_T("Full file name = %s\n"), status.m_szFullName);
}

CFile::hFileNull

Determina a presença de um identificador de arquivo válido para o objeto CFile.

static AFX_DATA const HANDLE hFileNull;

Comentários

Essa constante é usada para determinar se o objeto CFile tem um identificador de arquivo válido.

O exemplo a seguir demonstra essa operação:

if (myFile.m_hFile != CFile::hFileNull)
   ;//perform operations on the file
else
   ;//indicate the presence of an invalid handle         

CFile::LockRange

Bloqueia um intervalo de bytes em um arquivo aberto, gerando uma exceção se o arquivo já estiver bloqueado.

virtual void LockRange(
    ULONGLONG dwPos,
    ULONGLONG dwCount);

Parâmetros

dwPos
O deslocamento de bytes do início do intervalo de bytes a ser bloqueado.

dwCount
O número de bytes no intervalo a ser bloqueado.

Comentários

Os bytes bloqueados em um arquivo impedem o acesso a esses bytes por outros processos. Você pode bloquear mais de uma região de um arquivo, mas nenhuma região sobreposta é permitida.

Quando você desbloqueia a região usando a função membro UnlockRange, o intervalo de bytes deve corresponder exatamente à região que foi bloqueada anteriormente. A função LockRange não mescla regiões adjacentes. Se duas regiões bloqueadas estiverem adjacentes, você deverá desbloquear cada região separadamente.

Observação

Essa função não está disponível para a classe derivada CMemFile.

Exemplo

CFile cfile;
cfile.Open(_T("LockRange_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
ULONGLONG dwPos = 10;
ULONGLONG dwCount = 100;
cfile.LockRange(dwPos, dwCount);

// do something with the file

cfile.UnlockRange(dwPos, dwCount);

CFile::m_hFile

Contém o identificador de arquivo do sistema operacional para um arquivo aberto.

HANDLE m_hFile;

Comentários

m_hFile é uma variável pública do tipo UINT. Ela contém CFile::hFileNull, um indicador de arquivo vazio independente do sistema operacional se o identificador não tiver sido atribuído.

O uso de m_hFile não é recomendado, pois o significado do membro depende da classe derivada. m_hFile torna-se um membro público para a conveniência no suporte ao uso não polimórfico da classe.

CFile::m_pTM

Ponteiro para um objeto CAtlTransactionManager.

CAtlTransactionManager* m_pTM;

Comentários

CFile::Open

Sobrecarregado. Open foi projetada para ser usada com o construtor padrão CFile.

virtual BOOL Open(
    LPCTSTR lpszFileName,
    UINT nOpenFlags,
    CFileException* pError = NULL);

virtual BOOL Open(
    LPCTSTR lpszFileName,
    UINT nOpenFlags,
    CAtlTransactionManager* pTM,
    CFileException* pError = NULL);

Parâmetros

lpszFileName
Uma cadeia de caracteres que contém o caminho para o arquivo desejado. O caminho pode ser relativo, absoluto ou um nome de rede (UNC).

nOpenFlags
Um UINT que define o modo de compartilhamento e acesso do arquivo. Ele especifica a ação a ser executada ao abrir o arquivo. Você pode combinar opções usando o operador OR (|) bit a bit. São necessárias uma permissão de acesso e uma opção de compartilhamento; e os modos modeCreate e modeNoInherit são opcionais. Confira o construtor CFile para obter uma lista de opções de modos.

pError
Um ponteiro para um objeto de exceção de arquivo existente que receberá o status de uma operação com falha.

pTM
Ponteiro para objeto CAtlTransactionManager

Valor de Devolução

Não zero se a abertura tiver tido êxito; caso contrário, 0. O parâmetro pError só será significativo se 0 for retornado.

Comentários

As duas funções Open são métodos “seguros” de abertura do arquivo, em que falhas são uma condição normal e esperada.

Enquanto o construtor CFile gera uma exceção em uma condição de erro, Open retorna FALSE para condições de erro. Contudo, Open ainda pode inicializar um objeto CFileException para descrever o erro. Se você não fornecer o parâmetro pError ou se passar NULL para pError, Open retornará FALSE e não gerará uma CFileException. Se você passar um ponteiro para uma CFileException existente e Open encontrar um erro, a função o preencherá com informações que descrevem esse erro. Em ambos os casos, Open não gera uma exceção.

A tabela a seguir descreve os resultados possíveis de Open.

pError	Erro encontrado	Retornar valor	Conteúdo de CFileException
NULO	Não	TRUE	N/D
ptr para CFileException	Não	TRUE	inalterado
NULO	Sim	FALSE	N/D
ptr para CFileException	Sim	FALSE	inicializado para descrever o erro

Exemplo

CFile f;
CFileException e;
TCHAR* pszFileName = _T("Open_File.dat");
if(!f.Open(pszFileName, CFile::modeCreate | CFile::modeWrite, &e))
{
   TRACE(_T("File could not be opened %d\n"), e.m_cause);
}

 

//A second example for CFile::Open.
//This function uses CFile to copy binary files.
bool BinaryFileCopy(LPCTSTR pszSource, LPCTSTR pszDest)
{
   // constructing these file objects doesn't open them
   CFile sourceFile;
   CFile destFile;

   // we'll use a CFileException object to get error information
   CFileException ex;

   // open the source file for reading
   if (!sourceFile.Open(pszSource,
      CFile::modeRead | CFile::shareDenyWrite, &ex))
   {
      // complain if an error happened
      // no need to delete the ex object

      TCHAR szError[1024];
      ex.GetErrorMessage(szError, 1024);
      _tprintf_s(_T("Couldn't open source file: %1024s"), szError);
      return false;
   }
   else
   {
      if (!destFile.Open(pszDest, CFile::modeWrite |
         CFile::shareExclusive | CFile::modeCreate, &ex))
      {
         TCHAR szError[1024];
         ex.GetErrorMessage(szError, 1024);
         _tprintf_s(_T("Couldn't open source file: %1024s"), szError);

         sourceFile.Close();
         return false;
      }

      BYTE buffer[4096];
      DWORD dwRead;

      // Read in 4096-byte blocks,
      // remember how many bytes were actually read,
      // and try to write that many out. This loop ends
      // when there are no more bytes to read.
      do
      {
         dwRead = sourceFile.Read(buffer, 4096);
         destFile.Write(buffer, dwRead);
      }
      while (dwRead > 0);

      // Close both files

      destFile.Close();
      sourceFile.Close();
   }

   return true;
}

CFile::operator HANDLE

Use esse operador para passar um identificador para um objeto CFile para funções como ReadFileEx e GetFileTime que esperam um HANDLE.

operator HANDLE() const;

CFile::Read

Lê dados em um buffer do arquivo associado ao objeto CFile.

virtual UINT Read(
    void* lpBuf,
    UINT nCount);

Parâmetros

lpBuf
Ponteiro para o buffer fornecido pelo usuário que deve receber os dados lidos do arquivo.

nCount
O número máximo de bytes a serem lidos do arquivo. Para arquivos de modo de texto, os pares de feed de linha de retorno de carro são contados como caracteres únicos.

Valor de Devolução

O número de bytes transferidos ao buffer. Para todas as classes CFile, o valor retornado poderá ser menor que nCount se o final do arquivo tiver sido atingido.

Exemplo

CFile cfile;
cfile.Open(_T("Write_File.dat"), CFile::modeCreate | 
   CFile::modeReadWrite);
char pbufWrite[100];
memset(pbufWrite, 'a', sizeof(pbufWrite));
cfile.Write(pbufWrite, 100);         
cfile.Flush();
cfile.SeekToBegin();
char pbufRead[100];
cfile.Read(pbufRead, sizeof(pbufRead));
ASSERT(0 == memcmp(pbufWrite, pbufRead, sizeof(pbufWrite)));

Para ver outro exemplo, confira CFile::Open.

CFile::Remove

Essa função estática exclui o arquivo especificado pelo caminho.

static void PASCAL Remove(
    LPCTSTR lpszFileName,
    CAtlTransactionManager* pTM = NULL);

Parâmetros

lpszFileName
Uma cadeia de caracteres que é o caminho para o arquivo desejado. O caminho pode ser relativo ou absoluto e pode conter um nome de rede.

pTM
Ponteiro para objeto CAtlTransactionManager

Comentários

Remove não removerá um diretório.

A função membro Remove gera uma exceção se o arquivo conectado estiver aberto ou não puder ser removido. Essa função é equivalente ao comando DEL.

Exemplo

//example for CFile::Remove
TCHAR* pFileName = _T("Remove_File.dat");
try
{
   CFile::Remove(pFileName);
}
catch (CFileException* pEx)
{
   TRACE(_T("File %20s cannot be removed\n"), pFileName);
   pEx->Delete();
}

CFile::Rename

Essa função estática renomeia o arquivo especificado.

static void PASCAL Rename(
    LPCTSTR lpszOldName,
    LPCTSTR lpszNewName,
    CAtlTransactionManager* pTM = NULL);

Parâmetros

lpszOldName
O caminho antigo.

lpszNewName
O novo caminho.

pTM
Ponteiro para objeto CAtlTransactionManager

Comentários

Diretórios podem ser renomeados. Essa função é equivalente ao comando REN.

Exemplo

TCHAR* pOldName = _T("Oldname_File.dat");
TCHAR* pNewName = _T("Renamed_File.dat");

try
{
    CFile::Rename(pOldName, pNewName);
}
catch(CFileException* pEx )
{
    TRACE(_T("File %20s not found, cause = %d\n"), pOldName, 
       pEx->m_cause);
    pEx->Delete();
}

CFile::Seek

Reposiciona o ponteiro do arquivo em um arquivo aberto.

virtual ULONGLONG Seek(
LONGLONG lOff,
UINT nFrom);

Parâmetros

lOff
Número de bytes para mover o ponteiro do arquivo. Os valores positivos movem o ponteiro do arquivo para o final do arquivo; valores negativos movem o ponteiro do arquivo para o início do arquivo.

nFrom
Posição a partir da qual ser buscada. Confira a seção Comentários para obter valores possíveis.

Valor de Devolução

A posição do ponteiro do arquivo se o método tiver tido êxito; caso contrário, o valor retornado é indefinido e é gerado um ponteiro para uma exceção CFileException.

Comentários

A tabela a seguir lista os possíveis valores do parâmetro nFrom.

Valor	Descrição
CFile::begin	Procure do início do arquivo.
CFile::current	Procure a partir do local atual do ponteiro do arquivo.
CFile::end	Procure do final do arquivo.

Quando um arquivo é aberto, o ponteiro do arquivo fica posicionado em 0, no início do arquivo.

Você pode definir o ponteiro de arquivo para uma posição além do final de um arquivo. Se você fizer isso, o tamanho do arquivo não aumentará até que você escreva nele.

O manipulador de exceção para esse método deve excluir o objeto de exceção depois que a exceção for processada.

Exemplo

CFile cfile;
cfile.Open(_T("Seek_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
LONGLONG lOffset = 1000;
ULONGLONG lActual;
lActual = cfile.Seek(lOffset, CFile::begin);

CFile::SeekToBegin

Define o valor do ponteiro do arquivo para o início do arquivo.

void SeekToBegin();

Comentários

SeekToBegin() é equivalente a Seek( 0L, CFile::begin ).

Exemplo

CFile f;
f.Open(_T("Seeker_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
f.SeekToBegin();
ULONGLONG ullEnd = f.SeekToEnd();

CFile::SeekToEnd

Define o valor do ponteiro do arquivo para o final lógico do arquivo.

ULONGLONG SeekToEnd();

Valor de Devolução

O tamanho do arquivo em bytes.

Comentários

SeekToEnd() é equivalente a CFile::Seek( 0L, CFile::end ).

Exemplo

CFile f;
f.Open(_T("Seeker_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
f.SeekToBegin();
ULONGLONG ullEnd = f.SeekToEnd();

CFile::SetFilePath

Chame essa função para especificar o caminho do arquivo. Por exemplo, se o caminho de um arquivo não estiver disponível quando um objeto CFile for criado, chame SetFilePath para fornecê-lo.

virtual void SetFilePath(LPCTSTR lpszNewName);

Parâmetros

lpszNewName
Ponteiro para uma cadeia de caracteres especificando o novo caminho.

Comentários

Observação

SetFilePath não abre nem cria o arquivo; ele simplesmente associa o objeto CFile a um nome de caminho, o qual pode ser usado.

Exemplo

TCHAR* pstrName = _T("C:\\test\\SetPath_File.dat");

// open a file
HANDLE hFile = ::CreateFile(pstrName, GENERIC_WRITE, FILE_SHARE_READ,
   NULL, CREATE_ALWAYS, 0, NULL);

if (hFile != INVALID_HANDLE_VALUE)
{
   // attach a CFile object to it
   CFile myFile(hFile);

   // At this point, myFile doesn't know the path name for the file
   // it owns because Windows doesn't associate that information
   // with the handle. Any CFileExceptions thrown by this object
   // won't have complete information.

   // Calling SetFilePath() remedies that problem by letting CFile
   // know the name of the file that's associated with the object.

   myFile.SetFilePath(pstrName);

   // write something to the file and flush it immediately
   DWORD dwValue = 1234;
   myFile.Write(&dwValue, sizeof(dwValue));
   myFile.Flush();

   // destroying the CObject here will call ::CloseHandle() on the file
} 

CFile::SetLength

Chame essa função para alterar o comprimento do arquivo.

virtual void SetLength(ULONGLONG dwNewLen);

Parâmetros

dwNewLen
Comprimento desejado do arquivo em bytes. Esse valor pode ser maior ou menor do que o comprimento atual do arquivo. O arquivo será estendido ou truncado conforme apropriado.

Comentários

Observação

Com CMemFile, essa função poderia gerar um objeto CMemoryException.

Exemplo

CFile cfile;
cfile.Open(_T("SetLength_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
ULONGLONG dwNewLength = 10000;
cfile.SetLength(dwNewLength);

CFile::SetStatus

Define o status do arquivo associado a esse local de arquivo.

static void PASCAL SetStatus(
    LPCTSTR lpszFileName,
    const CFileStatus& status,
    CAtlTransactionManager* pTM = NULL);

Parâmetros

lpszFileName
Uma cadeia de caracteres que é o caminho para o arquivo desejado. O caminho pode ser relativo ou absoluto e pode conter um nome de rede.

status
O buffer que contém as novas informações de status. Chame a função membro GetStatus para pré-armazenar a estrutura CFileStatus com valores atuais e faça alterações conforme necessário. Se um valor for 0, o item de status correspondente não será atualizado. Confira a função membro GetStatus para obter uma descrição da estrutura CFileStatus.

pTM
Ponteiro para objeto CAtlTransactionManager

Comentários

Para definir a hora, modifique o campo m_mtime de status.

Quando você faz uma chamada a SetStatus como uma tentativa de alterar apenas os atributos do arquivo e o membro m_mtime da estrutura de status do arquivo não for zero, os atributos também podem ser afetados (alterar o carimbo de data/hora pode ter efeitos colaterais nos atributos). Caso queira alterar apenas os atributos do arquivo, primeiro defina o membro m_mtime da estrutura de status do arquivo como zero, depois faça uma chamada para SetStatus.

Exemplo

TCHAR* pFileName = _T("ReadOnly_File.dat");
CFileStatus status;
CFile::GetStatus(pFileName, status);
status.m_attribute |= CFile::readOnly;
CFile::SetStatus(pFileName, status);         

CFile::UnlockRange

Desbloqueia um intervalo de bytes em um arquivo aberto.

virtual void UnlockRange(
    ULONGLONG dwPos,
    ULONGLONG dwCount);

Parâmetros

dwPos
O deslocamento de bytes do início do intervalo de bytes a ser desbloqueado.

dwCount
O número de bytes no intervalo a ser desbloqueado.

Comentários

Confira a descrição da função membro LockRange para obter detalhes.

Observação

Essa função não está disponível para a classe derivada CMemFile.

Exemplo

CFile cfile;
cfile.Open(_T("LockRange_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
ULONGLONG dwPos = 10;
ULONGLONG dwCount = 100;
cfile.LockRange(dwPos, dwCount);

// do something with the file

cfile.UnlockRange(dwPos, dwCount);

CFile::Write

Grava dados de um buffer no arquivo associado ao objeto CFile.

virtual void Write(
    const void* lpBuf,
    UINT nCount);

Parâmetros

lpBuf
Um ponteiro para o buffer fornecido pelo usuário que contém os dados a serem gravados no arquivo.

nCount
O número de bytes a ser transferido do buffer. Para arquivos de modo de texto, os pares de feed de linha de retorno de carro são contados como caracteres únicos.

Comentários

Write gera uma exceção em resposta a várias condições, incluindo a condição de disco cheio.

Exemplo

CFile cfile;
cfile.Open(_T("Write_File.dat"), CFile::modeCreate | 
   CFile::modeReadWrite);
char pbufWrite[100];
memset(pbufWrite, 'a', sizeof(pbufWrite));
cfile.Write(pbufWrite, 100);         
cfile.Flush();

Veja também os exemplos de CFile::CFile e CFile::Open.

Confira também

DRAWCLI de exemplo do MFC
Classe CObject
Gráfico da hierarquia
Classe CStdioFile
Classe CMemFile