HyperFile Manual

Table of Contents

• About
• Access
• Allocation/Deallocation
• Open and Close
• Read and Write
  • A Typical Write Access
  • A Typical Read Access
  • Value
  • Char
  • String
  • Filename
  • Bool
  • Integer
  • Float
  • Vector
  • Matrix
  • Arrays
  • GeData
  • BaseContainer
  • BaseTime
  • BaseBitmap
  • Raw Memory
  • Uuid
  • Chunk
• Utility
  • Error
  • File Version
  • Other HyperFile Related Functions
• Further Reading

About

HyperFile is a class to read and write data to a file on disk. This class is for example used to store Cinema 4D scenes, but can also be used to create individual files storing Cinema 4D data types. A HyperFile can not be used to create arbitrary files (like e.g. text files) as all data stored in a HyperFile is prefixed with a value header describing the stored data, see BaseFile Manual on Byte Access instead.

HyperFile class makes many things easier compared to BaseFile class (e.g. one does not need to care about byte order), while sacrificing some of the power of the low-level functions provided there (no byte access possible, no repositioning of the read/write pointer). Most advantageous compared to BaseFile is the file versioning and chunk handling.

A HyperFile is always read (and also written) from the beginning of the file and the handling of the read/write pointer is handled completely internally. In theory replacing of parts of the data in a HyperFile is possible, but definitely not recommended, as good knowledge of the internal structure is needed to not corrupt the file.

Note

To delete a file see GeFKill() and the accompanying File Functions Manual.

Besides the code snippets shown on this page, there's also the hyperfile_objectdata example in example.main.

Throughout this page the code snippets use a helper function PrintFileError().

This looks like so:

// Small helper function used in HyperFile code snippets below.
// Depending on verbose parameter a file error (if any) will also be decoded to a human readable string.
// Can also be used, when there's no HyperFile (e.g. HyperFile allocation failed), then only the filename will be used.
// It returns true, if there was no error, otherwise false.
// In this way it can be used in snippets to directly return from the calling function.
static maxon::Result<void> PrintFileError(const Filename& fn, const HyperFile* const file, const maxon::String& errText, Bool verbose = false);
static maxon::Result<void> PrintFileError(const Filename& fn, const HyperFile* const file, const maxon::String& errText, Bool verbose/*= false*/)
{
  if (!file)
    return maxon::NullptrError(MAXON_SOURCE_LOCATION);
 
  if (verbose)
  {
    return FileErrorToString(file); // FileErrorToString() is a custom function.
  }
  else
  {
    const FILEERROR err = file->GetError();
    maxon::String   errString = "Error ("_s + maxon::String::IntToString((Int)err) + "): "_s + errText + ": "_s + maxon::String(fn.GetString());
 
    if (err != FILEERROR::NONE)
    {
      if (err == FILEERROR::OUTOFMEMORY)
        return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION, errString);
      else if (err == FILEERROR::UNKNOWN_VALUE)
        return maxon::UnknownError(MAXON_SOURCE_LOCATION, errString);
      else
        return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, errString);
    }
  }
 
  ApplicationOutput("No error: &"_s, maxon::String(fn.GetString()));
  return maxon::OK;
}

Access

A HyperFile argument is typically provided in NodeData::Read() and NodeData::Write() functions. See NodeData::Read() / NodeData::Write() Manual.

Allocation/Deallocation

HyperFile objects are created with the usual tools, see Entity Creation and Destruction Manual (Cinema API).

• HyperFile::Alloc(): Creates a HyperFile object.
• HyperFile::Free(): Destroys a HyperFile object.

Open and Close

After allocating a HyperFile object HyperFile::Open() needs to be called to bind it to a file in the filesystem (either an existing or a new one).

