HyperFile Manual

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 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 internal. 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 cinema4dsdk.

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 Bool PrintFileError(const Filename& fn, const HyperFile* const hf, const String& errText, Bool verbose = false)
{
if (hf && hf->GetError() != FILEERROR_NONE)
GePrint("Error (" + String::IntToString(hf->GetError()) + "): " + errText + ": " + fn.GetString());
else
GePrint("Error: " + errText + ": " + fn.GetString());
if (verbose)
GePrint(" " + String::IntToString(hf->GetError()) + ": " + FileErrorToString(hf)); // FileErrorToString() is a custom function.
return false;
}

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.

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.
// Let user select a target directory.
if (!fn.FileSelect(FILESELECTTYPE_ANYTHING, FILESELECT_DIRECTORY, "Select a directory..."))
return false;
fn += Filename("myhyperfile.dat");
if (!hf)
return PrintFileError(fn, hf, "Failed to allocate HyperFile for");
// 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");
// 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");
if (!hf->WriteString("Hello World!"))
return PrintFileError(fn, hf, "Failed to write a String into HyperFile");
// 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" or "HyperFile Append" examples is expected in this example.
// Let user select a file.
if (!fn.FileSelect(FILESELECTTYPE_ANYTHING, FILESELECT_LOAD, "Select the file from the HyperFile Create or Append command..."))
return false;
if (!hf)
return PrintFileError(fn, hf, "Failed to allocate HyperFile for");
// 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");
// 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");
if (value != 12345678)
{
GePrint("Error (" + String::IntToString(hf->GetError()) + "): This is not the expected HyperFile: " + fn.GetString());
return false;
}
GePrint("Int32 read from HyperFile: " + String::IntToString(value));
String myText;
if (!hf->ReadString(&myText))
return PrintFileError(fn, hf, "Failed to read a String from HyperFile");
GePrint("String read from HyperFile: " + 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 above) 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.

Char

See also Primitive Data Types Manual on Char.

String

See also String Manual.

Filename

See also Filename Manual.

Bool

See also Primitive Data Types Manual on Bool.

Integer

See also Primitive Data Types Manual on Integer.

Float

See also Primitive Data Types Manual on Float.

Vector

See also Vector Manual.

Matrix

See also Matrix Manual.

Arrays

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");
GePrint("Array (Float64) read from HyperFile:");
for (Int32 idx = 0; idx < arrSize; ++idx)
{
GePrint(" " + String::FloatToString(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");

And also with BaseArray:

// This example reads a BaseArray from a HyperFile.
arrInt.Resize(4); // 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");
GePrint("BaseArray<Int64> read from HyperFile:");
for (auto val : arrInt)
{
}
// This example writes a BaseArray to a HyperFile.
maxon::BaseArray<Int64> arrInt; // just an example BaseArray with arbitrary values
if (arrInt.Append(42) == nullptr) // Return value of BaseArray::Append() has always to be checked!
return false;
if (arrInt.Append(1984) == nullptr)
return false;
if (arrInt.Append(2001) == nullptr)
return false;
if (arrInt.Append(LIMIT<Int64>::Max()))
return false;
// 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");

GeData

// This example reads GeData from a HyperFile.
GeData d;
if (!hf->ReadGeData(&d))
return PrintFileError(fn, hf, "Failed to read a GeData from HyperFile");
if (d.GetType() == DTYPE_VECTOR) // In the write example, a vector was written as GeData, so lets verify.
GePrint("GeData(Vector) read from HyperFile: " + String::VectorToString(d.GetVector()));
// 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");

See also GeData Manual.

BaseContainer

See also BaseContainer Manual.

BaseTime

See also BaseTime Manual.

BaseBitmap

See also BaseBitmap Manual.

Raw Memory

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");
myStructure* myData = static_cast<myStructure*>(data); // Interpret the read data as struct.
GePrint("Memory (myStructure, size: " + String::IntToString(size) + ") read from HyperFile:");
GePrint(" " + String::FloatToString(myData->myFloat));
GePrint(" " + String::IntToString(myData->myInt));
GePrint(" " + String::IntToString(myData->myBool));
// 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");

Uuid

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.

Utility

Return value LOCATION:

Error

File Version

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.

// This example demonstrates reading a GeListNode (in this case an object) from a HyperFile (created by the code snippet on WriteHyperFile() below).
// Let user select a directory to save to.
if (!fn.FileSelect(FILESELECTTYPE_ANYTHING, FILESELECT_LOAD, "Select a file created by HyperFile ReadHyperFile example..."))
return false;
if (!op)
return false;
String errString = "";
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 " + op->GetName() + " to file (" + errString + "): ");
doc->InsertObject(op.Release(), nullptr, nullptr); // Note: Usage of Release(), when inserting the AutoAlloc'ed object into the scene.
// This example demonstrates writing a GeListNode (in this case the active object) into a separate HyperFile.
// Let user select a directory to save to.
if (!fn.FileSelect(FILESELECTTYPE_ANYTHING, FILESELECT_DIRECTORY, "Select a path for saving..."))
return false;
fn += Filename(op->GetName() + ".myobj");
// 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 " + op->GetName() + " to file: ");
GePrint("Successfully saved to file: " + fn.GetString());

Further Reading