Classe CFile

Articolo
10/12/2023

Classe di base per le classi di file MFC.

Sintassi

class CFile : public CObject

Membri

Costruttori pubblici

Nome	Descrizione
CFile::CFile	Costruisce un `CFile` oggetto da un percorso o da un handle di file.

Metodi pubblici

Nome	Descrizione
CFile::Abort	Chiude un file ignorando tutti gli avvisi e gli errori.
CFile::Close	Chiude un file ed elimina l'oggetto .
CFile::D uplicate	Costruisce un oggetto duplicato basato su questo file.
CFile::Flush	Scarica tutti i dati ancora da scrivere.
CFile::GetFileName	Recupera il nome file del file selezionato.
CFile::GetFilePath	Recupera il percorso completo del file selezionato.
CFile::GetFileTitle	Recupera il titolo del file selezionato.
CFile::GetLength	Recupera la lunghezza del file.
CFile::GetPosition	Recupera il puntatore al file corrente.
CFile::GetStatus	Recupera lo stato del file aperto o nella versione statica recupera lo stato del file specificato (funzione statica, virtuale).
CFile::LockRange	Blocca un intervallo di byte in un file.
CFile::Open	Cassaforte apre un file con un'opzione di test degli errori.
CFile::Read	Legge i dati (senza buffer) da un file nella posizione del file corrente.
CFile::Remove	Elimina il file specificato (funzione statica).
CFile::Rename	Rinomina il file specificato (funzione statica).
CFile::Seek	Posiziona il puntatore al file corrente.
CFile::SeekToBegin	Posiziona il puntatore del file corrente all'inizio del file.
CFile::SeekToEnd	Posiziona il puntatore del file corrente alla fine del file.
CFile::SetFilePath	Imposta il percorso completo del file selezionato.
CFile::SetLength	Modifica la lunghezza del file.
CFile::SetStatus	Imposta lo stato del file specificato (funzione statica, virtuale).
CFile::UnlockRange	Sblocca un intervallo di byte in un file.
CFile::Write	Scrive i dati (senza buffer) in un file nella posizione del file corrente.

Operatori pubblici

Nome	Descrizione
CFile::operator HANDLE	Handle di un `CFile` oggetto .

Membri dati pubblici

Nome	Descrizione
CFile::hFileNull	Determina se l'oggetto `CFile` dispone di un handle valido.
CFile::m_hFile	In genere contiene l'handle di file del sistema operativo.

Membri dati protetti

Nome	Descrizione
CFile::m_pTM	Puntatore all'oggetto `CAtlTransactionManager`.

Osservazioni:

Fornisce direttamente servizi di input/output di disco binario senza buffer e supporta indirettamente file di testo e file di memoria tramite le classi derivate. CFile funziona insieme alla classe per supportare la CArchive serializzazione di oggetti Microsoft Foundation Class.

La relazione gerarchica tra questa classe e le relative classi derivate consente al programma di operare su tutti gli oggetti file tramite l'interfaccia polimorfica CFile . Un file di memoria, ad esempio, si comporta come un file su disco.

Usare CFile e le relative classi derivate per l'I/O del disco per utilizzo generico. Usare ofstream o altre classi Microsoft iostream per il testo formattato inviato a un file su disco.

Normalmente, un file del disco viene aperto automaticamente durante CFile la costruzione e chiuso alla distruzione. Le funzioni membro statiche consentono di interrogare lo stato di un file senza aprire il file.

Per altre informazioni sull'uso CFiledi , vedere gli articoli File in MFC e Gestione dei file nelle informazioni di riferimento sulla libreria di runtime.

Gerarchia di ereditarietà

CObject

CFile

Requisiti

Intestazione: afx.h

CFile::Abort

Chiude il file associato a questo oggetto e rende il file non disponibile per la lettura o la scrittura.

virtual void Abort();

Osservazioni:

Se il file non è stato chiuso prima di eliminare definitivamente l'oggetto, il distruttore lo chiude per l'utente.

Quando si gestiscono le eccezioni, CFile::Abort differisce da CFile::Close due modi importanti. Prima di tutto, la Abort funzione non genererà un'eccezione in caso di errori, perché gli errori vengono ignorati da Abort. In secondo luogo, Abort non as edizione Standard RT se il file non è stato aperto o è stato chiuso in precedenza.