• HyperFile::Open(): Opens a file, two parameters influence the mode and error reporting behavior.
  • Parameter mode:
    • FILEOPEN::READ : The file is opened for reading, only. This is the default mode, if none gets specified.
    • FILEOPEN::WRITE : The file is opened for writing, only. Any existing file will be overwritten.
    • FILEOPEN::READWRITE : The file is opened for read and write access.
  • Parameter (error-) dialog:
    • FILEDIALOG::NONE : No dialog will be shown on error. To be used if working with files in a context, where no dialogs are allowed, or to implement a custom error notification for users.
    • FILEDIALOG::ANY : A dialog will be shown on every file error.
    • FILEDIALOG::IGNOREOPEN : A dialog will be shown on every file error, except if the file does not exist. This is the default option.
• HyperFile::Close(): Closes a file. In most cases this is not needed, as the file will be automatically closed, when the HyperFile object gets destroyed.

Note

A HyperFile is always read and written from the beginning of a file. So FILEOPEN::APPEND can NOT be used with a HyperFile, appending is not supported.

Read and Write

The following functions are used to store data in a "BaseContainer"-like fashion, where one does not need to worry about the size of datatypes or positioning the read/write pointer.

A Typical Write Access

• Allocate a HyperFile object with HyperFile::Alloc() (or of course AutoAlloc).
• Open a file using HyperFile::Open(), either creating a new one or opening an existing one.
• Simply write data into the file, see below. Cinema 4D will take care of all needed housekeeping internally.
• Close the file using HyperFile::Close(). This step is actually optional, as the file will also be closed when the HyperFile object gets destroyed.

Note

The order of write accesses will determine the order of read accesses (the order will need to be the same).

  // This example demonstrates creating a new HyperFile and writing some typed data into it.
 
  Filename fn;
 
  // Let user select a target directory.
  if (!fn.FileSelect(FILESELECTTYPE::ANYTHING, FILESELECT::DIRECTORY, "Select a directory..."_s))
    return maxon::OK;
  fn += Filename { "myhyperfile.dat" };
 
  AutoAlloc<HyperFile> hf;
  if (!hf)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  // Create a HyperFile with the purpose of writing into it.
  // BEWARE: FILEOPEN_WRITE will create a new file, any existing file will be overwritten.
  const Int32 ident = 42; // Set an ID for the new file, use a/the plugin ID to define a unique file type.
  if (!hf->Open(ident, fn, FILEOPEN::WRITE, FILEDIALOG::ANY))
    return PrintFileError(fn, hf, "Failed to create HyperFile"_s);
 
  // Write some data into the new HyperFile.
  // Note: The order of data being written needs to be the same, when reading.
  if (!hf->WriteInt32(12345678))
    return PrintFileError(fn, hf, "Failed to write an Int32 into HyperFile"_s);
 
  if (!hf->WriteString("Hello World!"_s))
    return PrintFileError(fn, hf, "Failed to write a String into HyperFile"_s);
 
  // Finally close the HyperFile.
  // Note: Actually not needed, as the file will be closed on destruction of the HyperFile object.
  hf->Close();

A Typical Read Access

• Allocate a HyperFile object with HyperFile::Alloc() (or of course AutoAlloc).
• Open an existing file using HyperFile::Open().
• Simply read data from the file in the same order it got written before, see below. Cinema 4D will take care of all needed housekeeping internally.
• Close the file using HyperFile::Close(). This step is actually optional, as the file will also be closed when the HyperFile object gets destroyed.

All of the following read/write functions automatically take care of the read/write pointer (i.e. advancing it by the correct amount of bytes depending on the access type) and are able to detect access with wrong data type. Internally this is achieved by not only writing the actual data to the file, but also an additional value header preceding each data, specifying the type and also (where needed) the amount of data.

Note

The order of read accesses has to match the order of write accesses.

