DataSerializeInterface Class Reference

#include <dataserialize.h>

Inheritance diagram for DataSerializeInterface:

Detailed Description

This is the base class for generic serialization of any data type. For reading and writing the interfaces are split into DataSerializeReaderInterface and DataSerializeWriterInterface. The DataFormatReaderInterface and DataFormatWriterInterface can add specific serialization for data types. The DataSerializeReaderClasses and DataSerializeWriterClasses registry lists all possible formats. io_overview_describeio

Public Member Functions

MAXON_METHOD Result< void > DescribeElement (const Char *name, const DataType &dt, Int objectOffset, KeyValueConversionFunc *func, DESCRIBEFLAGS flags, UInt64 mask, UInt64 value) const
 
MAXON_METHOD Result< void > PrepareHelperClass (CreateIoHelperFunc *createFunc, DeleteIoHelperFunc *deleteFunc, ReadIoHelperFunc *readFunc, WriteIoHelperFunc *writeFunc, PREPAREHELPERFLAGS flags) const
 
MAXON_METHOD Result< void > RegisterObjectSubstitution (ReferenceSubstitutionFunction &&func)
 
MAXON_METHOD Result< void * > RegisterDefaults (CreateIoHelperFunc *createFunc, DeleteIoHelperFunc *deleteFunc) const
 
template<typename HELPERCLASS , typename MAINCLASS >
Result< void > PrepareHelperClass (PREPAREHELPERFLAGS flags) const
 
template<typename CLASSNAME , typename CMP , decltype(DESCRIBEFLAGS::_value) FLAGS, typename T >
Result< void > DescribeElement (const Char *fileName, const UniqueRef< T > *member, decltype(DESCRIBEFLAGS::_value) additional, UInt64 mask=0, UInt64 value=0) const
 
template<typename CLASSNAME , typename CMP , decltype(DESCRIBEFLAGS::_value) FLAGS, typename T >
Result< void > DescribeElement (const Char *fileName, const WeakRef< T > *member, decltype(DESCRIBEFLAGS::_value) additional, UInt64 mask=0, UInt64 value=0) const
 
template<typename CLASSNAME , typename CMP , decltype(DESCRIBEFLAGS::_value) FLAGS, typename T >
std::enable_if< GetCollectionKind< T >::value==COLLECTION_KIND::NONE, Result< void > >::type DescribeElement (const Char *fileName, const T *member, decltype(DESCRIBEFLAGS::_value) additional, UInt64 mask=0, UInt64 value=0) const
 
template<typename CLASSNAME , typename CMP , decltype(DESCRIBEFLAGS::_value) FLAGS, typename T >
std::enable_if< GetCollectionKind< T >::value==COLLECTION_KIND::ARRAY, Result< void > >::type DescribeElement (const Char *fileName, const T *member, decltype(DESCRIBEFLAGS::_value) additional) const
 
template<typename CLASSNAME , typename CMP , decltype(DESCRIBEFLAGS::_value) FLAGS, typename T >
std::enable_if< GetCollectionKind< T >::value==COLLECTION_KIND::SET, Result< void > >::type DescribeElement (const Char *fileName, const T *member, decltype(DESCRIBEFLAGS::_value) additional) const
 
template<typename CLASSNAME , typename CMP , decltype(DESCRIBEFLAGS::_value) FLAGS, typename T >
std::enable_if< GetCollectionKind< T >::value==COLLECTION_KIND::MAP, Result< void > >::type DescribeElement (const Char *fileName, const T *member, decltype(DESCRIBEFLAGS::_value) additional) const
 

Private Member Functions

 MAXON_INTERFACE (DataSerializeInterface, MAXON_REFERENCE_NORMAL, "net.maxon.interface.dataserialize", MAXON_IMPLEMENTATION_MODULE("net.maxon.kernel"))
 

Member Function Documentation

◆ MAXON_INTERFACE()

MAXON_INTERFACE ( DataSerializeInterface  ,
MAXON_REFERENCE_NORMAL  ,
"net.maxon.interface.dataserialize"  ,
MAXON_IMPLEMENTATION_MODULE("net.maxon.kernel")   
)
private

◆ DescribeElement() [1/7]

MAXON_METHOD Result<void> DescribeElement ( const Char name,
const DataType dt,
Int  objectOffset,
KeyValueConversionFunc func,
DESCRIBEFLAGS  flags,
UInt64  mask,
UInt64  value 
) const

Describes an element for I/O operations. Usually this routine is not directly called. Instead the helper-defines Describe, DescribeHelper, DescribeIf etc. are used.

