通过

CAtlFile 类

注释

活动模板库（ATL）将继续受到支持。 但是，我们不再添加功能或更新文档。

此类围绕 Windows 文件处理 API 提供精简包装器。

重要

无法在 Windows 运行时中执行的应用程序中使用此类及其成员。

语法

class CAtlFile : public CHandle

成员

公共构造函数

名称 描述
CAtlFile::CAtlFile 构造函数。

公共方法

名称 描述
CAtlFile::Create 调用此方法以创建或打开文件。
CAtlFile::Flush 调用此方法可清除文件的缓冲区，导致所有缓冲数据都被写入文件中。
CAtlFile::GetOverlappedResult 调用此方法可获取在文件上进行的重叠操作的结果。
CAtlFile::GetPosition 调用此方法可从文件中获取当前文件指针位置。
CAtlFile::GetSize 调用此方法以获取文件的大小（以字节为单位）。
CAtlFile::LockRange 调用此方法可锁定文件中的某个区域，以防止其他进程访问它。
CAtlFile::Read 调用此方法，从文件指针指示的位置开始读取文件中的数据。
CAtlFile::Seek 调用此方法可移动文件的文件指针。
CAtlFile::SetSize 调用此方法可设置文件的大小。
CAtlFile::UnlockRange 调用此方法可解锁文件的某个区域。
CAtlFile::Write 调用此方法，从文件指针指示的位置开始将数据写入文件中。

受保护的数据成员

名称 描述
CAtlFile::m_pTM 指向 CAtlTransactionManager 对象的指针

备注

使用此类的前提是，文件处理需求相对简单，但需要的抽象超出 Windows API 所提供的，无需包含 MFC 依赖项。

继承层次结构

CHandle

CAtlFile

要求

头文件：atlfile.h

CAtlFile::CAtlFile

构造函数。

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

参数

文件
文件对象。

hFile
文件句柄。

pTM
指向 CAtlTransactionManager 对象的指针

备注

复制构造函数会将文件句柄的所有权从原始的 CAtlFile 对象转移到新构造的对象。

CAtlFile::Create

调用此方法以创建或打开文件。

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

参数

szFilename
文件名。

dwDesiredAccess
所需访问权限。 请参阅 Windows SDK 的 CreateFile 中的 dwDesiredAccess。

dwShareMode
共享模式。 请参阅 中的 dwShareModeCreateFile。

dwCreationDisposition
创建处置。 请参阅 中的 dwCreationDispositionCreateFile。

dwFlagsAndAttributes
标志和属性。 请参阅 中的 dwFlagsAndAttributesCreateFile。

lpsa
安全属性。 请参阅 中的 lpSecurityAttributesCreateFile。

hTemplateFile
模板文件。 请参阅 中的 hTemplateFileCreateFile。

返回值

如果成功，则返回 S_OK；否则返回错误 HRESULT。

备注

调用 CreateFile 来创建或打开文件。

CAtlFile::Flush

调用此方法可清除文件的缓冲区，导致所有缓冲数据都被写入文件中。

HRESULT Flush() throw();

返回值

如果成功，则返回 S_OK；否则返回错误 HRESULT。

备注

调用 FlushFileBuffers 将缓冲的数据刷新到文件。

CAtlFile::GetOverlappedResult

调用此方法可获取在文件上进行的重叠操作的结果。

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

参数

pOverlapped
重叠的结构。 请参阅 Windows SDK 的 GetOverlappedResult 中的 lpOverlapped。

dwBytesTransferred
传送的字节数。 请参阅 中的 lpNumberOfBytesTransferredGetOverlappedResult。

bWait
等待选项。 请参阅 中的 bWaitGetOverlappedResult。

返回值

如果成功，则返回 S_OK；否则返回错误 HRESULT。

备注

调用 GetOverlappedResult 可获取对文件执行的重叠操作的结果。

CAtlFile::GetPosition

调用此方法可获取当前文件指针位置。

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

参数

nPos
位置（以字节表示）。

返回值

如果成功，则返回 S_OK；否则返回错误 HRESULT。