These functions can not be used to read data from an arbitrary file, but only from files created by Cinema 4D, when data got written by the respective write functions.

  // This example demonstrates reading simple typed data from a HyperFile.
 
  // Note: The file created via the "HyperFile Create" example is expected in this example.
  Filename fn;
 
  // Let user select a file.
  if (!fn.FileSelect(FILESELECTTYPE::ANYTHING, FILESELECT::LOAD, "Select the file from the HyperFile Create or Append command..."_s))
    return maxon::OK;
 
  AutoAlloc<HyperFile> hf;
  if (!hf)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  // Open a HyperFile with the purpose of reading data from it.
  const Int32 ident = 42; // The ID of the file (-type) that's supposed to be opened.
  if (!hf->Open(ident, fn, FILEOPEN::READ, FILEDIALOG::ANY))
    return PrintFileError(fn, hf, "Failed to open the HyperFile for reading"_s);
 
  // Read data from file.
  // Note: The order needs to be the same as on write.
  Int32 value;
  if (!hf->ReadInt32(&value))
    return PrintFileError(fn, hf, "Failed to read an Int32 from HyperFile"_s);
  if (value != 12345678)
    return PrintFileError(fn, hf, "This is not the expected HyperFile"_s);
 
  ApplicationOutput("Int32 read from HyperFile: @"_s, value);
 
  maxon::String myText;
  if (!hf->ReadString(&myText))
    return PrintFileError(fn, hf, "Failed to read a String from HyperFile"_s);
 
  ApplicationOutput("String read from HyperFile: @"_s, myText);

Value

As mentioned in the beginning, data/values get stored inside the HyperFile as a pair consisting of a describing header followed by the actual data. With the following functions the type of the next value can be detected (see HYPERFILEVALUE_... defines below) and the value may also be skipped (i.e. continue reading with the next value). Usually this is not needed, but can be helpful if for example writing a loop reading arbitrary values.

• HyperFile::ReadValueHeader(): Reads the value header from the HyperFile.
• HyperFile::SkipValue(): Skips a given type of value.

Char

• HYPERFILEVALUE::CHAR : Marks a signed char value.
• HYPERFILEVALUE::UCHAR : Marks an unsigned char value.
• HyperFile::ReadChar(): Reads a signed character.
• HyperFile::WriteChar(): Writes a signed character.
• HyperFile::ReadUChar(): Reads an unsigned character.
• HyperFile::WriteUChar(): Writes an unsigned character.

See also Primitive Data Types Manual (Cinema API) on Char.

String

• HYPERFILEVALUE::STRING : Marks a String value.
• HyperFile::ReadString(): Reads a String.
• HyperFile::WriteString(): Writes a String.

See also String Manual (Cinema API).

Filename

• HYPERFILEVALUE::FILENAME : Marks a Filename value.
• HyperFile::ReadFilename(): Reads a Filename.
• HyperFile::WriteFilename(): Writes a Filename.

See also Filename Manual.

Bool

• HYPERFILEVALUE::BOOL : Marks a boolean value.
• HyperFile::ReadBool(): Reads a boolean value.
• HyperFile::WriteBool(): Writes a boolean value.

See also Primitive Data Types Manual (Cinema API) on Bool.

Integer

• HYPERFILEVALUE::INT16 : Marks a signed 16-bit wide integer value (Int16).
• HYPERFILEVALUE::UINT16 : Marks an unsigned 16-bit wide integer value (UInt16).
• HYPERFILEVALUE::INT32 : Marks a signed 32-bit wide integer value (Int32).
• HYPERFILEVALUE::UINT32 : Marks an unsigned 32-bit wide integer value (UInt32).
• HYPERFILEVALUE::INT64 : Marks a signed 64-bit wide integer value (Int64).
• HYPERFILEVALUE::UINT64 : Marks an unsigned 64-bit wide integer value (UInt64).
• HyperFile::ReadInt16(): Reads a signed 16-bit wide integer value (Int16).
• HyperFile::WriteInt16(): Writes a signed 16-bit wide integer value (Int16).
• HyperFile::ReadUInt16(): Reads an unsigned 16-bit wide integer value (UInt16).
• HyperFile::WriteUInt16(): Writes an unsigned 16-bit wide integer value (UInt16).
• HyperFile::ReadInt32(): Reads a signed 32-bit wide integer value (Int32).
• HyperFile::WriteInt32(): Writes a signed 32-bit wide integer value (Int32).
• HyperFile::ReadUInt32(): Reads an unsigned 32-bit wide integer value (UInt32).
• HyperFile::WriteUInt32(): Writes an unsigned 32-bit wide integer value (UInt32).
• HyperFile::ReadInt64(): Reads a signed 64-bit wide integer value (Int64).
• HyperFile::WriteInt64(): Writes a signed 64-bit wide integer value (Int64).
• HyperFile::ReadUInt64(): Reads an unsigned 64-bit wide integer value (UInt64).
• HyperFile::WriteUInt64(): Writes an unsigned 64-bit wide integer value (UInt64)

