Serialization::Archive Class Reference

Destination container for serialization, and source container for deserialization. More...

`#include <Serialization.h>`

## Classes

class | Syncer
| Synchronizes 2 archives with each other. More...

## Public Types

enum | operation_t { OPERATION_NONE , OPERATION_SERIALIZE , OPERATION_DESERIALIZE }
| Current activity of `Archive` object. More...

## Public Member Functions

| Archive ()
| Create an "empty" archive.
| Archive (const RawData &data)
| Create and fill the archive with the given serialized raw data.
| Archive (const uint8_t *data, size_t size)
| Create and fill the archive with the given serialized raw C-buffer data.
template<typename T>
void | serialize (const T *obj)
| Initiate serialization.
template<typename T>
void | deserialize (T *obj)
| Initiate deserialization.
template<typename T>
void | operator<< (const T &obj)
| Initiate serialization of your C++ objects.
template<typename T>
void | operator>> (T &obj)
| Initiate deserialization of your C++ objects.
const RawData & | rawData ()
| Raw data stream of this archive content.
virtual String | rawDataFormat () const
| Name of the encoding format used by this Archive class.
template<typename T_classType, typename T_memberType>
void | serializeMember (const T_classType &nativeObject, const T_memberType &nativeMember, const char *memberName)
| Serialize a native C/C++ member variable.
template<typename T_classType, typename T_memberType>
void | serializeHeapMember (const T_classType &nativeObject, const T_memberType &heapMember, const char *memberName)
| Serialize a C/C++ member variable allocated on the heap.
template<typename T_objectType>
void | serializeAnonymousObject (const T_objectType &heapObject)
| Serialize anonymous C/C++ data.
template<typename T_classType>
void | setVersion (const T_classType &nativeObject, Version v)
| Set current version number for your C++ class.
template<typename T_classType>
void | setMinVersion (const T_classType &nativeObject, Version v)
| Set a minimum version number for your C++ class.
virtual void | decode (const RawData &data)
| Fill this archive with the given serialized raw data.
virtual void | decode (const uint8_t *data, size_t size)
| Fill this archive with the given serialized raw C-buffer data.
void | clear ()
| Clear content of this archive.
bool | isModified () const
| Whether this archive was modified.
void | removeMember (Object &parent, const Member &member)
| Remove a member variable from the given object.
void | remove (const Object &obj)
| Remove an object from this archive.
Object & | rootObject ()
| Root C++ object of this archive.
Object & | objectByUID (const UID &uid)
| Access object by its unique identifier.
Object & | parentObjectOf (const Object &obj)
| Access parent of supplied object.
Object & | parentObjectOf (const Member &member)
| Access parent of supplied member.
void | setAutoValue (Object &object, String value)
| Automatically cast and assign appropriate value to object.
void | setIntValue (Object &object, int64_t value)
| Set new integer value for given integer object.
void | setRealValue (Object &object, double value)
| Set new floating point value for given floating point object.
void | setBoolValue (Object &object, bool value)
| Set new boolean value for given boolean object.
void | setEnumValue (Object &object, uint64_t value)
| Set new value for given `enum` object.
void | setStringValue (Object &object, String value)
| Set new textual string for given String object.
String | valueAsString (const Object &object)
| Get value of object as string.
int64_t | valueAsInt (const Object &object)
| Get integer value of object.
double | valueAsReal (const Object &object)
| Get floating point value of object.
bool | valueAsBool (const Object &object)
| Get boolean value of object.
void | setVersion (Object &object, Version v)
| Set the current version for the given object.
void | setMinVersion (Object &object, Version v)
| Set the minimum version for the given object.
String | name () const
| Optional name of this archive.
void | setName (String name)
| Assign a name to this archive.
String | comment () const
| Optional comments for this archive.
void | setComment (String comment)
| Assign a comment to this archive.
time_t | timeStampCreated () const
| Date and time when this archive was initially created.
time_t | timeStampModified () const
| Date and time when this archive was modified for the last time.
tm | dateTimeCreated (time_base_t base=LOCAL_TIME) const
| Date and time when this archive was initially created.
tm | dateTimeModified (time_base_t base=LOCAL_TIME) const
| Date and time when this archive was modified for the last time.
operation_t | operation () const

## Protected Member Functions

Object & | objectByBaseUID (const UID &uid)
| Find true object for a base pointer.
virtual void | encode ()

## Protected Attributes

ObjectPool | m_allObjects
operation_t | m_operation
UID | m_root
RawData | m_rawData
bool | m_isModified
String | m_name
String | m_comment
time_t | m_timeCreated
time_t | m_timeModified

## Detailed Description

Destination container for serialization, and source container for deserialization.

This is the main class for implementing serialization and deserialization with your C++ application. This framework does not require a a tree structured layout of your C++ objects being serialized/deserialized, it uses a concept of a "root" object though. So to start serialization construct an empty Archive object and then instruct it to serialize your C++ objects by pointing it to your "root" object:

Archive a;
a.serialize(&myRootObject);
Serialization::Archive::serialize
void serialize(const T *obj)
Initiate serialization.
Definition Serialization.h:1137
Serialization::Archive::Archive
Archive()
Create an "empty" archive.
Definition Serialization.cpp:1355

Or if you prefer the look of operator based code:

Archive a;
a << myRootObject;

