CFile 類別

發行項
10/12/2023

MFC 檔案類別的基底類別。

語法

class CFile : public CObject

成員

公用建構函式

名稱	描述
CFile：：CFile	`CFile`從路徑或檔案控制代碼建構物件。

公用方法

名稱	描述
CFile：：Abort	關閉檔案，忽略所有警告和錯誤。
CFile：：Close	關閉檔案並刪除物件。
CFile：:D uplicate	根據這個檔案建構重複的物件。
CFile：：Flush	排清尚未寫入的任何資料。
CFile：：GetFileName	擷取所選檔案的檔案名。
CFile：：GetFilePath	擷取所選檔案的完整檔案路徑。
CFile：：GetFileTitle	擷取所選檔案的標題。
CFile：：GetLength	擷取檔案的長度。
CFile：：GetPosition	擷取目前的檔案指標。
CFile：：GetStatus	擷取開啟檔案的狀態，或在靜態版本中擷取指定檔案的狀態（靜態、虛擬函式）。
CFile：：LockRange	鎖定檔案中的位元組範圍。
CFile：：Open	保管庫開啟含有錯誤測試選項的檔案。
CFile：：Read	從位於目前檔案位置的檔案讀取（未壓縮）資料。
CFile：：Remove	刪除指定的檔案（static 函式）。
CFile：：Rename	重新命名指定的檔案（static 函式）。
CFile：：Seek	放置目前的檔案指標。
CFile：：SeekToBegin	將目前的檔案指標放在檔案的開頭。
CFile：：SeekToEnd	將目前的檔案指標放在檔案結尾。
CFile：：SetFilePath	設定所選取檔案的完整檔案路徑。
CFile：：SetLength	變更檔案的長度。
CFile：：SetStatus	設定指定檔案的狀態（靜態、虛擬函式）。
CFile：：UnlockRange	解除鎖定檔案中的位元組範圍。
CFile：：Write	將檔案中的資料寫入至目前的檔案位置。

公用運算子

名稱	描述
CFile：：operator HANDLE	物件的控制碼 `CFile` 。

公用資料成員

名稱	描述
CFile：：hFileNull	判斷物件是否 `CFile` 具有有效的控制碼。
CFile：：m_hFile	通常包含作業系統檔案控制代碼。

受保護的資料成員

名稱	描述
CFile：：m_pTM	`CAtlTransactionManager`物件的指標。

備註

它直接提供無緩衝區、二進位磁片輸入/輸出服務，並透過其衍生類別間接支援文字檔和記憶體檔案。 CFile 可與類別 CArchive 搭配運作，以支援 Microsoft Foundation Class 物件的序列化。

這個類別與其衍生類別之間的階層式關聯性可讓您的程式透過多型 CFile 介面在所有檔案物件上操作。例如，記憶體檔案的行為就像磁片檔案一樣。

針對一般用途磁片 I/O，使用 CFile 及其衍生類別。針對傳送至磁片檔案的格式化文字，使用 ofstream 或其他 Microsoft iostream 類別。

一般而言，磁片檔案會在建構時 CFile 自動開啟，並在解構時關閉。靜態成員函式可讓您在不開啟檔案的情況下詢問檔案的狀態。

如需使用 CFile 的詳細資訊，請參閱中的中的 檔案>和 <檔案處理 > 一文。

繼承階層架構

CObject

CFile

需求

標頭： afx.h

CFile：：Abort

關閉與此物件相關聯的檔案，並讓檔案無法讀取或寫入。

virtual void Abort();

備註

如果您在終結物件之前尚未關閉檔案，解構函式會為您關閉它。

處理例外狀況時， CFile::Abort 有 CFile::Close 兩個重要方式不同。首先，函 Abort 式不會在失敗時擲回例外狀況，因為會忽略 Abort 失敗。其次， Abort 如果檔案尚未開啟或先前已關閉，則不會 ASSERT 。