See also Primitive Data Types Manual (Cinema API) on Integer.

Float

• HYPERFILEVALUE::FLOAT : Marks a floating point value (Float, nowadays usually 64-bit wide)
• HYPERFILEVALUE::FLOAT32 : Marks a 32-bit wide floating point value (Float32).
• HYPERFILEVALUE::FLOAT64 : Marks a 64-bit wide floating point value (Float64).
• HyperFile::ReadFloat(): Reads a floating point value (Float, nowadays usually 64-bit wide).
• HyperFile::WriteFloat(): Writes a floating point value (Float, nowadays usually 64-bit wide).
• HyperFile::ReadFloat32(): Reads a 32-bit wide floating point value (Float32).
• HyperFile::WriteFloat32(): Writes a 32-bit wide floating point value (Float32).
• HyperFile::ReadFloat64(): Reads a 64-bit wide floating point value (Float64).
• HyperFile::WriteFloat64(): Reads a 64-bit wide floating point value (Float64).

See also Primitive Data Types Manual (Cinema API) on Float.

Vector

• HYPERFILEVALUE::VECTOR : Marks a vector (Vector, nowadays usually 64-bit wide components).
• HYPERFILEVALUE::VECTOR64 : Marks a vector composed of 32-bit wide floating point values (Vector32).
• HYPERFILEVALUE::VECTOR32 : Marks a vector composed of 64-bit wide floating point values (Vector64).
• HyperFile::ReadVector(): Reads a vector composed of floating point values (Vector, nowadays usually 64-bit wide components).
• HyperFile::WriteVector(): Writes a vector composed floating point values (Vector, nowadays usually 64-bit wide components).
• HyperFile::ReadVector32(): Reads a vector composed of 32-bit wide floating point values (Vector32).
• HyperFile::WriteVector32(): Writes a vector composed of 32-bit wide floating point values (Vector32).
• HyperFile::ReadVector64(): Reads a vector composed of 64-bit wide floating point values (Vector64).
• HyperFile::WriteVector64(): Writes a vector composed of 64-bit wide floating point values (Vector64).

See also Vector Manual (Cinema API).

Matrix

• HYPERFILEVALUE::MATRIX : Marks a matrix (Matrix, nowadays usually 64-bit wide components).
• HYPERFILEVALUE::MATRIX32 : Marks a matrix composed of 32-bit wide floating point values (Matrix32).
• HYPERFILEVALUE::MATRIX64 : Marks a matrix composed of 64-bit wide floating point values (Matrix64).
• HyperFile::ReadMatrix(): Reads a matrix composed of floating point values (Matrix, nowadays usually 64-bit wide components).
• HyperFile::WriteMatrix(): Writes a matrix composed of floating point values (Matrix, nowadays usually 64-bit wide components).
• HyperFile::ReadMatrix32(): Reads a matrix composed of 32-bit wide floating point values (Matrix32).
• HyperFile::WriteMatrix32(): Writes a matrix composed of 32-bit wide floating point values (Matrix32).
• HyperFile::ReadMatrix64(): Reads a matrix composed of 64-bit wide floating point values (Matrix64).
• HyperFile::WriteMatrix64(): Writes a matrix composed of 64-bit wide floating point values (Matrix64).

