CAtlFileMappingBase Class

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CAtlFileMappingBase Class.

This class represents a memory-mapped file.

Syntax

class CAtlFileMappingBase

Members

Public Constructors

Public Methods

Public Operators

Remarks

File mapping is the association of a file's contents with a portion of the virtual address space of a process. This class provides methods for creating file-mapping objects that permit programs to easily access and share data.

For more information, see File Mapping in the Windows SDK.

Requirements

Header: atlfile.h

CAtlFileMappingBase::CAtlFileMappingBase

The constructor.

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

Parameters

orig
The original file-mapping object to copy to create the new object.

Remarks

Creates a new file-mapping object, optionally using an existing object. It is still necessary to call CAtlFileMappingBase::MapFile to open or create the file-mapping object for a particular file.

Example

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

The destructor.

~CAtlFileMappingBase() throw();

Remarks

Frees any resources allocated by the class and calls the CAtlFileMappingBase::Unmap method.

CAtlFileMappingBase::CopyFrom

Call this method to copy from a file-mapping object.

HRESULT CopyFrom(CAtlFileMappingBase& orig) throw();

Parameters

orig
The original file-mapping object to copy from.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

CAtlFileMappingBase::GetData

Call this method to get the data from a file-mapping object.

void* GetData() const throw();

Return Value

Returns a pointer to the data.

CAtlFileMappingBase::GetHandle

Call this method to return a handle to the file-mapping object.

HANDLE GetHandle() throw ();

Return Value

Returns a handle to the file-mapping object.

CAtlFileMappingBase::GetMappingSize

Call this method to get the mapping size from a file-mapping object.

SIZE_T GetMappingSize() throw();

Return Value

Returns the mapping size.

Example

See the example for CAtlFileMappingBase::CAtlFileMappingBase.

CAtlFileMappingBase::MapFile

Call this method to open or create a file-mapping object for the specified file.

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

Parameters

hFile
Handle to the file from which to create a mapping object. hFile must be valid and cannot be set to INVALID_HANDLE_VALUE.

nMappingSize
The mapping size. If 0, the maximum size of the file-mapping object is equal to the current size of the file identified by hFile.

nOffset
The file offset where mapping is to begin. The offset value must be a multiple of the system's memory allocation granularity.

dwMappingProtection
The protection desired for the file view when the file is mapped. See flProtect in CreateFileMapping in the Windows SDK.

dwViewDesiredAccess
Specifies the type of access to the file view and, therefore, the protection of the pages mapped by the file. See dwDesiredAccess in MapViewOfFileEx in the Windows SDK.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

After a file-mapping object has been created, the size of the file must not exceed the size of the file-mapping object; if it does, not all of the file's contents will be available for sharing. For more details, see CreateFileMapping and MapViewOfFileEx in the Windows SDK.

Example

See the example for CAtlFileMappingBase::CAtlFileMappingBase.

CAtlFileMappingBase::MapSharedMem

Call this method to create a file-mapping object that permits full access to all processes.

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

Parameters

nMappingSize
The mapping size. If 0, the maximum size of the file-mapping object is equal to the current size of the file-mapping object identified by szName.

szName
The name of the mapping object.

pbAlreadyExisted
Points to a BOOL value that is set to TRUE if the mapping object already existed.

lpsa
The pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. See lpAttributes in CreateFileMapping in the Windows SDK.

dwMappingProtection
The protection desired for the file view, when the file is mapped. See flProtect in CreateFileMapping in the Windows SDK.

dwViewDesiredAccess
Specifies the type of access to the file view and, therefore, the protection of the pages mapped by the file. See dwDesiredAccess in MapViewOfFileEx in the Windows SDK.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

MapShareMem allows an existing file-mapping object, created by CreateFileMapping, to be shared between processes.

CAtlFileMappingBase::OpenMapping

Call this method to open a named file-mapping object for the specified file.

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

Parameters

szName
The name of the mapping object. If there is an open handle to a file-mapping object by this name and the security descriptor on the mapping object does not conflict with the dwViewDesiredAccess parameter, the open operation succeeds.

nMappingSize
The mapping size. If 0, the maximum size of the file-mapping object is equal to the current size of the file-mapping object identified by szName.

nOffset
The file offset where mapping is to begin. The offset value must be a multiple of the system's memory allocation granularity.

dwViewDesiredAccess
Specifies the type of access to the file view and, therefore, the protection of the pages mapped by the file. See dwDesiredAccess in MapViewOfFileEx in the Windows SDK.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

In debug builds, an assertion error will occur if the input parameters are invalid.

CAtlFileMappingBase::operator =

Sets the current file-mapping object to another file-mapping object.

CAtlFileMappingBase& operator=(CAtlFileMappingBase& orig);

Parameters

orig
The current file-mapping object.

Return Value

Returns a reference to the current object.

CAtlFileMappingBase::Unmap

Call this method to unmap a file-mapping object.

HRESULT Unmap() throw();

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

See UnmapViewOfFile in the Windows SDK for more details.

See Also

CAtlFileMapping Class
Class Overview