The Archive object will then serialize all members of the passed C++ object, and will recursively serialize all other C++ objects which it contains or points to. So the root object is the starting point for the overall serialization. After the serialize() method returned, you can then access the serialized data stream by calling rawData() and send that data stream over "wire", or store it on disk or whatever you may intend to do with it.

Then on receiver side likewise, you create a new Archive object, pass the received data stream i.e. via constructor to the Archive object and call deserialize() by pointing it to the root object on receiver side:

Archive a(rawDataStream);
a.deserialize(&myRootObject);
Serialization::Archive::deserialize
void deserialize(T *obj)
Initiate deserialization.
Definition Serialization.h:1172

Or with operator instead:

Archive a(rawDataStream);
a >> myRootObject;

Now this framework automatically handles serialization and deserialization of fundamental data types (like i.e. `char`, `int`, `long` `int`, `float`, `double`, etc.) and common C++ classes (currently: `std::string`, `std::vector`, `std::set` and `std::map`) automatically for you. However for your own custom C++ classes and structs you must implement one method which defines which members of your class / struct should actually be serialized and deserialized. That method to be added must have the following signature:

void serialize(Serialization::Archive* archive);
Serialization::Archive
Destination container for serialization, and source container for deserialization.
Definition Serialization.h:1096

So let's say you have the following simple data structures:

struct Foo {
int a;
bool b;
double c;
std::string text;
std::vector<int> v;
};
struct Bar {
char one;
float two;
Foo foo1;
Foo* pFoo2;
Foo* pFoo3DontTouchMe; // shall not be serialized/deserialized
std::set<int> someSet;
std::map<double,Foo> someMap;
};

So in order to be able to serialize and deserialize objects of those two structures you would first add the mentioned method to each struct definition (i.e. in your header file):

struct Foo {
int a;
bool b;
double c;
std::string text;
std::vector<int> v;
void serialize(Serialization::Archive* archive);
};
struct Bar {
char one;
float two;
Foo foo1;
Foo* pFoo2;
Foo* pFoo3DontTouchMe; // shall not be serialized/deserialized
std::set<int> someSet;
std::map<double,Foo> someMap;
void serialize(Serialization::Archive* archive);
};

And then you would implement those two new methods like this (i.e. in your .cpp file):