如果您曾經 new 在堆積上配置 CFile 物件，則必須在關閉檔案之後刪除它。 Abort 會將設定 m_hFile 為 CFile::hFileNull 。

範例

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

建構並初始化 CFile 物件。

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

CFile(
LPCTSTR lpszFileName,
UINT nOpenFlags);

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

參數

hFile
要連結至 CFile 物件的檔案控制代碼。

lpszFileName
要連結至 CFile 物件的檔案相對或完整路徑。

nOpenFlags
指定檔案之檔案存取選項的位元組合 (OR)。如需可能的選項，請參閱＜備註＞一節。

pTM
CAtlTransactionManager 物件的指標

備註

下列五個數據表列出 nOpenFlags 參數的可能選項 。

請僅選擇下列其中一個檔案存取模式選項。預設檔案存取模式為 CFile::modeRead，其是唯讀的。

值	Description
`CFile::modeRead`	僅要求讀取權限。
`CFile::modeWrite`	僅要求寫入權限。
`CFile::modeReadWrite`	要求讀取和寫入權限。

請選擇下列其中一個字元模式選項。

值	Description
`CFile::typeBinary`	設定二進位模式 (僅在衍生的類別中使用)。
`CFile::typeText`	設定文字模式，並針對歸位字元換行字元組進行特殊處理（僅適用于衍生類別）。
`CFile::typeUnicode`	設定 Unicode 模式 (僅在衍生的類別中使用)。當應用程式在 Unicode 組態中建置時，文字會以 Unicode 格式寫入檔案。不會將 BOM 寫入檔案。

請僅選擇下列其中一個檔案共用模式選項。預設檔案共用模式為 CFile::shareExclusive，其是獨佔的。

值	Description
`CFile::shareDenyNone`	無共用限制。
`CFile::shareDenyRead`	拒絕所有其他項目的讀取權限。
`CFile::shareDenyWrite`	拒絕所有其他項目的寫入權限。
`CFile::shareExclusive`	拒絕所有其他項目的讀取及寫入權限。

請選擇下列檔案的第一個，或兩者都選，以建立模式選項。預設建立模式為 CFile::modeNoTruncate，其為開啟現有項目。

值	Description
`CFile::modeCreate`	如果沒有檔案存在，請建立新的檔案。如果檔案已經存在，則會覆寫它，並一開始設定為零長度。
`CFile::modeNoTruncate`	如果沒有檔案，請建立新的檔案;否則，如果檔案已經存在，則會附加至 `CFile` 物件。

請按照所述，選擇下列檔案快取選項。根據預設，系統會使用一般用途快取配置，但無法當做選項使用。

值	Description
`CFile::osNoBuffer`	系統不會使用檔案的中繼快取。此選項會取消下列 2 個選項。
`CFile::osRandomAccess`	檔案快取針對隨機存取最佳化。請勿同時使用此選項和循序掃描選項。
`CFile::osSequentialScan`	檔案快取針對循序存取最佳化。請勿同時使用此選項和隨機存取選項。
`CFile::osWriteThrough`	寫入作業不會延遲完成。

選擇下列安全選項，以防止繼承檔案控制代碼。根據預設，任何新子處理序都可以使用檔案控制代碼。

值	Description
`CFile::modeNoInherit`	防止任何子處理序使用檔案控制代碼。

預設建構函式會初始化成員，但不會將檔案附加至 CFile 物件。使用此建構函式之後，請使用 CFile：：Open 方法來開啟檔案，並將它附加至 CFile 物件。

具有一個參數的建構函式會初始化成員，並將現有檔案連結至 CFile 物件。

具有兩個參數的建構函式會初始化成員，並嘗試開啟指定的檔案。如果此建構函式成功開啟指定的檔案，則該檔案會連結至 CFile 物件；否則，此建構函式會擲回指向 CInvalidArgException 物件的指標。如需如何處理例外狀況的詳細資訊，請參閱例外狀況。