Se è stato usato new per allocare l'oggetto nell'heap CFile , è necessario eliminarlo dopo la chiusura del file. Abort imposta su m_hFileCFile::hFileNull.

Esempio

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

Costruisce e inizializza un oggetto CFile.

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

CFile(
LPCTSTR lpszFileName,
UINT nOpenFlags);

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

Parametri

hFile
Handle di un file da aggiungere all'oggetto CFile.

lpszFileName
Percorso completo o relativo di un file da aggiungere all'oggetto CFile.

nOpenFlags
Combinazione bit per bit (OR) di opzioni di accesso per il file specificato. Per le possibili opzioni, vedere la sezione Note.

Ptm
Puntatore all'oggetto CAtlTransactionManager

Osservazioni:

Nelle cinque tabelle seguenti sono elencate le opzioni possibili per il parametro nOpenFlags .

Scegliere una sola delle seguenti opzioni relative alla modalità di accesso al file. La modalità predefinita è CFile::modeRead, che prevede la sola lettura.

Valore	Descrizione
`CFile::modeRead`	Richiede l'accesso in sola lettura.
`CFile::modeWrite`	Richiede l'accesso in sola scrittura.
`CFile::modeReadWrite`	Richiede l'accesso in lettura e scrittura.

Scegliere una delle opzioni seguenti relative alla modalità carattere.

Valore	Descrizione
`CFile::typeBinary`	Imposta la modalità binaria (solo per le classi derivate).
`CFile::typeText`	Imposta la modalità di testo con elaborazione speciale per le coppie di avanzamento ritorno a capo (usate solo nelle classi derivate).
`CFile::typeUnicode`	Imposta la modalità Unicode (solo per le classi derivate). Il testo viene scritto nel file in formato Unicode quando l'applicazione viene compilata in una configurazione Unicode. Nessun BOM viene scritto nel file.

Scegliere una sola delle seguenti opzioni relative alla modalità di condivisione del file. La modalità di condivisione file predefinita è CFile::shareExclusive, che è esclusiva.

Valore	Descrizione
`CFile::shareDenyNone`	Nessuna restrizione alla condivisione.
`CFile::shareDenyRead`	Nega l'accesso in lettura a tutti gli altri utenti.
`CFile::shareDenyWrite`	Nega l'accesso in scrittura a tutti gli altri utenti.
`CFile::shareExclusive`	Nega l'accesso in lettura e scrittura a tutti gli altri utenti.

Scegliere la prima delle seguenti opzioni relative alla modalità di creazione del file oppure entrambe. La modalità di creazione predefinita è CFile::modeNoTruncate, che prevede l'apertura di un file esistente.

Valore	Descrizione
`CFile::modeCreate`	Crea un nuovo file se non esiste alcun file. Se il file esiste già, viene sovrascritto e inizialmente impostato su lunghezza zero.
`CFile::modeNoTruncate`	Crea un nuovo file se non esiste alcun file; in caso contrario, se il file esiste già, viene associato all'oggetto `CFile` .

Scegliere le opzioni di memorizzazione nella cache del file come descritto. Per impostazione predefinita, il sistema usa uno schema di memorizzazione nella cache per utilizzo generico che non è disponibile come opzione.

Valore	Descrizione
`CFile::osNoBuffer`	Il sistema non usa una cache intermedia per il file. Questa opzione annulla le due opzioni seguenti.
`CFile::osRandomAccess`	La cache dei file viene ottimizzata per l'accesso casuale. Non usare sia questa opzione che l'opzione analisi sequenziale.
`CFile::osSequentialScan`	La cache dei file viene ottimizzata per l'accesso sequenziale. Non usare sia questa opzione che l'opzione di accesso casuale.
`CFile::osWriteThrough`	Le operazioni di scrittura vengono eseguite senza ritardi.

Scegliere l'opzione di sicurezza seguente per evitare che l'handle di file venga ereditato. Per impostazione predefinita, l'handle di file può essere usato da tutti i nuovi processi figlio.

Valore	Descrizione
`CFile::modeNoInherit`	Evita l'uso dell'handle di file da parte di qualsiasi processo figlio.

Il costruttore predefinito inizializza i membri, ma non collega un file all'oggetto CFile . Dopo aver usato questo costruttore, usare il metodo CFile::Open per aprire un file e collegarlo all'oggetto CFile .