#define SRLZ(member) \
archive->serializeMember(*this, member, #member);
void Foo::serialize(Serialization::Archive* archive) {
SRLZ(a);
SRLZ(b);
SRLZ(c);
SRLZ(text);
SRLZ(v);
}
void Bar::serialize(Serialization::Archive* archive) {
SRLZ(one);
SRLZ(two);
SRLZ(foo1);
SRLZ(pFoo2);
// leaving out pFoo3DontTouchMe here
SRLZ(someSet);
SRLZ(someMap);
}

And that's it!

Now when you serialize such a `Bar` object, this framework will also automatically serialize the respective `Foo` object(s) accordingly, also for the `pFoo2` pointer for instance (as long as it is not a `NULL` pointer that is).

Note that there is only one method that you need to implement. So the respective `serialize()` method implementation of your classes/structs are both called for serialization, as well as for deserialization! Usually you don't need to know whether your `serialize()` method was called for serialization or deserialization, however if you need to do know for some reason you can call `archive->operation()` inside your `serialize()` method to distinguish between the two.

In case you need to enforce backward incompatibility for one of your C++ classes, you can do so by setting a version and minimum version for your class (see `setVersion()` and `setMinVersion()` for details).

Definition at line 1096 of file Serialization.h.

## Member Enumeration Documentation

## operation_t

enum Serialization::Archive::operation_t

Current activity of `Archive` object.

Enumerator
OPERATION_NONE | Archive is currently neither serializing, nor deserializing.
OPERATION_SERIALIZE | Archive is currently serializing.
OPERATION_DESERIALIZE | Archive is currently deserializing.

Definition at line 1100 of file Serialization.h.

## Constructor & Destructor Documentation

## Archive() [1/3]

Serialization::Archive::Archive | ( |  | ) |

Create an "empty" archive.

This default constructor creates an "empty" archive which you then subsequently for example might fill with serialized data like:

Archive a;
a.serialize(&myRootObject);

Or:

Archive a;
a << myRootObject;

Or you might also subsequently assign an already existing non-empty to this empty archive, which effectively clones the other archive (deep copy) or call decode() later on to assign a previously serialized raw data stream.

Definition at line 1355 of file Serialization.cpp.

References Serialization::NO_UID, and OPERATION_NONE.

Referenced by deserialize().

## Archive() [2/3]

Serialization::Archive::Archive | ( | const RawData & | data | ) |

Create and fill the archive with the given serialized raw data.

This constructor decodes the given raw data and constructs a (non-empty) Archive object according to that given serialized data stream.

After this constructor returned, you may then traverse the individual objects by starting with accessing the rootObject() for example. Finally you might call deserialize() to restore your native C++ objects with the content of this archive.

Parameters

  data | - the previously serialized raw data stream to be decoded

Exceptions

  Exception | if the provided raw data uses an invalid, unknown, incompatible or corrupt data stream or format.

Definition at line 1377 of file Serialization.cpp.

References decode(), Serialization::NO_UID, and OPERATION_NONE.

## Archive() [3/3]

Serialization::Archive::Archive | ( | const uint8_t * | data,
|  | size_t | size )

Create and fill the archive with the given serialized raw C-buffer data.

This constructor essentially works like the constructor above, but just uses another data type for the serialized raw data stream being passed to this class.

This constructor decodes the given raw data and constructs a (non-empty) Archive object according to that given serialized data stream.

After this constructor returned, you may then traverse the individual objects by starting with accessing the rootObject() for example. Finally you might call deserialize() to restore your native C++ objects with the content of this archive.

Parameters

  data | - the previously serialized raw data stream to be decoded
  size | - size of data in bytes

Exceptions

  Exception | if the provided raw data uses an invalid, unknown, incompatible or corrupt data stream or format.

Definition at line 1405 of file Serialization.cpp.

References decode(), Serialization::NO_UID, and OPERATION_NONE.

## ~Archive()

Serialization::Archive::~Archive | ( |  | ) |

virtual

Definition at line 1413 of file Serialization.cpp.

## Member Function Documentation

## clear()

void Serialization::Archive::clear | ( |  | ) |

Clear content of this archive.

Drops the entire content of this archive and thus resets this archive back to become an empty archive.

Definition at line 2092 of file Serialization.cpp.

References clear(), Serialization::NO_UID, and OPERATION_NONE.

Referenced by clear().

## comment()

String Serialization::Archive::comment | ( |  | ) | const

Optional comments for this archive.

Returns the optional comments for this archive that you might have assigned to this archive before by calling setComment(). If you haven't assigned any comment to this archive before, then this method simply returns an empty string instead.

Definition at line 2134 of file Serialization.cpp.

References comment().

Referenced by comment(), and setComment().

## dateTimeCreated()

tm Serialization::Archive::dateTimeCreated | ( | time_base_t | base = LOCAL_TIME | ) | const

Date and time when this archive was initially created.

Returns a calendar time information representing the date and time when this archive was initially created. The optional base parameter may be used to define to which time zone the returned data and time shall be related to.

Parameters

  base | - (optional) time zone the result shall relate to, by default UTC time (Greenwhich Mean Time) is assumed instead

Definition at line 2198 of file Serialization.cpp.

References dateTimeCreated().

Referenced by dateTimeCreated().

## dateTimeModified()

tm Serialization::Archive::dateTimeModified | ( | time_base_t | base = LOCAL_TIME | ) | const

Date and time when this archive was modified for the last time.

Returns a calendar time information representing the date and time when this archive has been modified for the last time. The optional base parameter may be used to define to which time zone the returned date and time shall be related to.

Parameters

  base | - (optional) time zone the result shall relate to, by default UTC time (Greenwhich Mean Time) is assumed instead

Definition at line 2212 of file Serialization.cpp.

References dateTimeModified().

Referenced by dateTimeModified().

## decode() [1/2]

void Serialization::Archive::decode | ( | const RawData & | data | ) |

virtual

Fill this archive with the given serialized raw data.

Calling this method will decode the given raw data and constructs a (non-empty) Archive object according to that given serialized data stream.

After this method returned, you may then traverse the individual objects by starting with accessing the rootObject() for example. Finally you might call deserialize() to restore your native C++ objects with the content of this archive.

Parameters

  data | - the previously serialized raw data stream to be decoded

Exceptions

  Exception | if the provided raw data uses an invalid, unknown, incompatible or corrupt data stream or format.

Definition at line 2000 of file Serialization.cpp.

References decode().

Referenced by Archive(), Archive(), decode(), and decode().

## decode() [2/2]

void Serialization::Archive::decode | ( | const uint8_t * | data,
|  | size_t | size )

virtual

Fill this archive with the given serialized raw C-buffer data.

This method essentially works like the decode() method above, but just uses another data type for the serialized raw data stream being passed to this method.

Calling this method will decode the given raw data and constructs a (non-empty) Archive object according to that given serialized data stream.

After this method returned, you may then traverse the individual objects by starting with accessing the rootObject() for example. Finally you might call deserialize() to restore your native C++ objects with the content of this archive.

Parameters

  data | - the previously serialized raw data stream to be decoded
  size | - size of data in bytes

Exceptions

  Exception | if the provided raw data uses an invalid, unknown, incompatible or corrupt data stream or format.

Definition at line 2033 of file Serialization.cpp.

References decode(), and rawData().

## deserialize()

template<typename T>

void Serialization::Archive::deserialize | ( | T * | obj | ) |

inline

Initiate deserialization.

Initiates deserialization of all native C++ objects, which means all your C++ objects will be restored with the values contained in this Archive. So that also means calling deserialize() only makes sense if this a non-empty Archive, which i.e. is the case if you either called serialize() with this Archive object before or if you passed a previously serialized raw data stream to the constructor of this Archive object.

This framework has a concept of a "root" object which you must pass to this method. The root object is the starting point for deserialization of your C++ objects. The framework will then recursively deserialize all members of that C++ object an continue to deserialize all other C++ objects that it might contain or point to, according to the values stored in this Archive.

Parameters

  obj | - native C++ root object where deserialization shall start

See also
  Archive::operator>>()

Exceptions

  Exception | if the data stored in this Archive cannot be restored to the C++ objects passed to this method, i.e. because of version or type incompatibilities.

Definition at line 1172 of file Serialization.h.

References Archive(), Serialization::UID::from(), OPERATION_DESERIALIZE, and OPERATION_NONE.

Referenced by operator>>().

## encode()

void Serialization::Archive::encode | ( |  | ) |

protected virtual

Definition at line 1664 of file Serialization.cpp.

## isModified()

bool Serialization::Archive::isModified | ( |  | ) | const

Whether this archive was modified.

This method returns the current "modified" state of this archive. When either decoding a previously serialized raw data stream or after serializing native C++ objects to this archive the modified state will initially be set to `false`. However whenever you are modifying the abstract data model of this archive afterwards, for example by removing objects from this archive by calling remove() or removeMember(), or by altering object values for example by calling setIntValue(), then the "modified" state of this archive will automatically be set to `true`.

You can reset the "modified" state explicitly at any time, by calling rawData().

Definition at line 2083 of file Serialization.cpp.

References isModified().

Referenced by isModified().

## name()

String Serialization::Archive::name | ( |  | ) | const

Optional name of this archive.

Returns the optional name of this archive that you might have assigned to this archive before by calling setName(). If you haven't assigned any name to this archive before, then this method simply returns an empty string instead.

Definition at line 2108 of file Serialization.cpp.

References name().

Referenced by name(), and setName().

## objectByBaseUID()

Object & Serialization::Archive::objectByBaseUID | ( | const UID & | uid | ) |

protected

Find true object for a base pointer.

Behaves equivalent to objectByUID(), with the difference that the latter only returns an object that matches exactly the passed UID, which is fine in most situations, however when dealing with base pointers in a polymorphic scenario, then objectByUID() might fail to find the pointed object because of a slight difference in the UID, as the pointer could have been of a base type, whereas the actual object being pointed to might be of a derived, higher type. In this particular situation this method here would proceed and resolve the actual true object and return it.

Parameters

  uid | - unique identifier of sought object

Definition at line 2290 of file Serialization.cpp.

References Serialization::UID::id, objectByBaseUID(), and Serialization::UID::size.

Referenced by objectByBaseUID().

## objectByUID()

Object & Serialization::Archive::objectByUID | ( | const UID & | uid | ) |

Access object by its unique identifier.

Returns the object of this archive with the given unique identifier uid. If the given uid is invalid, or if this archive does not contain an object with the given unique identifier, then this method returns an invalid object instead.

Parameters

  uid | - unique identifier of sought object

See also
  Object for more details about the overall object reflection concept.
  Object::isValid() for valid/invalid objects
  Object::objectByBaseUID() for finding true object of a base pointer

Definition at line 2272 of file Serialization.cpp.

References objectByUID().

Referenced by objectByUID(), Serialization::DataType::registerNativeDataType(), setBoolValue(), setEnumValue(), setIntValue(), setRealValue(), setStringValue(), valueAsBool(), valueAsInt(), valueAsReal(), and valueAsString().

## operation()

Archive::operation_t Serialization::Archive::operation | ( |  | ) | const

Definition at line 2660 of file Serialization.cpp.

## operator<<()

template<typename T>

void Serialization::Archive::operator<< | ( | const T & | obj | ) |

inline

Initiate serialization of your C++ objects.

Same as calling `serialize()`, this is just meant if you prefer to use operator based code instead, which you might find to be more intuitive.

Example:

Archive a;
a << myRootObject;

See also
  Archive::serialize() for more details.

Definition at line 1196 of file Serialization.h.

References serialize().

## operator>>()

template<typename T>

void Serialization::Archive::operator>> | ( | T & | obj | ) |

inline

Initiate deserialization of your C++ objects.

Same as calling `deserialize()`, this is just meant if you prefer to use operator based code instead, which you might find to be more intuitive.

Example:

Archive a(rawDataStream);
a >> myRootObject;

Exceptions

  Exception | if the data stored in this Archive cannot be restored to the C++ objects passed to this method, i.e. because of version or type incompatibilities.

See also
  Archive::deserialize() for more details.

Definition at line 1219 of file Serialization.h.

References deserialize().

## parentObjectOf() [1/2]

Object & Serialization::Archive::parentObjectOf | ( | const Member & | member | ) |

Access parent of supplied member.

Returns the parent object that contains and owns the passed member variable. Consequently this method always returns a valid Object.

Definition at line 2326 of file Serialization.cpp.

References parentObjectOf(), and Serialization::Member::parentUID().

## parentObjectOf() [2/2]

Object & Serialization::Archive::parentObjectOf | ( | const Object & | obj | ) |

Access parent of supplied object.

If the passed object is contained within the boundaries of another object, then this method will return that parent object.

If the object is located on the heap memory (e.g. pointed by a strong pointer), then this method returns an invalid Object instead.

Definition at line 2317 of file Serialization.cpp.

References parentObjectOf(), and Serialization::Object::parentUID().

Referenced by parentObjectOf(), and parentObjectOf().

## rawData()

const RawData & Serialization::Archive::rawData | ( |  | ) |

Raw data stream of this archive content.

Call this method to get a raw data stream for the current content of this archive, which you may use to i.e. store on disk or send vie network to another machine for deserializing there. This method only returns a meaningful content if this is a non-empty archive, that is if you either serialized with this Archive object or decoded a raw data stream to this Archive object before. If this is an empty archive instead, then this method simply returns an empty raw data stream (of size 0) instead.

Note that whenever you call this method, the "modified" state of this archive will be reset to `false`.

See also
  isModified()

Definition at line 2055 of file Serialization.cpp.

References rawData().

Referenced by decode(), and rawData().

## rawDataFormat()

String Serialization::Archive::rawDataFormat | ( |  | ) | const

virtual

Name of the encoding format used by this Archive class.

This method returns the name of the encoding format used to encode serialized raw data streams.

Definition at line 2065 of file Serialization.cpp.

References rawDataFormat().

Referenced by rawDataFormat().

## remove()

void Serialization::Archive::remove | ( | const Object & | obj | ) |

Remove an object from this archive.

Removes the object @obj from this archive and sets the modified state of this archive to `true`. If the passed object is either invalid, or does not exist in this archive, then this method does nothing.

This method provides a means of "partial" deserialization. By removing either objects or members from this archive before calling deserialize(), only the remaining objects and remaining members will be restored by this framework, all other data of your C++ classes remain untouched.

Parameters

  obj | - the object to be removed from this archive

See also
  isModified() for details about the modified state.
  Object for more details about the overall object reflection concept.

Definition at line 2253 of file Serialization.cpp.

References remove(), and Serialization::Object::uid().

Referenced by remove().

## removeMember()

void Serialization::Archive::removeMember | ( | Object & | parent,
|  | const Member & | member )

Remove a member variable from the given object.

Removes the member variable member from its containing object parent and sets the modified state of this archive to `true`. If the given parent object does not contain the given member then this method does nothing.

This method provides a means of "partial" deserialization. By removing either objects or members from this archive before calling deserialize(), only the remaining objects and remaining members will be restored by this framework, all other data of your C++ classes remain untouched.

Parameters

  parent | - Object which contains member
  member | - member to be removed

See also
  isModified() for details about the modified state.
  Object for more details about the overall object reflection concept.

Definition at line 2233 of file Serialization.cpp.

References removeMember().

Referenced by removeMember().

## rootObject()

Object & Serialization::Archive::rootObject | ( |  | ) |

Root C++ object of this archive.

In case this is a non-empty Archive, then this method returns the so called "root" C++ object. If this is an empty archive, then this method returns an "invalid" Object instance instead.

See also
  Archive::serialize() for more details about the "root" object concept.
  Object for more details about the overall object reflection concept.

Returns
  reflection of the original native C++ root object

Definition at line 1426 of file Serialization.cpp.

## serialize()

template<typename T>

void Serialization::Archive::serialize | ( | const T * | obj | ) |

inline

Initiate serialization.

Initiates serialization of all native C++ objects, which means capturing and storing the current data of all your C++ objects as content of this Archive.

This framework has a concept of a "root" object which you must pass to this method. The root object is the starting point for serialization of your C++ objects. The framework will then recursively serialize all members of that C++ object an continue to serialize all other C++ objects that it might contain or point to.

After this method returned, you might traverse all serialized objects by walking them starting from the rootObject(). You might then modify that abstract reflection of your C++ objects and finally you might call rawData() to get an encoded raw data stream which you might use for sending it "over wire" to somewhere where it is going to be deserialized later on.

Note that whenever you call this method, the previous content of this Archive will first be cleared.

Parameters

  obj | - native C++ root object where serialization shall start

See also
  Archive::operator<<()

Definition at line 1137 of file Serialization.h.

References Serialization::UID::from(), OPERATION_NONE, OPERATION_SERIALIZE, and serialize().

Referenced by operator<<(), and serialize().

## serializeAnonymousObject()

template<typename T_objectType>

void Serialization::Archive::serializeAnonymousObject | ( | const T_objectType & | heapObject | ) |

inline

Serialize anonymous C/C++ data.

Serializes data that's an arbitrary memory region being pointed at, i.e. by a previously serialized native pointer variable.

NOTE: Usually this method is not called directly by applications. This method is called automatically by this framework when serializing a (non-NULL) pointer variable.

This method can be called both for anonymous data on the heap, as well as for a foreign object's member variable being pointed at.

This framework automatically identifies strong vs. weak pointers to memory regions by the general data layout being analyzed, which is important when deserializing a data stream into a native application: For identified strong pointers the respective native data is allocated and initialized automatically on deserialization. Weak pointers on the other hand just point at data contained within another, already deserialized object.

Definition at line 1402 of file Serialization.h.

References Serialization::DataType::dataTypeOf(), and Serialization::Object::parentUID().

## serializeHeapMember()

template<typename T_classType, typename T_memberType>

void Serialization::Archive::serializeHeapMember | ( | const T_classType & | nativeObject,
|  | const T_memberType & | heapMember,
|  | const char * | memberName )

inline

Serialize a C/C++ member variable allocated on the heap.

This method is essentially used by applications in the same way as `serializeMember()` above, however `serializeMember()` must only be used for native C/C++ members which are variables that are memory located within their owning parent data structures. For any variable that's located on the RAM heap though, applications must use this method instead to make it clear that there's no constant, static offset relationship between the passed member and its owning parent.

@discussion To avoid member name conflicts with native members, it is recommended to always choose member names which would be impossible as names to be declared in C/C++ code. For instance this framework uses heap member names "[0]", "[1]", "[2]", ... in its out of the box support when serializing elements of `Array<>` objects, since brackets in general cannot be used as part of variable names in C++, so using such or other special characters in heap member names, makes such naming conflicts impossible.

Parameters

  nativeObject | - native C++ object to be registered for serialization / deserialization
  heapMember | - C/C++ variable (located on the heap) of nativeObject to be registered for serialization / deserialization
  memberName | - name of heapMember to be stored with this archive; an arbitrary but unique name should be chosen which must not collide with names of native members (see discussion above)

See also
  serializeMember() for native member variables

Definition at line 1350 of file Serialization.h.

References Serialization::DataType::dataTypeOf(), Serialization::UID::from(), Serialization::Object::members(), and Serialization::Object::parentUID().

## serializeMember()

template<typename T_classType, typename T_memberType>

void Serialization::Archive::serializeMember | ( | const T_classType & | nativeObject,
|  | const T_memberType & | nativeMember,
|  | const char * | memberName )

inline

Serialize a native C/C++ member variable.

This method is usually called by the serialize() method implementation of your C/C++ structs and classes, for each of the member variables that shall be serialized and deserialized automatically with this framework. It is recommend that you are not using this method name directly, but rather define a short hand C macro in your .cpp file like:

#define SRLZ(member) \
archive->serializeMember(*this, member, #member);
struct Foo {
int a;
Bar b; // a custom struct or class having a serialize() method
std::string c;
std::vector<double> d;
void serialize(Serialization::Archive* archive);
};
void Foo::serialize(Serialization::Archive* archive) {
SRLZ(a);
SRLZ(b);
SRLZ(c);
SRLZ(d);
}

As you can see, using such a macro makes your code more readable, compact and less error prone.

It is completely up to you to decide which ones of your member variables shall automatically be serialized and deserialized with this framework. Only those member variables which are registered by calling this method will be serialized and deserialized. It does not really matter in which order you register your individiual member variables by calling this method, but the sequence is actually stored as meta information with the resulting archive and the resulting raw data stream. That meta information might then be used by this framework to automatically correct and adapt deserializing that archive later on for a future (or older) and potentially heavily modified version of your software. So it is recommended, even though also not required, that you may retain the sequence of your serializeMember() calls for your individual C++ classes' members over all your software versions, to retain backward compatibility of older archives as much as possible.

Parameters

  nativeObject | - native C++ object to be registered for serialization / deserialization
  nativeMember | - native C++ member variable of nativeObject to be registered for serialization / deserialization
  memberName | - name of nativeMember to be stored with this archive

See also
  serializeHeapMember() for variables on the RAM heap

Definition at line 1283 of file Serialization.h.

References Serialization::DataType::dataTypeOf(), Serialization::UID::from(), Serialization::Object::members(), and Serialization::Object::parentUID().

## setAutoValue()

void Serialization::Archive::setAutoValue | ( | Object & | object,
|  | String | value )

Automatically cast and assign appropriate value to object.

This method automatically converts the given value from textual string representation into the appropriate data format of the requested object. So this method is a convenient way to change values of objects in this archive with your applications in automated way, i.e. for implementing an editor where the user is able to edit values of objects in this archive by entering the values as text with a keyboard.

Exceptions

  Exception | if the passed object is not a fundamental, primitive data type or if the provided textual value cannot be converted into an appropriate value for the requested object.

Definition at line 2546 of file Serialization.cpp.

References Serialization::DataType::isBool(), Serialization::DataType::isEnum(), Serialization::DataType::isInteger(), Serialization::DataType::isReal(), Serialization::DataType::isString(), setAutoValue(), setBoolValue(), setEnumValue(), setIntValue(), setRealValue(), and setStringValue().

Referenced by setAutoValue().

## setBoolValue()

void Serialization::Archive::setBoolValue | ( | Object & | object,
|  | bool | value )

Set new boolean value for given boolean object.

Sets the new boolean value to the given boolean object.

Parameters

  object | - the boolean object to be changed
  value | - the new value to be assigned to the object

Exceptions

  Exception | if object is not a boolean type.

Definition at line 2492 of file Serialization.cpp.

References objectByUID(), setBoolValue(), Serialization::DataType::size(), and Serialization::Object::type().

Referenced by setAutoValue(), and setBoolValue().

## setComment()

void Serialization::Archive::setComment | ( | String | comment | ) |

Assign a comment to this archive.

You may optionally assign arbitrary comments to this archive. The comment will be stored along with the archive, that is it will encoded with the resulting raw data stream, and accordingly it will be decoded from the raw data stream later on.

Parameters

  comment | - arbitrary new comment for this archive

Definition at line 2147 of file Serialization.cpp.

References comment(), and setComment().

Referenced by setComment().

## setEnumValue()

void Serialization::Archive::setEnumValue | ( | Object & | object,
|  | uint64_t | value )

Set new value for given `enum` object.

Sets the new value to the given `enum` object.

Parameters

  object | - the `enum` object to be changed
  value | - the new value to be assigned to the object

Exceptions

  Exception | if object is not an `enum` type.

Definition at line 2370 of file Serialization.cpp.

References objectByUID(), setEnumValue(), Serialization::DataType::size(), and Serialization::Object::type().

Referenced by setAutoValue(), and setEnumValue().

## setIntValue()

void Serialization::Archive::setIntValue | ( | Object & | object,
|  | int64_t | value )

Set new integer value for given integer object.

Sets the new integer value to the given integer object. Currently this framework handles any integer data type up to 64 bit. For larger integer types an assertion failure will be raised.

Parameters

  object | - the integer object to be changed
  value | - the new value to be assigned to the object

Exceptions

  Exception | if object is not an integer type.

Definition at line 2412 of file Serialization.cpp.

References Serialization::DataType::isSigned(), objectByUID(), setIntValue(), Serialization::DataType::size(), and Serialization::Object::type().

Referenced by setAutoValue(), and setIntValue().

## setMinVersion() [1/2]

template<typename T_classType>

void Serialization::Archive::setMinVersion | ( | const T_classType & | nativeObject,
|  | Version | v )

inline

Set a minimum version number for your C++ class.

Call this method to define a minimum version that your current C++ class implementation would be compatible with when it comes to deserialization of an archive containing an object of your C++ class. Like the version information, the minimum version will also be stored for objects of your C++ class with the resulting archive (and its resulting raw data stream respectively).

When you start to constrain version compatibility of your C++ class you usually start by using 1 as version and 1 as minimum version. So it is eligible to set the same number to both version and minimum version. However you must not set a minimum version higher than version. Doing so would not raise an exception, but the resulting behavior would be undefined.

It is not relevant whether you first set version and then minimum version or vice versa. It is also not relevant when exactly you set those two numbers, even though usually you would set both in your serialize() method implementation.

See also
  `setVersion()` for more details about this overall topic.

Parameters

  nativeObject | - your C++ object you want to set a version for
  v | - the minimum version you want to define for your C++ class (by default, that is if you do not explicitly call this method, then a minium version of `0` is assumed for your C++ class instead).

Definition at line 1544 of file Serialization.h.

References Serialization::DataType::dataTypeOf(), Serialization::UID::from(), and setMinVersion().

Referenced by setMinVersion(), and setMinVersion().

## setMinVersion() [2/2]

void Serialization::Archive::setMinVersion | ( | Object & | object,
|  | Version | v )

Set the minimum version for the given object.

Essentially behaves like above's setMinVersion() method, it just uses the abstract reflection data type instead for the respective object being passed to this method. Refer to above's setMinVersion() documentation about the precise behavior details of setMinVersion().

Parameters

  object | - object to set the minimum version for
  v | - new minimum version to set for object

Definition at line 2356 of file Serialization.cpp.

References setMinVersion().

## setName()

void Serialization::Archive::setName | ( | String | name | ) |

Assign a name to this archive.

You may optionally assign an arbitrary name to this archive. The name will be stored along with the archive, that is it will encoded with the resulting raw data stream, and accordingly it will be decoded from the raw data stream later on.

Parameters

  name | - arbitrary new name for this archive

Definition at line 2121 of file Serialization.cpp.

References name(), and setName().

Referenced by setName().

## setRealValue()

void Serialization::Archive::setRealValue | ( | Object & | object,
|  | double | value )

Set new floating point value for given floating point object.

Sets the new floating point value to the given floating point object. Currently this framework supports single precision `float` and double precision `double` floating point data types. For all other floating point types this method will raise an assertion failure.

Parameters

  object | - the floating point object to be changed
  value | - the new value to be assigned to the object

Exceptions

  Exception | if object is not a floating point based type.

Definition at line 2462 of file Serialization.cpp.

References objectByUID(), setRealValue(), Serialization::DataType::size(), and Serialization::Object::type().

Referenced by setAutoValue(), and setRealValue().

## setStringValue()

void Serialization::Archive::setStringValue | ( | Object & | object,
|  | String | value )

Set new textual string for given String object.

Sets the new textual string value to the given String object.

Parameters

  object | - the String object to be changed
  value | - the new textual string to be assigned to the object

Exceptions

  Exception | if object is not a String type.

Definition at line 2517 of file Serialization.cpp.

References objectByUID(), and setStringValue().

Referenced by setAutoValue(), and setStringValue().

## setVersion() [1/2]

template<typename T_classType>

void Serialization::Archive::setVersion | ( | const T_classType & | nativeObject,
|  | Version | v )

inline

Set current version number for your C++ class.

By calling this method you can define a version number for your current C++ class (that is a version for its current data structure layout and method implementations) that is going to be stored along with the serialized archive. Only call this method if you really want to constrain compatibility of your C++ class.

Along with calling `setMinVersion()` this provides a way for you to constrain backward compatibility regarding serialization and deserialization of your C++ class which the Archive class will obey to. If required, then typically you might do so in your `serialize()` method implementation like:

#define SRLZ(member) \
archive->serializeMember(*this, member, #member);
struct Foo {
int a;
Bar b; // a custom struct or class having a serialize() method
std::string c;
std::vector<double> d;
void serialize(Serialization::Archive* archive);
};
void Foo::serialize(Serialization::Archive* archive) {
// when serializing: the current version of this class that is
// going to be stored with the serialized archive
archive->setVersion(*this, 6);
// when deserializing: the minimum version this C++ class is
// compatible with
archive->setMinVersion(*this, 3);
// actual data mebers to serialize / deserialize
SRLZ(a);
SRLZ(b);
SRLZ(c);
SRLZ(d);
}
Serialization::Archive::setMinVersion
void setMinVersion(const T_classType &nativeObject, Version v)
Set a minimum version number for your C++ class.
Definition Serialization.h:1544
Serialization::Archive::setVersion
void setVersion(const T_classType &nativeObject, Version v)
Set current version number for your C++ class.
Definition Serialization.h:1503

In this example above, the C++ class "Foo" would be serialized along with the version number `6` and minimum version `3` as additional meta information in the resulting archive (and its raw data stream respectively).

When deserializing archives with the example C++ class code above, the Archive object would check whether your originally serialized C++ "Foo" object had at least version number `3`, if not the deserialization process would automatically be stopped with a `Serialization::Exception`, claiming that the classes are version incompatible.

But also consider the other way around: you might have serialized your latest version of your C++ class, and might deserialize that archive with an older version of your C++ class. In that case it will likewise be checked whether the version of that old C++ class is at least as high as the minimum version set with the already seralized bleeding edge C++ class.

Since this Serialization / deserialization framework is designed to be robust on changes to your C++ classes and aims trying to deserialize all your C++ objects correctly even if your C++ classes have seen substantial software changes in the meantime; you might sometimes see it as necessary to constrain backward compatibility this way. Because obviously there are certain things this framework can cope with, like for example that you renamed a data member while keeping the layout consistent, or that you have added new members to your C++ class or simply changed the order of your members in your C++ class. But what this framework cannot detect is for example if you changed the semantics of the values stored with your members, or even substantially changed the algorithms in your class methods such that they would not handle the data of your C++ members in the same and correct way anymore.

Parameters

  nativeObject | - your C++ object you want to set a version for
  v | - the version number to set for your C++ class (by default, that is if you do not explicitly call this method, then your C++ object will be stored with version number `0` ).

Definition at line 1503 of file Serialization.h.

References Serialization::DataType::dataTypeOf(), Serialization::UID::from(), and setVersion().

Referenced by setVersion(), and setVersion().

## setVersion() [2/2]

void Serialization::Archive::setVersion | ( | Object & | object,
|  | Version | v )

Set the current version for the given object.

Essentially behaves like above's setVersion() method, it just uses the abstract reflection data type instead for the respective object being passed to this method. Refer to above's setVersion() documentation about the precise behavior details of setVersion().

Parameters

  object | - object to set the current version for
  v | - new current version to set for object

Definition at line 2340 of file Serialization.cpp.

References setVersion().

## timeStampCreated()

time_t Serialization::Archive::timeStampCreated | ( |  | ) | const

Date and time when this archive was initially created.

Returns a UTC time stamp (date and time) when this archive was initially created.

Definition at line 2175 of file Serialization.cpp.

References timeStampCreated().

Referenced by timeStampCreated().

## timeStampModified()

time_t Serialization::Archive::timeStampModified | ( |  | ) | const

Date and time when this archive was modified for the last time.

Returns a UTC time stamp (date and time) when this archive was modified for the last time.

Definition at line 2184 of file Serialization.cpp.

References timeStampModified().

Referenced by timeStampModified().

## valueAsBool()

bool Serialization::Archive::valueAsBool | ( | const Object & | object | ) |

Get boolean value of object.

Returns the current boolean value of the requested boolean object.

Parameters

  object | - object whose value shall be retrieved

Exceptions

  Exception | if the given object is either invalid, or if the object is not a boolean data type.

Definition at line 2646 of file Serialization.cpp.

References objectByUID(), and valueAsBool().

Referenced by valueAsBool().

## valueAsInt()

int64_t Serialization::Archive::valueAsInt | ( | const Object & | object | ) |

Get integer value of object.

Returns the current integer value of the requested integer object or `enum` object.

Parameters

  object | - object whose value shall be retrieved

Exceptions

  Exception | if the given object is either invalid, or if the object is neither an integer nor `enum` data type.

Definition at line 2601 of file Serialization.cpp.

References objectByUID(), and valueAsInt().

Referenced by valueAsInt().

## valueAsReal()

double Serialization::Archive::valueAsReal | ( | const Object & | object | ) |

Get floating point value of object.

Returns the current floating point value of the requested floating point object.

Parameters

  object | - object whose value shall be retrieved

Exceptions

  Exception | if the given object is either invalid, or if the object is not a floating point based type.

Definition at line 2624 of file Serialization.cpp.

References objectByUID(), and valueAsReal().

Referenced by valueAsReal().

## valueAsString()

String Serialization::Archive::valueAsString | ( | const Object & | object | ) |

Get value of object as string.

Converts the current value of the given object into a textual string and returns that string.

Parameters

  object | - object whose value shall be retrieved

Exceptions

  Exception | if the given object is either invalid, or if the object is not a fundamental, primitive data type.

Definition at line 2578 of file Serialization.cpp.

References objectByUID(), and valueAsString().

Referenced by valueAsString().

## Member Data Documentation

## m_allObjects

ObjectPool Serialization::Archive::m_allObjects

protected

Definition at line 1989 of file Serialization.h.

## m_comment

String Serialization::Archive::m_comment

protected

Definition at line 1995 of file Serialization.h.

## m_isModified

bool Serialization::Archive::m_isModified

protected

Definition at line 1993 of file Serialization.h.

## m_name

String Serialization::Archive::m_name

protected

Definition at line 1994 of file Serialization.h.

## m_operation

operation_t Serialization::Archive::m_operation

protected

Definition at line 1990 of file Serialization.h.

## m_rawData

RawData Serialization::Archive::m_rawData

protected

Definition at line 1992 of file Serialization.h.

## m_root

UID Serialization::Archive::m_root

protected

Definition at line 1991 of file Serialization.h.

## m_timeCreated

time_t Serialization::Archive::m_timeCreated

protected

Definition at line 1996 of file Serialization.h.

## m_timeModified

time_t Serialization::Archive::m_timeModified

protected

Definition at line 1997 of file Serialization.h.

The documentation for this class was generated from the following files:

- Serialization.h
- Serialization.cpp