CFile如果物件成功開啟指定的檔案，它會在物件終結時 CFile 自動關閉此檔案;否則，您必須在檔案不再附加至 CFile 物件之後明確關閉該檔案。

範例

下列程式碼顯示如何使用 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

關閉與此物件相關聯的檔案，並讓檔案無法讀取或寫入。

virtual void Close();

備註

如果您在終結物件之前尚未關閉檔案，解構函式會為您關閉它。

如果您曾經 new 在堆積上配置 CFile 物件，則必須在關閉檔案之後刪除它。 Close 會將設定 m_hFile 為 CFile::hFileNull 。

範例

請參閱 CFile：：CFile 的範例。

CFile：:D uplicate

建構指定檔案的重複 CFile 物件。

virtual CFile* Duplicate() const;

傳回值

重複 CFile 物件的指標。

備註

此函式相當於 C 執行時間函式 _dup 。

CFile：：Flush

強制將檔案緩衝區中剩餘的任何資料寫入檔案。

virtual void Flush();

備註

的 Flush 用法並不保證緩衝區的 CArchive 排清。如果您使用封存，請先呼叫 CArchive：：Flush 。

範例

請參閱 CFile：：SetFilePath 的範例。

CFile：：GetFileName

呼叫這個成員函式以擷取指定檔案的名稱。

virtual CString GetFileName() const;

傳回值

檔案的檔名。

備註

例如，當您呼叫 GetFileName 以向使用者產生檔案的相關 c:\windows\write\myfile.wri 訊息時，會傳回檔案名、 myfile.wri 。

若要傳回檔案的完整路徑，包括名稱，請呼叫 GetFilePath 。若要傳回檔案的標題（ myfile ），請呼叫 GetFileTitle 。

範例

此程式碼片段會開啟 SYSTEM。WINDOWS 目錄中的 INI 檔案。如果找到，此範例將會列印出名稱和路徑和標題，如輸出下方所示：

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

呼叫這個成員函式，以擷取指定檔案的完整路徑。

virtual CString GetFilePath() const;

傳回值

指定檔案的完整路徑。

備註

例如，當您呼叫 GetFilePath 以向使用者產生檔案的相關 c:\windows\write\myfile.wri 訊息時， c:\windows\write\myfile.wri 會傳回檔案路徑、。

若要只傳回檔案的名稱（ myfile.wri ），請呼叫 GetFileName 。若要傳回檔案的標題（ myfile ），請呼叫 GetFileTitle 。

範例

請參閱 GetFileName 的範例。

CFile：：GetFileTitle

呼叫這個成員函式，以擷取檔案的檔案標題（顯示名稱）。

virtual CString GetFileTitle() const;

傳回值

基礎檔案的標題。

備註

這個方法會呼叫 GetFileTitle 來擷取檔案的標題。如果成功，此方法會傳回系統用來向使用者顯示檔案名的字串。否則，方法會呼叫 PathFindFileName 來擷取基礎檔案的檔案名（包括副檔名）。這表示副檔名不一定會包含在傳回的檔案標題字串中。如需詳細資訊，請參閱 Windows SDK 中的 GetFileTitle 和 PathFindFileName 。

若要傳回檔案的完整路徑，包括名稱，請呼叫 GetFilePath 。若要只傳回檔案名，請呼叫 GetFileName 。

範例

請參閱 GetFileName 的範例。

CFile：：GetLength

取得檔案的目前邏輯長度，以位元組為單位。

virtual ULONGLONG GetLength() const;

傳回值

檔案的長度。

範例

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

取得檔案指標的目前值，以供稍後呼叫 Seek 使用。

virtual ULONGLONG GetPosition() const;

傳回值

檔案指標。

範例

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

這個方法會擷取與指定 CFile 物件實例或指定檔案路徑相關的狀態資訊。

BOOL GetStatus(CFileStatus& rStatus) const;

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

參數

rStatus
將接收狀態資訊之使用者提供 CFileStatus 結構的參考。結構 CFileStatus 具有下欄欄位：

