HyperFile Class Reference

#include <c4d_file.h>

Detailed Description

Hyper files are used to save plugin data that cannot be stored in a BaseContainer.
Cinema 4D creates it and pass it to dedicated Load and Save overrides when needed (see NodeData and CustomDataTypeClass).
Access to the hyper file's data is like a FIFO (first in, first out) buffer; the values must be written and read in the same order.

Note
Has to be created with Alloc() and destroyed with Free(). Use AutoAlloc to automate the allocation and destruction based on scope.

Private Member Functions

 HyperFile ()
 
 ~HyperFile ()
 

Alloc/Free

static HyperFileAlloc (void)
 
static void Free (HyperFile *&fl)
 

Open/Close

Bool Open (Int32 ident, const Filename &filename, FILEOPEN mode, FILEDIALOG error_dialog)
 
Bool Close ()
 

Read

Bool ReadChar (Char *v)
 
Bool ReadUChar (UChar *v)
 
Bool ReadInt16 (Int16 *v)
 
Bool ReadUInt16 (UInt16 *v)
 
Bool ReadInt32 (Int32 *v)
 
Bool ReadUInt32 (UInt32 *v)
 
Bool ReadInt64 (Int64 *v)
 
Bool ReadUInt64 (UInt64 *v)
 
Bool ReadFloat (Float *v)
 
Bool ReadFloat32 (Float32 *v)
 
Bool ReadFloat64 (Float64 *v)
 
Bool ReadBool (Bool *v)
 
Bool ReadTime (BaseTime *v)
 
Bool ReadVector (Vector *v)
 
Bool ReadVector32 (Vector32 *v)
 
Bool ReadVector64 (Vector64 *v)
 
Bool ReadMatrix (Matrix *v)
 
Bool ReadMatrix32 (Matrix32 *v)
 
Bool ReadMatrix64 (Matrix64 *v)
 
Bool ReadString (String *v)
 
Bool ReadFilename (Filename *v)
 
Bool ReadImage (BaseBitmap *v)
 
Bool ReadGeData (GeData *v)
 
Bool ReadContainer (BaseContainer *v, Bool flush)
 
Bool ReadMemory (void **data, Int *size)
 
Bool ReadChannel (BaseChannel *bc)
 
Bool ReadChannelConvert (GeListNode *node, Int32 link_id)
 
Bool ReadArray (void *data, HYPERFILEARRAY type, Int32 structure_increment, Int32 count)
 
Bool ReadUuid (C4DUuid *v)
 

Write

Bool WriteChar (Char v)
 
Bool WriteUChar (UChar v)
 
Bool WriteInt16 (Int16 v)
 
Bool WriteUInt16 (UInt16 v)
 
Bool WriteInt32 (Int32 v)
 
Bool WriteUInt32 (UInt32 v)
 
Bool WriteInt64 (Int64 v)
 
Bool WriteUInt64 (UInt64 v)
 
Bool WriteFloat (Float v)
 
Bool WriteFloat32 (Float32 v)
 
Bool WriteFloat64 (Float64 v)
 
Bool WriteBool (Bool v)
 
Bool WriteTime (const BaseTime &v)
 
Bool WriteVector (const Vector &v)
 
Bool WriteVector32 (const Vector32 &v)
 
Bool WriteVector64 (const Vector64 &v)
 
Bool WriteMatrix (const Matrix &v)
 
Bool WriteMatrix32 (const Matrix32 &v)
 
Bool WriteMatrix64 (const Matrix64 &v)
 
Bool WriteString (const String &v)
 
Bool WriteFilename (const Filename &v)
 
Bool WriteImage (BaseBitmap *bmp, Int32 format, BaseContainer *data, SAVEBIT savebits=SAVEBIT_ALPHA)
 
Bool WriteGeData (const GeData &v)
 
Bool WriteContainer (const BaseContainer &v)
 
Bool WriteMemory (const void *data, Int count)
 
Bool WriteChannel (BaseChannel *bc)
 
