CAtlFileMappingBase 类

  • 项目

此类表示内存映射文件。

重要

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

语法

class CAtlFileMappingBase

成员

公共构造函数

名称 描述
CAtlFileMappingBase::CAtlFileMappingBase 构造函数。
CAtlFileMappingBase::~CAtlFileMappingBase 析构函数。

公共方法

名称 描述
CAtlFileMappingBase::CopyFrom 调用此方法以从文件映射对象进行复制。
CAtlFileMappingBase::GetData 调用此方法以从文件映射对象获取数据。
CAtlFileMappingBase::GetHandle 调用此方法可返回文件句柄。
CAtlFileMappingBase::GetMappingSize 调用此方法以从文件映射对象获取映射大小。
CAtlFileMappingBase::MapFile 调用此方法可创建文件映射对象。
CAtlFileMappingBase::MapSharedMem 调用此方法可创建允许对所有进程进行完全访问的文件映射对象。
CAtlFileMappingBase::OpenMapping 调用此方法可返回文件映射对象的句柄。
CAtlFileMappingBase::Unmap 调用此方法可取消映射文件映射对象。

公共运算符

“属性” 描述
CAtlFileMappingBase::operator = 将当前文件映射对象设置为另一个文件映射对象。

备注

文件映射是指将某个文件的内容与某个进程的部分虚拟地址空间相关联。 此类提供用于创建文件映射对象的方法，这些对象允许程序轻松访问和共享数据。

有关详细信息，请参阅 Windows SDK 中的文件映射。

要求

头文件：atlfile.h

CAtlFileMappingBase::CAtlFileMappingBase

构造函数。

CAtlFileMappingBase(CAtlFileMappingBase& orig);
CAtlFileMappingBase() throw();

参数

orig
原始文件映射对象，可以通过复制来创建新对象。

备注

可以选择使用现有对象创建新的文件映射对象。 仍需要调用 CAtlFileMappingBase::MapFile 来打开或创建特定文件的文件映射对象。

示例

int OpenMyFileMap()
{
   // Create the file-mapping object.
   CAtlFileMappingBase myFileMap;

   // Create a file.
   CAtlFile myFile;
   myFile.Create(_T("myMapTestFile"),
      GENERIC_READ|GENERIC_WRITE|STANDARD_RIGHTS_ALL,
      FILE_SHARE_READ|FILE_SHARE_WRITE,
      OPEN_ALWAYS);

   // The file handle.
   HANDLE hFile = (HANDLE)myFile;

   // Test the file has opened successfully.
   ATLASSERT(hFile != INVALID_HANDLE_VALUE);

   // Open the file for file-mapping.
   // Must give a size as the file is zero by default.
   if (myFileMap.MapFile(hFile,
      1024,
      0,
      PAGE_READWRITE,
      FILE_MAP_READ) != S_OK)
   {
      CloseHandle(hFile);
      return 0;
   }

   // Confirm the size of the mapping file.
   ATLASSERT(myFileMap.GetMappingSize() == 1024);

   // Now the file-mapping object is open, a second
   // process could access the filemap object to exchange
   // data.

   return 0;
}

CAtlFileMappingBase::~CAtlFileMappingBase

析构函数。

~CAtlFileMappingBase() throw();

备注

释放类分配的任何资源，并调用 CAtlFileMappingBase::Unmap 方法。

CAtlFileMappingBase::CopyFrom

调用此方法以从文件映射对象进行复制。

HRESULT CopyFrom(CAtlFileMappingBase& orig) throw();

参数

orig
要从中进行复制的原始文件映射对象。

返回值

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

CAtlFileMappingBase::GetData

调用此方法以从文件映射对象获取数据。

void* GetData() const throw();

返回值

返回指向数据的指针。

CAtlFileMappingBase::GetHandle

调用此方法可返回文件映射对象的句柄。

HANDLE GetHandle() throw ();

返回值

返回文件映射对象的句柄。

CAtlFileMappingBase::GetMappingSize

调用此方法以从文件映射对象获取映射大小。

SIZE_T GetMappingSize() throw();

返回值

返回映射大小。

示例

请参阅 CAtlFileMappingBase::CAtlFileMappingBase 的示例。

CAtlFileMappingBase::MapFile

调用此方法可打开或创建指定文件的文件映射对象。

