Condividi tramite

Classe CAtlFile

  • Articolo

Questa classe fornisce un wrapper sottile intorno all'API di gestione dei file di Windows.

Importante

Questa classe e i relativi membri non possono essere usati nelle applicazioni eseguite in Windows Runtime.

Sintassi

class CAtlFile : public CHandle

Membri

Costruttori pubblici

Nome Descrizione
CAtlFile::CAtlFile Costruttore.

Metodi pubblici

Nome Descrizione
CAtlFile::Create Chiamare questo metodo per creare o aprire un file.
CAtlFile::Flush Chiamare questo metodo per cancellare i buffer per il file e fare in modo che tutti i dati memorizzati nel buffer vengano scritti nel file.
CAtlFile::GetOverlappedResult Chiamare questo metodo per ottenere i risultati di un'operazione sovrapposta nel file.
CAtlFile::GetPosition Chiamare questo metodo per ottenere la posizione del puntatore del file corrente dal file.
CAtlFile::GetSize Chiamare questo metodo per ottenere le dimensioni in byte del file.
CAtlFile::LockRange Chiamare questo metodo per bloccare un'area nel file per impedire ad altri processi di accedervi.
CAtlFile::Read Chiamare questo metodo per leggere i dati da un file a partire dalla posizione indicata dal puntatore al file.
CAtlFile::Seek Chiamare questo metodo per spostare il puntatore al file.
CAtlFile::SetSize Chiamare questo metodo per impostare le dimensioni del file.
CAtlFile::UnlockRange Chiamare questo metodo per sbloccare un'area del file.
CAtlFile::Write Chiamare questo metodo per scrivere dati nel file a partire dalla posizione indicata dal puntatore al file.

Membri dati protetti

Nome Descrizione
CAtlFile::m_pTM Puntatore all'oggetto CAtlTransactionManager

Osservazioni:

Usare questa classe quando le esigenze di gestione dei file sono relativamente semplici, ma è necessaria un'astrazione maggiore rispetto all'API di Windows, senza includere dipendenze MFC.

Gerarchia di ereditarietà

CHandle

CAtlFile

Requisiti

Intestazione: atlfile.h

CAtlFile::CAtlFile

Costruttore.

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

Parametri

file
Oggetto file.

hFile
Handle di file.

pTM
Puntatore all'oggetto CAtlTransactionManager

Osservazioni:

Il costruttore di copia trasferisce la proprietà dell'handle di file dall'oggetto originale CAtlFile all'oggetto appena costruito.

CAtlFile::Create

Chiamare questo metodo per creare o aprire un file.

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

Parametri

szFilename
Nome del file.

dwDesiredAccess
Accesso desiderato. Vedere dwDesiredAccess in CreateFile in Windows SDK.

dwShareMode
Modalità di condivisione. Vedere dwShareMode in CreateFile.

dwCreationDisposition
Eliminazione della creazione. Vedere dwCreationDisposition in CreateFile.

dwFlagsAndAttributes
Flag e attributi. Vedere dwFlagsAndAttributes in CreateFile.

lpsa
Attributi di sicurezza. Vedere lpSecurityAttributes in CreateFile.

hTemplateFile
File modello. Vedere hTemplateFile in CreateFile.

Valore restituito

Restituisce S_OK in caso di esito positivo o errore HRESULT in caso di errore.

Osservazioni:

Chiama CreateFile per creare o aprire il file.

CAtlFile::Flush

Chiamare questo metodo per cancellare i buffer per il file e fare in modo che tutti i dati memorizzati nel buffer vengano scritti nel file.

HRESULT Flush() throw();

Valore restituito

Restituisce S_OK in caso di esito positivo o errore HRESULT in caso di errore.

Osservazioni:

Chiama FlushFileBuffers per scaricare i dati memorizzati nel buffer nel file.

CAtlFile::GetOverlappedResult

Chiamare questo metodo per ottenere i risultati di un'operazione sovrapposta nel file.

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

Parametri

pOverlapped
Struttura sovrapposta. Vedi lpOverlapped in GetOverlappedResult in Windows SDK.

dwBytesTransferred
Byte trasferiti. Vedere lpNumberOfBytesTransferred in GetOverlappedResult.

bWait
Opzione di attesa. Vedere bWait in GetOverlappedResult.

Valore restituito

Restituisce S_OK in caso di esito positivo o errore HRESULT in caso di errore.

Osservazioni:

Chiama GetOverlappedResult per ottenere i risultati di un'operazione sovrapposta nel file.

CAtlFile::GetPosition

Chiamare questo metodo per ottenere la posizione del puntatore del file corrente.

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

Parametri

nPos
Posizione in byte.

Valore restituito

Restituisce S_OK in caso di esito positivo o errore HRESULT in caso di errore.