Bool WriteArray (const void *data, HYPERFILEARRAY datatype, Int32 structure_increment, Int32 count)
 
Bool WriteUuid (const C4DUuid &v)
 

Error

FILEERROR GetError () const
 
void SetError (FILEERROR err)
 

HyperFile Value

Bool ReadValueHeader (HYPERFILEVALUE *h)
 
Bool SkipValue (HYPERFILEVALUE h)
 

Chunk Start/End

Bool WriteChunkStart (Int32 id, Int32 level)
 
Bool WriteChunkEnd (void)
 
Bool ReadChunkStart (Int32 *id, Int32 *level)
 
Bool ReadChunkEnd (void)
 
Bool SkipToEndChunk (void)
 

File Version

Int32 GetFileVersion () const
 
void SetFileVersion (Int32 val)
 

Miscellaneous

BaseDocumentGetDocument () const
 
LOCATION GetLocation (void) const
 

Constructor & Destructor Documentation

§ HyperFile()

HyperFile ( )
private

§ ~HyperFile()

~HyperFile ( )
private

Member Function Documentation

§ Alloc()

static HyperFile* Alloc ( void  )
static

Allocates a hyper file. Destroy the allocated hyper file with Free(). Use AutoAlloc to automate the allocation and destruction based on scope.

Returns
The allocated hyper file, or nullptr if the allocation failed.

§ Free()

static void Free ( HyperFile *&  fl)
static

Destructs hyper files allocated with Alloc(). Use AutoAlloc to automate the allocation and destruction based on scope.

Parameters
[in,out]flThe hyper file to destruct. If the pointer is nullptr nothing happens. The pointer is assigned nullptr afterwards.

§ Open()

Bool Open ( Int32  ident,
const Filename filename,
FILEOPEN  mode,
FILEDIALOG  error_dialog 
)

Opens the hyper file.

Parameters
[in]identThe file identification.
[in]filenameThe name of the file to open.
[in]modeThe file mode: FILEOPEN
[in]error_dialogThe file error dialog: FILEDIALOG
Returns
true if the hyper file could be opened, otherwise false.

§ Close()

Bool Close ( )

Closes the hyper file.

Returns
true if the hyper file could be closed, otherwise false.

§ ReadChar()

Bool ReadChar ( Char v)

Reads a Char value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ ReadUChar()

Bool ReadUChar ( UChar v)

Reads a UChar value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ ReadInt16()

Bool ReadInt16 ( Int16 v)

Reads a Int16 value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ ReadUInt16()

Bool ReadUInt16 ( UInt16 v)

Reads a UInt16 value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ ReadInt32()

Bool ReadInt32 ( Int32 v)

Reads a Int32 value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ ReadUInt32()

Bool ReadUInt32 ( UInt32 v)

Reads a UInt32 value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ ReadInt64()

Bool ReadInt64 ( Int64 v)

Reads a Int64 value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ ReadUInt64()

Bool ReadUInt64 ( UInt64 v)

Reads a UInt64 value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ ReadFloat()

Bool ReadFloat ( Float v)

Reads a Float value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ ReadFloat32()

Bool ReadFloat32 ( Float32 v)

Reads a Float32 value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ ReadFloat64()

Bool ReadFloat64 ( Float64 v)

Reads a Float64 value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ ReadBool()

Bool ReadBool ( Bool v)

Reads a Bool value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ ReadTime()

Bool ReadTime ( BaseTime v)

Reads a BaseTime value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ ReadVector()

Bool ReadVector ( Vector v)

Reads a Vector value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ ReadVector32()

Bool ReadVector32 ( Vector32 v)

Reads a Vector32 value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ ReadVector64()

Bool ReadVector64 ( Vector64 v)

Reads a Vector64 value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ ReadMatrix()

Bool ReadMatrix ( Matrix v)

Reads a Matrix value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ ReadMatrix32()

Bool ReadMatrix32 ( Matrix32 v)

Reads a Matrix32 value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ ReadMatrix64()

