65.9K
CodeProject 正在变化。 阅读更多。
Home

CFile64 - 文件系统包装器

PJ Naughter
starIconstarIconstarIcon
emptyStarIcon
starIcon
emptyStarIcon

3.40/5 (6投票s)

2000 年 3 月 4 日

viewsIcon

77390

downloadIcon

1176

一个免费的MFC类，用于封装Win32 64位文件系统API。

  • 下载源代码文件 - 15 Kb

    • 引言

    欢迎使用CFile64 v1.0，一个免费的MFC类，用于提供对Win32 SDK提供的64位文件系统API的访问。

    许多开发人员可能没有意识到，Win32 SDK的一部分已经包含了一些“64位”的特性。文件系统API就是一个例子。目前，MFC的CFile类隐藏了这些特性，以提供一种通用的API交互方式。如果您确实需要使用64位扩展，那么在使用原始SDK调用时，您可能会对微软感到沮丧。这个类试图为它提供一个更面向对象的接口。


    特点
    历史
    CFile64类成员
    联系作者


    特点

    • 提供对NTFS卷上可用的本地64位文件系统API的访问。注意：这并不阻止该类在FAT或FAT32卷上使用，只是文件的大小不能超过4GB。
    • 提供对SDK CreateFile API中所有参数的访问。当您想要完全控制文件的打开或创建方式时，这会非常有用。
    • 接口已尽可能地保持与CFile一致。
    • 使用Visual C++ 4.0或更高版本中内置的64位整数类型__in64。与使用原始Win32 SDK调用相比，这使得64位API的使用和理解更加容易。
    • 包含全面的文档。其风格应该与使用MS Developer Studio文档的任何人都能熟悉。


    历史

    V1.0 (1998年2月11日)
    • 首次公开发布。


    CFile64 类成员

    数据成员
    operator HANDLE() 返回此实例所代表的操作系统文件句柄。

    然后，当你开始迭代 2（这是构建迭代的开始）时，你可能想要复制测试用例并将它们重新分类到迭代 2。这还允许对测试用例进行粒度跟踪，并允许你说某个测试用例在一个迭代中是准备好的，但在另一个迭代中不是。同样，如何做到这一点取决于你以及你希望如何报告。 “场景”部分提供了更多细节。
    CFile64 构造一个CFile64对象，可选地从文件句柄构造。
    Attach 附加到一个已打开的文件句柄。
    Abort 关闭文件，忽略所有警告和错误。
    Duplicate 基于此文件构造一个副本对象。
    打开 安全地打开一个文件，并提供错误测试选项。
    Close 关闭文件并删除对象。
    Detach 将CFile64文件与其附加的文件句柄分离。

    输入/输出
    读取 从当前文件位置（非缓冲）读取数据。
    Write 将数据（非缓冲）写入当前文件位置的文件。
    Flush 刷新所有尚未写入的数据。

    职位
    Seek 定位当前文件指针。
    SeekToBegin 将当前文件指针定位到文件开头。
    SeekToEnd 将当前文件指针定位到文件末尾。
    GetLength 检索文件长度。
    SetLength 更改文件长度。

    Locking
    LockRange 锁定文件中的一个字节范围。
    UnlockRange 解锁文件中的一个字节范围。

    状态
    GetPosition 检索当前文件指针。
    GetFileName 检索选定文件的文件名。
    IsOpen 如果文件当前已打开，则返回TRUE。
    IsClosed 如果文件当前已关闭，则返回TRUE。
    SetFileName 设置选定文件的文件名。

    另请参阅 CFile64概述， 类成员


    CFile64::Abort

    void Abort();

    备注
    关闭与此对象关联的文件，并使文件无法读取或写入。如果您在销毁对象之前没有关闭文件，则析构函数会为您关闭它。

    在处理异常时，CFile64::Abort()与CFile64::Close()在两个重要方面有所不同。首先，Abort()函数在发生故障时不会抛出异常，因为Abort()会忽略这些故障。其次，如果文件尚未打开或先前已关闭，Abort()不会断言。

    如果您使用new在堆上分配CFile64对象，那么在关闭文件后必须删除它。Abort()会将m_hFile设置为INVALID_HANDLE_VALUE。

    示例

    //example for CFile64::Abort