CTime m_ctime 建立檔案的日期和時間。
CTime m_mtime 上次修改檔案的日期和時間。
CTime m_atime 上次存取檔案的讀取日期和時間。
ULONGLONG m_size 以位元組為單位的檔案邏輯大小，如 DIR 命令所報告。
BYTE m_attribute 檔案的屬性位元組。
char m_szFullName[_MAX_PATH] Windows 字元集中的絕對檔案名。

lpszFileName
Windows 字元集中的字串，這是所需檔案的路徑。路徑可以是相對或絕對路徑，也可以包含網路路徑名稱。

pTM
CAtlTransactionManager 物件的指標

傳回值

如果成功取得指定檔案的狀態資訊，則為 TRUE;否則為 FALSE。

備註

的非靜態版本 GetStatus 會擷取與指定 CFile 物件相關聯之開啟檔案的狀態資訊。的靜態版本 GetStatus 會從指定的檔案路徑取得檔案狀態，而不會實際開啟檔案。此版本適用于測試檔案是否存在和存取權限。

結構 m_attribute 的成員 CFileStatus 是指檔案屬性集。類別 CFile 會提供 Attribute 列舉類型，以便以符號方式指定檔案屬性：

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

範例

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

判斷物件的有效檔案控制代碼 CFile 是否存在。

static AFX_DATA const HANDLE hFileNull;

備註

這個常數是用來判斷物件是否 CFile 具有有效的檔案控制代碼。

下列範例示範此作業：

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

CFile：：LockRange

鎖定開啟檔案中的位元組範圍，如果檔案已鎖定，則會擲回例外狀況。

virtual void LockRange(
    ULONGLONG dwPos,
    ULONGLONG dwCount);

參數

dwPos
要鎖定之位元組範圍的開頭位元組位移。

dwCount
要鎖定之範圍中的位元組數目。

備註

鎖定檔案中的位元組可防止其他處理序存取這些位元組。您可以鎖定檔案的多個區域，但不允許重迭的區域。

當您使用 UnlockRange 成員函式解除鎖定區域時，位元組範圍必須完全符合先前鎖定的區域。函 LockRange 式不會合並相鄰區域。如果兩個鎖定的區域相鄰，您必須個別解除鎖定每個區域。

注意

此函式不適用於 CMemFile 衍生類別。

範例

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

包含開啟檔案的作業系統檔案控制代碼。

HANDLE m_hFile;

備註

m_hFile 是 UINT 類型的公用變數。如果尚未指派控制碼，它會包含 CFile::hFileNull 與作業系統無關的空白檔案指標。

m_hFile不建議使用，因為成員的意義取決於衍生類別。 m_hFile 會成為公用成員，以方便支援類別的非變形用法。

CFile：：m_pTM

指向 CAtlTransactionManager 物件的指標。

CAtlTransactionManager* m_pTM;

備註

CFile：：Open

已多載。 Open 是設計來搭配預設 CFile 建構函式使用。

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

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

參數

lpszFileName
包含所需檔案路徑的字串。路徑可以是相對、絕對或網路名稱（UNC）。

nOpenFlags
定義檔案共用和存取模式的 UINT。它會指定要在開啟檔案時採取的動作。您可以使用位 OR （ | ）運算子來合併選項。需要一個存取權限和一個共用選項;和 modeCreatemodeNoInherit 模式是選擇性的。如需模式選項清單，請參閱 CFile 建構函式。

pError
將接收失敗作業狀態的現有檔案例外狀況物件的指標。

pTM
CAtlTransactionManager 物件的指標

傳回值

如果開啟成功，則為非零;否則為 0。 只有在傳回 0 時，pError 參數才有意義。

備註

這兩 Open 個函式是開啟檔案的「安全」方法，其中失敗是正常且預期的狀況。