Bool ReadMatrix64 ( Matrix64 v)

Reads a Matrix64 value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ ReadString()

Bool ReadString ( String v)

Reads a String value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ ReadFilename()

Bool ReadFilename ( Filename v)

Reads a Filename value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ ReadImage()

Bool ReadImage ( BaseBitmap v)

Reads a BaseBitmap value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ ReadGeData()

Bool ReadGeData ( GeData v)

Reads a GeData value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ ReadContainer()

Bool ReadContainer ( BaseContainer v,
Bool  flush 
)

Reads a container from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
[in]flushSpecify if the container should be cleared before reading the new values.
Passing false will merge the container with the one read from the file.
Returns
Success of reading the container.

§ ReadMemory()

Bool ReadMemory ( void **  data,
Int size 
)

Reads a block of memory from the hyper file.

Note
Only use when really needed. Be aware that the byte sequences will not be platform independent. Example:
Int32 size;
void* data = nullptr;
Bool ok = ReadMemory(&data, &size);
DeleteMem(data);
Parameters
[out]dataA pointer to the start of the memory block to read.
[out]sizeAssigned the byte size of the memory data read.
Returns
Success of reading the memory block.

§ ReadChannel()

Bool ReadChannel ( BaseChannel bc)

Deprecated.

§ ReadChannelConvert()

Bool ReadChannelConvert ( GeListNode node,
Int32  link_id 
)

Deprecated.

§ ReadArray()

Bool ReadArray ( void *  data,
HYPERFILEARRAY  type,
Int32  structure_increment,
Int32  count 
)

Reads an array of the specified type from the hyper file.

Parameters
[out]dataA pointer to an array to be filled. The caller owns the pointed array.
[in]typeThe data type: HYPERFILEARRAY
[in]structure_incrementThe size of the data type (sizeof()).
[in]countThe umber of elements in data.
Returns
Success of reading the array.

§ ReadUuid()

Bool ReadUuid ( C4DUuid v)

Reads a C4DUuid value from the hyper file.

Parameters
[out]vAssigned the value read from the hyper file.
Returns
Success of reading the value.

§ WriteChar()

Bool WriteChar ( Char  v)

Writes a Char value to the hyper file.

Parameters
[in]vThe value to write to the hyper file.
Returns
Success of writing the value.

§ WriteUChar()

Bool WriteUChar ( UChar  v)

Writes a UChar value to the hyper file.

Parameters
[in]vThe value to write to the hyper file.
Returns
Success of writing the value.

§ WriteInt16()

Bool WriteInt16 ( Int16  v)

Writes a Int16 value to the hyper file.

Parameters
[in]vThe value to write to the hyper file.
Returns
Success of writing the value.

§ WriteUInt16()

Bool WriteUInt16 ( UInt16  v)

Writes a UInt16 value to the hyper file.

Parameters
[in]vThe value to write to the hyper file.
Returns
Success of writing the value.

§ WriteInt32()

Bool WriteInt32 ( Int32  v)

Writes a Int32 value to the hyper file.

Parameters
[in]vThe value to write to the hyper file.
Returns
Success of writing the value.

§ WriteUInt32()

Bool WriteUInt32 ( UInt32  v)

Writes a UInt32 value to the hyper file.

Parameters
[in]vThe value to write to the hyper file.
Returns
Success of writing the value.

§ WriteInt64()

Bool WriteInt64 ( Int64  v)

Writes a Int64 value to the hyper file.

Parameters
[in]vThe value to write to the hyper file.
Returns
Success of writing the value.

§ WriteUInt64()

Bool WriteUInt64 ( UInt64  v)

Writes a UInt64 value to the hyper file.

Parameters
[in]vThe value to write to the hyper file.
Returns
Success of writing the value.

§ WriteFloat()

Bool WriteFloat ( Float  v)

Writes a Float value to the hyper file.

Parameters
[in]vThe value to write to the hyper file.
Returns
Success of writing the value.

§ WriteFloat32()

Bool WriteFloat32 ( Float32  v)