See also Matrix Manual (Cinema API).

Arrays

• HYPERFILEVALUE::ARRAY : Marks an array.
• HyperFile::ReadArray(): Reads an array of the specified type from the HyperFile.
• HyperFile::WriteArray(): Writes an array of the specified datatype to the HyperFile.

These functions can be used with standard C arrays:

  // This example reads a C array from a HyperFile.
 
  Float64   arrFloat[4] = { 0.0 };
  const Int arrSize = sizeof(arrFloat) / sizeof(Float64);
 
  if (!hf->ReadArray(arrFloat, HYPERFILEARRAY::REAL, sizeof(Float64), arrSize))
    return PrintFileError(fn, hf, "Failed to read array (Float64) from HyperFile"_s);
 
  ApplicationOutput("Array (Float64) read from HyperFile:"_s);
  for (Int32 idx = 0; idx < arrSize; ++idx)
  {
    ApplicationOutput("  @", arrFloat[idx]);
  }

  // This example writes a standard C array to a HyperFile.
 
  const Float64 arrFloat[4] = { 42.0, PI, LIMIT<Float64>::MAX, (Float64)1.0 / (Float64)255.0 }; // just an example array with four Float64 values
  const Int     arrSize = sizeof(arrFloat) / sizeof(Float64);
 
  if (!hf->WriteArray(arrFloat, HYPERFILEARRAY::REAL, sizeof(Float64), arrSize))
    return PrintFileError(fn, hf, "Failed to write an array (Float64) into HyperFile"_s);

And also with maxon::BaseArray:

  // This example reads a BaseArray from a HyperFile.
 
  maxon::BaseArray<Int64> arrInt;
  arrInt.Resize(4) iferr_return;                      // Make sure, the BaseArray has enough space to hold the data to be read (otherwise read entry by entry and Append()).
  DebugAssert(arrInt.GetCount() < LIMIT<Int32>::MAX); // Read array's count parameter is only Int32.
 
  // A BaseArray stores data in a continguous memory block, the start address is returned by BaseArray::GetFirst().
  if (!hf->ReadArray(arrInt.GetFirst(), HYPERFILEARRAY::LLONG, sizeof(Int64), (Int32)arrInt.GetCount()))
    return PrintFileError(fn, hf, "Failed to read BaseArray<Int64> from HyperFile"_s);
 
  ApplicationOutput("BaseArray<Int64> read from HyperFile:"_s);
  for (auto val : arrInt)
  {
    ApplicationOutput("  @", val);
  }

  // This example writes a BaseArray to a HyperFile.
  maxon::BaseArray<Int64> arrInt; // just an example BaseArray with arbitrary values
  arrInt.Append(42) iferr_return;
  arrInt.Append(1984) iferr_return;
  arrInt.Append(2001) iferr_return;
  arrInt.Append(LIMIT<Int64>::MAX) iferr_return;
 
  // A BaseArray stores data in a continguous memory block, the start address is returned by BaseArray::GetFirst().
  if (!hf->WriteArray(arrInt.GetFirst(), HYPERFILEARRAY::LLONG, sizeof(Int64), (Int32)arrInt.GetCount()))
    return PrintFileError(fn, hf, "Failed to write a BaseArray (Int64) into HyperFile"_s);

GeData

• HyperFile::ReadGeData(): Reads a GeData value from the HyperFile.

  // This example reads GeData from a HyperFile.
 
  GeData d;
 
  if (!hf->ReadGeData(&d))
    return PrintFileError(fn, hf, "Failed to read a GeData from HyperFile"_s);
 
  if (d.GetType() == DTYPE_VECTOR)  // In the write example, a vector was written as GeData, so lets verify.
    ApplicationOutput("GeData(Vector) read from HyperFile: @", d.GetVector());