Il costruttore con un parametro inizializza i membri e aggiunge un file esistente all'oggetto CFile.

Il costruttore con due parametri inizializza i membri e prova ad aprire il file specificato. Se il costruttore apre correttamente il file specificato, il file viene aggiunto all'oggetto CFile. In caso contrario, questo costruttore genera un puntatore a un oggetto CInvalidArgException. Per altre informazioni su come gestire le eccezioni, vedere Eccezioni.

Se un oggetto apre correttamente un CFile file specificato, il file verrà chiuso automaticamente quando l'oggetto CFile viene eliminato. In caso contrario, è necessario chiudere in modo esplicito il file dopo che non è più collegato all'oggetto CFile .

Esempio

L'esempio di codice illustra come usare un oggetto 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

Chiude il file associato a questo oggetto e rende il file non disponibile per la lettura o la scrittura.

virtual void Close();

Osservazioni:

Se il file non è stato chiuso prima di eliminare definitivamente l'oggetto, il distruttore lo chiude per l'utente.

Se è stato usato new per allocare l'oggetto nell'heap CFile , è necessario eliminarlo dopo la chiusura del file. Close imposta su m_hFileCFile::hFileNull.

Esempio

Vedere l'esempio per CFile::CFile.

CFile::D uplicate

Costruisce un oggetto duplicato CFile per un determinato file.

virtual CFile* Duplicate() const;

Valore restituito

Puntatore a un oggetto duplicato CFile .

Osservazioni:

Questa funzione equivale alla funzione _dupdi runtime C .

CFile::Flush

Forza la scrittura di tutti i dati rimanenti nel buffer di file nel file.

virtual void Flush();

Osservazioni:

L'uso di Flush non garantisce lo scaricamento dei CArchive buffer. Se si usa un archivio, chiamare prima CArchive::Flush .

Esempio

Vedere l'esempio per CFile::SetFilePath.

CFile::GetFileName

Chiamare questa funzione membro per recuperare il nome di un file specificato.

virtual CString GetFileName() const;

Valore restituito

Nome del file.

Osservazioni:

Ad esempio, quando si chiama GetFileName per generare un messaggio all'utente sul file c:\windows\write\myfile.wri, viene restituito il nome file , myfile.wri, .

Per restituire l'intero percorso del file, incluso il nome, chiamare GetFilePath. Per restituire il titolo del file ( myfile), chiamare GetFileTitle.

Esempio

Questo frammento di codice apre system. File INI nella directory DI WINDOWS. Se trovato, nell'esempio verranno stampati il nome e il percorso e il titolo, come illustrato in Output:

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

Chiamare questa funzione membro per recuperare il percorso completo di un file specificato.

virtual CString GetFilePath() const;

Valore restituito

Percorso completo del file specificato.

Osservazioni:

Ad esempio, quando si chiama GetFilePath per generare un messaggio all'utente sul file c:\windows\write\myfile.wri, viene restituito il percorso del file , c:\windows\write\myfile.wri, .

Per restituire solo il nome del file (myfile.wri), chiamare GetFileName. Per restituire il titolo del file (myfile), chiamare GetFileTitle.

Esempio

Vedere l'esempio per GetFileName.

CFile::GetFileTitle

Chiamare questa funzione membro per recuperare il titolo del file (il nome visualizzato) per il file.

virtual CString GetFileTitle() const;

Valore restituito

Titolo del file sottostante.

Osservazioni:

Questo metodo chiama GetFileTitle per recuperare il titolo del file. In caso di esito positivo, il metodo restituisce la stringa che il sistema userebbe per visualizzare il nome del file all'utente. In caso contrario, il metodo chiama PathFindFileName per recuperare il nome del file (inclusa l'estensione di file) del file sottostante. Ciò significa che l'estensione del file non è sempre inclusa nella stringa del titolo del file restituito. Per altre informazioni, vedere GetFileTitle e PathFindFileName in Windows SDK.

Per restituire l'intero percorso del file, incluso il nome, chiamare GetFilePath. Per restituire solo il nome del file, chiamare GetFileName.

Esempio

Vedere l'esempio per GetFileName.

CFile::GetLength

Ottiene la lunghezza logica corrente del file in byte.

