Classe CAtlFile

Esta classe fornece um wrapper fino à API de gestão de ficheiros do Windows.

Sintaxe

class CAtlFile : public CHandle

Membros

Construtores Públicos

Métodos Públicos

Membros de Dados Protegidos

Observações

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

Hierarquia de herança

CHandle

CAtlFile

Requerimentos

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

ficheiro
O objeto do ficheiro.

hFile
A alça do ficheiro.

pTM
Apontador para o objeto CAtlTransactionManager

Observações

O construtor de cópias transfere a propriedade do handle do ficheiro do objeto original CAtlFile para o objeto recém-construído.

CAtlFile::Create

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

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

szNome do Ficheiro
O nome do arquivo.

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

dwShareMode
O modo partilhar. Ver dwShareMode em CreateFile.

dwCriaçãoDisposição
A disposição criativa. Ver dwCreationDisposition em CreateFile.

dwFlagsAndAttributes
As bandeiras e atributos. Ver dwFlagsAndAttributes em CreateFile.

LPSA
Os atributos de segurança. Ver lpSecurityAttributes em CreateFile.

hTemplateFile
O ficheiro modelo. Ver hTemplateFile em CreateFile.

Valor de retorno

Devolve S_OK em caso de sucesso, ou um erro HRESULT em caso de falha.

Observações

Chama o CreateFile para criar ou abrir o ficheiro.

CAtlFile::Flush

Chame este método para limpar os buffers do ficheiro e fazer com que todos os dados armazenados sejam escritos no ficheiro.

HRESULT Flush() throw();

Valor de retorno

Devolve S_OK em caso de sucesso, ou um erro HRESULT em caso de falha.

Observações

Chama FlushFileBuffers para limpar os dados armazenados no ficheiro.

CAtlFile::GetOverlappedResult

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

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

Parâmetros

pSobreposto
A estrutura sobreposta. Veja lpOverlapped em GetOverlappedResult no SDK do Windows.

dwBytesTransferred
Os bytes transferidos. Ver lpNumberOfBytesTransferido em GetOverlappedResult.

bEspera
A opção de esperar. Ver bEspera em GetOverlappedResult.

Valor de retorno

Devolve S_OK em caso de sucesso, ou um erro HRESULT em caso de falha.

Observações

Chama GetOverlappedResult para obter os resultados de uma operação sobreposta no ficheiro.

CAtlFile::GetPosition

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

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

Parâmetros

nPos
A posição em bytes.

Valor de retorno

Devolve S_OK em caso de sucesso, ou um erro HRESULT em caso de falha.

Observações

Chama SetFilePointer para obter a posição atual do ponteiro do ficheiro.

CAtlFile::GetSize

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

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

Parâmetros

nLen
O número de bytes no ficheiro.

Valor de retorno

Devolve S_OK em caso de sucesso, ou um erro HRESULT em caso de falha.

Observações

Chama GetFileSize para obter o tamanho em bytes do ficheiro.

CAtlFile::LockRange

Chame este método para bloquear uma região no ficheiro e impedir que outros processos acedam a ela.

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

Parâmetros

nPos
A posição no ficheiro onde a fechadura deve começar.

nContagem
O comprimento do intervalo de bytes a ser bloqueado.

Valor de retorno

Devolve S_OK em caso de sucesso, ou um erro HRESULT em caso de falha.

Observações

Chama o LockFile para bloquear uma região no ficheiro. Bloquear bytes em um arquivo impede 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 desbloqueias uma região, usando CAtlFile::UnlockRange, o intervalo de bytes deve corresponder exatamente à região que estava previamente bloqueada. LockRange não funde regiões adjacentes; Se duas regiões bloqueadas estiverem adjacentes, deve desbloquear cada uma separadamente.

CAtlFile::m_pTM

Ponteiro para um objeto CAtlTransactionManager.

CAtlTransactionManager* m_pTM;

Observações

CAtlFile::Read

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

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
Aponta para o buffer que irá receber os dados lidos do ficheiro.

nBufSize
O tamanho do buffer em bytes.

nBytesRead
O número de bytes lidos.

pSobreposto
A estrutura sobreposta. Veja lpOverlappped em ReadFile no SDK do Windows.

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

Valor de retorno

Devolve S_OK em caso de sucesso, ou um erro HRESULT em caso de falha.

Observações

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

CAtlFile::Seek

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

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

Parâmetros

nDeslocamento
O deslocamento em relação ao ponto inicial dado pelo dwFrom.

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

Valor de retorno

Devolve S_OK em caso de sucesso, ou um erro HRESULT em caso de falha.

Observações

Chama o SetFilePointer para mover o ponteiro do ficheiro.

CAtlFile::SetSize

Chama este método para definir o tamanho do ficheiro.

HRESULT SetSize(ULONGLONG nNewLen) throw();

Parâmetros

nNewLen
O novo comprimento do ficheiro em bytes.

Valor de retorno

Devolve S_OK em caso de sucesso, ou um erro HRESULT em caso de falha.

Observações

Chama SetFilePointer e SetEndOfFile para definir o tamanho do ficheiro. Ao retornar, o ponteiro do ficheiro é posicionado no final do ficheiro.

CAtlFile::UnlockRange

Chama este método para desbloquear uma região do ficheiro.

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

Parâmetros

nPos
A posição no ficheiro onde o desbloqueio deve começar.

nContagem
O comprimento do intervalo de bytes a desbloquear.

Valor de retorno

Devolve S_OK em caso de sucesso, ou um erro HRESULT em caso de falha.

Observações

Chama o UnlockFile para desbloquear uma região do ficheiro.

CAtlFile::Write

Chame este método para escrever dados no ficheiro a partir da posição indicada pelo ponteiro do ficheiro.

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 escritos no ficheiro.

nBufSize
O número de bytes a serem transferidos do buffer.

pSobreposto
A estrutura sobreposta. Veja lpOverlapped no WriteFile no SDK do Windows.

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

pnBytesWritten
Os bytes escritos.

Valor de retorno

Devolve S_OK em caso de sucesso, ou um erro HRESULT em caso de falha.

Observações

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

Consulte também

Amostra de Destaque
Visão geral da classe
Classe CHandle