CFile64 fileTest;
char* pFileName = "test.dat";
TRY
{
    // do stuff that may throw exceptions
    fileTest.Open( pFileName, CFile64::modeWrite );
}
CATCH_ALL( e )
{
    fileTest.Abort();    // close file safely and quietly
    THROW_LAST();
}
END_CATCH_ALL

    另请参阅
    CFile64概述， 类成员， CFile64::Close()， CFile64::Open()。


    CFile64::Attach

    void Attach(HANDLE hFile, BOOL bAutoClose);
    throw(CFileException);

    返回值
    如果applet已成功显示，则为TRUE，否则为FALSE。

    参数

    • hFile -- 已打开文件的句柄。
    • bAutoClose -- 析构函数或Detach是否应调用Close()。

    备注
    创建一个CFile64对象，该对象对应于由hFile标识的现有操作系统文件。不会检查访问模式或文件类型。当CFile64对象被销毁时，如果将bAutoClose设置为TRUE，则会关闭操作系统文件。

    另请参阅
    CFile64概述， 类成员， CFile64::Detach()。


    CFile64::CFile64

    CFile64();

    CFile64(HANDLE hFile, BOOL bAutoClose = TRUE);
    throw(CFileException);

    返回值
    如果applet已成功显示，则为TRUE，否则为FALSE。

    参数

    • hFile -- 已打开文件的句柄。
    • bAutoClose -- 析构函数是否应调用Close()。

    备注
    默认构造函数不打开文件，而是将m_hFile设置为INVALID_HANDLE_VALUE。由于此构造函数不抛出异常，因此使用TRY/CATCH逻辑没有意义。使用Open()成员函数，然后直接测试异常条件。有关异常处理策略的讨论，请参阅Programming with MFC中的“Exceptions”一文。

    带有两个参数的构造函数通过调用Attach()方法来创建CFile64。

    另请参阅
    CFile64概述， 类成员， CFile64::Open()。


    CFile64::Close

    void Close();
    throw(CFileException);

    备注
    关闭与此对象关联的文件，并使文件无法读取或写入。如果您在销毁对象之前没有关闭文件，则析构函数会为您关闭它。

    如果您使用new在堆上分配CFile64对象，那么在关闭文件后必须删除它。Close()将m_hFile设置为INVALID_HANDLE_VALUE。

    另请参阅
    CFile64概述， 类成员， CFile64::Open()。


    CFile64::Detach

    void Detach();
    throw(CFileException);

    备注
    调用此函数以将m_hFile与CFile64对象分离，并将m_hFile设置为INVALID_HANDLE_VALUE。如果通过Attach()告知关闭文件，则文件将被关闭。

    另请参阅
    CFile64概述， 类成员， CFile64::Attach()。


    CFile64::Duplicate

    CFile64* Duplicate() const;
    throw(CFileException);

    返回值
    指向复制的CFile64对象的指针。

    备注
    为给定文件构造一个复制的CFile64对象。

    另请参阅
    CFile64概述， 类成员。


    CFile64::Flush

    void Flush();
    throw(CFileException);

    备注
    将文件缓冲区中剩余的所有数据强制写入文件。

    另请参阅
    CFile64概述， 类成员。


    CFile64::GetFileName

    CString GetFileName( ) const;

    返回值
    文件的名称。

    备注
    调用此成员函数以检索指定文件的文件名。例如，当您调用GetFileName()为文件c:\windows\write\myfile.wri生成一条给用户的消息时，将返回文件名c:\windows\write\myfile.wri。

    另请参阅
    CFile64概述， 类成员， CFile64::SetFileName()。


    CFile64::GetLength

    UINT64 GetLength() const;
    throw(CFileException);

    返回值
    文件的长度。

    备注
    获取文件的当前逻辑长度（以字节为单位），而不是已传输的字节数。

    另请参阅
    CFile64概述， 类成员， CFile64::SetLength()。


    CFile64::GetPosition

    UINT64 GetPosition() const;
    throw(CFileException);

    返回值
    文件指针，表示为64位无符号整数。

    备注
    获取文件指针的当前值，该值可用于后续对Seek()的调用。

    示例

    //example for CFile64::GetPosition
