libgig  4.4.1
Classes | Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
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. More...
 
 Archive (const RawData &data)
 Create and fill the archive with the given serialized raw data. More...
 
 Archive (const uint8_t *data, size_t size)
 Create and fill the archive with the given serialized raw C-buffer data. More...
 
template<typename T >
void serialize (const T *obj)
 Initiate serialization. More...
 
template<typename T >
void deserialize (T *obj)
 Initiate deserialization. More...
 
template<typename T >
void operator<< (const T &obj)
 Initiate serialization of your C++ objects. More...
 
template<typename T >
void operator>> (T &obj)
 Initiate deserialization of your C++ objects. More...
 
const RawData & rawData ()
 Raw data stream of this archive content. More...
 
virtual String rawDataFormat () const
 Name of the encoding format used by this Archive class. More...
 
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. More...
 
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. More...
 
template<typename T_classType >
void setVersion (const T_classType &nativeObject, Version v)
 Set current version number for your C++ class. More...
 
template<typename T_classType >
void setMinVersion (const T_classType &nativeObject, Version v)
 Set a minimum version number for your C++ class. More...
 
virtual void decode (const RawData &data)
 Fill this archive with the given serialized raw data. More...
 
virtual void decode (const uint8_t *data, size_t size)
 Fill this archive with the given serialized raw C-buffer data. More...
 
void clear ()
 Clear content of this archive. More...
 
bool isModified () const
 Whether this archive was modified. More...
 
void removeMember (Object &parent, const Member &member)
 Remove a member variable from the given object. More...
 
void remove (const Object &obj)
 Remove an object from this archive. More...
 
Object & rootObject ()
 Root C++ object of this archive. More...
 
Object & objectByUID (const UID &uid)
 Access object by its unique identifier. More...
 
void setAutoValue (Object &object, String value)
 Automatically cast and assign appropriate value to object. More...
 
void setIntValue (Object &object, int64_t value)
 Set new integer value for given integer object. More...
 
void setRealValue (Object &object, double value)
 Set new floating point value for given floating point object. More...
 
void setBoolValue (Object &object, bool value)
 Set new boolean value for given boolean object. More...
 
void setEnumValue (Object &object, uint64_t value)
 Set new value for given enum object. More...
 
void setStringValue (Object &object, String value)
 Set new textual string for given String object. More...
 
String valueAsString (const Object &object)
 Get value of object as string. More...
 
int64_t valueAsInt (const Object &object)
 Get integer value of object. More...
 
double valueAsReal (const Object &object)
 Get floating point value of object. More...
 
bool valueAsBool (const Object &object)
 Get boolean value of object. More...
 
void setVersion (Object &object, Version v)
 Set the current version for the given object. More...
 
void setMinVersion (Object &object, Version v)
 Set the minimum version for the given object. More...
 
String name () const
 Optional name of this archive. More...
 
void setName (String name)
 Assign a name to this archive. More...
 
String comment () const
 Optional comments for this archive. More...
 
void setComment (String comment)
 Assign a comment to this archive. More...
 
time_t timeStampCreated () const
 Date and time when this archive was initially created. More...
 
time_t timeStampModified () const
 Date and time when this archive was modified for the last time. More...
 
tm dateTimeCreated (time_base_t base=LOCAL_TIME) const
 Date and time when this archive was initially created. More...
 
tm dateTimeModified (time_base_t base=LOCAL_TIME) const
 Date and time when this archive was modified for the last time. More...
 
operation_t operation () const
 

Protected Member Functions

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
 

Friends

String _encode (const ObjectPool &objects)
 

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);

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);

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);

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 897 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 901 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 1257 of file Serialization.cpp.

References Serialization::NO_UID.

◆ 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
Exceptionif the provided raw data uses an invalid, unknown, incompatible or corrupt data stream or format.

Definition at line 1279 of file Serialization.cpp.

References Serialization::NO_UID.

◆ 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
Exceptionif the provided raw data uses an invalid, unknown, incompatible or corrupt data stream or format.

Definition at line 1307 of file Serialization.cpp.

References Serialization::NO_UID.

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 1979 of file Serialization.cpp.

References Serialization::NO_UID.

◆ 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 2021 of file Serialization.cpp.

◆ 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 2085 of file Serialization.cpp.

◆ 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 2099 of file Serialization.cpp.

◆ 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
Exceptionif the provided raw data uses an invalid, unknown, incompatible or corrupt data stream or format.

Definition at line 1887 of file Serialization.cpp.

◆ 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
Exceptionif the provided raw data uses an invalid, unknown, incompatible or corrupt data stream or format.

Definition at line 1920 of file Serialization.cpp.

◆ 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
Exceptionif 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 973 of file Serialization.h.

References Serialization::UID::from().

◆ 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 1970 of file Serialization.cpp.

◆ 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 1995 of file Serialization.cpp.

