CMemMapFile v1.52 An MFC class to encapsulate Memory Mapped Files

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(static_cast<LPSTR>(lpData), static_cast<DWORD>(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.

The enclosed zip file contains the CMemMapFile source code and a simple dialog based application which demonstrates all the functionality of the class. 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

Copyright

• You are allowed to include the source code in any product (commercial, shareware, freeware or otherwise) when your product is released in binary form.
• You are allowed to modify the source code in any way you want except you cannot modify the copyright details at the top of each module.
• If you want to distribute source code with your application, then you are only allowed to distribute versions released by the author. This is to maintain a single distribution point for the source code.

Updates

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 a 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.

V1.4 (30 March 1999)

• Minor updates to the style of the help file.
• Code is now UNICODE compliant and build configurations are provided.
• Code now supports growable memory mapped files as provided with Windows 2000 and NTFS 5 volumes.
• Addition of accessor functions for file handle and file mapping handle

V1.41 (21 April 1999)

• Added code to work around a Windows bug where you try to memory map a zero length file on Windows 95 or 98.

V1.42 (24 March 2000)

• Fixed a simple typo problem in a TRACE statement when compiled for UNICODE

V1.43 (7 March 2001)

• Updated copyright information.
• Fixed problem where mutex was not being locked when read only access to the memory mapped file was desired. Access to the MMF should be synchronised irrespective of the access mode.

V1.44 (4 April 2001)

• Now supports passing in a security descriptor to MapFile and MapMemory
• Now supports opening a specified portion of a file, rather than always mapping all of the file

V1.45 (5 October 2003)

• Updated copyright details.
• Fixed a small typo in the description of the FSCTL_SET_SPARSE IOCTL. Thanks to amores perros for reporting this.
• Fixed a minor tab indentation problem at the start of the MapFile method. Again thanks to amores perros for reporting this.
• Removed the unnecessary AssertValid function. Again thanks to amores perros for reporting this.

V1.46 (17 November 2003)

• Fixed a memory leak in UnMap as reported by Bart Duijndam using "Memory Validator". The memory leak may in fact not be real, but the code change avoids the reported problem.

V1.47 (6 June 2004)

• Fixed an issue in MapHandle where the wrong value was sent to CreateFileMapping. This issue only occurs when you are not mapping the whole of a file, but instead decide to perform the mapping a chunk at a time. Thanks to Nicolas Stohler for reporting this problem.
• Removed the AppendNull option as it is incompatible with general use of memory mapped files.
• Reviewed all the TRACE statements throughout the class
• Added ASSERT validation at the top of functions which modify member variables
• Failing to create mutex in MapHandle and MapExistingMemory not fails the function

V1.48 (23 December 2004)

• Removed unnecessary include of winioctl.h header file.
• Fixed a problem with the declaration of the FSCTL_SET_SPARSE macro which is used in the support of growable MMF. With the VC6 WinIOCTL.h, the macro generates the value 0x000980C4, but the correct value for the DeviceIoControl function to enable the sparse file option is 0x000900C4. Thanks to a posting on CodeProject for pointing out this problem.
• Optimized CMemMapFile::CreateMappingName by now using CString::Replace.
• Addition of a bInheritHandle parameter to MapExistingMemory.
• Fixed a bug in the handling of calls to GetFileSize()
• Removed unnecessary check to verify that mapping size is greater than 4GB since CreateFileMapping will do this for us.
• Updated sample app to use a sample "input.txt" file for demonstration purposes instead of using "c:\config.sys"
• Code now uses unsigned __int64 for specifying indexes and lengths for memory mapping. This should allow the code to be easily used to map > 4GB on 64 bit versions of Windows.
• Tidied up some of the ASSERT code at the top of each key function in the class.

V1.49 (30 April 2005)

• Removed derivation from CObject MFC class. In fact the class can now operate entirely independently of MFC.
• Destructor is now virtual.
• Fixed a bug where the mutex name which is used to synchronize access to the MMF's data could by default have the same name for multiple MMF's.
• CreateMappingName and CreateMutexName methods are now virtual

V1.50 (2 May 2006)

• Updated the copyright details in the modules.
• Updated the documentation to use the same style as the web site.
• Addition of a CMEMMAPFILE_EXT_CLASS macro to allow the class to be easily incorporated into an extension dll.
• The sample app now uses filenames without "(" or ")" characters in their filenames. Thanks to Andrew MacGinitie for reporting this issue.
• Fixed a bug in the sample app where it reports the wrong filename when doing the lowercase conversion. Again thanks to Andrew MacGinitie for reporting this issue.
• Fixed an issue in the download where the sample file called "input.txt" is now provided out of the box. Again thanks to Andrew MacGinitie for reporting this issue.
• Fixed an issue in the sample app when the code is compiled with /Wp64

V1.51 (7 July 2006)

• Code now uses newer C++ style casts instead of C style casts.
• The code now requires the Platform SDK if compiled using VC 6.
• Updated code to compile cleanly using VC 2005.

V1.52 (16 August 2008)

• Updated copyright details
• Code now compiles cleanly using Code Analysis (/analyze)
• Updated code to compile correctly using _ATL_CSTRING_EXPLICIT_CONSTRUCTORS define
• The code now only supports VC 2005 or later.
• Removed VC 6 style AppWizard comments from the code.
• Updated the code to correctly handle "Global\" and "Local\" prefixes which can be included with any Win32 Named object. Thanks to Gert Rijs for reporting this bug. To achieve this the parameters to the MapFile method has been reworked. This function now takes a pszMappingName which allows client code to explicitly specify the mapping name
• The mutex name use to serialize access to the contents of the memory mapped file is now explicitly provided as a external parameter to the class.
• MapExistingMemory now has a LPSECURITY_ATTRIBUTES parameter