extern CFile64 CFile64;
UINT64 lPosition = CFile64.GetPosition();

    另请参阅
    CFile64概述， 类成员。


    CFile64::IsClosed

    BOOL IsClosed() const;

    返回值
    如果文件当前已关闭，则返回TRUE，否则返回FALSE。

    另请参阅
    CFile64概述， 类成员。


    CFile64::IsOpen

    BOOL IsOpen() const;

    返回值
    如果文件当前已打开，则返回TRUE，否则返回FALSE。

    另请参阅
    CFile64概述， 类成员。


    CFile64::LockRange

    void LockRange(const UINT64& lPos, const UINT64& lCount);
    throw(CFileException);

    返回值
    如果applet已成功显示，则为TRUE，否则为FALSE。

    参数

    • lPos -- 要锁定的字节范围的起始字节偏移量。
    • lCount -- 要锁定的范围中的字节数。

    备注
    锁定一个打开文件中的字节范围，如果文件已被锁定，则抛出异常。锁定文件中的字节会阻止其他进程访问这些字节。您可以锁定文件的多个区域，但不能重叠。

    当您使用UnlockRange()成员函数解锁区域时，字节范围必须与先前锁定的区域完全对应。LockRange()函数不合并相邻区域；如果两个锁定区域是相邻的，您必须分别解锁每个区域。

    示例

    //example for CFile64::LockRange
extern UINT64 lPos;
extern UINT64 lCount;
extern CFile64 file;
file.LockRange( lPos, lCount );

    另请参阅
    CFile64概述， 类成员， CFile64::UnlockRange()。


    CFile64::Open

    BOOL Open(LPCTSTR lpFileName, DWORD dwDesiredAccess, DWORD dwShareMode, DWORD dwCreationDistribution, CFileException* pError = NULL, LPSECURITY_ATTRIBUTES lpSecurityAttributes = NULL, DWORD dwFlagsAndAttributes = 0, HANDLE hTemplateFile = NULL );

    返回值
    如果打开成功，则为非零；否则为0。当返回FALSE时，pError参数才有意义。

    参数

    • lpFileName -- 指向一个以null结尾的字符串，该字符串指定要创建或打开的对象的名称（文件、管道、邮件槽、通信资源、磁盘设备、控制台或目录）。有关更多详细信息，请参阅SDK函数CreateFile。
    • dwDesiredAccess -- 要锁定的范围中的字节数。
    • lCount -- 指定对对象的访问类型。应用程序可以获得读取访问、写入访问、读写访问或设备查询访问。有关更多详细信息，请参阅SDK函数CreateFile()。
    • dwShareMode -- 一组位标志，指定对象的共享方式。如果dwShareMode为0，则该对象不能共享。之后对该对象的打开操作将失败，直到句柄关闭。有关更多详细信息，请参阅SDK函数CreateFile()。
    • lpSecurityAttributes -- 指向SECURITY_ATTRIBUTES结构的指针，该结构决定了返回的句柄是否可以被子进程继承。如果lpSecurityAttributes为NULL，则句柄不能被继承。
    • dwCreationDisposition -- 指定对已存在文件的操作，以及对不存在文件的操作。有关此参数的更多信息，请参阅“Remarks”部分。有关更多详细信息，请参阅SDK函数CreateFile()。
    • dwFlagsAndAttributes -- 指定文件的属性和标志。有关更多详细信息，请参阅SDK函数CreateFile()。
    • hTemplateFile -- 指定一个具有GENERIC_READ访问权限的模板文件的句柄。模板文件为正在创建的文件提供文件属性和扩展属性。有关更多详细信息，请参阅SDK函数CreateFile()。
    • pError -- 指向一个现有的文件异常对象的指针，该对象将接收失败操作的状态。

    备注
    Open()是为与默认CFile64构造函数一起使用而设计的。这两个函数构成了一种“安全”的文件打开方法，其中失败是一种正常、可预期的条件。

    如果您不提供pError参数，或者将NULL传递给pError，Open将返回FALSE并且不会抛出CFileException。如果您传递一个指向现有CFileException的指针，并且Open()遇到错误，该函数将用描述该错误的详细信息填充它。在这两种情况下，Open()都不会抛出异常。

    下表描述了Open()的可能结果

    pError 是否遇到错误？ 返回值 CFileException内容
    NULL 否 TRUE 不适用
    指向CFileException的指针 否 TRUE 不变
    NULL 是 FALSE 不适用
    指向CFileException的指针 是 FALSE 初始化以描述错误

    示例

    //example for CFile64::Open