◆ 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

Definition at line 2158 of file Serialization.cpp.

Referenced by setMinVersion().

◆ 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 997 of file Serialization.h.

◆ 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
Exceptionif 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 1020 of file Serialization.h.

◆ 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 1942 of file Serialization.cpp.

◆ 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 1952 of file Serialization.cpp.

◆ remove()

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

Remove an object from this archive.

Removes the object 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 2140 of file Serialization.cpp.

References Serialization::Object::uid().

◆ 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 2120 of file Serialization.cpp.

◆ 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 1328 of file Serialization.cpp.

References Serialization::DataType::baseTypeName(), Serialization::DataType::customTypeName(), Serialization::DataType::customTypeName2(), Serialization::UID::id, Serialization::DataType::isBool(), Serialization::DataType::isEnum(), Serialization::DataType::isInteger(), Serialization::DataType::isPointer(), Serialization::DataType::isPrimitive(), Serialization::DataType::isReal(), Serialization::DataType::isSigned(), Serialization::DataType::isString(), Serialization::UID::isValid(), Serialization::Object::members(), Serialization::Object::minVersion(), Serialization::Member::name(), Serialization::Member::offset(), Serialization::UID::size, Serialization::DataType::size(), Serialization::Member::type(), Serialization::Object::type(), Serialization::Member::uid(), Serialization::Object::uid(), Serialization::Object::uidChain(), and Serialization::Object::version().

Referenced by valueAsBool().

◆ 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 938 of file Serialization.h.

References Serialization::UID::from().

◆ 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.

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 1142 of file Serialization.h.

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

Referenced by setMinVersion().

◆ 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 1084 of file Serialization.h.

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

◆ 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
Exceptionif 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 2378 of file Serialization.cpp.

References Serialization::DataType::isBool(), Serialization::DataType::isEnum(), Serialization::DataType::isInteger(), Serialization::DataType::isReal(), and Serialization::DataType::isString().

◆ 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
Exceptionif object is not a boolean type.

Definition at line 2324 of file Serialization.cpp.

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

◆ 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 2034 of file Serialization.cpp.

References Serialization::LOCAL_TIME, and Serialization::UTC_TIME.

◆ 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
Exceptionif object is not an enum type.

Definition at line 2202 of file Serialization.cpp.

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

◆ 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
Exceptionif object is not an integer type.

Definition at line 2244 of file Serialization.cpp.

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

◆ 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 1288 of file Serialization.h.

References Serialization::DataType::dataTypeOf(), Serialization::UID::from(), Serialization::UID::isValid(), Serialization::LOCAL_TIME, Serialization::Object::memberNamed(), Serialization::Object::members(), Serialization::Member::name(), objectByUID(), serializeHeapMember(), Serialization::Object::setNativeValueFromString(), Serialization::UID::size, and Serialization::Object::uid().

◆ 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 2188 of file Serialization.cpp.

◆ 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 2008 of file Serialization.cpp.

◆ 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
Exceptionif object is not a floating point based type.

Definition at line 2294 of file Serialization.cpp.

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

◆ 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
Exceptionif object is not a String type.

Definition at line 2349 of file Serialization.cpp.

◆ 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);
}

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 1247 of file Serialization.h.

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

◆ 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 2172 of file Serialization.cpp.

◆ 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 2062 of file Serialization.cpp.

◆ 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 2071 of file Serialization.cpp.

◆ 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
Exceptionif the given object is either invalid, or if the object is not a boolean data type.

Definition at line 2478 of file Serialization.cpp.

References Serialization::DataType::asLongDescr(), Serialization::UID::id, Serialization::DataType::isArray(), Serialization::DataType::isClass(), Serialization::DataType::isMap(), Serialization::DataType::isPointer(), Serialization::DataType::isPrimitive(), Serialization::DataType::isSet(), Serialization::DataType::isString(), Serialization::Object::isVersionCompatibleTo(), Serialization::Object::memberNamed(), Serialization::Object::members(), Serialization::Object::membersOfType(), Serialization::Object::minVersion(), Serialization::Member::name(), Serialization::Member::offset(), Serialization::Object::rawData(), rootObject(), Serialization::Object::sequenceIndexOf(), Serialization::DataType::size(), Serialization::Member::type(), Serialization::Object::type(), Serialization::Member::uid(), Serialization::Object::uid(), and Serialization::Object::version().

◆ 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
Exceptionif the given object is either invalid, or if the object is neither an integer nor enum data type.

Definition at line 2433 of file Serialization.cpp.

◆ 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
Exceptionif the given object is either invalid, or if the object is not a floating point based type.

Definition at line 2456 of file Serialization.cpp.

◆ 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
Exceptionif the given object is either invalid, or if the object is not a fundamental, primitive data type.

Definition at line 2410 of file Serialization.cpp.

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