virtual ULONGLONG GetLength() const;

Valore restituito

Lunghezza del file.

Esempio

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

Ottiene il valore corrente del puntatore al file, che può essere usato nelle chiamate successive a Seek.

virtual ULONGLONG GetPosition() const;

Valore restituito

Puntatore al file.

Esempio

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

Questo metodo recupera informazioni sullo stato correlate a una determinata CFile istanza dell'oggetto o a un determinato percorso di file.

BOOL GetStatus(CFileStatus& rStatus) const;

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

Parametri

rStatus
Riferimento a una struttura fornita dall'utente CFileStatus che riceverà le informazioni sullo stato. La CFileStatus struttura include i campi seguenti:

CTime m_ctime Data e ora di creazione del file.
CTime m_mtime Data e ora dell'ultima modifica del file.
CTime m_atime Data e ora dell'ultimo accesso al file per la lettura.
ULONGLONG m_size Dimensioni logiche del file in byte, come indicato dal comando DIR.
BYTE m_attribute Byte dell'attributo del file.
char m_szFullName[_MAX_PATH] Nome file assoluto nel set di caratteri di Windows.

lpszFileName
Stringa nel set di caratteri di Windows che rappresenta il percorso del file desiderato. Il percorso può essere relativo o assoluto oppure può contenere un nome di percorso di rete.

Ptm
Puntatore all'oggetto CAtlTransactionManager

Valore restituito

TRUE se le informazioni sullo stato per il file specificato vengono ottenute correttamente; in caso contrario, FAL edizione Standard.

Osservazioni:

La versione non statica di GetStatus recupera le informazioni sullo stato del file aperto associato all'oggetto specificato CFile . La versione statica di GetStatus ottiene lo stato del file da un determinato percorso di file senza aprire effettivamente il file. Questa versione è utile per testare l'esistenza e i diritti di accesso di un file.

Il m_attribute membro della CFileStatus struttura fa riferimento al set di attributi del file. La CFile classe fornisce il tipo di enumerazione Attribute in modo che gli attributi del file possano essere specificati simbolicamente:

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

Esempio

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 la presenza di un handle di file valido per l'oggetto CFile .

static AFX_DATA const HANDLE hFileNull;

Osservazioni:

Questa costante viene utilizzata per determinare se l'oggetto CFile dispone di un handle di file valido.

L'esempio seguente illustra questa operazione:

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

CFile::LockRange

Blocca un intervallo di byte in un file aperto, generando un'eccezione se il file è già bloccato.

virtual void LockRange(
    ULONGLONG dwPos,
    ULONGLONG dwCount);

Parametri

dwPos
Offset di byte dell'inizio dell'intervallo di byte da bloccare.

dwCount
Numero di byte nell'intervallo da bloccare.

Osservazioni:

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 l'area usando la UnlockRange funzione membro, l'intervallo di byte deve corrispondere esattamente all'area precedentemente bloccata. La LockRange funzione non unisce aree adiacenti. Se due aree bloccate sono adiacenti, è necessario sbloccare ogni area separatamente.

Nota

Questa funzione non è disponibile per la CMemFileclasse derivata da .

Esempio

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

Contiene l'handle di file del sistema operativo per un file aperto.

HANDLE m_hFile;

Osservazioni:

m_hFile è una variabile pubblica di tipo UINT. CFile::hFileNullContiene , un indicatore di file vuoto indipendente dal sistema operativo, se l'handle non è stato assegnato.

L'uso di m_hFile non è consigliato, perché il significato del membro dipende dalla classe derivata. m_hFile viene reso membro pubblico per praticità nel supportare l'uso nonpomorfico della classe .

CFile::m_pTM

Puntatore a un oggetto CAtlTransactionManager.

CAtlTransactionManager* m_pTM;

Osservazioni:

CFile::Open

Con overload. Open è progettato per l'uso con il costruttore predefinito CFile .

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

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

Parametri

lpszFileName
Stringa contenente il percorso del file desiderato. Il percorso può essere relativo, assoluto o un nome di rete (UNC).

nOpenFlags
UINT che definisce la modalità di condivisione e accesso del file. Specifica l'azione da eseguire all'apertura del file. È possibile combinare le opzioni usando l'operatore OR bit per bit ( | ). Sono necessarie un'autorizzazione di accesso e un'opzione di condivisione; le modeCreate modalità e modeNoInherit sono facoltative. Per un elenco delle opzioni della modalità, vedere il costruttore CFile .