CFile64 f;
CFileException e;
char* pFileName = "test.dat";
if( !f.Open( pFileName, GENERIC_READ, 0, OPEN_EXISTING, &e ) )
    {
#ifdef _DEBUG
    afxDump << "File could not be opened " << e.m_cause << "\n";
#endif
    }

    另请参阅
    CFile64概述， 类成员， CFile64::CFile64()， CFile64::Close()。


    CFile64::Read

    DWORD Read(void* lpBuf, DWORD dwCount);
    throw(CFileException);

    返回值
    传输到缓冲区的字节数。注意，对于所有CFile64类，如果到达文件末尾，返回值可能小于nCount。

    参数

    • lpBuf -- 指向用户提供的要从文件中读取的数据的缓冲区。
    • dwCount -- 要从文件中读取的最大字节数。

    备注
    从与CFile64对象关联的文件向缓冲区读取数据。

    目前此函数只允许读取最多ULONG_MAX（4294967295）个字节，因为Win32只有4GB的地址空间（其中1-2GB对用户模式应用程序不可用）。这只有在Win64 API出现后才能得到解决。

    示例

    //example for CFile64::Read
extern CFile64 CFile64;
char pbuf[100];
DWORD dwBytesRead = CFile64.Read( pbuf, 100 );

    另请参阅
    CFile64概述， 类成员。


    CFile64::Seek

    LONG Seek(const UINT64& lDistanceToMove, SeekPosition MoveMethod, BOOL bForward);
    throw(CFileException);

    返回值
    如果请求的位置合法，Seek()将返回相对于文件开头的新的字节偏移量。否则，返回值是未定义的，并且会抛出CFileException对象。

    参数

    • lDistanceToMove -- 要移动指针的字节数。
    • nMoveMethod -- 指针移动模式。必须是以下值之一
      • CFile64::begin -- 将文件指针从文件开头向前移动lOff个字节。
      • CFile64::current -- 从文件中的当前位置向前移动lOff个字节。
      • CFile64::end -- 从文件末尾向前移动lOff个字节。
    • bForward -- 如果是向前查找，则为TRUE，否则为FALSE（表示向后查找）。

    备注
    重新定位先前打开的文件中的指针。Seek()函数通过按指定量绝对或相对地移动指针，允许对文件内容进行随机访问。在查找过程中不会实际读取数据。

    打开文件时，文件指针定位在偏移量0（文件开头）。

    示例

    //example for CFile64::Seek
