About

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

Note: The Maxon API 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 (Cinema API).

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