• HyperFile::WriteGeData(): Writes a GeData value to the HyperFile.

  // This example writes GeData to a HyperFile.
 
  GeData d;
  d.SetVector(Vector { 10.0, 20.0, 30.0 });
 
  if (!hf->WriteGeData(d))
    return PrintFileError(fn, hf, "Failed to write a GeData(Vector) into HyperFile"_s);

See also GeData Manual.

BaseContainer

• HYPERFILEVALUE::CONTAINER : Marks a BaseContainer.
• HyperFile::ReadContainer(): Reads a BaseContainer from the HyperFile.
• HyperFile::WriteContainer(): Writes a BaseContainer to the HyperFile.

See also BaseContainer Manual.

BaseTime

• HYPERFILEVALUE::TIME : Marks a BaseTime.
• HyperFile::ReadTime(): Reads a BaseTime value from the HyperFile.
• HyperFile::WriteTime(): Writes a BaseTime value to the HyperFile.

See also BaseTime Manual.

BaseBitmap

• HYPERFILEVALUE::IMAGE : Marks an image (BaseBitmap).
• HyperFile::ReadImage(): Reads a BaseBitmap from the HyperFile.
• HyperFile::WriteImage(): Writes a BaseBitmap to the HyperFile.

See also BaseBitmap Manual.

Raw Memory

• HYPERFILEVALUE::MEMORY : Marks a block of memory.
• HYPERFILEVALUE::LMEMORY : Marks a long block of memory (size exceeding 32-bit range, larger LIMIT<Int32>::MAX).
• HyperFile::ReadMemory(): Reads a block of memory from the HyperFile.

Note

Only use when really needed. Be aware that the byte sequences will not be platform independent.

// Following HyperFile::ReadMemory() and HyperFile:WriteMemory() code snippets use this structure.
 
struct myStructure
{
  Float64 myFloat;
  Int64   myInt;
  Bool    myBool;
};

  // This example reads some arbitrary data (in this case the struct stored earlier on) from a HyperFile.
 
  void* data;
  Int   size = 0;
 
  if (!hf->ReadMemory(&data, &size))
    return PrintFileError(fn, hf, "Failed to read memory (myStructure) from HyperFile"_s);
 
  myStructure* const myData = static_cast<myStructure*>(data);  // Interpret the read data as struct.
 
  ApplicationOutput("Memory (myStructure, size: @ ) read from HyperFile:"_s, size);
  ApplicationOutput("  @", myData->myFloat);
  ApplicationOutput("  @", myData->myInt);
  ApplicationOutput("  @", myData->myBool);

• HyperFile::WriteMemory(): Writes a block of memory to the HyperFile.

  // This example writes a C structure to a HyperFile.
 
  myStructure someData;
  someData.myFloat = 0.5;
  someData.myInt  = 42;
  someData.myBool = true;
 
  if (!hf->WriteMemory(&someData, sizeof(someData)))
    return PrintFileError(fn, hf, "Failed to write an memory (myStructure) into HyperFile"_s);

Uuid

• HYPERFILEVALUE::UUID : Marks a C4DUuid value.
• HyperFile::ReadUuid(): Reads a C4DUuid value from the HyperFile.
• HyperFile::WriteUuid(): Writes a C4DUuid value to the HyperFile.

Chunk

Chunks provide means to group or organize several values. This can be useful if for example different versions of a plugin store different sets of parameters, so a parameter set no longer understood can be skipped.

• HYPERFILEVALUE::START : Marks the start of a chunk.
• HYPERFILEVALUE::STOP : Marks the end of a chunk.
• HyperFile::ReadChunkStart(): Reads a chunks identification from the HyperFile.
• HyperFile::WriteChunkStart(): Writes a chunk marker into the HyperFile indicating the beginning of a new chunk of data.
• HyperFile::ReadChunkEnd(): Reads a chunk end marker from the HyperFile.
• HyperFile::WriteChunkEnd(): Writes a chunk ending marker into the HyperFile.
• HyperFile::SkipToEndChunk(): Moves the file pointer to the end of the chunk. Should always be called after having finished reading values from the current chunk (note the code snippet provided for HyperFile::ReadValueHeader()).

