![]() | ![]() | 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; struct GwySerializeItem; 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); GByteArray* gwy_serialize_pack (GByteArray *buffer, const gchar *templ, ...); void gwy_serialize_store_int32 (GByteArray *buffer, gsize position, guint32 value); 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); GByteArray* gwy_serialize_object_items (GByteArray *buffer, const guchar *object_name, gsize nitems, const GwySerializeItem *items); GwySerializeItem* gwy_deserialize_object_hash (const guchar *buffer, gsize size, gsize *position, const guchar *object_name, gsize *nitems);
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. |
struct GwySerializeItem { guchar ctype; const guchar *name; GwySerializeValue value; guint32 array_size; };
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. |
GByteArray* gwy_serialize_pack (GByteArray *buffer, const gchar *templ, ...);
gwy_serialize_pack is deprecated and should not be used in newly-written code.
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 gdouble, '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 gdouble array.
'o' for a serializable object.
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. |
void gwy_serialize_store_int32 (GByteArray *buffer, gsize position, guint32 value);
gwy_serialize_store_int32 is deprecated and should not be used in newly-written code.
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. |
gboolean gwy_serialize_unpack_boolean (const guchar *buffer, gsize size, gsize *position);
gwy_serialize_unpack_boolean is deprecated and should not be used in newly-written code.
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);
gwy_serialize_unpack_char is deprecated and should not be used in newly-written code.
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);
gwy_serialize_unpack_char_array is deprecated and should not be used in newly-written code.
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 on success. |
Returns : | The unpacked character array (newly allocated). |
gint32 gwy_serialize_unpack_int32 (const guchar *buffer, gsize size, gsize *position);
gwy_serialize_unpack_int32 is deprecated and should not be used in newly-written code.
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);
gwy_serialize_unpack_int32_array is deprecated and should not be used in newly-written code.
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 on success. |
Returns : | The unpacked 32bit integer array (newly allocated). |
gint64 gwy_serialize_unpack_int64 (const guchar *buffer, gsize size, gsize *position);
gwy_serialize_unpack_int64 is deprecated and should not be used in newly-written code.
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);
gwy_serialize_unpack_int64_array is deprecated and should not be used in newly-written code.
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 on success. |
Returns : | The unpacked 64bit integer array (newly allocated). |
gdouble gwy_serialize_unpack_double (const guchar *buffer, gsize size, gsize *position);
gwy_serialize_unpack_double is deprecated and should not be used in newly-written code.
Deserializes a one gdouble.
buffer : | A memory location containing a serialized gdouble 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);
gwy_serialize_unpack_double_array is deprecated and should not be used in newly-written code.
Deserializes a gdouble array.
buffer : | A memory location containing a serialized gdouble 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 on success. |
Returns : | The unpacked gdouble array (newly allocated). |
guchar* gwy_serialize_unpack_string (const guchar *buffer, gsize size, gsize *position);
gwy_serialize_unpack_string is deprecated and should not be used in newly-written code.
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);
gwy_serialize_check_string is deprecated and should not be used in newly-written code.
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);
gwy_serialize_pack_struct is deprecated and should not be used in newly-written code.
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);
gwy_serialize_unpack_struct is deprecated and should not be used in newly-written code.
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.
Caller is responsible for use/clean-up of these values if deserialization succeeds or not.
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). |
GByteArray* gwy_serialize_object_items (GByteArray *buffer, const guchar *object_name, gsize nitems, const GwySerializeItem *items);
Serializes an object to buffer.
buffer : | A buffer to which the serialized components should be appended, or NULL. |
object_name : | The g_type_name() of the object. |
nitems : | The number of items items. |
items : | The components to serialize. |
Returns : | buffer or a newly allocated GByteArray with serialization of items components appended. |
Since 1.7
GwySerializeItem* gwy_deserialize_object_hash (const guchar *buffer, gsize size, gsize *position, const guchar *object_name, gsize *nitems);
Deserializes an object with arbitrary components.
This function works like gwy_serialize_unpack_object_struct(), except that it does not use any a priori knowledge of what the object contains. So instead of filling values in supplied GwySerializeSpec's, it constructs GwySerializeItem's completely from what is found in buffer. It can do considerably less sanity checks and even allows several components of the same name.
buffer : | A block of memory of size size contaning object representation. |
size : | The size of buffer. |
position : | Current position in buffer, will be updated to point after object. |
object_name : | The g_type_name() of the object. |
nitems : | Where the number of deserialized components should be stored. |
Returns : | A newly allocated array of deserialized components. Note the name fields of GwySerializeSpec's point to buffer and thus are valid only as long as buffer is; any arrays or strings are newly allocated and must be reused or freed by caller. |
Since 1.7
<< GwyWatchable | GwyContainer >> |