Parameters
[in]nameThe clear-text name of an element in the file format. It can be arbitrarily chosen, but usually matches the respective member name. Once it has been used in files the identifier needs to stay the same to remain compatible (unless some conversion code is added). The name must only contain (latin) alphanumeric characters or '_' and it must not start with a numeric character. 'name' must be permanently available (and not only during the time of this call).
[in]dtThe data type of the member (a registered data type must exist).
[in]objectOffsetThe offset position of the member in the class (or the helper class).
[in]funcA conversion function that translates an address into the appropriate accessor interface (e.g. MapInterface or ArrayInterface).
[in]flagsProperties of the element.
[in]maskConditional mask for DESCRIBEFLAGS::CONDITION_IF and DESCRIBEFLAGS::CONDITION_ELSE.
[in]valueConditional value for DESCRIBEFLAGS::CONDITION_IF and DESCRIBEFLAGS::CONDITION_ELSE.
Returns
OK on success.

◆ PrepareHelperClass() [1/2]

MAXON_METHOD Result<void> PrepareHelperClass ( CreateIoHelperFunc createFunc,
DeleteIoHelperFunc deleteFunc,
ReadIoHelperFunc readFunc,
WriteIoHelperFunc writeFunc,
PREPAREHELPERFLAGS  flags 
) const

Declares and prepares a helper class. This can only be done once within DescribeIO. The helper class is used to convert I/O data and initialize temporary values. Usually this routine is not directly called. Instead the helper-define @ PrepareHelper is used.

Parameters
[in]createFuncThe function to create the helper class.
[in]deleteFuncThe function to delete the helper class.
[in]readFuncThe function pointing to the helper's ReadAction member function.
[in]writeFuncThe function pointing to the helper's WriteAction member function.
[in]flagsProperties of the helper.
Returns
OK on success.

◆ RegisterObjectSubstitution()

MAXON_METHOD Result<void> RegisterObjectSubstitution ( ReferenceSubstitutionFunction &&  func)

Registers a substitution function to replace virtual objects (objects with virtual interfaces) during the I/O process. The registration must happen before the main Read/Write call. The substitution will be able to write a different object than the one that exists in memory - or restore a different object than what is written into the stream. An example is e.g. RPC: instead of writing a WindowRef object only an object containing an Id is written to the file. On the other side then the object with the Id is read and a RPC WindowRef created. Substitutions fully support the referencing system, so all StrongReferences and WeakReferences will remain valid.

Parameters
[in]funcThe substitution function (used for both reading and writing).
Returns
OK on success.

◆ RegisterDefaults()

MAXON_METHOD Result<void*> RegisterDefaults ( CreateIoHelperFunc createFunc,
DeleteIoHelperFunc deleteFunc 
) const

Registers a class to support a later default value comparison. If the writer supports this feature an allocated class (using the createFunc) will be returned. Otherwise a nullptr is returned, which is no error state.

Parameters
[in]createFuncThe function to create the class.
[in]deleteFuncThe function to delete the class.
Returns
The allocated class or a nullptr.

◆ PrepareHelperClass() [2/2]

Result<void> PrepareHelperClass ( PREPAREHELPERFLAGS  flags) const

◆ DescribeElement() [2/7]

Result<void> DescribeElement ( const Char fileName,
const UniqueRef< T > *  member,
decltype(DESCRIBEFLAGS::_value additional,
UInt64  mask = 0,
UInt64  value = 0 
) const

◆ DescribeElement() [3/7]

Result<void> DescribeElement ( const Char fileName,
const WeakRef< T > *  member,
decltype(DESCRIBEFLAGS::_value additional,
UInt64  mask = 0,
UInt64  value = 0 
) const

◆ DescribeElement() [4/7]

std::enable_if<GetCollectionKind<T>::value == COLLECTION_KIND::NONE, Result<void> >::type DescribeElement ( const Char fileName,
const T *  member,
decltype(DESCRIBEFLAGS::_value additional,
UInt64  mask = 0,
UInt64  value = 0 
) const

◆ DescribeElement() [5/7]

std::enable_if<GetCollectionKind<T>::value == COLLECTION_KIND::ARRAY, Result<void> >::type DescribeElement ( const Char fileName,
const T *  member,
decltype(DESCRIBEFLAGS::_value additional 
) const

◆ DescribeElement() [6/7]

std::enable_if<GetCollectionKind<T>::value == COLLECTION_KIND::SET, Result<void> >::type DescribeElement ( const Char fileName,
const T *  member,
decltype(DESCRIBEFLAGS::_value additional 
) const

◆ DescribeElement() [7/7]

std::enable_if<GetCollectionKind<T>::value == COLLECTION_KIND::MAP, Result<void> >::type DescribeElement ( const Char fileName,
const T *  member,
decltype(DESCRIBEFLAGS::_value additional 
) const