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 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)
{
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;
}
Manages file and path names.
Definition: c4d_file.h:94
String GetString() const
Definition: c4d_file.h:1085
Definition: string.h:1235
maxon::Bool Bool
Definition: ge_sys_math.h:55
maxon::Int Int
Definition: ge_sys_math.h:64
return OK
Definition: apibase.h:2747
FILEERROR
Definition: ge_prepass.h:3957
@ UNKNOWN_VALUE
Unknown value detected.
@ OUTOFMEMORY
Not enough memory.
@ NONE
No error.
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:67
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:210
const char const char const char * file
Definition: object.h:439

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 (Classic).

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..."_s))
return maxon::OK;
fn += Filename { "myhyperfile.dat" };
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();
Definition: ge_autoptr.h:37
Bool FileSelect(FILESELECTTYPE type, FILESELECT flags, const maxon::String &title, const maxon::String &force_suffix=maxon::String())
maxon::Int32 Int32
Definition: ge_sys_math.h:60
@ ANY
Show an error dialog for any error.
@ DIRECTORY
Folder selection dialog.
@ ANYTHING
Any file.

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.
// 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;
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.
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);
PyObject * value
Definition: abstract.h:715
@ READ
Open the file for reading.
@ LOAD
Load dialog.

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.

Char

See also Primitive Data Types Manual (Classic) on Char.

String

See also String Manual (Classic).

Filename

See also Filename Manual.

Bool

See also Primitive Data Types Manual (Classic) on Bool.

Integer

See also Primitive Data Types Manual (Classic) on Integer.

Float

See also Primitive Data Types Manual (Classic) on Float.

Vector

See also Vector Manual (Classic).

Matrix

See also Matrix Manual (Classic).

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"_s);
ApplicationOutput("Array (Float64) read from HyperFile:"_s);
for (Int32 idx = 0; idx < arrSize; ++idx)
{
ApplicationOutput(" @", arrFloat[idx]);
}
maxon::Float64 Float64
Definition: ge_sys_math.h:67
@ REAL
Float array.
// 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);
Definition: apibasemath.h:34
PI
Definition: unicodeutils.h:16

And also with maxon::BaseArray:

// This example reads a BaseArray from a HyperFile.
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)
{
}
MAXON_ATTRIBUTE_FORCE_INLINE const T * GetFirst() const
Definition: basearray.h:1166
ResultMem Resize(Int newCnt, COLLECTION_RESIZE_FLAGS resizeFlags=COLLECTION_RESIZE_FLAGS::DEFAULT)
Definition: basearray.h:1209
MAXON_ATTRIBUTE_FORCE_INLINE Int GetCount() const
Definition: basearray.h:576
maxon::Int64 Int64
Definition: ge_sys_math.h:62
@ LLONG
Int64 array.
#define DebugAssert(condition,...)
Definition: debugdiagnostics.h:248
PyObject const char PyObject PyObject ** val
Definition: pycore_pyerrors.h:76
#define iferr_return
Definition: resultbase.h:1521
// 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;
// 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);
MAXON_ATTRIBUTE_FORCE_INLINE ResultRef< T > Append(ARG &&x)
Appends a new element at the end of the array and constructs it using the forwarded value.
Definition: basearray.h:619

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"_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());
Definition: c4d_gedata.h:83
Int32 GetType() const
Definition: c4d_gedata.h:436
const Vector & GetVector() const
Definition: c4d_gedata.h:486
@ DTYPE_VECTOR
Vector
Definition: lib_description.h:70
// 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);
void SetVector(const Vector &v)
Definition: c4d_gedata.h:670

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"_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);
Py_ssize_t size
Definition: bytesobject.h:86
// 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

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

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..."_s))
return maxon::OK;
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.
#define Onull
Null.
Definition: ge_prepass.h:1074
FILEERROR ReadHyperFile(BaseDocument *doc, GeListNode *node, const Filename &filename, Int32 ident, maxon::String *warning_string)
const char * doc
Definition: pyerrors.h:226
PyObject * op
Definition: object.h:520
// 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..."_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() });
FILEERROR WriteHyperFile(BaseDocument *doc, GeListNode *node, const Filename &filename, Int32 ident)

Further Reading