libgig  4.1.0.svn2
Serialization Namespace Reference

Serialization / deserialization framework. More...

Classes

class  Archive
 Destination container for serialization, and source container for deserialization. More...
 
class  DataType
 Abstract reflection of a native C++ data type. More...
 
class  Exception
 Will be thrown whenever an error occurs during an serialization or deserialization process. More...
 
class  Member
 Abstract reflection of a native C++ class/struct's member variable. More...
 
class  Object
 Abstract reflection of some native serialized C/C++ data. More...
 
class  UID
 Unique identifier referring to one specific native C++ object, member, fundamental variable, or any other native C++ data. More...
 

Typedefs

typedef std::string String
 
typedef std::vector< uint8_t > RawData
 Raw data stream of serialized C++ objects. More...
 
typedef void * ID
 Abstract identifier for serialized C++ objects. More...
 
typedef uint32_t Version
 Version number data type. More...
 
typedef std::vector< UIDUIDChain
 Chain of UIDs. More...
 

Enumerations

enum  time_base_t { LOCAL_TIME, UTC_TIME }
 To which time zone a certain timing information relates to. More...
 

Functions

template<typename T >
bool IsEnum (const T &data)
 Check whether data is a C/C++ enum type. More...
 
template<typename T >
bool IsUnion (const T &data)
 Check whether data is a C++ union type. More...
 
template<typename T >
bool IsClass (const T &data)
 Check whether data is a C/C++ struct or C++ class type. More...
 
String _encode (const Archive::ObjectPool &objects)
 

Variables

const UID NO_UID = _createNullUID()
 Reflects an invalid UID and behaves similar to NULL as invalid value for pointer types. More...
 

Detailed Description

Serialization / deserialization framework.

See class Archive as starting point for how to implement serialization and deserialization with your application.

The classes in this namespace allow to serialize and deserialize native C++ objects in a portable, easy and flexible way. Serialization is a technique that allows to transform the current state and data of native (in this case C++) objects into a data stream (including all other objects the "serialized" objects relate to); the data stream may then be sent over "wire" (for example via network connection to another computer, which might also have a different OS, CPU architecture, native memory word size and endian type); and finally the data stream would be "deserialized" on that receiver side, that is transformed again to modify all objects and data structures on receiver side to resemble the objects' state and data as it was originally on sender side.

In contrast to many other already existing serialization frameworks, this implementation has a strong focus on robustness regarding long-term changes to the serialized C++ classes of the serialized objects. So even if sender and receiver are using different versions of their serialized/deserialized C++ classes, structures and data types (thus having different data structure layout to a certain extent), this framework aims trying to automatically adapt its serialization and deserialization process in that case so that the deserialized objects on receiver side would still reflect the overall expected states and overall data as intended by the sender. For being able to do so, this framework stores all kind of additional information about each serialized object and each data structure member (for example name of each data structure member, but also the offset of each member within its containing data structure, precise data types, and more).

Like most other serialization frameworks, this frameworks does not require a tree-structured layout of the serialized data structures. So it automatically handles also cyclic dependencies between serialized data structures correctly, without i.e. causing endless recursion or redundancy.

Additionally this framework also allows partial deserialization. Which means the receiver side may for example decide that it wants to restrict deserialization so that it would only modify certain objects or certain members by the deserialization process, leaving all other ones untouched. So this partial deserialization technique for example allows to implement flexible preset features for applications in a powerful and easy way.

Typedef Documentation

typedef void* Serialization::ID

Abstract identifier for serialized C++ objects.

This data type is used for identifying serialized C++ objects and members of your C++ objects. It is important to know that such an ID might not necessarily be unique. For example the ID of one C++ object might often be identical to the ID of the first member of that particular C++ object. That's why there is additionally the concept of an UID in this framework.

See also
UID

Definition at line 142 of file Serialization.h.

typedef std::vector<uint8_t> Serialization::RawData

Raw data stream of serialized C++ objects.

This data type is used for the data stream as a result of serializing your C++ objects with Archive::serialize(), and for native raw data representation of individual serialized C/C++ objects, members and variables.

See also
Archive::rawData(), Object::rawData()

Definition at line 130 of file Serialization.h.

typedef std::vector<UID> Serialization::UIDChain

Chain of UIDs.

This data type is used for native C++ pointers. The first member of the UID chain is the unique identifier of the C++ pointer itself, then the following UIDs are the respective objects or variables the pointer is pointing to. The size (the amount of elements) of the UIDChain depends solely on the degree of the pointer type. For example the following C/C++ pointer:

int* pNumber;

is an integer pointer of first degree. Such a pointer would have a UIDChain with 2 members: the first element would be the UID of the pointer itself, the second element of the chain would be the integer data that pointer is pointing to. In the following example:

bool*** pppSomeFlag;

That boolean pointer would be of third degree, and thus its UIDChain would have a size of 4 (elements).

Accordingly a non pointer type like:

float f;

would yield in a UIDChain of size 1.

Since however this serialization framework currently only supports pointers of first degree yet, all UIDChains are currently either of size 1 or 2, which might change in future though.

Definition at line 324 of file Serialization.h.

typedef uint32_t Serialization::Version

Version number data type.

This data type is used for maintaining version number information of your C++ class implementations.

See also
Archive::setVersion() and Archive::setMinVersion()

Definition at line 151 of file Serialization.h.

Enumeration Type Documentation

To which time zone a certain timing information relates to.

The constants in this enum type are used to define to which precise time zone a time stamp relates to.

Enumerator
LOCAL_TIME 

The time stamp relates to the machine's local time zone. Request a time stamp in local time if you want to present that time stamp to the end user.

UTC_TIME 

The time stamp relates to "Greenwhich Mean Time" zone, also known as "Coordinated Universal Time". Request time stamp with UTC if you want to compare that time stamp with other time stamps.

Definition at line 158 of file Serialization.h.

Function Documentation

template<typename T >
bool Serialization::IsClass ( const T &  data)

Check whether data is a C/C++ struct or C++ class type.

Returns true if the supplied C++ variable or object is of C/C++ struct or C++ class type. Note that if you are using a C++ compiler which does have built-in type traits support, then this function will also return true on C/C++ union types.

Parameters
data- the variable or object whose data type shall be checked

Definition at line 208 of file Serialization.h.

template<typename T >
bool Serialization::IsEnum ( const T &  data)

Check whether data is a C/C++ enum type.

Returns true if the supplied C++ variable or object is of a C/C++ enum type.

Parameters
data- the variable or object whose data type shall be checked

Definition at line 171 of file Serialization.h.

template<typename T >
bool Serialization::IsUnion ( const T &  data)

Check whether data is a C++ union type.

Returns true if the supplied C++ variable or object is of a C/C++ union type. Note that the result of this function is only reliable if the C++ compiler you are using has support for built-in type traits. If your C++ compiler does not have built-in type traits support, then this function will simply return false on all your calls.

Parameters
data- the variable or object whose data type shall be checked

Definition at line 190 of file Serialization.h.

Variable Documentation

const UID Serialization::NO_UID = _createNullUID()

Reflects an invalid UID and behaves similar to NULL as invalid value for pointer types.

All UID objects are first initialized with this value, and it essentially an all zero object.

Definition at line 50 of file Serialization.cpp.

Referenced by Serialization::Archive::Archive(), Serialization::Archive::clear(), and Serialization::Member::Member().