Utility

• HyperFile::GetDocument(): Gets the active document for the HyperFile operation. Can be nullptr, for instance when saving layouts.
• HyperFile::GetLocation(): Gets the HyperFile location.
  • Return value:
    • LOCATION::DISK : The file is stored on disk.
    • LOCATION::IPCONNECTION : File is stored on an IP connection.
    • LOCATION::MEMORY : The file is located in memory.
• HyperFile::GetFilterFlags(): Returns the ::SCENEFILTER flags set when opening the scene file with LoadDocument(). Used to check for ::SCENEFILTER::DIALOGSALLOWED etc.

Error

• HyperFile::GetError(): Gets the error from the last HyperFile operation (see also FILEERROR).
• HyperFile::SetError(): Sets the error for the HyperFile. Useful to reset the error.

File Version

• HyperFile::GetFileVersion(): Gets the version of Cinema 4D that wrote the file (Only valid while reading a Cinema 4D scene, object, material etc.).
• HyperFile::SetFileVersion(): Private.

Other HyperFile Related Functions

Actually not part of the HyperFile class, these convenience functions can be used to read or write a complete GeListNode from/into a single HyperFile referenced by Filename.

• ReadHyperFile(): Read a GeListNode from a file.

  // This example demonstrates reading a GeListNode (in this case an object) from a HyperFile (created by the code snippet on WriteHyperFile() below).
 
  Filename fn;
 
  // Let user select a directory to save to.
  if (!fn.FileSelect(FILESELECTTYPE::ANYTHING, FILESELECT::LOAD, "Select a file created by HyperFile ReadHyperFile example..."_s))
    return maxon::OK;
 
  AutoAlloc<BaseObject> op { Onull };
  if (!op)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  maxon::String errString = ""_s;
  if (ReadHyperFile(doc, op, fn, 123456, &errString) != FILEERROR::NONE)  // Note: ident has to match in WriteHyperFile(), get a unique plugin ID!
    return PrintFileError(fn, nullptr, "Failed to write object "_s + maxon::String(op->GetName()) + " to file ("_s + errString + "): "_s);
 
  doc->InsertObject(op.Release(), nullptr, nullptr);  // Note: Usage of Release(), when inserting the AutoAlloc'ed object into the scene.

• WriteHyperFile(): Write a GeListNode into a file.

  // This example demonstrates writing a GeListNode (in this case the active object) into a separate HyperFile.
 
  Filename fn;
 
  // Let user select a directory to save to.
  if (!fn.FileSelect(FILESELECTTYPE::ANYTHING, FILESELECT::DIRECTORY, "Select a path for saving..."_s))
    return maxon::OK;
 
  fn += Filename { maxon::String(op->GetName()) + ".myobj"_s };
 
  // Write the object to the HyperFile.
  if (WriteHyperFile(doc, op, fn, 123456) != FILEERROR::NONE) // Note: ident has to match in ReadHyperFile(), get a unique plugin ID!
    return PrintFileError(fn, nullptr, "Failed to write object "_s + maxon::String { op->GetName() } +" to file: "_s);
 
  ApplicationOutput("Successfully saved to file: "_s + maxon::String { fn.GetString() });

Further Reading

• Files & Media
• Cinema API Files & Media
• Filename Manual
• BaseFile Manual
• BrowseFiles Manual
• File Functions Manual
• FileMonitor Manual
• BaseDocument Manual on Disc I/O for loading and saving of Cinema 4D scenefiles.
• BaseBitmap Manual on Disc I/O for loading and saving of images.
• NodeData::Read() / NodeData::Write() Manual