HRESULT MapFile(
    HANDLE hFile,
    SIZE_T nMappingSize = 0,
    ULONGLONG nOffset = 0,
    DWORD dwMappingProtection = PAGE_READONLY,
    DWORD dwViewDesiredAccess = FILE_MAP_READ) throw();

参数

hFile
要从中创建映射对象的文件的句柄。 hFile 必须有效，不能设置为 INVALID_HANDLE_VALUE。

nMappingSize
映射大小。 如果为 0，则文件映射对象的最大大小等于 hFile 标识的文件的当前大小。

nOffset
映射开始处的文件偏移量。 偏移值必须是系统的内存分配粒度的倍数。

dwMappingProtection
映射文件时文件视图所需的保护。 请参阅 Windows SDK 的 CreateFileMapping 中的 flProtect。

dwViewDesiredAccess
指定对文件视图的访问的类型，从而指定对文件所映射的页面的保护。 请参阅 Windows SDK 的 MapViewOfFileEx 中的 dwDesiredAccess。

返回值

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

注解

创建文件映射对象后，文件的大小不得超过文件映射对象的大小；如果超过，则并非所有文件内容都可用于共享。 有关详细信息，请参阅 Windows SDK 中的 CreateFileMapping 和 MapViewOfFileEx。

示例

请参阅 CAtlFileMappingBase::CAtlFileMappingBase 的示例。

CAtlFileMappingBase::MapSharedMem

调用此方法可创建允许对所有进程进行完全访问的文件映射对象。

HRESULT MapSharedMem(
    SIZE_T nMappingSize,
    LPCTSTR szName,
    BOOL* pbAlreadyExisted = NULL,
    LPSECURITY_ATTRIBUTES lpsa = NULL,
    DWORD dwMappingProtection = PAGE_READWRITE,
    DWORD dwViewDesiredAccess = FILE_MAP_ALL_ACCESS) throw();

参数

nMappingSize
映射大小。 如果为 0，则文件映射对象的最大大小等于 szName 标识的文件映射对象的当前大小。

szName
映射对象的名称。

pbAlreadyExisted
如果映射对象已存在，则指向设置为 TRUE 的 BOOL 值。

lpsa
指向 SECURITY_ATTRIBUTES 结构的指针，此结构确定返回的句柄是否可由子进程继承。 请参阅 Windows SDK 的 CreateFileMapping 中的 lpAttributes。

dwMappingProtection
映射文件时文件视图所需的保护。 请参阅 Windows SDK 的 CreateFileMapping 中的 flProtect。

dwViewDesiredAccess
指定对文件视图的访问的类型，从而指定对文件所映射的页面的保护。 请参阅 Windows SDK 的 MapViewOfFileEx 中的 dwDesiredAccess。

返回值

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

注解

MapShareMem 允许在进程之间共享由 CreateFileMapping 创建的现有文件映射对象。

CAtlFileMappingBase::OpenMapping

调用此方法可打开指定文件的命名文件映射对象。

HRESULT OpenMapping(
    LPCTSTR szName,
    SIZE_T nMappingSize,
    ULONGLONG nOffset = 0,
    DWORD dwViewDesiredAccess = FILE_MAP_ALL_ACCESS) throw();

参数

szName
映射对象的名称。 如果某个使用此名称的文件映射对象有一个打开的句柄，并且映射对象上的安全描述符与 dwViewDesiredAccess 参数不冲突，则打开操作会成功。

nMappingSize
映射大小。 如果为 0，则文件映射对象的最大大小等于 szName 标识的文件映射对象的当前大小。

nOffset
映射开始处的文件偏移量。 偏移值必须是系统的内存分配粒度的倍数。

dwViewDesiredAccess
指定对文件视图的访问的类型，从而指定对文件所映射的页面的保护。 请参阅 Windows SDK 的 MapViewOfFileEx 中的 dwDesiredAccess。

返回值

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

注解

在调试版本中，如果输入参数无效，将发生断言错误。

CAtlFileMappingBase::operator =

将当前文件映射对象设置为另一个文件映射对象。

CAtlFileMappingBase& operator=(CAtlFileMappingBase& orig);

参数

orig
当前文件映射对象。

返回值

返回对当前对象的引用。

CAtlFileMappingBase::Unmap

调用此方法可取消映射文件映射对象。

HRESULT Unmap() throw();

返回值

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

注解

有关更多详细信息，请参阅 Windows SDK 中的 UnmapViewOfFile。

另请参阅

CAtlFileMapping 类
类概述