CFile 类

Microsoft 基础类文件类的基类。

语法

class CFile : public CObject

成员

公共构造函数

名称	描述
CFile::CFile	从路径或文件句柄构造 CFile 对象。

公共方法

名称	描述
CFile::Abort	关闭文件并忽略所有警告和错误。
CFile::Close	关闭文件并删除对象。
CFile::Duplicate	基于此文件构造一个重复对象。
CFile::Flush	刷新任何尚未写入的数据。
CFile::GetFileName	检索所选文件的文件名。
CFile::GetFilePath	检索所选文件的完整文件路径。
CFile::GetFileTitle	检索所选文件的标题。
CFile::GetLength	检索文件的长度。
CFile::GetPosition	检索当前文件指针。
CFile::GetStatus	检索打开的文件的状态，或者在静态版本中检索指定文件的状态（静态、虚拟函数）。
CFile::LockRange	锁定文件中的字节范围。
CFile::Open	使用错误测试选项安全打开文件。
CFile::Read	从位于当前文件位置的文件中读取（未缓冲）数据。
CFile::Remove	删除指定的文件（静态函数）。
CFile::Rename	重命名指定的文件（静态函数）。
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 基础类对象的序列化。

此类与其派生类之间的层次关系允许程序通过多态 CFile 接口来操作所有文件对象。 例如，内存文件的行为类似于磁盘文件。

将 CFile 及其派生类用于通用磁盘 I/O。 将 ofstream 或其他 Microsoft iostream 类用于发送到磁盘文件的带格式文本。

通常，磁盘文件在 CFile 构造时自动打开，在销毁时关闭。 静态成员函数允许在不打开文件的情况下查询文件的状态。

有关如何使用 CFile 的详细信息，请参阅运行时库参考中的文章 MFC 中的文件和文件处理。

继承层次结构

CObject

CFile

要求

标头： afx.h

CFile::Abort

关闭与此对象关联的文件并使该文件不可读取或写入。

virtual void Abort();

备注

如果在销毁对象之前尚未关闭文件，析构函数会为你关闭该文件。

在处理异常时，CFile::Abort 在两个重要方面不同于 CFile::Close。 首先，Abort 函数在失败时不会引发异常，因为失败会被 Abort 忽略。 其次，如果文件尚未打开或之前已关闭，则 Abort 不会断言。

如果使用 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，该模式为只读模式。

值	说明
CFile::modeRead	只请求读取访问权限。
CFile::modeWrite	只请求写入访问权限。
CFile::modeReadWrite	请求读写访问权限。

选择以下字符模式选项之一。

值	说明
CFile::typeBinary	设置二元模式（仅在派生类中使用）。
CFile::typeText	通过对回车符-换行符对进行特殊处理，来设置文本模式（仅在派生类中使用）。
CFile::typeUnicode	设置 Unicode 模式（仅在派生类中使用）。 当应用程序在 Unicode 配置中生成时，文本将以 Unicode 格式写入文件中。 不会将 BOM 写入该文件中。

仅选择下列文件共享模式选项之一。 默认文件共享模式为 CFile::shareExclusive，该模式是独占模式。

值	说明
CFile::shareDenyNone	没有任何共享限制。
CFile::shareDenyRead	拒绝向所有其他用户提供读取访问权限。
CFile::shareDenyWrite	拒绝向所有其他用户提供写入访问权限。
CFile::shareExclusive	拒绝向所有其他用户提供读写访问权限。

选择下面的第一个（或全选）文件创建模式选项。 默认创建模式为 CFile::modeNoTruncate，该模式当前处于打开状态。

值	说明
CFile::modeCreate	如果文件不存在，则创建一个新文件。 如果文件已存在，则将其覆盖并初始设置为零长度。
CFile::modeNoTruncate	如果文件不存在，则创建新文件；否则，如果文件已存在，则将其附加到 CFile 对象。

按照描述选择以下文件缓存选项。 默认情况下，系统将使用通用的缓存方案，该方案不可用作选项。

值	说明
CFile::osNoBuffer	系统没有为文件使用中间缓存。 此选项取消以下 2 个选项。
CFile::osRandomAccess	文件缓存针对随机访问进行了优化。 不要同时使用此选项和顺序扫描选项。
CFile::osSequentialScan	文件缓存针对顺序访问进行了优化。 不要同时使用此选项和随机访问选项。
CFile::osWriteThrough	写入操作将无延迟地完成。

选择下列安全选项以防止继承文件句柄。 默认情况下，所有新的子进程都可以使用文件句柄。

值	说明
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::Duplicate

为给定的文件构造一个重复的 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。

示例

此代码片段打开 WINDOWS 目录中的 SYSTEM.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 的静态版本从给定文件路径中获取文件状态，但不实际打开文件。 此版本可用于测试文件的存在状态和访问权限。

CFileStatus 结构的 m_attribute 成员引用文件属性集。 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。 它指定打开文件时要执行的操作。 可以使用按位“或”(|) 运算符来组合选项。 一个访问权限和一个共享选项是必需的；modeCreate 和 modeNoInherit 模式是可选的。 有关模式选项的列表，请参阅 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	否	TRUE	不适用
指向 CFileException 的指针	否	TRUE	未更改
Null	是	FALSE	不适用
指向 CFileException 的指针	是	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 对象的句柄传递给需要 HANDLE 的函数，例如 ReadFileEx 和 GetFileTime。

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 参数的可能值。

值	说明
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 对象的指针

备注

若要设置时间，请修改 status 的 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 类