當建 CFile 構函式在錯誤條件中擲回例外狀況時， Open 會針對錯誤狀況傳回 FALSE。 Open 不過，仍然可以初始化 CFileException 物件來描述錯誤。如果您未提供 pError 參數，或針對 pError 傳遞 Null ， Open 則傳回 FALSE，且不會擲回 CFileException 。如果您將指標傳遞給現有的 CFileException ，並 Open 遇到錯誤，則函式會填入描述該錯誤的資訊。 Open 在這兩種情況下，都不會擲回例外狀況。

下表描述的 Open 可能結果。

`pError`	發生錯誤	傳回值	CFileException 內容
NULL	No	TRUE	n/a
ptr 至 `CFileException`	No	TRUE	未變更
NULL	Yes	FALSE	n/a
ptr 至 `CFileException`	Yes	FALSE	初始化以描述錯誤

範例

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

使用此運算子將控制碼傳遞至 CFile 物件，例如需要的 ReadFileEx 和 GetFileTime HANDLE 等函式。

operator HANDLE() const;

CFile：：Read

從與 CFile 物件相關聯的檔案將資料讀入緩衝區。

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

參數

lpBuf
使用者提供的緩衝區指標，該緩衝區是接收從檔案讀取的資料。

nCount
要從檔案讀取的最大位元組數目。針對文字模式檔案，歸位字元換行字元組會計算為單一字元。

傳回值

傳輸至緩衝區的位元組數目。針對所有 CFile 類別，如果到達檔案結尾，傳回值可能會小於 nCount 。

範例

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

如需另一個範例，請參閱 CFile：：Open 。

CFile：：Remove

此靜態函式會刪除路徑所指定的檔案。

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

參數

lpszFileName
字串，這是所需檔案的路徑。路徑可以是相對或絕對路徑，而且可以包含網路名稱。

pTM
CAtlTransactionManager 物件的指標

備註

Remove 不會移除目錄。

如果已連線的檔案已開啟，或是無法移除檔案，則 Remove 成員函式會擲回例外狀況。此函式相當於 DEL 命令。

範例

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

這個靜態函式會重新命名指定的檔案。

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

參數

lpszOldName
舊路徑。

lpszNewName
新路徑。

pTM
CAtlTransactionManager 物件的指標

備註

無法重新命名目錄。此函式相當於 REN 命令。

範例

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

將檔案指標重新置放在開啟的檔案中。

virtual ULONGLONG Seek(
LONGLONG lOff,
UINT nFrom);

參數

lOff
移動檔案指標的位元組數目。正值會將檔案指標移至檔案結尾;負值會將檔案指標移至檔案開頭。

nFrom
要搜尋的位置。如需可能的值，請參閱一節。

傳回值

如果方法成功，則為檔案指標的位置;否則，傳回值是未定義的，而且擲回例外狀況的 CFileException 指標。

備註

下表列出 nFrom 參數的可能值 。

值	Description
`CFile::begin`	從檔案開頭搜尋。
`CFile::current`	從檔案指標的目前位置搜尋。
`CFile::end`	從檔案結尾搜尋。

開啟檔案時，檔案指標會放在 0，也就是檔案的開頭。

您可以將檔案指標設定為檔案結尾以外的位置。如果您這樣做，檔案的大小不會增加，直到您寫入檔案為止。

這個方法的例外狀況處理常式必須在處理例外狀況之後刪除例外狀況物件。

範例

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

將檔案指標的值設定為檔案開頭。

void SeekToBegin();

備註

SeekToBegin() 等於 Seek( 0L, CFile::begin )。

範例

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

CFile：：SeekToEnd

將檔案指標的值設定為檔案的邏輯結尾。

ULONGLONG SeekToEnd();

傳回值

檔案的長度 (以位元組為單位)。

備註

SeekToEnd() 等於 CFile::Seek( 0L, CFile::end )。

範例

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

CFile：：SetFilePath

呼叫此函式以指定檔案的路徑。例如，如果在建構 CFile 物件時無法使用檔案的路徑，請呼叫 SetFilePath 以提供它。

