Back to the WFC main page

CMemoryFile

$Revision: 9 $

---

Description

This class makes memory mapped files easy to use. Memory mapped files are great when you have to access the contents of a file directly. Instead of declaring a big buffer (at least the size of the file) then reading the file into that buffer, mapping the file contents to a pointer is much faster.
Mapping a file to a pointer lets you dereference the pointer as needed and let the operating system handle the retrieval of the bytes from the file. Very cool.

Constructors

CMemoryFile()

Constructs the object.

Data Members

DWORD Size

Holds the same value as GetLength(). This member is exposed for speed only. It is not used internally by the class.

Methods

void Close( void )

Closes the file.

BOOL Flush( void )

Synchronizes the contents of memory with the contents of the physical disk file.

ULONGLONG GetFileLength( void ) const

Returns the length of the Open()'d file. Yes, this returns a 64-bit length.

void GetFilename( CString& filename ) const

Retrieves the name of the file that is mapped. If filename is empty, no file has been opened.

DWORD GetLength( void ) const

Returns the number of bytes that were mapped.

void * GetPointer( void ) const

Returns the pointer to the mapped bytes. If this method returns NULL, it means there is no file mapped.

BOOL Open( LPCTSTR filename,
          UINT open_flags = CFile::modeRead,
          DWORD beginning_at = 0,
          DWORD number_of_bytes_to_map,
          void * desired_address = NULL )
BOOL Open( LPCTSTR filename,
          UINT open_flags = CFile::modeRead,
          ULONGLONG beginning_at = 0,
          DWORD number_of_bytes_to_map,
          void * desired_address = NULL )          

This method is patterend after the Open() method in the MFC CFile class. In it's simplest form, you pass a name of a file and it will open that file in read only mode. This is great for parsing data files. You don't have to worry about the beginning_at value be a special value (like in the call to the MapViewOfFile() API). The other parameters have these meanings:

• open_flags - May be one of the following values:
  • CFile::modeRead - Open the file for read only
  • CFile::modeWrite - Open the file for read/write
  • CFile::modeReadWrite - Open the file for read/write
• beginning_at - The offset into the file of where to start mapping.
• number_of_bytes_to_map - The number of bytes to map. If this parameter is zero, the default is to compute the number of bytes that were mapped. You can call GetLength() to find out how many bytes were mapped.
• desired_address - This is where you ask nicely that the address returned by GetPointer() be this value. Win32 may or may not be able to map the bytes in the file to desired_address. Never count on desired_address actually being used.

Example

#include <wfc.h>
#pragma hdrstop

void test_CMemoryFile( void )
{
   WFCTRACEINIT( TEXT( "test_CMemoryFile()" ) );

   CMemoryFile memory_mapped_file;

   BYTE * pointer = NULL;

   if ( memory_mapped_file.Open( TEXT( "datafile.dat" ) ) == FALSE )
   {
      return;
   }

   pointer = (BYTE *) memory_mapped_file.GetPointer();

   _tprintf( TEXT( "The last byte of the file is %X\n" ),
             pointer[ mempory_mapped_file.GetLength() - 1 ] );
}

API's Used

• CloseHandle
• CreateFileMapping
• FlushViewOfFile
• GetFileSize
• GetLastError
• GetSystemInfo
• InitializeSecurityDescriptor
• MapViewOfFileEx
• SetSecurityDescriptorDacl
• UnmapViewOfFile

---

Copyright, 2000, Samuel R. Blackburn
$Workfile: CMemoryFile.cpp $
$Modtime: 1/17/00 9:07a $