CMemMapFile v1.3

Welcome to CMemMapFile, A freeware MFC class to encapsulate memory mapped files.

Features

Memory mapping is a powerful mechanism Win32 provides to implement shared memory and also to access files though a simple memory pointer without having to implement your own home brewed buffering mechanisms. As an example its as simple as calling

void* lpData = mmf.Open();
CharUpperBuff((char*) lpData, mmf.GetLength());

to convert a file (of any length) to upper case.

Areas where you might find this of interest include very large database files with fixed records, audio processing, string operations and image processing.

The other side of memory mapped files is to implement shared memory. As you will probably know, Win32 puts each process into its own address space, thus making it impossible to pass ordinary pointers across process boundaries. With memory mapped files you get back this very useful mechanism.

This class provides a simple MFC class interface and a simple dialog based application which demonstrates all the functionality of the class.

History

V1.0 (31 March 1998)

• Class now avoids trying to lock the mutex if only read access is required
• User now has the option of specifying whether a file should be mapped with A Null terminator at the end. Can prove helpful when you want to use some of the "C" runtime functions on the pointer returned.

V1.1 (20 April 1998)

• Now uses GetFileSize SDK call instead of GetFileInformationByHandle as a more "reliable" way to determine file length.
• Included TRACE statements to call GetLastError in all places where SDK functions fail

V1.2 (29 May 1998)

• Mapping a file now has the option of making it named or not.

V1.3 (22 October 1998)

• Fixed a bug in a number of calls to CreateMappingName when the classes were being used to share memory.
• New documentation in the form of this HTML file.
• Sample now ships as standard with VC 5 workspace files
• Tidy up of the demo app including:

  Made the amount of text being shared a constant of MAX_EDIT_TEXT instead of hardcoding it to 20 everywhere in the sample.

  Changed where the timer is being created to OnInitDialog

  Tidied up the initialisation sequence in OnInitDialog

  Now using _tcscpy instead of _tcsncpy to ensure array is null terminated

  Fixed resource.h which was causing the resources to fail to compile

  Removed unnecessary symbols from resource.h

  Optimized the way the OnTimer code works to only update the text when it has changed in the MMF. This means that you can type continuously into the edit control.

CMemMapFile Class Members

CMemMapFile
~CMemMapFile
MapFile
MapMemory
MapExistingMemory
Open
Close
UnMap
IsOpen
GetLength
Flush
GetMappingName

CMemMapFile::CMemMapFile

CMemMapFile( );

Remarks

Standard Constructor for the class.

CMemMapFile::~CMemMapFile

~CMemMapFile( );

Remarks

Standard destructor for the class. Calls the UnMap function

CMemMapFile::MapFile

BOOL MapFile(const CString& sFilename, BOOL bReadOnly = FALSE, DWORD dwShareMode = 0, BOOL bAppendNull = FALSE, BOOL bNamed = FALSE);

Return Value

TRUE if the file was successfully mapped otherwise FALSE.

Parameters

sFilename is the filename to memory map

bReadOnly can be set to true if you are not interested in modifying the file

dwShareMode is the share flags to use when calling CreateFile. This may be prove useful if you want to map a file using MMF techniques but allow other processes access to it as read only

bAppendNULL if set to TRUE will add a double null to the end of the file mapping. This may prove useful if you want to treat the data as a null terminated ascii or unicode character array

bNamed determines whether or not you want to make the memory mapped files named. Normally when
you map a file there is no need to do this as the MMF is not being used to share memory

Remarks

Maps a file system file. Note that an attempt to modify a file mapping when it is in read only mode will generate an access violation.

CMemMapFile::MapMemory

BOOL MapMemory(const CString& sName, DWORD dwBytes, BOOL bReadOnly = FALSE);

Return Value

TRUE if the memory was successfully mapped otherwise FALSE.

Parameters

sName is the name to use

dwBytes is the size to map

bReadOnly is as in MapFile.

Remarks

This creates a piece of shared memory.

CMemMapFile::MapExistingMemory

BOOL MapMemory(const CString& sName, DWORD dwBytes, BOOL bReadOnly = FALSE);

Return Value

TRUE if the memory was successfully mapped otherwise FALSE.

Parameters

sName is the name to use

dwBytes is the size to map

bReadOnly is as in MapFile.

Remarks

This function is quite similar to MapMemory except that it fails it the mapping is already created. This function can be used to connect to existing shared memory or where you want to detect if this is the first instance of your program to run.

CMemMapFile::Open

LPVOID Open(DWORD dwTimeout = INFINITE);

Return Value

Pointer to the data as stored in the memory mapped file.

Parameters

dwTimeout The dwTimeout value is the time in milliseconds to wait if the mapping is already opened by another thread or process.

Remarks

Once you have called MapFile, MapMemory or MapExisitingMemory you can call this function to actually get a pointer to the data. Internally the class uses a mutex to synchronise access to the memory so that you do not have to worry about thread synchronisation problems when using the class. . If you use the default value then your thread will be suspended indefinitely if another thread is using the object.

CMemMapFile::Close

BOOL Close();

Remarks

This is the corollary of the Open function and there should be a matching call to Close for each call to Open. After calling close you are free to call Open again to get back the pointer.

CMemMapFile::UnMap

void UnMap();

Remarks

This unmaps the object and releases all the file handles and synchronisation objects. You can consider this function to be the corollary to the Map...() functions. This function is also called in the destructor if you forget to do it yourself.

CMemMapFile::IsOpen

BOOL IsOpen();

Return Value

Returns TRUE if this object is already open otherwise FALSE

CMemMapFile::GetLength

DWORD GetLength();

Return Value

Returns the length of the mapping object. This is the maximum offset in bytes which you can index into the mapping pointer. Overshooting this boundary will generate an access violation. If you have mapped a file, then this will correspond to the file size.

CMemMapFile::Flush

BOOL Flush();

Return Value

Returns TRUE if the flush was successful otherwise FALSE

Remarks

Flushes the mapping object to disk.

CMemMapFile::GetMappingName

CString GetMappingName() const;

Return Value

Returns the name as a CString which this object is known to the OS as.

Usage

Included is a simple dialog based application which demonstrates the 2 main features of memory mapped files, namely mapping a file system file to a pointer and implementation of shared memory. For further details about the example program have a look at the BOOL CTestmemmapApp::InitInstance() function and the CDialog1 member functions both in testmemmap.cpp

To use CMemMapFile in your project simply include memmap.cpp from the test application in your application and #include "memmap.h" in whichever files you want to use the class in.

Contacting the Author

PJ Naughter
Email: pjn@indigo..ie
Web: http://indigo.ie/~pjn
22nd October 1998