![]() | ![]() | Gwyddion Library Reference Manual | ![]() |
---|
GwySerializable — Abstract interface for serializable objects.
struct GwySerializableIface; struct GwySerializable; GByteArray* (*GwySerializeFunc) (GObject *serializable, GByteArray *buffer); GObject* (*GwyDeserializeFunc) (const guchar *buffer, gsize size, gsize *position); GObject* (*GwyDuplicateFunc) (GObject *object); struct GwySerializeSpec; GByteArray* gwy_serializable_serialize (GObject *serializable, GByteArray *buffer); GObject* gwy_serializable_deserialize (const guchar *buffer, gsize size, gsize *position); GObject* gwy_serializable_duplicate (GObject *object); void gwy_serialize_store_int32 (GByteArray *buffer, gsize position, guint32 value); GByteArray* gwy_serialize_pack (GByteArray *buffer, const gchar *templ, ...); gboolean gwy_serialize_unpack_boolean (const guchar *buffer, gsize size, gsize *position); guchar gwy_serialize_unpack_char (const guchar *buffer, gsize size, gsize *position); guchar* gwy_serialize_unpack_char_array (const guchar *buffer, gsize size, gsize *position, gsize *asize); gint32 gwy_serialize_unpack_int32 (const guchar *buffer, gsize size, gsize *position); gint32* gwy_serialize_unpack_int32_array (const guchar *buffer, gsize size, gsize *position, gsize *asize); gint64 gwy_serialize_unpack_int64 (const guchar *buffer, gsize size, gsize *position); gint64* gwy_serialize_unpack_int64_array (const guchar *buffer, gsize size, gsize *position, gsize *asize); gdouble gwy_serialize_unpack_double (const guchar *buffer, gsize size, gsize *position); gdouble* gwy_serialize_unpack_double_array (const guchar *buffer, gsize size, gsize *position, gsize *asize); guchar* gwy_serialize_unpack_string (const guchar *buffer, gsize size, gsize *position); gsize gwy_serialize_check_string (const guchar *buffer, gsize size, gsize position, const guchar *compare_to); GByteArray* gwy_serialize_pack_struct (GByteArray *buffer, gsize nspec, const GwySerializeSpec *spec); gboolean gwy_serialize_unpack_struct (const guchar *buffer, gsize size, gsize nspec, const GwySerializeSpec *spec); GByteArray* gwy_serialize_pack_object_struct (GByteArray *buffer, const guchar *object_name, gsize nspec, const GwySerializeSpec *spec); gboolean gwy_serialize_unpack_object_struct (const guchar *buffer, gsize size, gsize *position, const guchar *object_name, gsize nspec, const GwySerializeSpec *spec);
GwySerializable is an abstract interface for value-like object that can be serialized and deserialized. You can serialize any object implementing this interface with gwy_serializable_serialize() and the restore (deserialize) it with gwy_serializable_deserialize(). It is also posible it duplicate any such object with gwy_serializable_duplicate().
There are quite a few helper functions available for implementation of serialization and deserialization in your classes, most high-level (and thus probably most useful) are gwy_serialize_pack_object_struct() and gwy_serialize_unpack_object_struct() that do all the hard work themselves and are sufficient for serialization of simple objects. Even if you don not use these functions, you should keep object name and serialized data length in the same format as they do in new objects, to allow old Gwyddion versions to safely ignore (skip) these new objects.
struct GwySerializableIface { GTypeInterface parent_class; GwySerializeFunc serialize; GwyDeserializeFunc deserialize; GwyDuplicateFunc duplicate; };
GByteArray* (*GwySerializeFunc) (GObject *serializable, GByteArray *buffer);
The type of serialization method, see gwy_serializable_serialize() for description.
serializable : | An object to serialize. |
buffer : | A buffer to append the representation to, may be NULL indicating a new one should be allocated. |
Returns : | buffer with serialized object appended. |
GObject* (*GwyDeserializeFunc) (const guchar *buffer, gsize size, gsize *position);
The type of deserialization method, see gwy_serializable_deserialize() for description.
buffer : | A buffer containing a serialized object. |
size : | The size of buffer. |
position : | The current position in buffer. |
Returns : | A newly created (restored) object. |
GObject* (*GwyDuplicateFunc) (GObject *object);
The type of duplication method, see gwy_serializable_duplicate() for description.
object : | An object to duplicate. |
Returns : | A copy of object. |
struct GwySerializeSpec { guchar ctype; const guchar *name; gpointer value; guint32 *array_size; };
A structure containing information for one object/struct component serialization or deserialization.
guchar ctype | Component type, as in gwy_serialize_pack(). |
const guchar *name | Component name as a null terminated string. |
gpointer value | Pointer to component (always add one level of indirection; for an object, a GObject** pointer should be stored). |
guint32 *array_size | Pointer to array size if component is an array, NULL otherwise. |
GByteArray* gwy_serializable_serialize (GObject *serializable, GByteArray *buffer);
Serializes an object implementing GwySerializable interface.
serializable : | A GObject implementing GwySerializable interface. |
buffer : | A buffer to which the serialized object should be appended, or NULL. |
Returns : | buffer or a newly allocated GByteArray with serialized object appended. |
GObject* gwy_serializable_deserialize (const guchar *buffer, gsize size, gsize *position);
Restores a serialized object.
The newly created object has reference count according to its nature, thus a GtkObject will have a floating reference, a GObject will have a refcount of 1, etc.
buffer : | A block of memory of size size contaning object representation. |
size : | The size of buffer. |
position : | The position of the object in buffer, it's updated to point after it. |
Returns : | A newly created object. |
GObject* gwy_serializable_duplicate (GObject *object);
Creates a copy of object object.
If the object doesn't support duplication natively, it's brute-force serialized and then deserialized, this may be quite inefficient, namely for large objects.
You can duplicate a NULL, too, but you are discouraged from doing it.
object : | A GObject implementing GwySerializable interface. |
Returns : | The newly created object copy. However if the object is a singleton, object itself (with incremented reference count) can be returned, too. |
void gwy_serialize_store_int32 (GByteArray *buffer, gsize position, guint32 value);
Stores a 32bit integer to a buffer.
buffer : | A buffer to which the value should be stored. |
position : | Position in the buffer to store value to. |
value : | A 32bit integer. |
GByteArray* gwy_serialize_pack (GByteArray *buffer, const gchar *templ, ...);
Serializes a list of plain atomic types.
The templ string can contain following characters:
'b' for a a boolean, 'c' for a character, 'i' for a 32bit integer, 'q' for a 64bit integer, 'd' for a double, 's' for a null-terminated string.
'C' for a character array (a gsize length followed by a pointer to the array), 'I' for a 32bit integer array, 'Q' for a 64bit integer array, 'D' for a double array.
'o' for a serializable object.
FIXME: this function currently doesn't create architecture-independent representations, it just copies the memory.
buffer : | A buffer to which the serialized values should be appended, or NULL. |
templ : | A template string. |
... : | A list of atomic values to serialize. |
Returns : | buffer or a newly allocated GByteArray with serialization of given values appended. |
gboolean gwy_serialize_unpack_boolean (const guchar *buffer, gsize size, gsize *position);
Deserializes a one boolean.
buffer : | A memory location containing a serialized boolean at position position. |
size : | The size of buffer. |
position : | The position of the character in buffer, it's updated to point after it. |
Returns : | The boolean as gboolean. |
guchar gwy_serialize_unpack_char (const guchar *buffer, gsize size, gsize *position);
Deserializes a one character.
buffer : | A memory location containing a serialized character at position position. |
size : | The size of buffer. |
position : | The position of the character in buffer, it's updated to point after it. |
Returns : | The character as guchar. |
guchar* gwy_serialize_unpack_char_array (const guchar *buffer, gsize size, gsize *position, gsize *asize);
Deserializes a character array.
buffer : | A memory location containing a serialized character array at position position. |
size : | The size of buffer. |
position : | The position of the array in buffer, it's updated to point after it. |
asize : | Where the size of the array is to be returned. |
Returns : | The unpacked character array (newly allocated). |
gint32 gwy_serialize_unpack_int32 (const guchar *buffer, gsize size, gsize *position);
Deserializes a one 32bit integer.
buffer : | A memory location containing a serialized 32bit integer at position position. |
size : | The size of buffer. |
position : | The position of the integer in buffer, it's updated to point after it. |
Returns : | The integer as gint32. |
gint32* gwy_serialize_unpack_int32_array (const guchar *buffer, gsize size, gsize *position, gsize *asize);
Deserializes an int32 array.
buffer : | A memory location containing a serialized int32 array at position position. |
size : | The size of buffer. |
position : | The position of the array in buffer, it's updated to point after it. |
asize : | Where the size of the array is to be returned. |
Returns : | The unpacked 32bit integer array (newly allocated). |
gint64 gwy_serialize_unpack_int64 (const guchar *buffer, gsize size, gsize *position);
Deserializes a one 64bit integer.
buffer : | A memory location containing a serialized 64bit integer at position position. |
size : | The size of buffer. |
position : | The position of the integer in buffer, it's updated to point after it. |
Returns : | The integer as gint64. |
gint64* gwy_serialize_unpack_int64_array (const guchar *buffer, gsize size, gsize *position, gsize *asize);
Deserializes an int64 array.
buffer : | A memory location containing a serialized int64 array at position position. |
size : | The size of buffer. |
position : | The position of the array in buffer, it's updated to point after it. |
asize : | Where the size of the array is to be returned. |
Returns : | The unpacked 64bit integer array (newly allocated). |
gdouble gwy_serialize_unpack_double (const guchar *buffer, gsize size, gsize *position);
Deserializes a one double.
buffer : | A memory location containing a serialized double at position position. |
size : | The size of buffer. |
position : | The position of the integer in buffer, it's updated to point after it. |
Returns : | The integer as gdouble. |
gdouble* gwy_serialize_unpack_double_array (const guchar *buffer, gsize size, gsize *position, gsize *asize);
Deserializes an double array.
buffer : | A memory location containing a serialized double array at position position. |
size : | The size of buffer. |
position : | The position of the array in buffer, it's updated to point after it. |
asize : | Where the size of the array is to be returned. |
Returns : | The unpacked double array (newly allocated). |
guchar* gwy_serialize_unpack_string (const guchar *buffer, gsize size, gsize *position);
Deserializes a one nul-terminated string.
buffer : | A memory location containing a serialized nul-terminated string at position position. |
size : | The size of buffer. |
position : | The position of the string in buffer, it's updated to point after it. |
Returns : | A newly allocated, nul-terminated string. |
gsize gwy_serialize_check_string (const guchar *buffer, gsize size, gsize position, const guchar *compare_to);
Check whether size bytes of memory in buffer can be interpreted as a nul-terminated string, and eventually whether it's equal to compare_to.
When compare_to is NULL, the comparsion is not performed.
buffer : | A memory location containing a nul-terminated string at position position. |
size : | The size of buffer. |
position : | The position of the string in buffer. |
compare_to : | String to compare buffer to, or NULL. |
Returns : | The length of the nul-terminated string including the nul character; zero otherwise. |
GByteArray* gwy_serialize_pack_struct (GByteArray *buffer, gsize nspec, const GwySerializeSpec *spec);
Serializes a struct with named and somewhat typed fields.
For object serialization gwy_serialize_pack_object_struct() should be more convenient and less error prone.
buffer : | A buffer to which the serialized components should be appended, or NULL. |
nspec : | The number of items in spec. |
spec : | The components to serialize. |
Returns : | buffer or a newly allocated GByteArray with serialization of spec components appended. |
gboolean gwy_serialize_unpack_struct (const guchar *buffer, gsize size, gsize nspec, const GwySerializeSpec *spec);
Deserializes a structure with named components packed by gwy_serialize_pack_struct().
Extra components are ignored (but cause a warning), components of different type than expected cause failure, missing components are not detected.
It is safe to pass pointers to existing non-atomic objects (strings, arrays, objects) in spec values, they will be dereferenced and freed as necessary when an unpacked value is about to replace them. For the same reason it is an error to pass pointers to unintialized memory there, always initialize non-atomic spec values to NULL pointers, at least.
For object deserialization gwy_serialize_unpack_object_struct() should be more convenient and less error prone.
buffer : | A memory location containing a serialized structure. |
size : | The size of buffer. |
nspec : | The number of items in spec. |
spec : | The components to deserialize. |
Returns : | TRUE if the unpacking succeeded, FALSE otherwise (some fields may be unpacked in this case). |
GByteArray* gwy_serialize_pack_object_struct (GByteArray *buffer, const guchar *object_name, gsize nspec, const GwySerializeSpec *spec);
Packs a struct as an object.
This is a wrapper around gwy_serialize_pack_struct(), taking care of adding type name and packed object size.
Here's how a serialization method of a simple object whose state is described by a single real number foo could look (without error checking):
static guchar* my_object_serialize(GObject *obj, guchar *buffer, gsize *size) { MyObject *my_object = MY_OBJECT(obj); GwySerializeSpec spec[] = { { 'd', "foo", &my_object->foo, NULL, }, }; return gwy_serialize_pack_object_struct(buffer, size, "MyObject", G_N_ELEMENTS(spec), spec); }
buffer : | A buffer to which the serialized components should be appended. |
object_name : | The g_type_name() of the object. |
nspec : | The number of items in spec. |
spec : | The components to serialize. |
Returns : | The buffer with serialization of spec components appended. |
gboolean gwy_serialize_unpack_object_struct (const guchar *buffer, gsize size, gsize *position, const guchar *object_name, gsize nspec, const GwySerializeSpec *spec);
Deserializes an object with named components packed by gwy_serialize_pack_object_struct().
Here's how a deserialization method of a simple object whose state is described by a single real number foo could look (without error checking):
static GObject* my_object_deserialize(const guchar *buffer, gsize size, gsize *position) { double foo = 1.0; GwySerializeSpec spec[] = { { 'd', "foo", &foo, NULL, }, }; MyObject *my_object; gwy_serialize_unpack_object_struct(buffer, size, position, "MyObject", G_N_ELEMENTS(spec), spec); return my_object_new(foo); }
buffer : | A memory location containing a serialized object at position position. |
size : | Current size of buffer, new size is returned here. |
position : | The position of the object in buffer, it's updated to point after it. |
object_name : | The g_type_name() of the object. |
nspec : | The number of items in spec. |
spec : | The components to deserialize. |
Returns : | Whether the unpacking succeeded (see gwy_serialize_unpack_struct() for definition of success). |
<< GwyWatchable | GwyContainer >> |