![]() | ![]() | ![]() | Gwyddion Library Reference Manual | ![]() |
---|
GwySerializable — Abstract interface for serializable objects.
guchar* (*GwySerializeFunc) (GObject *serializable, guchar *buffer, gsize *size); GObject* (*GwyDeserializeFunc) (const guchar *buffer, gsize size, gsize *position); GObject* (*GwyDuplicateFunc) (GObject *object); struct GwySerializable; struct GwySerializableClass; struct GwySerializeSpec; guchar* gwy_serializable_serialize (GObject *serializable, guchar *buffer, gsize *size); GObject* gwy_serializable_deserialize (const guchar *buffer, gsize size, gsize *position); GObject* gwy_serializable_duplicate (GObject *object); void gwy_serialize_store_int32 (guchar *buffer, guint32 value); guchar* gwy_serialize_pack (guchar *buffer, gsize *size, 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); guchar* gwy_serialize_pack_struct (guchar *buffer, gsize *size, gsize nspec, const GwySerializeSpec *spec); gboolean gwy_serialize_unpack_struct (const guchar *buffer, gsize size, gsize nspec, const GwySerializeSpec *spec); guchar* gwy_serialize_pack_object_struct (guchar *buffer, gsize *size, 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);
GInterface +----GwySerializable
GwySerializable is implemented by GwySIUnit and GwyContainer.
GwySerializable requires GObject.
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().
guchar* (*GwySerializeFunc) (GObject *serializable, guchar *buffer, gsize *size);
The type of serialization method, see gwy_serializable_serialize() for description.
serializable: | An object to serialize. |
buffer: | A buffer. |
size: | The size of buffer. |
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 GwySerializableClass { GTypeClass parent_class; GwySerializeFunc serialize; GwyDeserializeFunc deserialize; GwyDuplicateFunc duplicate; };
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. |
guchar* gwy_serializable_serialize (GObject *serializable, guchar *buffer, gsize *size);
Serializes an object implementing GwySerializable interface.
serializable: | A GObject implementing GwySerializable interface. |
buffer: | A buffer to which the serialized object should be appended. |
size: | Current size of buffer, new size is returned here. |
Returns : | A reallocated block of memory of size size containing the current contents of buffer with object representation 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 (guchar *buffer, guint32 value);
Stored a 32bit integer to a buffer.
buffer: | A buffer to which the value should be stored. |
value: | A 32bit integer. |
guchar* gwy_serialize_pack (guchar *buffer, gsize *size, 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.
The buffer buffer may be NULL (and size should be zero then), or it can contain some data. In the former case a new one will be allocated, in the latter case the existing buffer will be extended to be able to keep both the old and the new data; size will be updated.
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. |
size: | Current size of buffer, new size is returned here. |
templ: | A template string. |
...: | A list of atomic values to serialize. |
Returns : | The buffer 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. |
guchar* gwy_serialize_pack_struct (guchar *buffer, gsize *size, 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. |
size: | Current size of buffer, new size is returned here. |
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_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). |
guchar* gwy_serialize_pack_object_struct (guchar *buffer, gsize *size, 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. |
size: | Current size of buffer, new size is returned here. |
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 >> |