CAtlFile 类

  • 项目

此类围绕 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
共享模式。 请参阅 CreateFile 中的 dwShareMode。

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

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

lpsa
安全属性。 请参阅 CreateFile 中的 lpSecurityAttributes。

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

返回值

如果成功，则返回 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
传送的字节数。 请参阅 GetOverlappedResult 中的 lpNumberOfBytesTransferred。

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

返回值

如果成功，则返回 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 类