extern CFile64 file;
LONG lOffset = 1000, lActual;
lActual = file.Seek( lOffset, CFile64::begin );

    另请参阅
    CFile64概述， 类成员。


    CFile64::SeekToBegin

    void SeekToBegin();
    throw(CFileException);

    备注
    将文件指针的值设置为文件开头。SeekToBegin()等同于Seek(0L, CFile64::begin )。

    示例

    //example for CFile64::SeekToBegin
extern CFile64 file;
file.SeekToBegin();

    另请参阅
    CFile64概述， 类成员。


    CFile64::SeekToEnd

    UINT64 SeekToEnd();
    throw(CFileException);

    返回值
    文件长度（以字节为单位）。

    备注
    将文件指针的值设置为文件的逻辑末尾。SeekToEnd()等同于CFile64::Seek( 0L, CFile64::end )。

    示例

    //example for CFile64::SeekToEnd
extern CFile64 file;
UINT64 lActual = file.SeekToEnd();

    另请参阅
    CFile64概述， 类成员， CFile64::GetLength()， CFile64::Seek()， CFile64::SeekToBegin()。


    CFile64::SetFileName

    void SetFilePath( LPCTSTR lpszNewName);

    参数

    • lpszNewName -- 指向指定新文件名的字符串的指针。

    备注
    调用此函数来指定文件的路径；例如，如果在构造CFile64对象时文件路径不可用，则调用SetFileName()来提供它。

    注意：SetFileName()不会打开或创建文件，它只是将CFile64对象与一个路径名关联起来，然后可以使用该路径名。

    另请参阅
    CFile64概述， 类成员， CFile64::CFile64()， CFile64::GetFileName()。


    CFile64::SetLength

    void SetLength(const UINT64& lNewLen);
    throw(CFileException);

    参数

    • lNewLen -- 文件的目标长度（以字节为单位）。此值可以大于或小于文件的当前长度。文件将相应地扩展或截断。

    备注
    调用此函数来更改文件长度。

    示例

    //example for CFile64::SetLength
extern CFile64 file;
UINT64 lNewLength = 10000;
file.SetLength( lNewLength );

    另请参阅
    CFile64概述， 类成员。


    CFile64::UnlockRange

    void UnlockRange(const UINT64& lPos, const UINT64& lCount);
    throw(CFileException);

    参数

    • dwPos -- 要解锁的字节范围的起始字节偏移量。
    • dwCount -- 要解锁的范围中的字节数。

    备注
    解锁一个打开文件中的字节范围。有关详细信息，请参阅LockRange()成员函数的说明。

    示例

    //example for CFile64::UnlockRange
extern INT64 lPos;
extern INT64 lCount;
extern CFile64 file;
file.UnlockRange( lPos, lCount );

    另请参阅
    CFile64概述， 类成员， CFile64::LockRange()。


    CFile64::Write

    void Write(const void* lpBuf, DWORD dwCount );
    throw(CFileException);

    参数

    • lpBuf -- 指向用户提供的包含要写入文件的数据的缓冲区的指针。
    • dwCount -- 要从缓冲区传输的字节数。

    备注
    将缓冲区中的数据写入与CFile64对象关联的文件。

    Write会因多种情况抛出异常，包括磁盘已满的情况。

    目前此函数只允许读取最多ULONG_MAX（4294967295）个字节，因为Win32只有4GB的地址空间（其中1-2GB对用户模式应用程序不可用）。这只有在Win64 API出现后才能得到解决。

    示例

    //example for CFile64::Write
extern CFile64 CFile64;
char pbuf[100];
CFile64.Write( pbuf, 100 );

    另请参阅
    CFile64概述， 类成员， CFile64::Read()。


    CFile64::operator HANDLE();

    返回值
    已打开文件的操作系统文件句柄。

    备注
    不建议使用operator HANDLE()，而应使用CFile64接口公开的成员函数。

    另请参阅
    CFile64概述， 类成员。



    联系作者

    PJ Naughter
    电子邮件： pjn@indigo..ie
    网站：http://www.naughter.com
    1998年2月11日


    © . All rights reserved.