Edit

Share via

CMemFile Class

  • Article

The CFile-derived class that supports memory files.

Syntax

class CMemFile : public CFile

Members

Public Constructors

Name Description
CMemFile::CMemFile Constructs a memory file object.

Public Methods

Name Description
CMemFile::Attach Attaches a block of memory to CMemFile.
CMemFile::Detach Detaches the block of memory from CMemFile and returns a pointer to the block of memory detached.
CMemFile::GetBufferPtr Get or write to the memory buffer that backs a memory file.

Protected Methods

Name Description
CMemFile::Alloc Override to modify memory allocation behavior.
CMemFile::Free Override to modify memory deallocation behavior.
CMemFile::GrowFile Override to modify behavior when growing a file.
CMemFile::Memcpy Override to modify memory copy behavior when reading and writing files.
CMemFile::Realloc Override to modify memory reallocation behavior.

Remarks

These memory files behave like disk files except the file is stored in RAM rather than on disk. A memory file is useful for:

  • fast temporary storage
  • transferring raw bytes between independent processes
  • transferring 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 isn't 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. Creating a CMemFile automatically opens it: you don't call CFile::Open, which is only used for disk files. Because CMemFile doesn't use a disk file, the data member CFile::m_hFile isn't used.

The CFile member functions Duplicate, LockRange, and UnlockRange are not implemented for CMemFile. If you call these functions on a CMemFile object, you'll 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 can't be grown.

Since the file can't 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

The file is opened by the constructor. Don't 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. If you attach a memory block to CMemFile so that you can use its data ( nGrowBytes == 0), then you can't 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::GetBufferPtr

Get or write to the memory buffer that backs a memory file.

virtual UINT GetBufferPtr(
    UINT nCommand,
    UINT nCount = 0,
    void** ppBufStart = NULL,
    void** ppBufMax = NULL
);

Parameters

nCommand
The bufferCommand to carry out (bufferCheck, bufferCommit, bufferRead, or bufferWrite ).

nCount
Depending on nCommand, the number of bytes in the buffer to read, write, or commit. When reading from the buffer, specify -1 to return a buffer from the current position to the end of the file.

ppBufStart
[out] The start of the buffer. Must be NULL when nCommand is bufferCommit.

ppBufMax
[out] The end of the buffer. Must be NULL when nCommand is bufferCommit.

Return Value

command value Return value
buffercheck Returns bufferDirect if direct buffering is supported, otherwise 0.
bufferCommit Returns 0
bufferRead or bufferWrite Returns the number of bytes in the returned buffer space. ppBufStart and ppBufMax point to the start and end of the read/written buffer.

Remarks

The current position in the memory buffer (m_nPosition) is advanced in the following ways, depending on nCommand:

nCommand buffer position
bufferCommit The current position advances by the size of the committed buffer.
bufferRead The current position advances by the size of the read buffer.

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