![]() | ![]() | 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 you classes, most high-level (and thus probably most useful) are gwy_serialize_pack_object_struct() and gwy_serialize_unpack_object_struct().
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 GBaseInitFunc 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, components of different type than expected cause failure, missing components are not detected.
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 >> |