virtual void SetFilePath(LPCTSTR lpszNewName);

參數

lpszNewName
指定新路徑之字串的指標。

備註

注意

SetFilePath 不會開啟檔案或建立檔案;它只會將 CFile 物件與路徑名稱產生關聯，然後即可使用。

範例

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

呼叫此函式以變更檔案的長度。

virtual void SetLength(ULONGLONG dwNewLen);

參數

dwNewLen
所需的檔案長度，以位元組為單位。這個值可以大於或小於檔案的目前長度。檔案會視需要擴充或截斷。

備註

注意

使用 CMemFile 時，此函式可能會擲回 CMemoryException 物件。

範例

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

CFile：：SetStatus

設定與此檔案位置相關聯的檔案狀態。

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

參數

lpszFileName
字串，這是所需檔案的路徑。路徑可以是相對或絕對路徑，而且可以包含網路名稱。

status
包含新狀態資訊的緩衝區。 GetStatus呼叫成員函式以使用目前的值預先填入 CFileStatus 結構，然後視需要進行變更。如果值為 0，則不會更新對應的狀態專案。如需結構的描述 CFileStatus ，請參閱 GetStatus 成員函式。

pTM
CAtlTransactionManager 物件的指標

備註

若要設定時間，請修改 m_mtime 狀態欄位。

當您嘗試只變更檔案的屬性而呼叫 SetStatus 時，且 m_mtime 檔案狀態結構的成員為非零，屬性也可能受到影響（變更時間戳記可能會對屬性產生副作用）。如果您想要只變更檔案的屬性，請先將檔案狀態結構的成員設定 m_mtime 為零，然後呼叫 SetStatus 。

範例

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

CFile：：UnlockRange

解除鎖定開啟檔案中的位元組範圍。

virtual void UnlockRange(
    ULONGLONG dwPos,
    ULONGLONG dwCount);

參數

dwPos
要解除鎖定之位元組範圍的開頭位元組位移。

dwCount
要解除鎖定的範圍中的位元組數目。

備註

如需詳細資訊，請參閱 LockRange 成員函式的描述。

注意

此函式不適用於 CMemFile 衍生類別。

範例

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

將資料從緩衝區寫入與 CFile 物件相關聯的檔案。

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

參數

lpBuf
使用者提供的緩衝區指標，其中包含要寫入檔案的資料。

nCount
要從緩衝區傳輸的位元組數目。針對文字模式檔案，歸位字元換行字元組會計算為單一字元。

備註

Write 會擲回例外狀況以回應數個條件，包括磁片完整條件。

範例

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：：CFile 和 CFile：：Open 的範例。

另請參閱

MFC 範例 DRAWCLI
CObject 類別
 階層架構圖表
 CStdioFile 類別
 CMemFile 類別

共用方式為

CFile 類別

語法

成員

公用建構函式

公用方法

公用運算子

公用資料成員

受保護的資料成員

備註

繼承階層架構

需求

CFile：：Abort

備註

範例

CFile：：CFile

參數

備註

範例

CFile：：Close

備註

範例

CFile：:D uplicate

傳回值

備註

CFile：：Flush

備註

範例

CFile：：GetFileName

傳回值

備註

範例

CFile：：GetFilePath

傳回值

備註

範例

CFile：：GetFileTitle

傳回值

備註

範例

CFile：：GetLength

傳回值

範例

CFile：：GetPosition

傳回值

範例

CFile：：GetStatus

參數

傳回值

備註

範例

CFile：：hFileNull

備註

CFile：：LockRange

參數

備註

範例

CFile：：m_hFile

備註

CFile：：m_pTM

備註

CFile：：Open

參數

傳回值

備註

範例

CFile：：operator HANDLE

CFile：：Read

參數

傳回值

範例

CFile：：Remove

參數

備註

範例

CFile：：Rename

參數

備註

範例

CFile：：Seek