CMemFile Class

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

The CFile-derived class that supports memory files.

Syntax

class CMemFile : public CFile  

Members

Public Constructors

Public Methods

Protected Methods

Remarks

These memory files behave like disk files except that the file is stored in RAM rather than on disk. A memory file is useful for fast temporary storage or for transferring raw bytes or serialized objects between independent processes.

CMemFile objects can automatically allocate their own memory or you can attach your own memory block to the CMemFile object by calling Attach. In either case, memory for growing the memory file automatically is allocated in nGrowBytes-sized increments if nGrowBytes is not zero.

The memory block will automatically be deleted upon destruction of the CMemFile object if the memory was originally allocated by the CMemFile object; otherwise, you are responsible for deallocating the memory you attached to the object.

You can access the memory block through the pointer supplied when you detach it from the CMemFile object by calling Detach.

The most common use of CMemFile is to create a CMemFile object and use it by calling CFile member functions. Note that creating a CMemFile automatically opens it: you do not call CFile::Open, which is only used for disk files. Because CMemFile doesn't use a disk file, the data member CFile::m_hFile is not used and has no meaning.

The CFile member functions Duplicate, LockRange, and UnlockRange are not implemented for CMemFile. If you call these functions on a CMemFile object, you will get a CNotSupportedException.

CMemFile uses the run-time library functions malloc, realloc, and free to allocate, reallocate, and deallocate memory; and the intrinsic memcpy to block copy memory when reading and writing. If you'd like to change this behavior or the behavior when CMemFile grows a file, derive your own class from CMemFile and override the appropriate functions.

For more information on CMemFile, see the articles Files in MFC and Memory Management (MFC) and see File Handling in the Run-Time Library Reference.

Inheritance Hierarchy

CObject

CFile

CMemFile

Requirements

Header: afx.h

CMemFile::Alloc

This function is called by CMemFile member functions.

virtual BYTE* Alloc(SIZE_T nBytes);

Parameters

nBytes
Number of bytes of memory to be allocated.

Return Value

A pointer to the memory block that was allocated, or NULL if the allocation failed.

Remarks

Override this function to implement custom memory allocation. If you override this function, you'll probably want to override Free and Realloc as well.

The default implementation uses the run-time library function malloc to allocate memory.

CMemFile::Attach

Call this function to attach a block of memory to CMemFile.

void Attach(
    BYTE* lpBuffer,  
    UINT nBufferSize,  
    UINT nGrowBytes = 0);

Parameters

lpBuffer
Pointer to the buffer to be attached to CMemFile.

nBufferSize
An integer that specifies the size of the buffer in bytes.

nGrowBytes
The memory allocation increment in bytes.

Remarks

This causes CMemFile to use the block of memory as the memory file.

If nGrowBytes is 0, CMemFile will set the file length to nBufferSize. This means that the data in the memory block before it was attached to CMemFile will be used as the file. Memory files created in this manner cannot be grown.

Since the file cannot be grown, be careful not to cause CMemFile to attempt to grow the file. For example, don't call the CMemFile overrides of CFile:Write to write past the end or don't call CFile:SetLength with a length longer than nBufferSize.

If nGrowBytes is greater than 0, CMemFile will ignore the contents of the memory block you've attached. You'll have to write the contents of the memory file from scratch using the CMemFile override of CFile::Write. If you attempt to write past the end of the file or grow the file by calling the CMemFile override of CFile::SetLength, CMemFile will grow the memory allocation in increments of nGrowBytes. Growing the memory allocation will fail if the memory block you pass to Attach wasn't allocated with a method compatible with Alloc. To be compatible with the default implementation of Alloc, you must allocate the memory with the run-time library function malloc or calloc.

CMemFile::CMemFile

The first overload opens an empty memory file.

CMemFile(UINT nGrowBytes = 1024);

 
CMemFile(
    BYTE* lpBuffer,  
    UINT nBufferSize,  
    UINT nGrowBytes = 0);

Parameters

nGrowBytes
The memory allocation increment in bytes.

lpBuffer
Pointer to a buffer that receives information of the size nBufferSize.

nBufferSize
An integer that specifies the size of the file buffer, in bytes.

Remarks

Note that the file is opened by the constructor and that you should not call CFile::Open.

The second overload acts the same as if you used the first constructor and immediately called Attach with the same parameters. See Attach for details.

Example

            CMemFile f; // Ready to use - no Open necessary.

            BYTE * pBuf = (BYTE *)new char [1024];
            CMemFile g(pBuf, 1024, 256);
            // same as CMemFile g; g.Attach(pBuf, 1024, 256);

CMemFile::Detach

Call this function to get a pointer to the memory block being used by CMemFile.

BYTE* Detach();

Return Value

A pointer to the memory block that contains the contents of the memory file.

Remarks

Calling this function also closes the CMemFile. You can reattach the memory block to CMemFile by calling Attach. If you want to reattach the file and use the data in it, you should call CFile::GetLength to get the length of the file before calling Detach. Note that if you attach a memory block to CMemFile so that you can use its data ( nGrowBytes == 0), then you won't be able to grow the memory file.

CMemFile::Free

This function is called by CMemFile member functions.

virtual void Free(BYTE* lpMem);

Parameters

lpMem
Pointer to the memory to be deallocated .

Remarks

Override this function to implement custom memory deallocation. If you override this function, you'll probably want to override Alloc and Realloc as well.

CMemFile::GrowFile

This function is called by several of the CMemFile member functions.

virtual void GrowFile(SIZE_T dwNewLen);

Parameters

dwNewLen
New size of the memory file.

Remarks

You can override it if you want to change how CMemFile grows its file. The default implementation calls Realloc to grow an existing block (or Alloc to create a memory block), allocating memory in multiples of the nGrowBytes value specified in the constructor or Attach call.

CMemFile::Memcpy

This function is called by the CMemFile overrides of CFile::Read and CFile::Write to transfer data to and from the memory file.

virtual BYTE* Memcpy(
    BYTE* lpMemTarget,  
    const BYTE* lpMemSource,  
    SIZE_T nBytes);

Parameters

lpMemTarget
Pointer to the memory block into which the source memory will be copied.

lpMemSource
Pointer to the source memory block.

nBytes
Number of bytes to be copied.

Return Value

A copy of lpMemTarget.

Remarks

Override this function if you want to change the way that CMemFile does these memory copies.

CMemFile::Realloc

This function is called by CMemFile member functions.

virtual BYTE* Realloc(
    BYTE* lpMem,  
    SIZE_T nBytes);

Parameters

lpMem
A pointer to the memory block to be reallocated.

nBytes
New size for the memory block.

Return Value

A pointer to the memory block that was reallocated (and possibly moved), or NULL if the reallocation failed.

Remarks

Override this function to implement custom memory reallocation. If you override this function, you'll probably want to override Alloc and Free as well.

See Also

CFile Class
Hierarchy Chart