GwySerializable

GwySerializable — Abstract interface for serializable objects.

Synopsis




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);

Object Hierarchy


  GInterface
   +----GwySerializable

Prerequisites

GwySerializable requires GObject.

Known Implementations

GwySerializable is implemented by GwySIUnit and GwyContainer.

Description

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.

Details

struct GwySerializableIface

struct GwySerializableIface {

    GTypeInterface parent_class;

    GwySerializeFunc serialize;
    GwyDeserializeFunc deserialize;
    GwyDuplicateFunc duplicate;
};


struct GwySerializable

struct GwySerializable;


GwySerializeFunc ()

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.

GwyDeserializeFunc ()

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.

GwyDuplicateFunc ()

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

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

struct GwySerializeItem {

    guchar ctype;
    const guchar *name;
    GwySerializeValue value;
    guint32 array_size;
};


gwy_serializable_serialize ()

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.

gwy_serializable_deserialize ()

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.

gwy_serializable_duplicate ()

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.

gwy_serialize_pack ()

GByteArray* gwy_serialize_pack              (GByteArray *buffer,
                                             const gchar *templ,
                                             ...);

Warning

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.

gwy_serialize_store_int32 ()

void        gwy_serialize_store_int32       (GByteArray *buffer,
                                             gsize position,
                                             guint32 value);

Warning

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.

gwy_serialize_unpack_boolean ()

gboolean    gwy_serialize_unpack_boolean    (const guchar *buffer,
                                             gsize size,
                                             gsize *position);

Warning

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.

gwy_serialize_unpack_char ()

guchar      gwy_serialize_unpack_char       (const guchar *buffer,
                                             gsize size,
                                             gsize *position);

Warning

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.

gwy_serialize_unpack_char_array ()

guchar*     gwy_serialize_unpack_char_array (const guchar *buffer,
                                             gsize size,
                                             gsize *position,
                                             gsize *asize);

Warning

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).

gwy_serialize_unpack_int32 ()

gint32      gwy_serialize_unpack_int32      (const guchar *buffer,
                                             gsize size,
                                             gsize *position);

Warning

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.

gwy_serialize_unpack_int32_array ()

gint32*     gwy_serialize_unpack_int32_array
                                            (const guchar *buffer,
                                             gsize size,
                                             gsize *position,
                                             gsize *asize);

Warning

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).

gwy_serialize_unpack_int64 ()

gint64      gwy_serialize_unpack_int64      (const guchar *buffer,
                                             gsize size,
                                             gsize *position);

Warning

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.

gwy_serialize_unpack_int64_array ()

gint64*     gwy_serialize_unpack_int64_array
                                            (const guchar *buffer,
                                             gsize size,
                                             gsize *position,
                                             gsize *asize);

Warning

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).

gwy_serialize_unpack_double ()

gdouble     gwy_serialize_unpack_double     (const guchar *buffer,
                                             gsize size,
                                             gsize *position);

Warning

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.

gwy_serialize_unpack_double_array ()

gdouble*    gwy_serialize_unpack_double_array
                                            (const guchar *buffer,
                                             gsize size,
                                             gsize *position,
                                             gsize *asize);

Warning

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).

gwy_serialize_unpack_string ()

guchar*     gwy_serialize_unpack_string     (const guchar *buffer,
                                             gsize size,
                                             gsize *position);

Warning

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.

gwy_serialize_check_string ()

gsize       gwy_serialize_check_string      (const guchar *buffer,
                                             gsize size,
                                             gsize position,
                                             const guchar *compare_to);

Warning

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.

gwy_serialize_pack_struct ()

GByteArray* gwy_serialize_pack_struct       (GByteArray *buffer,
                                             gsize nspec,
                                             const GwySerializeSpec *spec);

Warning

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.

gwy_serialize_unpack_struct ()

gboolean    gwy_serialize_unpack_struct     (const guchar *buffer,
                                             gsize size,
                                             gsize nspec,
                                             const GwySerializeSpec *spec);

Warning

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).

gwy_serialize_pack_object_struct ()

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.

gwy_serialize_unpack_object_struct ()

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).

gwy_serialize_object_items ()

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


gwy_deserialize_object_hash ()

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