pError
Puntatore a un oggetto eccezione file esistente che riceve lo stato di un'operazione non riuscita.

Ptm
Puntatore all'oggetto CAtlTransactionManager

Valore restituito

Diverso da zero se l'apertura ha avuto esito positivo; in caso contrario, 0. Il parametro pError è significativo solo se viene restituito 0.

Osservazioni:

Le due Open funzioni sono metodi "sicuri" per l'apertura di un file, in cui un errore è una condizione normale e prevista.

Mentre il CFile costruttore genera un'eccezione in una condizione di errore, Open restituisce FAL edizione Standard per le condizioni di errore. Open può comunque inizializzare un oggetto CFileException per descrivere l'errore. Se non si specifica il parametro pError o se si passa NULL per pError, Open restituisce FAL edizione Standard e non genera un'eccezione CFileException. Se si passa un puntatore a un oggetto esistente CFileExceptione Open viene rilevato un errore, la funzione lo riempie di informazioni che descrivono tale errore. Open non genera un'eccezione in entrambi i casi.

Nella tabella seguente vengono descritti i possibili risultati di Open.

`pError`	Errore rilevato	Valore restituito	Contenuto di CFileException
NULL	No	TRUE	n/d
ptr to `CFileException`	No	TRUE	non modificato
NULL	Sì	FALSE	n/d
ptr to `CFileException`	Sì	FALSE	inizializzato per descrivere l'errore

Esempio

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

Usare questo operatore per passare un handle a un CFile oggetto a funzioni come ReadFileEx e GetFileTime che prevedono un oggetto HANDLE.

operator HANDLE() const;

CFile::Read

Legge i dati in un buffer dal file associato all'oggetto CFile .

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

Parametri

lpBuf
Puntatore al buffer fornito dall'utente che deve ricevere i dati letti dal file.

nCount
Numero massimo di byte da leggere dal file. Per i file in modalità testo, le coppie di avanzamento ritorno a capo vengono conteggiate come singoli caratteri.

Valore restituito

Numero di byte trasferiti nel buffer. Per tutte le CFile classi, il valore restituito può essere minore di nCount se è stata raggiunta la fine del file.

Esempio

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

Per un altro esempio, vedere CFile::Open.

CFile::Remove

Questa funzione statica elimina il file specificato dal percorso.

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

Parametri

lpszFileName
Stringa che rappresenta il percorso del file desiderato. Il percorso può essere relativo o assoluto e può contenere un nome di rete.

Ptm
Puntatore all'oggetto CAtlTransactionManager

Osservazioni:

Remove non rimuoverà una directory.

La Remove funzione membro genera un'eccezione se il file connesso è aperto o se il file non può essere rimosso. Questa funzione equivale al comando DEL.

Esempio

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

Questa funzione statica rinomina il file specificato.

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

Parametri

lpszOldName
Percorso precedente.

lpszNewName
Nuovo percorso.

Ptm
Puntatore all'oggetto CAtlTransactionManager

Osservazioni:

Non è possibile rinominare le directory. Questa funzione equivale al comando REN.

Esempio

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

Riposiziona il puntatore al file in un file aperto.

virtual ULONGLONG Seek(
LONGLONG lOff,
UINT nFrom);

Parametri

lOff
Numero di byte per spostare il puntatore del file. I valori positivi spostano il puntatore del file verso la fine del file; i valori negativi spostano il puntatore del file verso l'inizio del file.

nFrom
Posizione da cui cercare. Per i valori possibili, vedere la sezione Osservazioni.

Valore restituito

Posizione del puntatore al file se il metodo ha avuto esito positivo; in caso contrario, il valore restituito non è definito e viene generato un puntatore a un'eccezione CFileException .

Osservazioni:

Nella tabella seguente sono elencati i valori possibili per il parametro nFrom .

Valore	Descrizione
`CFile::begin`	Cercare dall'inizio del file.
`CFile::current`	Cercare dal percorso corrente del puntatore al file.
`CFile::end`	Cercare dalla fine del file.

Quando un file viene aperto, il puntatore al file viene posizionato su 0, l'inizio del file.

