About

Using MemoryFileStruct one can read/write from/into memory using a file class.

Note: The MAXON API ALIASES equivalent is maxon::IoMemoryInterface.

Typical use cases:

Accessing memory like a file, basically a BaseFile or a HyperFile in memory.
Compress or encrypt file content (e.g. keep an image in JPEG format in memory).
Initialize a BaseBitmap from memory.
Transfer arbitrary GeListNode derived entities (e.g. BaseObject, BaseMaterial, BaseContainer,...) via a network connection.

A general example on writing into a HyperFile in memory:

 // This example writes some data into memory and accesses the raw memory afterwards.
 
 AutoAlloc<HyperFile> hf;
 AutoAlloc<MemoryFileStruct> mfs;
 if (hf == nullptr || mfs == nullptr)
 return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
 // By setting the write mode of the filename, it will point to a file in memory.
 Filename fn;
 fn.SetMemoryWriteMode(mfs);
 // DO NOT use fn.SetFile() or fn.SetDirectory()
 
 // Open a HyperFile in memory and write some data into it.
 if (!hf->Open(0, fn, FILEOPEN::WRITE, FILEDIALOG::NONE))
 return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
 hf->WriteInt32(123);
 hf->WriteString("foo"_s);
 hf->WriteString("bar"_s);
 hf->WriteInt32(456);
 // Close() is explicitly needed here, as the completed file is accessed a few lines below by GetData().
 hf->Close();
 
 // Get the raw data of the HyperFile and do something with it.
 void* rawData = nullptr;
 Int rawDataSize = 0;
 
 mfs->GetData(rawData, rawDataSize, false);
 
 // ... do something with rawData...

This is how one can easily transfer an object (or a complete hierarchy) via network:

 // This example demonstrates how to send an object (or a hierarchy of objects) over a network connection.
 
 BaseObject* const op = doc->GetActiveObject();
 if (op == nullptr)
 return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
 // By setting the write mode of the filename, it will point to a file in memory.
 Filename fn;
 AutoAlloc<MemoryFileStruct> mfs;
 if (mfs == nullptr)
 return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
 // No actual name needs to be set, switching mode is enough.
 fn.SetMemoryWriteMode(mfs);
 // DO NOT use fn.SetFile() or fn.SetDirectory()
 
 // Write the object(s) into the HyperFile in memory.
 if (FILEERROR::NONE != WriteHyperFile(doc, op, fn, 0))
 return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
 // Now, get the pointer to the HyperFile in memory and its size.
 void* rawData = nullptr;
 Int rawDataSize = 0;
 // Note: Pay special attention to the last parameter, defining the ownership of the memory block.
 mfs->GetData(rawData, rawDataSize, false);
 
 // ... Send data (rawData, rawDataSize) via for example a NetworkIpConnection...
 SendToNetwork(rawData, rawDataSize) iferr_return;

 // This example demonstrates how to receive an object (or a hierarchy of objects) from a network connection.
 
 // ... receive data from an NetworkIpConnection, we get a pointer to the data and the size of the data...
 void* rawData = nullptr;
 Int rawDataSize = 0;
 ReceiveFromNetwork(rawData, rawDataSize); // custom helper function
 if (!rawData || rawDataSize == 0)
 return maxon::OK; // nothing received
 
 // By setting the read mode of the filename, it will point to a file in memory.
 // No actual name needs to be set, switching mode is enough.
 Filename fn;
 fn.SetMemoryReadMode(rawData, rawDataSize, false);
 // DO NOT use fn.SetFile() or fn.SetDirectory()
 
 // Read object(s) from the HyperFile in memory.
 AutoAlloc<BaseObject> op { Onull };
 if (op == nullptr)
 return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
 String error;
 if (FILEERROR::NONE != ReadHyperFile(doc, op, fn, 0, &error))
 return maxon::UnknownError(MAXON_SOURCE_LOCATION);
 
 // Insert the object(s) into the active document.
 doc->InsertObject(op.Release(), nullptr, nullptr, false);

Allocation/Deallocation

MemoryFileStruct objects are created with the usual tools, see Entity Creation and Destruction Manual (Classic).

MemoryFileStruct::Alloc(): Allocates a memory file.
MemoryFileStruct::Free(): Destructs memory files allocated with Alloc().

Writing Data to a File in Memory and Accessing the Raw Data

Allocate a MemoryFileStruct.
Set a Filename to memory write mode via Filename::SetMemoryWriteMode().
DO NOT set an actual filename via functions like e.g. Filename::SetFile().
Open the file as usual via BaseFile::Open() or HyperFile::Open() with the above Filename.
Simply write into the file as usual.
Close the file.
Afterwards the raw data of the file can be accessed via MemoryFileStruct::GetData().
MemoryFileStruct::GetData(): Gets the data previously written to the memory file.

Reading Data From a File in Memory

Set a Filename to memory read mode via Filename::SetMemoryReadMode(), pointing it to data in memory.
DO NOT set an actual filename via functions like e.g. Filename::SetFile().
Open the file as usual via BaseFile::Open() or HyperFile::Open() with the above Filename.
Simply read data from the file as usual.
Close the file.

Table of Contents

About

Allocation/Deallocation

Writing Data to a File in Memory and Accessing the Raw Data

Reading Data From a File in Memory

Further Reading