备注

调用 SetFilePointer 可获取当前文件指针位置。

CAtlFile::GetSize

调用此方法以获取文件的大小（以字节为单位）。

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

参数

nLen
文件中的字节数。

返回值

如果成功，则返回 S_OK；否则返回错误 HRESULT。

备注

调用 GetFileSize 可获取文件的大小（以字节为单位）。

CAtlFile::LockRange

调用此方法可锁定文件中的某个区域，以防止其他进程访问它。

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

参数

nPos
文件中应开始进行锁定的位置。

nCount
要锁定的字节范围的长度。

返回值

如果成功，则返回 S_OK；否则返回错误 HRESULT。

备注

调用 LockFile 可锁定文件中的区域。 锁定文件中的字节将阻止其他进程访问这些字节。 可以锁定文件的多个区域，但不允许使用重叠区域。 使用 CAtlFile::UnlockRange 解锁区域时，字节范围必须与之前锁定的区域完全对应。 LockRange 不会合并相邻区域；如果有两个相邻的锁定区域，则必须单独解锁每个区域。

CAtlFile::m_pTM

指向 CAtlTransactionManager 对象的指针。

CAtlTransactionManager* m_pTM;

备注

CAtlFile::Read

调用此方法，从文件指针指示的位置开始读取文件中的数据。

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

参数

pBuffer
指向缓冲区的指针，该缓冲区将接收从文件读取的数据。

nBufSize
缓冲区大小（以字节为单位）。

nBytesRead
读取的字节数。

pOverlapped
重叠的结构。 请参阅 Windows SDK 的 ReadFile 中的 lpOverlapped。

pfnCompletionRoutine
完成例程。 请参阅 Windows SDK 的 ReadFileEx 中的 lpCompletionRoutine。

返回值

如果成功，则返回 S_OK；否则返回错误 HRESULT。

备注

前三个窗体调用 ReadFile，最后一个窗体调用 ReadFileEx 从文件读取数据。 使用 CAtlFile::Seek 移动文件指针。

CAtlFile::Seek

调用此方法可移动文件的文件指针。

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

参数

nOffset
从 dwFrom 提供的起点算起的偏移量。

dwFrom
起点（FILE_BEGIN、FILE_CURRENT 或 FILE_END）。

返回值

如果成功，则返回 S_OK；否则返回错误 HRESULT。

备注

调用 SetFilePointer 可移动文件指针。

CAtlFile::SetSize

调用此方法可设置文件的大小。

HRESULT SetSize(ULONGLONG nNewLen) throw();

参数

nNewLen
文件的新长度（以字节为单位）。

返回值

如果成功，则返回 S_OK；否则返回错误 HRESULT。

备注

调用 SetFilePointer 和 SetEndOfFile 可设置文件的大小。 返回时，文件指针位于文件末尾。

CAtlFile::UnlockRange

调用此方法可解锁文件的某个区域。

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

参数

nPos
文件中应开始进行解锁的位置。

nCount
要解锁的字节范围的长度。

返回值

如果成功，则返回 S_OK；否则返回错误 HRESULT。

备注

调用 UnlockFile 可解锁文件的某个区域。

CAtlFile::Write

调用此方法，从文件指针指示的位置开始将数据写入文件中。

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

参数

pBuffer
缓冲区，其中包含要写入到文件中的数据。

nBufSize
要从缓冲区传输的字节数。

pOverlapped
重叠的结构。 请参阅 Windows SDK 的 WriteFile 中的 lpOverlapped。

pfnCompletionRoutine
完成例程。 请参阅 Windows SDK 的 WriteFileEx 中的 lpCompletionRoutine。

pnBytesWritten
已写入的字节数。

返回值

如果成功，则返回 S_OK；否则返回错误 HRESULT。

备注

前三个窗体调用 WriteFile，最后一个窗体调用 WriteFileEx 将数据写入文件。 使用 CAtlFile::Seek 移动文件指针。

另请参阅

Marquee 示例
类概述
CHandle 类

  • Last updated on