È possibile impostare il puntatore del file su una posizione oltre la fine di un file. In questo caso, le dimensioni del file non aumentano fino a quando non si scrive nel file.

Il gestore eccezioni per questo metodo deve eliminare l'oggetto eccezione dopo l'elaborazione dell'eccezione.

Esempio

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

Imposta il valore del puntatore al file all'inizio del file.

void SeekToBegin();

Osservazioni:

SeekToBegin() è pari a Seek( 0L, CFile::begin ).

Esempio

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

CFile::SeekToEnd

Imposta il valore del puntatore al file alla fine logica del file.

ULONGLONG SeekToEnd();

Valore restituito

Lunghezza, in byte, del file.

Osservazioni:

SeekToEnd() è pari a CFile::Seek( 0L, CFile::end ).

Esempio

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

CFile::SetFilePath

Chiamare questa funzione per specificare il percorso del file. Ad esempio, se il percorso di un file non è disponibile quando viene costruito un oggetto CFile , chiamare SetFilePath per specificarlo.

virtual void SetFilePath(LPCTSTR lpszNewName);

Parametri

lpszNewName
Puntatore a una stringa che specifica il nuovo percorso.

Osservazioni:

Nota

SetFilePath non apre il file o crea il file; associa semplicemente l'oggetto CFile a un nome di percorso, che può quindi essere usato.

Esempio

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

Chiamare questa funzione per modificare la lunghezza del file.

virtual void SetLength(ULONGLONG dwNewLen);

Parametri

dwNewLen
Lunghezza desiderata del file in byte. Questo valore può essere maggiore o minore della lunghezza corrente del file. Il file verrà esteso o troncato in base alle esigenze.

Osservazioni:

Nota

Con CMemFile, questa funzione potrebbe generare un CMemoryException oggetto .

Esempio

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

CFile::SetStatus

Imposta lo stato del file associato al percorso del file.

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

Parametri

lpszFileName
Stringa che rappresenta il percorso del file desiderato. Il percorso può essere relativo o assoluto e può contenere un nome di rete.

status
Buffer contenente le nuove informazioni sullo stato. Chiamare la GetStatus funzione membro per precompilare la CFileStatus struttura con i valori correnti, quindi apportare modifiche in base alle esigenze. Se un valore è 0, l'elemento di stato corrispondente non viene aggiornato. Per una descrizione della CFileStatus struttura, vedere la funzione membro GetStatus.

Ptm
Puntatore all'oggetto CAtlTransactionManager

Osservazioni:

Per impostare l'ora, modificare il m_mtime campo di stato.

Quando si effettua una chiamata a SetStatus in un tentativo di modificare solo gli attributi del file e il m_mtime membro della struttura dello stato del file è diverso da zero, gli attributi possono essere interessati anche (la modifica del timestamp potrebbe avere effetti collaterali sugli attributi). Se si desidera modificare solo gli attributi del file, impostare prima il m_mtime membro della struttura dello stato del file su zero e quindi effettuare una chiamata a SetStatus.

Esempio

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

CFile::UnlockRange

Sblocca un intervallo di byte in un file aperto.

virtual void UnlockRange(
    ULONGLONG dwPos,
    ULONGLONG dwCount);

Parametri

dwPos
Offset dei byte dell'inizio dell'intervallo di byte da sbloccare.

dwCount
Numero di byte nell'intervallo da sbloccare.

Osservazioni:

Per informazioni dettagliate, vedere la descrizione della funzione membro LockRange .

Nota

Questa funzione non è disponibile per la CMemFileclasse derivata da .

Esempio

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

Scrive i dati da un buffer nel file associato all'oggetto CFile .

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

Parametri

lpBuf
Puntatore al buffer fornito dall'utente che contiene i dati da scrivere nel file.

nCount
Numero di byte da trasferire dal buffer. Per i file in modalità testo, le coppie di avanzamento ritorno a capo vengono conteggiate come singoli caratteri.

Osservazioni:

Write genera un'eccezione in risposta a diverse condizioni, inclusa la condizione completa del disco.

Esempio

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

Vedere anche gli esempi per CFile::CFile e CFile::Open.

Vedi anche

MFC Sample DRAWCLI
Classe CObject
Grafico della gerarchia
Classe CStdioFile
Classe CMemFile