Osservazioni:

Chiama SetFilePointer per ottenere la posizione corrente del puntatore al file.

CAtlFile::GetSize

Chiamare questo metodo per ottenere le dimensioni in byte del file.

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

Parametri

nLen
Numero di byte nel file.

Valore restituito

Restituisce S_OK in caso di esito positivo o errore HRESULT in caso di errore.

Osservazioni:

Chiama GetFileSize per ottenere le dimensioni in byte del file.

CAtlFile::LockRange

Chiamare questo metodo per bloccare un'area nel file per impedire ad altri processi di accedervi.

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

Parametri

nPos
Posizione nel file in cui deve iniziare il blocco.

nCount
Lunghezza dell'intervallo di byte da bloccare.

Valore restituito

Restituisce S_OK in caso di esito positivo o errore HRESULT in caso di errore.

Osservazioni:

Chiama LockFile per bloccare un'area nel file. Il blocco di byte in un file impedisce l'accesso a tali byte da altri processi. È possibile bloccare più aree di un file, ma non sono consentite aree sovrapposte. Quando si sblocca un'area usando CAtlFile::UnlockRange, l'intervallo di byte deve corrispondere esattamente all'area bloccata in precedenza. LockRange non unisce aree adiacenti; se due aree bloccate sono adiacenti, è necessario sbloccare ognuna separatamente.

CAtlFile::m_pTM

Puntatore a un oggetto CAtlTransactionManager.

CAtlTransactionManager* m_pTM;

Osservazioni:

CAtlFile::Read

Chiamare questo metodo per leggere i dati da un file a partire dalla posizione indicata dal puntatore al file.

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();

Parametri

pBuffer
Puntatore al buffer che riceverà i dati letti dal file.

nBufSize
Dimensioni del buffer, in byte.

nBytesRead
Numero di byte letti.

pOverlapped
Struttura sovrapposta. Vedere lpOverlapped in ReadFile in Windows SDK.

pfnCompletionRoutine
Routine di completamento. Vedere lpCompletionRoutine in ReadFileEx in Windows SDK.

Valore restituito

Restituisce S_OK in caso di esito positivo o errore HRESULT in caso di errore.

Osservazioni:

I primi tre moduli chiamano ReadFile, l'ultimo ReadFileEx per leggere i dati dal file. Usare CAtlFile::Seek per spostare il puntatore al file.

CAtlFile::Seek

Chiamare questo metodo per spostare il puntatore al file.

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

Parametri

nOffset
Offset dal punto iniziale specificato da dwFrom.

dwFrom
Punto iniziale (FILE_BEGIN, FILE_CURRENT o FILE_END).

Valore restituito

Restituisce S_OK in caso di esito positivo o errore HRESULT in caso di errore.

Osservazioni:

Chiama SetFilePointer per spostare il puntatore al file.

CAtlFile::SetSize

Chiamare questo metodo per impostare le dimensioni del file.

HRESULT SetSize(ULONGLONG nNewLen) throw();

Parametri

nNewLen
Nuova lunghezza del file in byte.

Valore restituito

Restituisce S_OK in caso di esito positivo o errore HRESULT in caso di errore.

Osservazioni:

Chiama SetFilePointer e SetEndOfFile per impostare le dimensioni del file. In caso di restituzione, il puntatore al file viene posizionato alla fine del file.

CAtlFile::UnlockRange

Chiamare questo metodo per sbloccare un'area del file.

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

Parametri

nPos
Posizione nel file in cui deve iniziare lo sblocco.

nCount
Lunghezza dell'intervallo di byte da sbloccare.

Valore restituito

Restituisce S_OK in caso di esito positivo o errore HRESULT in caso di errore.

Osservazioni:

Chiama UnlockFile per sbloccare un'area del file.

CAtlFile::Write

Chiamare questo metodo per scrivere dati nel file a partire dalla posizione indicata dal puntatore al file.

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();

Parametri

pBuffer
Buffer contenente i dati da scrivere nel file.

nBufSize
Numero di byte da trasferire dal buffer.

pOverlapped
Struttura sovrapposta. Vedere lpOverlapped in WriteFile in Windows SDK.

pfnCompletionRoutine
Routine di completamento. Vedere lpCompletionRoutine in WriteFileEx in Windows SDK.

pnBytesWritten
Byte scritti.

Valore restituito

Restituisce S_OK in caso di esito positivo o errore HRESULT in caso di errore.

Osservazioni:

I primi tre moduli chiamano WriteFile, l'ultima chiama WriteFileEx per scrivere dati nel file. Usare CAtlFile::Seek per spostare il puntatore al file.

Vedi anche

Esempio di marquee
Cenni preliminari sulla classe
Classe CHandle