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.
Important
This class and its members cannot be used in applications that execute in the Windows Runtime.
Syntax
class CAtlFileMappingBase
Members
Public Constructors
| Name | Description |
|---|---|
| CAtlFileMappingBase::CAtlFileMappingBase | The constructor. |
| CAtlFileMappingBase::~CAtlFileMappingBase | The destructor. |
Public Methods
| Name | Description |
|---|---|
| CAtlFileMappingBase::CopyFrom | Call this method to copy from a file-mapping object. |
| CAtlFileMappingBase::GetData | Call this method to get the data from a file-mapping object. |
| CAtlFileMappingBase::GetHandle | Call this method to return the file handle. |
| CAtlFileMappingBase::GetMappingSize | Call this method to get the mapping size from a file-mapping object. |
| CAtlFileMappingBase::MapFile | Call this method to create a file-mapping object. |
| CAtlFileMappingBase::MapSharedMem | Call this method to create a file-mapping object that permits full access to all processes. |
| CAtlFileMappingBase::OpenMapping | Call this method to return a handle to the file-mapping object. |
| CAtlFileMappingBase::Unmap | Call this method to unmap a file-mapping object. |
Public Operators
| Name | Description |
|---|---|
| CAtlFileMappingBase::operator = | Sets the current file-mapping object to another file-mapping object. |
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.