Partilhar via

Classe CAtlFile

  • Artigo

Essa classe fornece um wrapper fino em torno da API de tratamento de arquivos do Windows.

Importante

Essa classe e os respectivos membros não podem ser usados em aplicativos executados no Windows Runtime.

Sintaxe

class CAtlFile : public CHandle

Membros

Construtores públicos

Nome Descrição
CAtlFile::CAtlFile O construtor .

Métodos públicos

Nome Descrição
CAtlFile::Create Chame este método para criar ou abrir um arquivo.
CAtlFile::Flush Chame este método para limpar os buffers do arquivo e fazer com que todos os dados em buffer sejam gravados no arquivo.
CAtlFile::GetOverlappedResult Chame este método para obter os resultados de uma operação sobreposta no arquivo.
CAtlFile::GetPosition Chame este método para obter a posição atual do ponteiro do arquivo.
CAtlFile::GetSize Chame este método para obter o tamanho em bytes do arquivo.
CAtlFile::LockRange Chame esse método para bloquear uma região no arquivo para impedir que outros processos o acessem.
CAtlFile::Read Chame este método para ler dados de um arquivo começando na posição indicada pelo ponteiro do arquivo.
CAtlFile::Seek Chame este método para mover o ponteiro do arquivo.
CAtlFile::SetSize Chame este método para definir o tamanho do arquivo.
CAtlFile::UnlockRange Chame este método para desbloquear uma região do arquivo.
CAtlFile::Write Chame este método para gravar dados no arquivo começando na posição indicada pelo ponteiro do arquivo.

Membros de dados protegidos

Nome Descrição
CAtlFile::m_pTM Ponteiro para o objeto CAtlTransactionManager

Comentários

Use esta classe quando as necessidades de tratamento de arquivo forem relativamente simples, mas é necessária mais abstração do que a API do Windows fornece, sem incluir dependências MFC.

Hierarquia de herança

CHandle

CAtlFile

Requisitos

Cabeçalho: atlfile.h

CAtlFile::CAtlFile

O construtor .

CAtlFile() throw();
CAtlFile(CAtlTransactionManager* pTM = NULL) throw();
CAtlFile(CAtlFile& file) throw();
explicit CAtlFile(HANDLE hFile) throw();

Parâmetros

file
O objeto do arquivo.

hFile
O identificador do arquivo.

pTM
Ponteiro para objeto CAtlTransactionManager

Comentários

O construtor de cópia transfere a propriedade do identificador do arquivo do objeto CAtlFile original para o objeto recém-construído.

CAtlFile::Create

Chame este método para criar ou abrir um arquivo.

HRESULT Create(
    LPCTSTR szFilename,
    DWORD dwDesiredAccess,
    DWORD dwShareMode,
    DWORD dwCreationDisposition,
    DWORD dwFlagsAndAttributes = FILE_ATTRIBUTE_NORMAL,
    LPSECURITY_ATTRIBUTES lpsa = NULL,
    HANDLE hTemplateFile = NULL) throw();

Parâmetros

szFilename
O nome do arquivo.

dwDesiredAccess
O acesso desejado. Consulte dwDesiredAccess no CreateFile no SDK do Windows.

dwShareMode
O modo de compartilhamento. Confira dwShareMode em CreateFile.

dwCreationDisposition
A disposição de criação. Confira dwCreationDisposition em CreateFile.

dwFlagsAndAttributes
Os sinalizadores e atributos. Confira dwFlagsAndAttributes em CreateFile.

lpsa
Os atributos de segurança. Confira lpSecurityAttributes em CreateFile.

hTemplateFile
O arquivo de modelo. Confira hTemplateFile em CreateFile.

Valor de retorno

Retornará S_OK se houver êxito ou um erro HRESULT, em caso de falha.

Comentários

Chame CreateFile para criar ou abrir o arquivo.

CAtlFile::Flush

Chame este método para limpar os buffers do arquivo e fazer com que todos os dados em buffer sejam gravados no arquivo.

HRESULT Flush() throw();

Valor de retorno

Retornará S_OK se houver êxito ou um erro HRESULT, em caso de falha.

Comentários

Chame FlushFileBuffers para liberar dados em buffer para o arquivo.

CAtlFile::GetOverlappedResult

Chame este método para obter os resultados de uma operação sobreposta no arquivo.

HRESULT GetOverlappedResult(
    LPOVERLAPPED pOverlapped,
    DWORD& dwBytesTransferred,
    BOOL bWait) throw();

Parâmetros

pOverlapped
A estrutura sobreposta. Confira lpOverlapped em GetOverlappedResult no SDK do Windows.

dwBytesTransferred
Os bytes transferidos. Confira lpNumberOfBytesTransferred em GetOverlappedResult.

bWait
A opção de espera. Confira bWait em GetOverlappedResult.

Valor de retorno

Retornará S_OK se houver êxito ou um erro HRESULT, em caso de falha.

Comentários

Chame GetOverlappedResult para obter os resultados de uma operação sobreposta no arquivo.

CAtlFile::GetPosition

Chame este método para obter a posição atual do ponteiro do arquivo.

HRESULT GetPosition(ULONGLONG& nPos) const throw();

Parâmetros

nPos
A posição em bytes.

Valor de retorno

Retornará S_OK se houver êxito ou um erro HRESULT, em caso de falha.

Comentários

Chame SetFilePointer para obter a posição atual do ponteiro do arquivo.

CAtlFile::GetSize

Chame este método para obter o tamanho em bytes do arquivo.

HRESULT GetSize(ULONGLONG& nLen) const throw();

Parâmetros

nLen
O número de bytes no arquivo.

Valor de retorno