Writes a Float32 value to the hyper file.

Parameters
[in]vThe value to write to the hyper file.
Returns
Success of writing the value.

§ WriteFloat64()

Bool WriteFloat64 ( Float64  v)

Writes a Float64 value to the hyper file.

Parameters
[in]vThe value to write to the hyper file.
Returns
Success of writing the value.

§ WriteBool()

Bool WriteBool ( Bool  v)

Writes a Bool value to the hyper file.

Parameters
[in]vThe value to write to the hyper file.
Returns
Success of writing the value.

§ WriteTime()

Bool WriteTime ( const BaseTime v)

Writes a BaseTime value to the hyper file.

Parameters
[in]vThe value to write to the hyper file.
Returns
Success of writing the value.

§ WriteVector()

Bool WriteVector ( const Vector v)

Writes a Vector value to the hyper file.

Parameters
[in]vThe value to write to the hyper file.
Returns
Success of writing the value.

§ WriteVector32()

Bool WriteVector32 ( const Vector32 v)

Writes a Vector32 value to the hyper file.

Parameters
[in]vThe value to write to the hyper file.
Returns
Success of writing the value.

§ WriteVector64()

Bool WriteVector64 ( const Vector64 v)

Writes a Vector64 value to the hyper file.

Parameters
[in]vThe value to write to the hyper file.
Returns
Success of writing the value.

§ WriteMatrix()

Bool WriteMatrix ( const Matrix v)

Writes a Matrix value to the hyper file.

Parameters
[in]vThe value to write to the hyper file.
Returns
Success of writing the value.

§ WriteMatrix32()

Bool WriteMatrix32 ( const Matrix32 v)

Writes a Matrix32 value to the hyper file.

Parameters
[in]vThe value to write to the hyper file.
Returns
Success of writing the value.

§ WriteMatrix64()

Bool WriteMatrix64 ( const Matrix64 v)

Writes a Matrix64 value to the hyper file.

Parameters
[in]vThe value to write to the hyper file.
Returns
Success of writing the value.

§ WriteString()

Bool WriteString ( const String v)

Writes a String value to the hyper file.

Parameters
[in]vThe value to write to the hyper file.
Returns
Success of writing the value.

§ WriteFilename()

Bool WriteFilename ( const Filename v)

Writes a Filename value to the hyper file.

Parameters
[in]vThe value to write to the hyper file.
Returns
Success of writing the value.

§ WriteImage()

Bool WriteImage ( BaseBitmap bmp,
Int32  format,
BaseContainer data,
SAVEBIT  savebits = SAVEBIT_ALPHA 
)

Writes an image to the hyper file.

Parameters
[in]bmpThe bitmap to write to the hyperfile. The caller owns the pointed bitmap.
[in]formatThe image format: FILTER
[in]dataA container with additional format settings, or nullptr
[in]savebitsThe save bits: SAVEBIT
Returns
Success of writing the image.

§ WriteGeData()

Bool WriteGeData ( const GeData v)

Writes a Char value to the hyper file.

Parameters
[in]vThe value to write to the hyper file.
Returns
Success of writing the value.

§ WriteContainer()

Bool WriteContainer ( const BaseContainer v)

Writes a container to the hyper file.

Parameters
[in]vThe container to write to the hyper file.
Returns
Success of writing the container.

§ WriteMemory()

Bool WriteMemory ( const void *  data,
Int  count 
)

Writes a block of memory to the hyper file.

Note
Only use when really needed. Be aware that the byte sequences will not be platform independent.
Parameters
[in]dataThe start of the memory block to write to the hyper file.
[in]countThe size in bytes of the memory data to write.
Returns
Success of writing the memory block.

§ WriteChannel()

Bool WriteChannel ( BaseChannel bc)

Deprecated.

§ WriteArray()

Bool WriteArray ( const void *  data,
HYPERFILEARRAY  datatype,
Int32  structure_increment,
Int32  count 
)

Writes an array of the specified datatype to the hyper file.

