CMemFile Class
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
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.