Retornará S_OK se houver êxito ou um erro HRESULT, em caso de falha.

Comentários

Chame GetFileSize para obter o tamanho em bytes do arquivo.

CAtlFile::LockRange

Chame esse método para bloquear uma região no arquivo para impedir que outros processos o acessem.

HRESULT LockRange(ULONGLONG nPos, ULONGLONG nCount) throw();

Parâmetros

nPos
A posição no arquivo em que o bloqueio deve começar.

nCount
O comprimento do intervalo de bytes a ser bloqueado.

Valor de retorno

Retornará S_OK se houver êxito ou um erro HRESULT, em caso de falha.

Comentários

Chame LockFile para bloquear uma região no arquivo. 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 uma região usando CAtlFile::UnlockRange, o intervalo de bytes deve corresponder exatamente à região que foi bloqueada anteriormente. LockRange não mescla regiões adjacentes; se duas regiões bloqueadas forem adjacentes, cada região deverá ser desbloqueada separadamente.

CAtlFile::m_pTM

Ponteiro para um objeto CAtlTransactionManager.

CAtlTransactionManager* m_pTM;

Comentários

CAtlFile::Read

Chame este método para ler dados de um arquivo começando na posição indicada pelo ponteiro do arquivo.

HRESULT Read(
    LPVOID pBuffer,
    DWORD nBufSize) throw();

HRESULT Read(
    LPVOID pBuffer,
    DWORD nBufSize,
    DWORD& nBytesRead) throw();

HRESULT Read(
    LPVOID pBuffer,
    DWORD nBufSize,
    LPOVERLAPPED pOverlapped) throw();

HRESULT Read(
    LPVOID pBuffer,
    DWORD nBufSize,
    LPOVERLAPPED pOverlapped,
    LPOVERLAPPED_COMPLETION_ROUTINE pfnCompletionRoutine) throw();

Parâmetros

pBuffer
Ponteiro para o buffer que receberá os dados lidos do arquivo.

nBufSize
O tamanho do buffer em bytes.

nBytesRead
O número de bytes lidos.

pOverlapped
A estrutura sobreposta. Confira lpOverlapped em ReadFile no SDK do Windows.

pfnCompletionRoutine
A rotina de conclusão. Confira lpCompletionRoutine em ReadFileEx no SDK do Windows.

Valor de retorno

Retornará S_OK se houver êxito ou um erro HRESULT, em caso de falha.

Comentários

Os três primeiros formulários chamam ReadFile, o último chama ReadFileEx para ler dados do arquivo. Use CAtlFile::Seek para mover o ponteiro do arquivo.

CAtlFile::Seek

Chame este método para mover o ponteiro do arquivo.

HRESULT Seek(
    LONGLONG nOffset,
    DWORD dwFrom = FILE_CURRENT) throw();

Parâmetros

nOffset
O deslocamento do ponto de partida fornecido pelo dwFrom.

dwFrom
O ponto de partida (FILE_BEGIN, FILE_CURRENT ou FILE_END).

Valor de retorno

Retornará S_OK se houver êxito ou um erro HRESULT, em caso de falha.

Comentários

Chame SetFilePointer para mover o ponteiro do arquivo.

CAtlFile::SetSize

Chame este método para definir o tamanho do arquivo.

HRESULT SetSize(ULONGLONG nNewLen) throw();

Parâmetros

nNewLen
O novo tamanho do arquivo em bytes.

Valor de retorno

Retornará S_OK se houver êxito ou um erro HRESULT, em caso de falha.

Comentários

Chame SetFilePointer e SetEndOfFile para definir o tamanho do arquivo. No retorno, o ponteiro do arquivo é posicionado no final do arquivo.

CAtlFile::UnlockRange

Chame este método para desbloquear uma região do arquivo.

HRESULT UnlockRange(ULONGLONG nPos, ULONGLONG nCount) throw();

Parâmetros

nPos
A posição no arquivo em que o desbloqueio deve começar.

nCount
O comprimento do intervalo de bytes a ser desbloqueado.

Valor de retorno

Retornará S_OK se houver êxito ou um erro HRESULT, em caso de falha.

Comentários

Chame UnlockFile para desbloquear uma região do arquivo.

CAtlFile::Write

Chame este método para gravar dados no arquivo começando na posição indicada pelo ponteiro do arquivo.

HRESULT Write(
    LPCVOID pBuffer,
    DWORD nBufSize,
    LPOVERLAPPED pOverlapped,
    LPOVERLAPPED_COMPLETION_ROUTINE pfnCompletionRoutine) throw();

HRESULT Write(
    LPCVOID pBuffer,
    DWORD nBufSize,
    DWORD* pnBytesWritten = NULL) throw();

HRESULT Write(
    LPCVOID pBuffer,
    DWORD nBufSize,
    LPOVERLAPPED pOverlapped) throw();

Parâmetros

pBuffer
O buffer que contém os dados a serem gravados no arquivo.

nBufSize
O número de bytes a ser transferido do buffer.

pOverlapped
A estrutura sobreposta. Confira lpOverlapped em WriteFile no SDK do Windows.

pfnCompletionRoutine
A rotina de conclusão. Confira lpCompletionRoutine em WriteFileEx no SDK do Windows.

pnBytesWritten
Os bytes gravados.

Valor de retorno

Retornará S_OK se houver êxito ou um erro HRESULT, em caso de falha.

Comentários

Os três primeiros formulários chamam WriteFile, o último chama WriteFileEx para gravar dados no arquivo. Use CAtlFile::Seek para mover o ponteiro do arquivo.

Confira também

Amostra de letreiro
Visão geral da aula
Classe CHandle