Parameters
[in]dataThe pointer to the array. The caller owns the pointed array.
[in]datatypeThe array data type: HYPERFILEARRAY
[in]structure_incrementSize of the data type (sizeof()).
[in]countThe number of elements in data.
Returns
Success of writing the array.

§ WriteUuid()

Bool WriteUuid ( const C4DUuid v)

Writes a C4DUuid value to the hyper file.

Parameters
[in]vThe value to write to the hyper file.
Returns
Success of writing the value.

§ GetError()

FILEERROR GetError ( ) const

Gets the error from the last hyper file operation.

Returns
The error: FILEERROR

§ SetError()

void SetError ( FILEERROR  err)

Sets the error for the hyper file.

Parameters
[in]errThe error to set: FILEERROR

§ ReadValueHeader()

Bool ReadValueHeader ( HYPERFILEVALUE h)

Reads the value header from the hyper file.
This is only necessary in combination with loops.
For example:

static Bool ReadSettings(BaseObject *op, HyperFile *hf, Int32 level)
{
Int32 id, level, v;
String test;
while (hf->ReadValueHeader(&h) && h==HYPERFILEVALUE_START)
{
if (!hf->ReadChunkStart(&id, &level))
return false;
if (id==2)
{
hf->ReadInt32(&v);
hf->ReadInt32(&v);
}
else if (id==3)
{
hf->ReadInt32(&v);
hf->ReadInt32(&v);
hf->ReadInt32(&v);
}
hf->SkipToEndChunk(); // Never forget this at the end
if (id==0)
break; // Chunk ID 0 is end chunk
}
hf->ReadString(test);
return true;
}
Parameters
[in]hA pointer to a HYPERFILEVALUE to take the header value: HYPERFILEVALUE
Returns
true if the header was read successfully, otherwise false.

§ SkipValue()

Bool SkipValue ( HYPERFILEVALUE  h)

Skips a given type of value.

Parameters
[in]hThe hyper file value to skip: HYPERFILEVALUE
Returns
true if the value was of the given header type and it was skipped, otherwise false.

§ WriteChunkStart()

Bool WriteChunkStart ( Int32  id,
Int32  level 
)

Writes a chunk marker into the file indicating the beginning of a new chunk of data.

Parameters
[in]idThe ID for the chunk.
[in]levelTo write additional information, increase this level to save/read new values.
Returns
true if the chunk identification was written successfully, otherwise false.

§ WriteChunkEnd()

Bool WriteChunkEnd ( void  )

Writes a chunk ending marker into the hyper file.

Returns
true if the chunk end was written successfully, otherwise false.

§ ReadChunkStart()

Bool ReadChunkStart ( Int32 id,
Int32 level 
)

Reads a chunks identification from the hyper file.

Parameters
[out]idAssigned the chunk ID.
[out]levelAssigned the chunk level.
Returns
true if the chunk start was read successfully, otherwise false.

§ ReadChunkEnd()

Bool ReadChunkEnd ( void  )

Reads a chunk end marker from the hyper file.

Returns
true if the chunk end was read successfully, otherwise false.

§ SkipToEndChunk()

Bool SkipToEndChunk ( void  )

Moves the file pointer to the end of the chunk.

Note
Should always be called after having finished reading values from the current chunk.
Returns
true if the end of the chunk was found and skipped to, otherwise false.

§ GetFileVersion()

Int32 GetFileVersion ( ) const

Gets the version of Cinema 4D that wrote the file. (Only valid while reading a Cinema 4D scene, object, material etc.)

Returns
The file version.

§ SetFileVersion()

void SetFileVersion ( Int32  val)

Private.

§ GetDocument()

BaseDocument* GetDocument ( ) const

Gets the active document for the hyper file operation.
Can be nullptr, for instance when saving layouts.

Returns
The document for the hyper file operation. Cinema 4D owns the pointed document.

§ GetLocation()

LOCATION GetLocation ( void  ) const

Gets the hyper file location.

Returns
The hyper file location: LOCATION